Skip to content

04-zcode-private-protocol.md

Latest commit

 

History

History
106 lines (69 loc) · 6.32 KB

04-zcode-private-protocol.md

File metadata and controls

106 lines (69 loc) · 6.32 KB
Raw

ZCode private host protocol

この文書は現在のversion固有contractを記録します。hostの起動方式はADR 0003、互換性方針はADR 0005、interaction境界はADR 0007を参照してください。

1. Scope

対象はZCode 3.11.2 / CLI 0.16.5のapp.asar/out/hostに含まれる公式local host serviceです。これは公開APIではないため、現在のmanifestが示すartifact fingerprintと完全一致する場合だけ起動します。

zcode.cjs app-server --stdioの直接protocolではdesktopのmodel-provider registryを利用できないことが実測されています。production経路の選定理由はADR 0003に記録しています。

2. Artifactとprotocolの分離

HostArtifactDescriptorは実ファイルの同一性を表します。

  • ID: zcode-host-3.11.2
  • app version: 3.11.2
  • CLI version: 0.16.5
  • host index: out/host/index.js
  • RPC module: out/host/chunk-KGXW6KHC.js
  • required exports: g、i、j

HostProtocolDescriptorは意味変換を表します。

  • ID: zcode-task-v1
  • common service: zcode-agent
  • task service: zcode-task
  • cancel: stopGeneration({taskId})
  • structured input: respondElicitation({taskId, requestId, action, content})
  • permission: respondPermission({taskId, requestId, optionId})

artifactの更新とprotocol意味論の更新を別々のdescriptorで表します。artifactからprotocol IDへの参照が一致しない場合も起動しません。

3. Launch and bridge

  1. インストール済みZCodeのElectron executableをELECTRON_RUN_AS_NODE=1で起動
  2. worker_threads.Worker内で公式out/host/index.jsをimport
  3. Electron utility-processのprocess.parentPort event shapeをNode MessagePortへ変換
  4. descriptorが指定するRPC module/exportとservice channelへ接続
  5. allowlist済みservice methodだけを内部NDJSON bridgeへ公開

bridgeのsuccess responseは、公式methodがundefinedを返す場合もresult: nullを明示します。公式hostのstdout/stderrはACP stdoutへ流しません。

公式hostはprompt送信前にparent processへbrowser-execute-requestを送り、desktop browserの状態を取得します。headless bridgeにはbrowser backendがないため、同じrequest IDのbrowser-execute-resultでbackend_unavailableを即時に返します。request payloadを転送・保存せず、公式hostの30秒timeoutを待って同じ結果へ到達することを避けます。PaseoなどACP clientがsession/newで渡すMCP serverと、このZCode内部のbrowser IPCは別の経路です。

4. Internal envelope

{"id":1,"method":"initialize","params":{"workspacePath":"/workspace"}}
{"id":1,"result":{"available":true}}
{"method":"event","params":{"subscriptionId":"...","event":{"type":"session.event"}}}
  • UTF-8、1 JSON object/line
  • jsonrpc fieldなし
  • bounded frame size
  • request ID correlation、method別timeout
  • malformed/unknown responseはfail closed
  • late responseはpending requestがなければ無視

5. Dynamic event schema

top-level eventはsnapshot、state.updated、permission.request、userInput.request、userInput.response、providerRuntimeHeaders.request、session.eventだけを受理します。

session.eventはeventId、sessionId、non-negative seq、timestamp、delivery kind、type、payloadを必須とします。model stream、tool update、turn terminal、session stateの未知typeを成功終了へ丸めません。

6. Reverse interactions

Permission

通常のtool permissionでは、native optionのoptionId、name、意味を保持してACPの選択肢へ一対一で写像します。ACP clientが返したIDが元optionに存在しなければ拒否します。cancel/error/disconnect時は実在するdeny optionを選び、option IDをexactly onceで返します。toolName === "ExitPlanMode" はplan承認として分離します。

Plan approval

userInput.request の schema.interaction === "plan_approval" または permission.request の toolName === "ExitPlanMode" をplan承認として扱います。どちらも input.plan のMarkdown本文をACPへ先に通知し、form elicitation/create の結果を元のnative応答methodへ返します。本文欠落や未知optionではallowを返しません。

Structured user input

form elicitation capabilityを持つACP clientには複数質問・multiple selectを保持してelicitation/createへ変換します。client応答はactionとcontentへ平坦化してrespondStructuredInputへ渡します。form非対応clientでは実際のdecline応答を返し、turnをINTERACTION_UNSUPPORTEDで停止します。

Provider runtime headers

通常のprovider headerは公式host内のmodel-provider serviceがcredentialとregistryから構築するため、adapterは値を受け取りません。hostからinteractive requestが来た場合はheadersApplied: falseを返し、turnを明示的に停止します。

7. Compatibility identity

互換性判定は次の順序で行います。

  1. metadataのruntime、entry、sourceを既知値と照合
  2. metadata platformを実行中のOS/architectureと完全一致で検証
  3. app versionとCLI versionを現在のmanifestと照合
  4. host index、RPC module、required exportsを完全一致で検証
  5. CLI SHA-256の差分をmodifiedと診断

app buildとmetadata raw SHA-256は診断表示だけで、互換性条件ではありません。CLIがmodifiedでもhost artifactが一致すれば起動を許可します。

同一app versionのCLIとhost内容は全OSで同一と扱います。OS別manifest entryは作らず、OS差はinstall layoutとmetadata platform一致に限定します。未知OSはlayout解決時に拒否します。

8. Current fingerprints

CLI SHA-256:        e9f1868c0fdb863537ed910ee3828b9be96b8c2fd805473f63b439e1113266b8
host index SHA-256: 30911a90dadc5c384959d00d95ccc70c8cf38c74a9cb99c3168b0897d046d215
RPC module SHA-256: e66203598b60d8728260ad7631f295f9d6deb8276b06e8f0cab8776773c75b31

未知identityにunsafe bypass、旧response形式、system runtime fallbackはありません。