套件進入點

分別安裝 Runtime 與 Remote Client

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

npm install @roackb2/heddle

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

npm install @roackb2/heddle-remote

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

Entrypoint 對照表

@roackb2/heddle：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。Hosted Process Code 則應從明確的 /hosted 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。

@roackb2/heddle/hosted：Process-local Active Run

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

import {
  ConversationRunService,
  ConversationRunConflictError,
  ConversationRunReplayUnavailableError,
} from '@roackb2/heddle/hosted'

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

@roackb2/heddle/hosted/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。

@roackb2/heddle-remote：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。

@roackb2/heddle-remote/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。

@roackb2/heddle/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 不會自動加入 /hosted、HTTP/SSE 或 Remote Package。

選擇規則

1. Node Product Host 從 @roackb2/heddle 開始。
2. Work 會超過單一 Caller 壽命，或需要可定址 Replay、Cancellation、Approval Resolution 時，才加入 /hosted。
3. Node HTTP/SSE Adapter 才加入 /hosted/http-sse。
4. Remote Consumer 才安裝 @roackb2/heddle-remote。
5. API 真正使用 Conventional REST/SSE Contract 時，才加入 Remote Package 的 /http-sse Subpath。
6. Curated SDK Export 無法表達所需 Runtime Customization 時，才使用 /advanced。
7. 絕不 Import Internal Build Path；需要的 Contract 若尚未公開，應提出 SDK API Request，而不是讓產品耦合 Implementation File。

版本與驗證

當 Node Runtime 與 Remote Package 交換 Canonical Run Envelope 時，兩者應維持相容的 Release Line，並在 Public Protocol Boundary 驗證雙向資料。

更新版本後，請驗證：

• 可以重新開啟並延續持久 Session；
• Public Activity 與 Result Schema 仍接受預期 Field，並移除其餘 Field；
• 從已知 Sequence 重新連線不會重複或跳過 Event；
• Cancel 與 Error Settlement 維持 Terminal；
• Browser Bundle 不會包含 Node Runtime Package；
• 選定的 Subpath 存在於 Installed Package 的 exports Map。