@kodax-ai/kodax 0.7.67 → 0.7.69

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -28,6 +28,9 @@ are NOT obvious from inspecting the type definitions alone:
 18. [External-agent executor plane](#18-external-agent-executor-plane-feature_258-v0767)
 19. [Session surface filtering and cursor pagination](#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767)
 20. [Cost-disciplined workflow routing and telemetry](#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)
+21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260-v0768)
+22. [Bidirectional A2A 1.0 — `/a2a`](#22-bidirectional-a2a-10--a2a-feature_267-v0769)
+23. [Shared Coder daemon for Space and IDE hosts](#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)
 
 §1–§3 (and the Phase-7/8 MCP-popout surface in §1) land in v0.7.42
 under FEATURE_186 (see [ADR-032](ADR.md#adr-032-sdk-embedder-surface-closure-feature_186-v0742)).
@@ -964,7 +967,7 @@ running your project's test suite against `main` — you can `npm link`
 the in-tree KodaX checkout instead of waiting for a published version.
 
 As of v0.7.43 the root `package.json` is in **already-published shape**:
-`"name": "@kodax-ai/kodax"` is baked in along with all 8 SDK subpath
+`"name": "@kodax-ai/kodax"` is baked in along with all 10 SDK subpath
 exports. `npm link` "just works" — no need to run `scripts/release.mjs`
 first.
 
@@ -2000,9 +2003,14 @@ By default your `topics` **extend** the KodaX base manual. v0.7.58 adds
 
 `KODAX_UNDERLYING_CAPABILITY_TOPICS` (exported) is the recommended mechanism-topic
 subset a product built on KodaX should keep even in a full replace — so your users
-still get correct answers about the underlying engine (providers / config /
-permissions / tools / skills / extensions / mcp / repo-intelligence / sessions /
-sdk / custom-providers) without the KodaX brand:
+still get correct answers about the underlying engine (providers / config /
+permissions / tools / skills / extensions / mcp / repo-intelligence / sessions /
+sdk / custom-providers) without the KodaX brand:
+
+The default full manual also includes the `memory` topic. It is intentionally
+not part of `KODAX_UNDERLYING_CAPABILITY_TOPICS` because `/experimental-memory`
+is opt-in; hosts that expose it should add `memory` explicitly or provide a
+product-specific override.
 
 ```ts
 import {
@@ -2733,13 +2741,16 @@ fields requires a protocol version bump.
 
 ### Current verification status
 
-The v0.7.67 release validation covers the runtime migration, the Worker
+The v0.7.69 release validation covers the runtime migration, the Worker
 isolation follow-ups delivered ahead of their original v0.7.71/v0.7.72
-planning slots, and the v0.7.67 external-agent/session additions:
-
-- complete repository test suite on Node 20 and Node 22;
-- package builds, Worker sidecar builds, and self-contained
-  `dist/sdk-runtime.d.ts` generation;
+planning slots, the v0.7.67 external-agent/session additions, the v0.7.68
+experimental Memory Agent surface, and the v0.7.69 A2A/integration/shared-
+daemon delivery:
+
+- Node 20 and Node 22 post-review regression for process cleanup, lock
+  ownership, frozen eval inputs, A2A transport, and the built-in manual;
+- root `tsc --noEmit`, package builds, bundle builds, and all 12 public DTS
+  entries on Node 20 and Node 22;
 - runtime/daemon/SDK/ACP/REPL integration tests, including process-distinct SDK
   auto-start and multi-client sessions/permissions;
 - Worker Runtime identity, service parity, hard close, capability requirements,
@@ -2751,6 +2762,22 @@ planning slots, and the v0.7.67 external-agent/session additions:
   recovery, policy/credential/artifact gates, and disabled-plane failure;
 - exact session `surface` filtering plus opaque cursor continuation through the
   narrow `/session` API, embedded Runtime, and daemon transport;
+- scoped zero-wait memory recall, read-only deliberate query, trace-only
+  receipts, bounded episode review, governed consult-before-write promotion,
+  and the self-contained `/experimental-memory` bundle/DTS surface;
+- bidirectional A2A 1.0 discovery/call/serve, durable task replay, no-code
+  configuration, local-Agent binding, exact Skill-script admission, SSRF/
+  credential boundaries, and the self-contained `/a2a` bundle/DTS surface;
+- split MCP/A2A/Extension configuration, lossless migration, canonical-template
+  drift checks, last-known-good hot reload, draining, and restart-required
+  classification;
+- atomic shared-daemon observation/resync, durable operations and same-session
+  ordering, settings/grant CAS, AskUser/permission transport, credential/Host
+  Tool reverse bridges, owner fencing, restart outcomes, and process-distinct
+  client/daemon smokes with credential-canary scans;
+- a fresh `0.7.69` tarball consumer importing all 11 public subpaths, creating a
+  Worker-hosted session, running the packaged CLI, and checking packaged DTS and
+  Worker sidecars; plus a Windows x64 binary/version/sidecar smoke;
 - external fresh npm consumer installation of the `0.7.67` tarball, proving
   Worker isolation and a distinct daemon PID through the published subpath;
 - Ubuntu Node 22 Unix-domain-socket daemon gate, including two clients sharing
@@ -2763,8 +2790,13 @@ The portable manual gates remain in
 two filenames retain their original planning slots while their content records
 the v0.7.66 delivery. v0.7.67 adds
 `FEATURE_258_v0.7.67_TEST_GUIDE.md`, `FEATURE_259_v0.7.67_TEST_GUIDE.md`, and
-`FEATURE_261_v0.7.67_TEST_GUIDE.md`. The final GitHub Actions run is recorded in
-the v0.7.67 release after the release commit is pushed.
+`FEATURE_261_v0.7.67_TEST_GUIDE.md`; v0.7.69 adds
+`FEATURE_267_v0.7.69_TEST_GUIDE.md`, `FEATURE_268_v0.7.69_TEST_GUIDE.md`, and
+`FEATURE_269_v0.7.69_TEST_GUIDE.md`. The earlier release-preparation Actions
+run is not reused after the severe-fix review. Fresh GitHub Actions run
+`29385073422` passes the Node 20/22 build, bundle, DTS, and full-test matrix plus
+the Node 22 Unix-domain-socket daemon gate. npm publication remains a
+maintainer-owned manual step.
 
 ---
 
@@ -3070,8 +3102,694 @@ The report is an audit/optimization artifact; correctness still comes from the
 workflow's structured findings, verification results, and quality gates.
 
 ---
-
-## See also
+
+## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260, v0.7.68)
+
+KodaX has one durable memory plane: the F228 Memory Control Plane. FEATURE_260
+adds a thin, opt-in agent/session API over that plane; it does not add a second
+database, filesystem memory actions, a resident memory specialist, or online
+self-modification.
+
+Top-level `runKodaX()` coding runs wire this lifecycle automatically. They build
+an exact-scoped memory pack at session start, keep passive recall off the
+blocking hot path, expose `memory_recall` only when the memory session starts,
+record bounded observations/outcomes, and close the session at the run boundary.
+Use the direct SDK below when a custom host needs to own those boundaries.
+
+### Minimal direct session
+
+```ts
+import { createMemoryControlPlane } from '@kodax-ai/kodax/agent';
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory';
+
+const identity = {
+  tenantId: 'tenant:acme',
+  workspaceId: 'workspace:desktop',
+  userId: 'user:42',
+  agentId: 'agent:reviewer',
+  projectId: 'project:kodax',
+  sessionId: 'session:20260712',
+};
+
+const controlPlane = createMemoryControlPlane({
+  cwd: process.cwd(),
+  identity,
+  projectDocs: [],
+  discoverSkills: false,
+});
+const memory = createMemoryAgent({ controlPlane });
+const session = await memory.startSession({
+  identity,
+  objective: 'Review the runtime shutdown change',
+});
+
+const immediate = session.recall({
+  decisionRevision: 'decision:1',
+  objective: 'Review the runtime shutdown change',
+  decisionContext: 'Choosing the first verification step',
+  decisionIntent: 'runtime shutdown regression',
+  throughSequence: 0,
+});
+const deliberate = await session.query({
+  decisionRevision: 'decision:2',
+  need: 'What uncommon daemon cleanup failure happened before?',
+  throughSequence: 0,
+});
+
+await session.complete({
+  status: 'succeeded',
+  summary: 'Shutdown state replacement verified',
+  evidence: [],
+});
+await session.close();
+```
+
+`recall()` is synchronous: exact observations/hints can be returned immediately,
+while an optional semantic prefetch finishes for a later matching decision.
+`query()` is deliberate and read-only; one distinct query is admitted per
+decision epoch, and the result is bounded to at most three prompt-safe hints and
+512 estimated tokens. `undefined` means there is no governed reminder to inject.
+
+### Evidence, tracing, and persistence boundaries
+
+- Recalled content is low-authority evidence. Current repository/config/runtime
+  facts must still come from current tools or host state.
+- `observe()` accepts monotonic, evidence-linked observations and rejects secret
+  material. `rewind()` removes observations after a sequence boundary.
+- `complete()` can emit an Outcome Digest through `persistOutcomeDigest` and run
+  bounded episode review through `reviewEpisode`; cancellation creates neither.
+- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
+  candidates, selection, injection, and later outcome influence. Receipts are
+  trace-only and contain no hidden reasoning.
+- Durable memory mutation remains owned by F228's
+  proposal/preview/fingerprint/apply flow. `/memory` is the CLI governance
+  surface; direct file/shell writes to managed memory roots are denied.
+- Identity/applicability matching is exact and fail-closed. Hosts should supply
+  stable tenant/workspace/user/agent/project/session identifiers and must not put
+  credentials into those identifiers.
+
+The subpath is experimental and ESM-only. Treat its exported types as opt-in
+v0.7.x contracts; keep persistence and product policy behind your own adapter.
+
+---
+
+## 22. Bidirectional A2A 1.0 — `/a2a` (FEATURE_267, v0.7.69)
+
+`@kodax-ai/kodax/a2a` is the protocol edge for the A2A 1.0 JSON-RPC/SSE
+profile. It composes the protocol-neutral F258 executor plane with the Runtime
+facade; `/agent` and `/coding` remain free of A2A wire types and dependencies.
+
+### Call an A2A Agent through F258
+
+Discovery is an explicit host action. The URL must match `allowedOrigins`, and
+the default safe transport pins the validated DNS address for each connection
+and independently revalidates redirects, rejects public plain HTTP, bounds
+time/body/redirects, and strips authorization on a cross-origin redirect. A
+custom `fetch` option is a trusted transport override: the embedder then owns
+equivalent DNS-to-connection binding in that transport or proxy.
+
+```ts
+import {
+  createA2AAgentExecutorFactory,
+  discoverA2ARegistration,
+} from '@kodax-ai/kodax/a2a';
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const client = {
+  networkPolicy: {
+    allowedOrigins: ['https://reviewer.example'],
+    allowPrivateAddresses: false,
+    requestTimeoutMs: 10_000,
+    maxResponseBytes: 1_048_576,
+    maxRedirects: 2,
+  },
+  pollIntervalMs: 500,
+} as const;
+
+const discovered = await discoverA2ARegistration({
+  agentId: 'external:a2a-reviewer',
+  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
+  credentialRef: 'a2a/reviewer',
+  effects: { remote: 'read' },
+}, client);
+
+const runtime = await createKodaXRuntime({
+  mode: 'embedded',
+  isolation: 'inline',
+  externalAgents: {
+    factories: [createA2AAgentExecutorFactory(client)],
+    credentialBroker: {
+      async withCredential(ref, use) {
+        if (ref !== 'a2a/reviewer') throw new Error('Unknown credential reference.');
+        return use(process.env.A2A_REVIEWER_TOKEN ?? '');
+      },
+    },
+    policy: ({ registration }) => ({ allowed: registration.effects.remote === 'read' }),
+    defaultContext: { actorId: 'a2a-host' },
+  },
+});
+
+await runtime.admin.agentRegistrations.upsert(discovered.registration);
+const started = await runtime.agentTasks.start({
+  agentId: discovered.registration.agentId,
+  objective: 'Review this change and return cited findings.',
+  context: { actorId: 'a2a-host' },
+  readOnly: true,
+  expectedConfigurationRevision: discovered.registration.configurationRevision,
+});
+const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
+```
+
+The executor supports durable task start/get, input continuation, cancel,
+reconcile, SSE events, and polling fallback. An ambiguous start is not retried
+automatically. A `credentialRef` is resolved just in time by the F258 broker;
+the registration, task store, and diagnostics never contain the credential.
+
+### Built-in configured path (no host code)
+
+The CLI product path stores one user document at
+`~/.kodax/integrations/a2a.json` and uses the same F258 plane:
+
+```bash
+kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
+  --credential-env A2A_REVIEWER_TOKEN --effect read
+kodax a2a test reviewer
+kodax a2a call reviewer "Review this document"
+```
+
+Embedded CLI Runtimes and the user-owned daemon automatically reconcile these
+entries as `external:<name>`. Discovery/update failure retains that entry's
+last-known-good registration; another entry can still update. The environment
+broker resolves `credentialEnv` only at call time. Automatic Runtime
+registration accepts public HTTPS and exact loopback targets; explicit private
+network access remains an operator action on the direct CLI/SDK path.
+
+Inbound publication is also no-code:
+
+```bash
+export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
+kodax a2a expose                    # Runtime default Agent
+kodax a2a expose document-agent     # ~/.kodax/agents/document-agent.md
+kodax a2a serve --port 8765
+```
+
+`expose` validates a named user Markdown Agent before writing its reference.
+`serve` loads configured MCP and Extensions before it resolves the execution
+binding or opens a socket. Native workspace read tools are admitted by
+workspace access; writes, narrow Extension Tools, MCP capabilities, subagents,
+and isolated Skill scripts require their corresponding exact `toolPolicy`
+authority. Internal Skills come from `~/.kodax/skills`, `~/.agents/skills`,
+plugins, and built-ins; public Agent Card skills are a separate explicit
+projection and never reveal the private Skill inventory.
+
+The running server pins Agent, Skill, workspace, tool registration, process and
+store revisions. Card/auth/limits can hot reload; execution-authority changes
+require an explicit restart. Managed contexts live below
+`~/kodax_a2a_server_workspace/<profile>/contexts/`. Exact Skill scripts require
+`process: isolated`, an admitted `scripts/...` path, and a passing
+`kodax sandbox doctor`; KodaX never falls back to an unsandboxed shell.
+
+### Publish one KodaX Agent
+
+Publication is host-owned and opt-in. The public card describes only the
+configured Agent, media types, and skills. Authentication runs before task
+lookup; authorization runs per operation; task visibility is principal-scoped.
+
+```ts
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const runtime = await createKodaXRuntime({ mode: 'embedded', isolation: 'inline' });
+const server = createKodaXA2AServer({
+  runtime,
+  dataDir: '/var/lib/kodax/a2a',
+  agent: {
+    name: 'KodaX Reviewer',
+    description: 'Reviews bounded code changes.',
+    version: '1.0.0',
+    publicBaseUrl: 'https://kodax.example',
+    skills: [{ id: 'review', name: 'Review', description: 'Review code.', tags: ['code'] }],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+  },
+  authentication: {
+    securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: 'Bearer' } } },
+    securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+    async authenticate(request) {
+      return request.headers.get('authorization') === `Bearer ${process.env.KODAX_A2A_TOKEN}`
+        ? { subject: 'trusted-orchestrator', scopes: ['a2a'] }
+        : null;
+    },
+  },
+  async authorize({ principal }) { return principal.scopes.includes('a2a'); },
+  limits: {
+    maxRequestBytes: 1_048_576,
+    maxPartBytes: 524_288,
+    maxConcurrentTasks: 8,
+    maxTaskWaitMs: 30_000,
+    maxActiveTasksPerPrincipal: 8,
+    maxRetainedTasksPerPrincipal: 64,
+    maxEventsPerTask: 1_000,
+    maxEventBytesPerTask: 16_777_216,
+    maxWorkspaceBytesPerContext: 1_073_741_824,
+  },
+});
+
+// Development only: the built-in listener refuses non-loopback hosts.
+const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
+```
+
+Production hosts route `GET /.well-known/agent-card.json` and JSON-RPC `POST /`
+to `server.handle(request)` behind their own TLS terminator. `POST /a2a` remains
+an accepted compatibility alias. `listen()` waits for durable recovery before
+it resolves. A host that wires `handle()` directly may explicitly await
+`server.whenReady()` before it starts accepting traffic; `handle()` also waits
+for the same recovery promise. The durable edge store supports get/list,
+continuation, cancellation, ordered SSE subscription, and surviving Runtime-run
+reattachment after an edge restart. Push notifications, A2A 0.3, gRPC, and
+HTTP+JSON are not advertised; unsupported push methods return the standard
+`PushNotificationNotSupportedError`.
+
+Non-streaming `SendMessage` waits at most `maxTaskWaitMs` (30 seconds by
+default). When that bound is reached the response contains the current working
+task; it does not cancel the Runtime run, and clients can continue with
+`GetTask` or `SubscribeToTask`.
+
+Remote messages are ordinary user inputs. They cannot select provider, model,
+profile, tools, working directory, permission mode, or Runtime configuration.
+URL parts are rejected; inline raw/data parts are bounded and materialized under
+the server-owned data directory. Responses expose final approved output only,
+not system prompts, reasoning deltas, tool payloads, credentials, or local paths.
+
+The normative baseline is A2A repository commit
+`2183794bfb9b67af4aee1be0a0ef726050642873`, protocol `1.0`, with
+`specification/a2a.proto` SHA-256
+`e195bf96ab630c69797851970203e1b2b6b19528f2e9803b7d904b91a5104016`.
+
+---
+
+## 23. Shared Coder daemon for Space and IDE hosts (FEATURE_269, v0.7.69)
+
+FEATURE_269 makes one local daemon the source of truth for a Coder profile.
+CLI, Space, IDE, and SDK clients can observe and control the same sessions and
+runs. The transport remains local to the current OS user; it is not a remote
+collaboration protocol. Closing a client detaches that client and does not stop
+the daemon or another client's run.
+
+Partner is deliberately outside this migration. Keep Partner on its existing
+inline callbacks and give it a distinct product data root and sessions root.
+Do not point a Partner inline Runtime at the Coder daemon profile or the Coder
+data root.
+
+### Connect and fail closed on required capabilities
+
+Space should own the daemon SDK client in Electron Main. Persist a random,
+stable `instanceId` and a separate 32+ character `instanceSecret` per Space
+installation. Store the secret in the OS keychain; never accept either value
+from renderer or model output. `connectKodaXRuntime()` is attach-only unless `autoStart: true`.
+An explicit inline rollback policy blocks auto-start until the owner policy is
+explicitly changed back to daemon.
+
+```ts
+import { connectKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const runtime = await connectKodaXRuntime({
+  profile: 'coder',
+  autoStart: true,
+  clientInfo: {
+    name: 'kodax-space',
+    version: '0.1.32',
+    instanceId: spaceInstallationId,
+    instanceSecret: await spaceKeychain.readRuntimeClientSecret(),
+  },
+  capabilities: {
+    richEvents: true,
+    permissionPrompts: true,
+    operationDeduplication: true,
+  },
+  requirements: {
+    operationDeduplication: 1,
+    sessionObservation: 1,
+    afterTurnInput: 1,
+    askUserTransport: 1,
+    permissionCas: 1,
+    providerCredentialBroker: 1,
+    runBoundHostTools: 1,
+    coderOwnerFencing: 1,
+    crashOutcomeModel: 1,
+    coderFeatureMatrix: 1,
+    sessionAdmission: 1,
+    completeObservationSnapshot: 1,
+    connectionLifecycle: 1,
+    typedRuntimeEvents: 1,
+    daemonSafeRunInput: 1,
+    sharedSessionSettings: 1,
+    durableRecoveryQueries: 1,
+  },
+});
+```
+
+Requirements are server facts, not authorization requests. Check
+`runtime.grantedScopes` before enabling controls. Missing capabilities or
+scopes must disable the affected UI; Space must not silently start inline
+Coder. FEATURE_269 does not advertise `interruptInput`, so an interrupt-only
+product must require `{ interruptInput: 1 }` and fail connection. The supported
+fallback is `delivery: 'after_turn'` only when that is the user's intent.
+
+The `coderFeatureMatrix` capability reports daemon availability for managed
+runs, transcript/session operations, Todo projection, managed tasks, Workflow,
+MCP, Reference External Agent, Memory, and Runtime artifacts. Reference
+External Agent is `false` when the daemon owner did not install its executor
+plane.
+
+The packaged daemon authenticates one local OS-user/profile trust domain with
+a random token stored beside daemon state and a user-only local endpoint. It
+does not issue a different daemon token to each application in v0.7.69. The
+returned scope set is chosen by the host (the packaged host grants the public
+local-user set). `clientInfo.instanceId` is stable attribution for origin and
+operation deduplication. `instanceSecret` proves that a new authenticated
+connection is the same stable client when it resumes that client's credential
+or Host Tool leases; only its hash participates in daemon-owned bridge state.
+Keep all three values in Electron Main. Mutually distrusting processes running
+as the same OS account remain outside this release's threat model.
+
+### Join atomically and resync after disconnect
+
+`sessions.observe()` installs the live subscription before taking the
+snapshot. Its snapshot contains one authoritative `runtimeId`, cursor,
+`transcriptRevision`, complete transcript, versioned settings, run/queue state,
+queued continuation IDs/order/origin/safe previews, pending permission and
+AskUser requests, and live assistant/thinking/tool/Todo/managed-task
+projection. Run requirements include the current credential/Host Tool
+availability. Listener events are strictly after the returned cursor.
+
+```ts
+let observedRuntimeId: string | undefined;
+let lastCursor = 0;
+
+async function openCoderSession(sessionId: string) {
+  const observation = await runtime.sessions.observe(sessionId, (event) => {
+    if (event.seq <= lastCursor) return;
+    applyRuntimeEvent(event);
+    lastCursor = event.seq;
+  });
+
+  const { snapshot } = observation;
+  const runtimeChanged = observedRuntimeId !== undefined
+    && observedRuntimeId !== snapshot.runtimeId;
+  observedRuntimeId = snapshot.runtimeId;
+  lastCursor = snapshot.cursor;
+  replaceSessionProjection(snapshot, { runtimeChanged });
+  return observation;
+}
+```
+
+Subscribe to `runtime.connection` to freeze mutation UI immediately rather
+than waiting for a status poll:
+
+```ts
+runtime.connection?.subscribe((state) => {
+  setCoderConnectionState(state.state, state.reason);
+  if (state.state === 'disconnected' && state.reconnectable) {
+    scheduleReconnect();
+  }
+});
+```
+
+The SDK reports the current `connectionId`, `runtimeEpoch`, optional
+`journalEpoch`, disconnect reason, and whether a new connection may be
+attempted. It does not transparently replay requests or subscriptions. Space
+creates a replacement Runtime client, checks its new epochs, resumes eligible
+leases, and observes the session again.
+
+On transport failure, Runtime change, expired history, or `resync_required`,
+discard the local derived projection and call `sessions.observe()` again. Do
+not merge a new snapshot into the old projection. The handshake buffer is
+bounded; overflow fails explicitly instead of dropping events. A Runtime
+restart changes `runtimeId`, marks persisted non-terminal runs with a durable
+terminal fact, and closes old in-memory AskUser/permission requests through the
+reset boundary.
+
+### Durable mutations, stable ordering, and settings CAS
+
+Every public control mutation uses a durable operation envelope. Credential
+supply and Host Tool completion are connection-local reverse-result frames and
+are deliberately excluded from the control journal so secrets/results are not
+persisted. The SDK creates an operation ID for ordinary one-shot calls. A
+product-level retry after a lost response must reuse its own stable operation
+ID; changing its method, payload, resource, or authenticated principal is
+rejected.
+
+```ts
+const session = await runtime.sessions.create({
+  sessionId: stableSpaceSessionId,
+  title: 'Shared session',
+  surface: 'space-desktop',
+  operation: { operationId: loadOrCreatePendingOperationId('space-session-draft-7') },
+});
+
+const operationId = loadOrCreatePendingOperationId('space-run-draft-42');
+const handle = await runtime.runs.start({
+  sessionId: session.id,
+  input: { type: 'text', text: prompt },
+  options: { provider: 'anthropic' },
+  operation: { operationId },
+});
+
+const current = await runtime.sessions.getSettingsVersioned(session.id);
+const updated = await runtime.sessions.updateSettingsVersioned(
+  session.id,
+  { model: 'claude-sonnet-4-5' },
+  {
+    operationId: loadOrCreatePendingOperationId('space-settings-draft-9'),
+    expectedRevision: current.revision,
+  },
+);
+```
+
+Create retries with the same explicit session and operation IDs cannot overwrite
+an existing session. Same-session starts and after-turn inputs receive a durable `sessionOrder`.
+Retries with the same operation ID return the canonical result and do not
+create another run. Settings use compare-and-swap; a stale revision returns a
+structured conflict and must be reloaded, never silently overwritten. The
+shared settings keys are `provider`, `model`, `effort`, `thinking`,
+`reasoningMode`, `permissionMode`, `executionCwd`, `agentMode`, and
+`autoModeEngine`.
+
+```ts
+const queued = await runtime.runs.submitInput({
+  sessionId: session.id,
+  afterRunId: handle.runId,
+  delivery: 'after_turn',
+  input: { type: 'text', text: 'Also update the tests.' },
+  operation: { operationId: loadOrCreatePendingOperationId('space-input-17') },
+});
+
+if (!queued.accepted) {
+  // stale_run or unsupported_capability: show the factual result.
+}
+```
+
+Run status exposes acceptance/start/queue times, authenticated origin,
+`sessionOrder`, and a single terminal fact. Important terminal codes include
+`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
+`host_not_dispatched`, `host_outcome_unknown`, and
+`control_history_untrusted`. Respect `effectOutcome`; `unknown` must never be
+presented as success or automatically retried. After a lost response, query
+`runtime.operations.get({ operationId, journalEpoch })`; applied receipts
+include the canonical result. Permission grants remain daemon-owned and
+revisioned.
+
+### AskUser and permission from any client
+
+AskUser is no longer an in-process callback for daemon Coder runs. Any client
+with the responder scope can list the pending request and answer or dismiss it.
+The request revision and run binding prevent a stale UI from answering a new
+request. Exactly one concurrent answer is accepted.
+
+```ts
+for (const request of await runtime.userInputs.listPending({ sessionId })) {
+  const resolution = await runtime.userInputs.respond(request.id, answer, {
+    expectedRevision: request.revision,
+    runId: request.runId,
+  });
+  if (!resolution.accepted) refreshPendingInteractions();
+}
+
+for (const request of await runtime.permissions.listPending({ sessionId })) {
+  const accepted = await runtime.permissions.respond(
+    request.id,
+    { type: 'allow_once' },
+    { runId: request.runId },
+  );
+  if (!accepted) refreshPendingInteractions();
+}
+```
+
+Persistent `allow_always` grants are owned by the daemon and require
+`permission:grant-admin`. Use `permissions.listGrants()` and
+`revokeGrant(grantId, expectedRevision)` for revision-safe administration.
+Clients must not keep separate persistent permission rule stores.
+
+### Broker a Space keychain credential
+
+Credentials remain owned by Space's OS keychain. Register a broker in Electron
+Main, bind the returned lease only to runs that Space starts, and return the
+key only after checking the daemon-provided provider/session/run context.
+
+```ts
+const credentialLease = await runtime.credentials.register(
+  { providers: ['anthropic'] },
+  async ({ provider, sessionId: requestedSession, runId }) => {
+    authorizeSpaceRunCredential({ provider, sessionId: requestedSession, runId });
+    return spaceKeychain.readProviderCredential(provider);
+  },
+);
+
+const run = await runtime.runs.start({
+  sessionId,
+  input: { type: 'text', text: prompt },
+  options: { provider: 'anthropic' },
+  credential: { leaseId: credentialLease.id, provider: 'anthropic' },
+  operation: { operationId: loadOrCreatePendingOperationId('space-run-88') },
+});
+```
+
+The secret crosses only the authenticated reverse frame and an in-memory
+run/provider scope. It is excluded from events, status, logs, diagnostics,
+operation records, and Runtime persistence. While such a scope is active,
+provider mismatch fails closed and never falls back to daemon environment.
+Without a stable `instanceSecret`, registration ends when the Space connection
+closes. With it, the daemon keeps the registration owned by that stable client;
+a replacement Space process reattaches the callback with
+`runtime.credentials.resume(leaseId, broker)`. An accepted run has already
+acquired its scoped credential, so it reports `requirements.credential.state`
+as `ready` and may continue after disconnect. If the broker cannot answer, the
+start is rejected instead of accepting an indefinitely waiting run. Expiry or
+Runtime restart is explicit (`expired` or terminal); no provider request is
+automatically replayed.
+
+### Bind Space-owned Host Tools to one run
+
+Register only narrow product capabilities. Descriptors are data; handlers stay
+in Electron Main. A lease grants nothing until its ID is explicitly bound to a
+run.
+
+```ts
+const hostLease = await runtime.hostTools.register([{
+  name: 'space_artifact_create',
+  description: 'Create a Space-owned artifact for this run.',
+  inputSchema: {
+    type: 'object',
+    properties: { title: { type: 'string' } },
+    required: ['title'],
+    additionalProperties: false,
+  },
+  sideEffect: 'non_idempotent',
+}], {
+  async space_artifact_create(invocation) {
+    authorizeBoundSpaceInvocation(invocation);
+    const artifact = await createSpaceArtifact(invocation.input);
+    return { content: `Created artifact ${artifact.displayId}` };
+  },
+});
+
+await runtime.runs.start({
+  sessionId,
+  input: { type: 'text', text: 'Create the report artifact.' },
+  hostTools: { leaseId: hostLease.id },
+  operation: { operationId: loadOrCreatePendingOperationId('space-artifact-run') },
+});
+```
+
+The daemon injects session/run/lease/invocation identity; renderer, model, and
+ordinary tool input cannot choose it. CLI runs never inherit a Space lease just
+because Space later observes their session. The client memoizes one handler
+promise per invocation ID, and the daemon never replays a dispatched Host Tool.
+After a stable-client reconnect, call
+`runtime.hostTools.resume(leaseId, handlers)`. Bound run status reports
+`ready`, `waiting_host`, `expired`, or `terminal`. Disconnect or timeout after dispatch produces `host_outcome_unknown`; Space
+must reconcile the product side effect itself before offering a new user
+action. `runtime.hostTools.getInvocation(invocationId)` returns the durable
+metadata state `prepared`, `dispatched`, `completed`, `unknown`, or
+`not_dispatched`; it never returns handler input, result, or credential data.
+The daemon writes the `dispatched` marker before attempting the reverse frame
+and never auto-replays an invocation.
+
+### Coder admission, typed events, and transport-safe inputs
+
+The daemon enforces Coder session admission on the server for list/create/load,
+run, settings, delete, rewind, fork, compact, transcript, event, interaction,
+and diagnostic paths. Coder
+surfaces are `code`, `cli`, `repl`, `acp`, `a2a`, `sdk`, `ide`, and
+`space-desktop`. A session marked with
+Partner surface/profile metadata, or any unknown product surface, fails with
+typed `session_not_admitted` before mutation. Space must continue marking
+Partner sessions as `surface: 'partner'` and keep their inline storage root
+separate. Legacy sessions without a surface remain admitted for existing Coder
+compatibility, so absence of metadata is not a Partner namespace mechanism.
+
+`RuntimeEventPayloadMap` and `RuntimeTypedEvent` provide the public
+discriminated contract for known events. Existing raw listeners remain
+compatible; consumers can use `parseRuntimeEvent(value)` before exhaustive
+handling. One unknown or malformed event is diagnosed and dropped without
+closing the observation stream.
+
+Daemon clients use `RuntimeDaemonStartRunInput`. Function callbacks,
+`AbortSignal`, Extension Runtime objects, and guardrail instances are excluded
+from that type and rejected at runtime with `RuntimeTransportBoundaryError`
+and an exact value path if an untyped caller supplies them. Host-only values
+remain valid only for embedded Runtime calls.
+
+### Recovery queries and stop preflight
+
+`runtime.status.preflight()` returns connected-client count, active and queued
+runs, pending AskUser/permission records, blockers, and `canStop`. Treat this as
+a required check before stop or inline rollback; the query does not stop the
+daemon by itself. `runtime.operations.get()` reconciles durable mutations,
+`hostTools.getInvocation()` reconciles Host Tool metadata, and
+`permissions.listGrants()` returns the daemon-owned persistent grant set.
+
+Terminal notification read/unread state is intentionally client-owned in
+v0.7.69 (`durableRecoveryQueries.terminalAcknowledgement === false`): Space
+persists its own UI acknowledgement cursor against Runtime/run terminal facts.
+This avoids a false claim that one client's acknowledgement is global daemon
+truth.
+
+### Owner policy, rollback, and Electron boundary
+
+Daemon and inline Coder use one profile fence. For an emergency rollback, stop
+the daemon, switch the policy with revision CAS, then acquire the inline owner:
+
+```ts
+import {
+  acquireKodaXInlineOwner,
+  setKodaXRuntimeOwnerMode,
+} from '@kodax-ai/kodax/runtime';
+
+const policy = setKodaXRuntimeOwnerMode({
+  homeDir: kodaxHome,
+  profile: 'coder',
+  mode: 'inline',
+  expectedRevision: currentPolicyRevision,
+});
+const inlineOwner = acquireKodaXInlineOwner({ homeDir: kodaxHome, profile: 'coder' });
+```
+
+The inline policy is sticky: later CLI auto-start is rejected until an explicit
+CAS changes the policy back to `daemon`. Stale-owner handling validates the
+owned lock/state and never kills a process merely because a PID was reused.
+
+Keep all trusted objects in Electron Main: daemon token/endpoint, stable client
+identity, operation IDs, owner policy, keychain broker, Host Tool handlers, and
+permission-grant administration. Renderer IPC should expose product-specific
+commands and sanitized projections only. Never pass daemon credentials,
+leases, operation epochs, or trusted session/run context to renderer or model
+tool arguments.
+
+---
+
+## See also
 
 - [README.md](../README.md) — end-user CLI quick start
 - [docs/ADR.md ADR-024](ADR.md#adr-024-npm-发布物正名-kodax-aikodax--sdk-subpath-exports-形式化-v0739) — SDK subpath architecture rationale