套件進入點

只安裝你需要的 Boundary

需要完整 Coding-agent Product 與 heddle Command 時，全域安裝 CLI：

npm install --global @heddleagent/cli

Node Runtime Package 需要 Node.js 20 或更新版本：

npm install @heddleagent/runtime

只有在 Application 要消費 Hosted Run、但不嵌入 Node Agent Runtime 時，才獨立安裝 Remote Package：

npm install @heddleagent/run-client

TypeScript Control Plane 呼叫另外部署的 Compatible Execution Host 時，安裝 Adopter Package：

npm install @heddleagent/execution-host-client

只有 Backend 要把通用 Execution Host Conversation Lifecycle 持久化到 PostgreSQL 時，才加入官方 Adapter：

npm install @heddleagent/postgres @heddleagent/execution-host-client drizzle-orm pg

非 TypeScript Control Plane 直接使用 Versioned OpenAPI、JSON Schema 與 Golden Fixture，不必安裝或移植 Heddle Runtime。舊的 @roackb2/* Coordinate 已 Deprecated，只為既有 Consumer 保留安裝能力。新的 Heartbeat Integration 使用官方 @heddleagent/postgres/heartbeat Adapter。

JavaScript Package 使用 ESM。請從文件記載的 Package 與 Subpath Entrypoint Import，不要深入 dist 或 Internal src Path。

Entrypoint 對照表

@heddleagent/runtime：Curated Product-host SDK

預設 Entrypoint 依照五層 Progressive-disclosure Ladder 組織。

1. 啟動 Conversation

主要 Export：

• runQuickstartConversationCli；
• resolveQuickstartConversationCliDefaults；
• QuickstartConversationCliRunnerService；
• createConversationEngine；
• Built-in Default Model Constant。

當 Heddle 可以擁有簡單的 Terminal Prompt Loop 時，使用 Quickstart Runner。產品要擁有 Presentation、Session Browser、Approval 或 Lifecycle 時，使用 Conversation Engine。

核心契約

Root 會 Export RunInput、RunResult、RunFailure、ModelRunFailureCode、ToolDefinition、ToolCall、ToolResult、TraceEvent 與 StopReason 等常用 Type。

這些是 Host-facing Contract。請從 Package Root Import，不要重複定義 Shape。

2. 加入能力

主要 Export 包含：

• defineHostExtension 與 ConversationEngineHostExtensionService；
• prepareMcpHostExtension、prepareMcpHostExtensionCatalog 與 MCP Option/Result Type；
• ToolRegistry、ToolExecutionService、ToolBundleComposer 與 RuntimeToolService；
• Artifact 與 Agent Skills Toolkit/Service。

較舊的 Top-level Engine tools Option 已 Deprecated；新的 Product Host 應透過 hostExtensions.tools 組合 Product Tool。

3. 調整 Input 與 Output

主要 Export 包含：

• createConversationTextHost 與 ConversationTextHostService；
• ConversationActivity 以及 Handler/Correlation Type；
• HeddleEventType 與 HeddleEventTypeValue；
• ConversationTurnResultSummary 與 ConversationTurnToolResult；
• ToolActivitySummarizer。

使用這些 Contract 建立自訂 Terminal、API、Telemetry 或 UI Adapter，不必 Import Internal Runtime Module。

4. 擁有 Lifecycle 與 Approval

Root 會 Export Conversation Engine Type、Session 與 Turn Service Contract、Turn Input/Result、為相容性保留的 Run-service Contract、Approval Service 與 Policy、Remembered Project Rule、Runtime Tool-selection Profile，以及給已擁有低階 Session Path 的 Host 使用的 EngineConversationTurnService。

新的 Host 應優先使用 createConversationEngine。長駐 Process Code 則應從明確的 /runs Entrypoint Import ConversationRunService，即使 Root 仍保留 Compatibility Export。

5. 提供 Storage

主要 Export 包含：

• ArtifactRepository、ArtifactService、FileArtifactRepository 與 Artifact Record Type；
• ChatSessionRepository、FileChatSessionRepository、Revision/Conflict Error、Catalog Input/Result 與 ChatSession；
• RuntimeCredentialService 與 Credential-source Type。

Session 與 Artifact Repository 可以獨立替換。Trace 與 Memory 目前仍透過 stateRoot 使用 Path-oriented Storage。

@heddleagent/runtime/runs：Process-local Active Run

當 Request 與 Subscription 的生命週期不同時，從這裡 Import ConversationRunService，以及 Run Address、Handle、Replay、Stream Item、Approval、Projection 與 Error Contract。

import {
  ConversationRunService,
  ConversationRunConflictError,
  ConversationRunReplayUnavailableError,
} from '@heddleagent/runtime/runs'

這個 Subpath 不會增加 Transport，也不是 Durable Broker；它只是把「長駐 Process」的假設明確放在 Import 中。

@heddleagent/runtime/runs/http-sse：Node SSE 正確性

Export：

• parseConversationRunSseReplayCursor；
• streamConversationRunSse；
• ConversationRunSseReplayCursorError；
• SSE Event、Protocol、Cursor Input 與 Streaming Option Type。

這些 Helper 針對 Node Request/Response Primitive，因此 Express 與其他 Node Framework 都能使用，不會讓 Express 進入 Heddle Core。

@heddleagent/run-client：Browser-safe Run Protocol

主要 Export：

• ConversationRunProtocolCodec 與 ConversationRunProtocolValidationError；
• ConversationRunConsumerService；
• ConversationRunSequenceGapError 與 ConversationRunTerminalViolationError；
• Reference、Envelope、Event、Subscription、Acceptance、Retry 與 Codec Type；
• ConversationRunReferenceSchema 與 ConversationRunReplayCursorSchema。

Codec 接受同步 Standard Schema Validator。Zod、Valibot、ArkType 與其他相容 Validator 都能定義 Host 的 Public Activity 與 Result Projection。這個 Package 刻意排除 Heddle 的 Node Runtime、Model Provider、Server、CLI 與 Web Control Plane。

@heddleagent/run-client/http-sse：Conventional REST/SSE Client

Export ConversationRunHttpSseClient、ConversationRunHttpSseClientError，以及相關 Option/Input/Error-payload Type。

當 Host API 遵循 Conventional Start、Event Subscription 與 Cancellation Resource Shape 時使用。Client 負責 URL/Header Composition、Response Schema Validation、Incremental Event Parsing、Reader Cleanup，以及 Envelope/SSE Identity Agreement。產品提供 Auth Header、Public Schema、Abort Lifecycle、Retry Timing 與 UI Behavior。

@heddleagent/execution-host-client：獨立 Execution Host Boundary

Product Control Plane 呼叫另外部署的 Compatible Execution Host 時使用這個 Package。它以不同 Subpath 分開 Contract、Execution Authority、Conversation Orchestration、MCP Capability Verification、Transport、Node Edge 與 Testing。

Conversation Surface 包含可重用的 Durable Lifecycle Service。Heddle 決定 Requested、Accepted、Terminal、Cancelled、Interrupted 與 Expired Transition 的意義，並在公開對應 Event 前完成 Commit；Adopter 注入 Atomic Store，仍然擁有 ID、Schema、Migration、Retention、User-scoped Query 與 Presentation。如此每個產品不必重做通用 State Machine，Heddle 也不會因此接管 Product Record。

公開 Package 內的 Canonical spec/v1 OpenAPI、JSON Schema、Lifecycle Profile 與 Golden Fixture 是 Language-neutral Authority。Permissioned Canonical Source 內的 Python 實作證明 Clean-room Adopter 能遵守這些 Artifact；它不是已發布或受支援的 Python SDK，也不承諾 TypeScript Helper Parity。Compatible Execution Host 目前採 Permissioned Access，Heddle 尚未提供公開 Hosted Service。

@heddleagent/postgres/execution-host/conversations：官方 Lifecycle Storage

這個 Adapter 實作由 @heddleagent/execution-host-client/conversation 擁有的 Durable Lifecycle Port。它提供 Ordered SQL Migration 與具 Scope Fencing 的 Atomic Store；PostgreSQL Service、Pool、Authenticated Scope、Product Record、History Query、Retention 與 Migration Execution 仍由 Application 負責。

依 Export 順序，把每個 Package 內附的 SQL 檔複製到 Application 自己 Check in 的 Migration Sequence，並在建立 Store 前套用。公開 Package README 說明 Library 不在 Runtime 修改 Production Schema 的原因，並提供實際 Copy Command。

Deprecated @roackb2/heddle-postgres：Legacy Heartbeat Durability

這個 Deprecated Package 為既有 Heddle Heartbeat Deployment 提供 PostgreSQL Authority，負責 Row Locking、Claim、Stale-writer Fencing、Lease、Recovery、Checkpoint、Run History 與 Atomic Operator Control。它刻意不提供 Product Table 或 Execution Host Conversation-lifecycle Adapter。新的 Package-family Integration 不應把它當作通用 Database Layer。

@heddleagent/runtime/advanced：Deep Core Customization

Advanced Entrypoint 會重新 Export Curated Root，並加入較低階 Building Block：

• LLM Adapter、Provider Registry、OpenAI-compatible Discovery 與 Model Catalog；
• 個別 Coding、Shell、Browser-research 與 External-context Tool；
• Trace Recording、Review Parsing、Observability 與 System-prompt Construction；
• Memory Catalog、Maintenance、Note、Visibility 與 Knowledge Tool；
• Awareness Provider 與 Coding-workspace Snapshot；
• 較低階的 Agent Loop 與 Checkpoint；
• Heartbeat Runner、Storage、Scheduler 與 Presenter；
• Semantic-drift Observer 等選用 Integration；
• Budget、Logger 與 Runtime Error。

只有當產品必須替換或組合較低階 Runtime Mechanic 時，才使用這個 Surface。Import /advanced 不會自動加入 /runs、HTTP/SSE 或 Run-client Package。

選擇規則

1. Node Product Host 從 @heddleagent/runtime 開始。
2. Work 會超過單一 Caller 壽命，或需要可定址 Replay、Cancellation、Approval Resolution 時，才加入 /runs。
3. Node HTTP/SSE Adapter 才加入 /runs/http-sse。
4. Remote Consumer 才安裝 @heddleagent/run-client。
5. API 真正使用 Conventional REST/SSE Contract 時，才加入 Remote Package 的 /http-sse Subpath。
6. Product Control Plane 呼叫獨立 Compatible Execution Host 時才使用 @heddleagent/execution-host-client；非 TypeScript Adopter 實作 Canonical v1 Artifact。
7. 只用 @heddleagent/postgres/execution-host/conversations 保存通用 Execution Host Lifecycle，不要把它當作 Product Conversation History。
8. 新的 Heartbeat Persistence 使用 @heddleagent/postgres/heartbeat；@roackb2/heddle-postgres 只作為既有 Consumer 的 Deprecated Coordinate。
9. Curated SDK Export 無法表達所需 Runtime Customization 時，才使用 /advanced。
10. 絕不 Import Internal Build Path；需要的 Contract 若尚未公開，應提出 SDK API Request，而不是讓產品耦合 Implementation File。

版本與驗證

交換 Public Contract 的 Package 應維持相容的 Release Line。Adopter v1 Artifact Version 應獨立於 Implementation Language 固定，並讓每個 Store 或 Clean-room Adopter 執行 Published Conformance Fixture。

更新版本後，請驗證：

• 可以重新開啟並延續持久 Session；
• Public Activity 與 Result Schema 仍接受預期 Field，並移除其餘 Field；
• 從已知 Sequence 重新連線不會重複或跳過 Event；
• Cancel 與 Error Settlement 維持 Terminal；
• Browser Bundle 不會包含 Node Runtime Package；
• Durable Adopter Transition 通過 Shared Store 與 Terminal-projection Fixture；
• Heartbeat PostgreSQL Migration 先於需要該 Schema 的程式碼部署；
• 選定的 Subpath 存在於 Installed Package 的 exports Map。