@jini-ai/agent-runtime 0.3.9 → 0.4.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * @module @jini-ai/agent-runtime
  *
  * Public barrel. See `ADS-memory/reports/jini-port/extraction-plan.md` for the target
- * architecture and `source-map.md` for full provenance.
+ * architecture and `archived provenance ledger` for full provenance.
  *
  * This barrel merges two independently-ported trees:
  * - the flat `runtimes/` -> agent-runtime TypeScript source (`src/*.ts` +
@@ -14,8 +14,231 @@
  *
  * Two names are exported by both ported trees under the same identifier
  * and are aliased below to avoid a duplicate-export error; see
- * source-map.md's "Barrel merge (2026-07-18)" section for the full
+ * archived provenance ledger's "Barrel merge (2026-07-18)" section for the full
  * rationale.
+
+ * Archived provenance rationale:
+ * ### Design decisions (judgment calls)
+ *
+ * **1. The ACP subprocess transport (1744 lines) and pi-rpc transport (684 lines) are out of
+ * scope — `AcpModelProbe` is a fourth port beyond the anticipated trio + vela import.** The
+ * task brief named the coupled trio (PromptAugmenter/ArtifactTaxonomy/TelemetrySink) plus the
+ * single vela import in `detection.ts` as "the only real judgment-call work". In practice,
+ * `defs/shared.ts` also imports `detectAcpModels` from OD's top-level ACP transport module —
+ * the full ACP JSON-RPC handshake protocol (session/new, session/list_models, …), used by 8 of
+ * the 24 def literals (devin, hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe) as their
+ * `fetchModels` implementation. `r1-daemon.md` itself classifies OD's `agent-protocol/` (the
+ * ACP + pi-rpc subprocess layer, 17 files) as its OWN separate GENERIC-ENGINE extraction
+ * target, not part of `runtimes/`'s file scope — porting 2400+ lines of a distinct subsystem
+ * into this task would have blown "harvest wholesale" far past what was asked. So
+ * `detectAcpModels` becomes `AcpModelProbe` (interface + no-op default + module-level
+ * `setAcpModelProbe()` installer), mirroring the `AmrProfileResolver` pattern the brief already
+ * asked for. Every ACP-based def's `fetchModels` keeps calling `detectAcpModels(...)` unchanged
+ * (via `defs/shared.ts`'s re-export) — with the no-op probe installed, they degrade to "no live
+ * models" and fall back to `fallbackModels`, exactly like a real vela/ACP timeout would. Proven
+ * wired end-to-end in `ports.test.ts` (`setAcpModelProbe(stub)` then calling
+ * `devinAgentDef.fetchModels(...)` directly and asserting the stub was reached).
+ *
+ * **2. `env.ts` needed the same port treatment as the coupled trio, despite being listed as a
+ * "supporting generic file".** The real `runtimes/env/env.ts` reads OD's `app-config.js` (for
+ * an installation-id analytics identity env var, gated on a telemetry-consent flag), OD's
+ * `sandbox-mode.ts`, and a vela-specific profile-forwarding module, and hardcodes the origin
+ * product's own identity string as an `AMR_CLIENT_SOURCE` env value plus a product-prefixed
+ * data-dir-derived temp-home path. None of that is generic. `spawnEnvForAgent` keeps its real,
+ * generic behavior (proxy-aware merge via `@jini/platform`, OpenCode/MiMo
+ * project-config-discovery disabling, AMR's `HOME`/`VELA_OPENCODE_BIN` backfill) and gains two
+ * optional hooks — `perAgentEnv` and `sandboxOverlay` — so a host can re-attach its own
+ * vela/sandbox-specific behavior without this package needing to import OD's
+ * app-config/sandbox-mode/vela-profile modules. OD's AMR trace-env helper (a small function
+ * whose whole purpose was emitting a product-prefixed trace-correlation env triad) is dropped
+ * entirely, not ported — it is inherently OD/vela-adapter-owned and has no generic equivalent
+ * to keep.
+ *
+ * **3. `reasonix.ts`'s design-instructions constant is a real strip, not a comment reword.**
+ * Unlike every other def literal (pure declarative CLI-adapter config), OD's `reasonix.ts`
+ * injected a hardcoded system-prompt block via `env.REASONIX_ACP_SYSTEM_APPEND` that literally
+ * told the model it was running inside the host product and instructed it to wrap output in
+ * that product's own artifact-tag convention. That is genuine product-specific prompt content
+ * smuggled into what the task brief assumed was a pure literal. It is dropped; a host wanting
+ * equivalent behavior should compose it via `PromptAugmenter.systemOverlay` and merge the result
+ * into this def's `env.REASONIX_ACP_SYSTEM_APPEND` itself (the engine has no generic mechanism
+ * to know a given def has an env-based system-prompt hook — that's inherently a reasonix-specific
+ * integration detail the host must wire).
+ *
+ * **4. `registry/local-profiles.ts` (the user-configurable local-agent-profile-file loader) is
+ * deliberately not ported.** The task's own scope description for `registry.ts` names only
+ * "`BASE_AGENT_DEFS` array + dup-id guard + `getAgentDef(id)`" — it does not mention
+ * local-profile merging. The real file also turned out to be far more coupled than a
+ * "supporting generic file" would suggest: it reads a product-prefixed config-path override env
+ * var, falls back to a product-branded default path under the user's home directory, reads a
+ * product-prefixed data-dir env var, and depends on OD's daemon-level `sandbox-mode.ts`
+ * subsystem entirely outside this package's charter. Rather than either violate the explicit
+ * scope or half-port a coupled file, it's left out; `AGENT_DEFS` here is exactly
+ * `BASE_AGENT_DEFS`. Flagged as a real follow-up: a future task could reintroduce a de-branded,
+ * sandbox-free local-profile loader as an injected port (e.g. a `LocalProfileSource` interface)
+ * if a consumer needs runtime-configurable custom agent defs.
+ *
+ * **5. `amr/amr-model-probe.ts` (the other file in OD's `runtimes/amr/` subdir) is not ported;
+ * only `amr/amr-model-cache.ts` is.** `amr-model-probe.ts`'s `resolveAmrModelProbe` composes
+ * `launch`/`env`/`registry` (all in-scope) with OD's `app-config.js` (`readAppConfig`,
+ * persisted settings) and a vela-integration module's credential-revision reader (both
+ * out-of-scope OD subsystems) to build a cache key + spawn env for probing AMR's live model
+ * catalog. This is daemon-level composition glue, not a pure CLI-adapter concern, and the task
+ * brief never named `runtimes/amr/` in its explicit scope. `AmrModelLoadingCache` (the reusable
+ * generic caching *pattern*) is kept; the OD-app-config-coupled probe-composition function is
+ * not. A host wiring AMR needs to build its own equivalent of `resolveAmrModelProbe` using its
+ * own config/credential ports plus this package's `AmrModelLoadingCache` + `resolveAgentLaunch`
+ * + `spawnEnvForAgent`.
+ *
+ * **6. `chat-prompt-inputs.ts` is entirely OD-product prompt content, not partially generic —
+ * confirmed after reading the full 938-line file.** Beyond the design-system-selection
+ * functions r1b explicitly named (`resolveEffectiveDesignSystemSelection`,
+ * `designSystemIdFromPluginSnapshot`, `formatDesignFilesWorkspaceHint`), the file also contains
+ * comment-attachment rendering (OD's "attached preview comments" annotation feature), Codex
+ * image-generation prompt overrides (OD's media-generation feature), and a research-command-
+ * contract composer (OD's "research" feature) — every one of them product-specific, none of
+ * them a generic prompt-composition mechanism. Per the task's explicit instruction ("do NOT
+ * lift the OD logic itself"), none of it is ported; `PromptAugmenter` is the injection seam in
+ * full.
+ *
+ * ### Product-neutral seams (design decisions)
+ *
+ * The task brief identified four real OD coupling points to port-inject; a fifth (literal `promoted_by` strings) and a build-config note surfaced during the coverage-driven pass. Each below follows this codebase's existing DI/port convention (`packages/core/src/pack.ts`'s small explicit interfaces, `packages/daemon/archived provenance ledger`'s injected-collaborator framing) — a small named interface, a default no-op implementation, injected via caller options, not a kitchen-sink object.
+ *
+ * **1. `AccountFailureClassifier` (`acp/account-failure.ts`).** OD's `acp/updates.ts` imported `classifyAmrAccountFailure`/`amrAccountFailureDetails` directly from `../../integrations/vela-errors.js` — a real AMR/vela-branded text classifier with a hardcoded `https://open-design.ai/amr/wallet?source=open_design` recharge URL literal (read in full from `/tmp/od-source`). That URL alone makes the file impossible to port verbatim. The replacement is a two-method-shaped port (`AccountFailureClassifier.classify(text): AccountFailure | null`) with fields named generically (`code`/`message`/`action`/`actionUrl`, not AMR's field names) so any provider's classifier can satisfy it. `promotedAmrRetryStatusPayload`/`promotedAmrStderrPayload` (kept their AMR-referencing names, per the task brief's own framing of "the two call sites are `promotedAmrRetryStatusPayload(update)` and `promotedAmrStderrPayload(chunk)`" — AMR is a routing/vendor concept the task treated as out of scope to rename, unlike the literal `'open-design'` string) now take a `classifier` parameter defaulting to `noopAccountFailureClassifier` (always returns `null`). This reproduces "the feature doesn't exist" for any caller that doesn't inject a real classifier — verified by dedicated tests exercising both the no-op default and an injected matching classifier in `acp/updates.test.ts` and `acp/session.test.ts`. A future OD adapter package (not this task) would implement the real vela-backed classifier and inject it.
+ *
+ * **2. `ExecutionProfile` inlined (`acp/types.ts`).** OD's `acp/session.ts` imported `type ExecutionProfile from '@open-design/contracts'`. The real type, read from `/tmp/od-source/packages/contracts/src/execution-profile.ts`, is `export type ExecutionProfile = 'filesystem' | 'text_artifact';` plus one small helper function this port does not need (`executionProfileFromStreamFormat`, an OD-stream-format-specific mapper not used by `acp/session.ts` itself). Importing an entire external package for a two-value literal union would be the tail wagging the dog, so it's inlined as a local exported type instead.
+ *
+ * **3. Client-name / env-var de-branding.** Two literal `'open-design'`-prefixed defaults (`acp/session.ts`'s `clientName = 'open-design'` → `'agent-runtime'`; `acp/models.ts`'s `clientName = 'open-design-detect'` → `'agent-runtime-detect'`) and one hardcoded env var name (`acp/json.ts`'s `resolveAcpTimeoutMs` reading `env.OD_ACP_TIMEOUT_MS` → an optional `envVarName` parameter, default `'AGENT_RUNTIME_ACP_TIMEOUT_MS'`). All three are harmless-to-rename ACP protocol/runtime details (a handshake `clientInfo.name` value, a timeout knob), not behavior changes. **Extended beyond the task brief's explicit list**: three `promoted_by: 'open_design_acp...'` marker-string *values* (not just doc comments) found in `acp/rpc.ts` and `acp/updates.ts` during the audit — these don't match the literal grep patterns the task specified (`open-design` has a hyphen; the marker strings use an underscore, `open_design_acp`), but are clearly the same class of product-identity leak in spirit, so they were renamed too (`agent_runtime_acp`, `agent_runtime_acp_retry_status`, `agent_runtime_acp_stderr_retry_status`) and called out explicitly here rather than silently fixed.
+ *
+ * **4. `resolveAcpTimeoutMs`'s env var name.** Covered under seam 3 above; listed separately in the task brief as its own numbered item, so cross-referenced here for clarity.
+ *
+ * **5. Doc-comment / prose rewording.** "Open Design", `OD_ACP_STAGE_TIMEOUT_MS`, `OD_ACP_TIMEOUT_MS`, and `server.ts` (an OD-specific file path with no Jini equivalent) references in JSDoc/inline comments across `acp/constants.ts`, `acp/json.ts`, `acp/rpc.ts`, `acp/updates.ts`, and `acp/session.ts` were reworded to generic language (e.g., "a structured error object", "a host application may resolve its own branded environment variable"). The `text-suppression.ts` port additionally needed this treatment in its own new `@module` docblock (see next item) and one internal comment referencing this skill's coverage-discipline convention by a path that itself contains the substring `open-design` (`ADS-memory/reports/jini-port/skills/fixing-open-design.md`) — reworded to avoid the literal path.
+ *
+ * **6. `text-suppression.ts`'s two dropped dead functions.** `possibleDsmlArtifactOpenStart` and `possibleArtifactCloseStart` are declared in the origin file but never called anywhere in it (confirmed by `grep -n` across the full origin file — zero call sites, not exported). The task brief said "port this file verbatim," but keeping genuinely dead, unreachable, unexported code would force a choice between a contrived test asserting nothing real, or a coverage-suppression comment — both of which `ADS-memory/reports/jini-port/skills/fixing-open-design.md`'s Phase 6.5 explicitly rules out ("a hard-to-cover branch is a refactor signal, not something to suppress"). Dropped instead; this is the one deliberate "not quite verbatim" deviation in an otherwise byte-for-byte port of that file.
+ *
+ * **7. Four dead-branch removals in `acp/session.ts` and one in `core/json-line-stream.ts`'s `flush()`, plus three `noUncheckedIndexedAccess`-guard-to-non-null-assertion conversions across `core/json-line-stream.ts`, `pi-rpc/models.ts`, and `pi-rpc/session.ts`.** These surfaced only during the coverage-driven pass (Phase 6.5), not from the OD-coupling analysis — each is a genuinely unreachable branch given the *current* call graph, not a speculative "this could never happen" guess:
+ *    - `core/json-line-stream.ts`'s `flush()` had a defensive re-emit-and-clear on a leftover `pendingJson` candidate; proven dead because `pendingJson` is only ever retained when `classifyJsonCandidate` most recently judged it `'incomplete'`, and a 200,000-trial fuzz (random truncated valid-JSON fragments) found zero cases where `classifyJsonCandidate` says `'incomplete'` while `JSON.parse` on the identical string would actually succeed — so a bare re-attempt at end-of-stream could never succeed either.
+ *    - `core/json-line-stream.ts`'s `closeFrame` helper carried a `!current || current.kind !== kind` mismatch guard; proven dead because every one of its 4 call sites is already nested inside a branch that established the popped frame's kind, confirmed by a 2,000,000-trial adversarial fuzz (malformed bracket sequences) finding zero mismatches.
+ *    - `acp/session.ts`'s `failWithPayload` and `finishCleanPrompt` each carried their own `if (finished) return;` re-entry guard; both have call sites entirely nested inside the parser callback's own `if (aborted || finished) return;` at that callback's top, or (for the stderr-promotion call site) the stderr handler's own equivalent guard — so neither function can actually be invoked a second time once `finished` is true. **Contrast**: `fail()`'s own `if (finished) return;` guard was *kept*, because it has two call sites (`child.on('error', ...)` and `stdin.on('error', ...)`) with no pre-check of their own — genuinely reachable, and a real test (`acp/session.test.ts`) exercises it by emitting a stdin error followed by a child-process error.
+ *    - `acp/session.ts`'s parser callback had a second, inline `if (finished) return;` inside its RPC-error-handling block, fully redundant with the same callback's own top-of-function check three lines earlier (nothing between them can flip `finished`) — removed.
+ *    - `acp/session.ts`'s `emitVisibleTextDelta` carried an `if (!delta) return;` guard; all three call sites already guard against an empty delta before calling it (`if (flushedText) {...}`, `if (outputDelta) {...}`, and the plain-else branch which is only reached after an earlier `if (!toolCallStrippedDelta) return;` already ruled out emptiness).
+ *    - `pi-rpc/models.ts` (`if (line === undefined) continue;`, `if (provider === undefined || modelId === undefined) continue;`) and `pi-rpc/session.ts` (`changed[0]?.path ?? null`) each had a `noUncheckedIndexedAccess`-driven guard around an array index that the enclosing loop bound / length check already guarantees is defined — converted to a documented non-null assertion (`fixing-open-design.md` Phase 6.5's fourth classification bucket: "TS-required fallback with no real runtime path").
+ *
+ *    Every removal is accompanied by an inline comment in the source explaining the reachability proof, and none change observable behavior for any input reachable through the public API — verified by re-running the full test suite (450 tests) after each change.
+ *
+ * ## Barrel merge (2026-07-18)
+ *
+ * `packages/agent-runtime/` was independently built out from an empty stub on
+ * two separate branches: `port/agent-runtime-from-runtimes` (merged to `main`
+ * as PR #24, the "runtimes/" section above) and
+ * `port/agent-protocol-toolexecutor-daemoncore` (this PR, the
+ * "agent-protocol/" section above). Merging `main` into the latter conflicted
+ * on the shared package scaffolding (`package.json`, this file, `src/index.ts`,
+ * `tsconfig.json`, `vitest.config.ts`) since both branches independently
+ * created it — not on either side's actual ported content, which is disjoint
+ * (`src/agent-protocol/**` vs. everything else under `src/`).
+ *
+ * **`package.json`**: merged `dependencies` (`@jini/platform`, from the
+ * `runtimes/` port's `invocation.ts`/`executables.ts`/`env.ts`) and
+ * `devDependencies` (`@vitest/coverage-v8`, from the `agent-protocol/` port)
+ * into one list; kept the `runtimes/` port's `test:coverage` script.
+ *
+ * **`tsconfig.json`** / **`vitest.config.ts`**: both sides independently
+ * excluded `src/skills/**` (needed — one skill,
+ * `chat-motion-overlay`, ships a self-contained Remotion template with its own
+ * `.ts`/`.tsx` files that aren't part of this package's own compilation/test
+ * surface); only the `runtimes/` side also excluded `src/craft/**` (a no-op
+ * today since `craft/` is markdown-only, but kept for explicitness as content
+ * grows). Merged to exclude both directories in both files. `vitest.config.ts`
+ * also merged `include` (`src/**`, the broader of the two — the
+ * `agent-protocol/`-scoped `src/agent-protocol/**` from this PR was a subset)
+ * and merged the type-only-file coverage carve-outs (`src/types.ts` from the
+ * `runtimes/` port, `src/agent-protocol/acp/types.ts` from this PR) into one
+ * `exclude` list. Coverage `thresholds` differed (this PR: 99/99/99/99; the
+ * `runtimes/` port: 99.9/99.9/99.9/99.9) — set to 99 on all four metrics,
+ * matching the documented floor in `ADS-memory/reports/jini-port/skills/fixing-open-design.md`
+ * Phase 6.5 (">=99% ... 100% as the actual goal"), and verified against the
+ * actual merged coverage run (see this package's own CI/PR validation output
+ * for the authoritative merged numbers, same as the `runtimes/` section's own
+ * "Independent re-verification pass" above).
+ *
+ * **`src/index.ts`**: merged both barrels' export statements. Two real name
+ * collisions were found between the two ported trees (verified via a
+ * top-level `export (function|const|class|interface|type) <name>` scan across
+ * both trees, not just an alphabetical-ordering artifact of the merge) and
+ * resolved by aliasing rather than dropping either side:
+ *
+ * 1. **`detectAcpModels`.** This PR's `src/agent-protocol/acp/models.ts`
+ *    exports the REAL ACP subprocess transport: it spawns the CLI and performs
+ *    the actual `initialize` + `session/new` JSON-RPC handshake to fetch live
+ *    models. The `runtimes/` port's `src/acp-model-probe.ts` (see that
+ *    section's Design decision 1) *also* exports a function named
+ *    `detectAcpModels` — but it is an injectable, no-op-by-default seam
+ *    (`AcpModelProbe.detectModels`) that `defs/shared.ts` re-exports and 8 def
+ *    literals (devin, hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe) call
+ *    as their `fetchModels` implementation, because at the time that branch
+ *    was written the real ACP transport did not yet exist in this package (it
+ *    was a separate, not-yet-ported subsystem — see that section's Design
+ *    decision 1). Now that the real transport IS present, both are kept:
+ *    the plain `detectAcpModels` name is bound to the real transport (from
+ *    `agent-protocol/`, arguably the more generally useful public name for an
+ *    external consumer), and `acp-model-probe.ts`'s seam function is
+ *    re-exported as `probeAcpModels` instead. **Not touched**: `defs/shared.ts`
+ *    still imports its own `detectAcpModels` directly from
+ *    `./acp-model-probe.js` (a same-package file import, unaffected by the
+ *    barrel-level alias) — the 8 ACP-based def literals' `fetchModels` still
+ *    resolve to the no-op-by-default seam exactly as before this merge. Wiring
+ *    those defs' `fetchModels` to the real transport instead (i.e., calling
+ *    `setAcpModelProbe()` with an adapter over `agent-protocol`'s
+ *    `detectAcpModels`) is a real, valuable follow-up this merge deliberately
+ *    does not attempt — it is new integration work, not a conflict-resolution
+ *    choice, and needs its own scoped task with its own tests (the two
+ *    functions' request/response shapes are structurally similar but not
+ *    identical: `AcpModelProbeRequest`/`RuntimeModelOption` vs.
+ *    `DetectAcpModelsOptions`/`ModelOption`).
+ * 2. **`parsePiModels`.** Both ports independently lifted the identical OD
+ *    origin function (`apps/daemon/src/pi-rpc.ts#parsePiModels`, a pure
+ *    string-parsing function with no transport dependency) into two different
+ *    files: the `runtimes/` port's standalone `src/pi-models.ts` (used
+ *    internally by `defs/shared.ts` for the `pi` CLI's own model listing) and
+ *    this PR's `src/agent-protocol/pi-rpc/models.ts` (part of the
+ *    patch-mirrored `agent-protocol/` subtree, used internally by
+ *    `pi-rpc/session.ts`). Confirmed byte-for-logic-identical (same
+ *    line-parsing algorithm, same `DEFAULT_MODEL_OPTION` shape, same
+ *    dedup-by-`provider/modelId` behavior; only cosmetic differences — return
+ *    type name `PiModelOption` vs. `RuntimeModelOption`, and
+ *    non-null-assertion vs. `undefined`-check style for the
+ *    `noUncheckedIndexedAccess` guard). `pi-models.ts`'s copy keeps the plain
+ *    `parsePiModels` name (it is the one with real internal consumers reached
+ *    through this package's own barrel-adjacent re-export chain); the
+ *    `agent-protocol/pi-rpc` copy is re-exported as `parsePiRpcModels`
+ *    instead. Neither internal consumer (`defs/shared.ts`, `pi-rpc/session.ts`)
+ *    was touched — both import their own local copy by direct file path, not
+ *    through the package barrel, so the alias only affects the barrel's public
+ *    surface, not either port's internal behavior.
+ *    `src/index.test.ts` was extended (not just left as the pre-merge,
+ *    `agent-protocol/`-only assertions) to prove both aliases resolve to two
+ *    distinct, real functions (`not.toBe`) and that the two independent
+ *    `parsePiModels`/`parsePiRpcModels` ports still agree on output for the
+ *    same input, backing up the "verified byte-for-logic-identical" claim
+ *    above with an executable assertion rather than only a source-reading one.
+ *
+ * No other export names collided (`ModelOption` vs. `RuntimeModelOption`,
+ * `AttachAcpSessionOptions`, `AccountFailure`/`AccountFailureClassifier`, the
+ * 24 `*AgentDef` def-literal exports, etc. are all distinctly named across the
+ * two trees).
+ *
+ * **`packages/platform/src/index.ts`**: the two sides added disjoint modules
+ * (this PR's `home-expansion.ts`/`sandbox-env.ts`/`resource-paths.ts`/
+ * `terminal.ts`, from the "flat generic daemon primitives" part of this PR's
+ * scope, vs. `main`'s unrelated `download.ts` from a different, already-merged
+ * PR) — no name collisions; both sides' export blocks and module-doc bullet
+ * list entries were concatenated as-is.
+ *
+ * **`pnpm-lock.yaml`**: not hand-merged; `origin/main`'s version was accepted
+ * to resolve the conflict marker, then `CI=true pnpm install` was run from the
+ * repo root to regenerate it from the merged `package.json` files.
  */
 export * from './types.js';
 export * from './paths.js';
@@ -39,6 +262,7 @@ export * from './prompt-budget.js';
 export * from './prompt-file.js';
 export * from './log-file.js';
 export * from './amr-model-cache.js';
+export * from './model-catalog-cache.js';
 export * from './registry.js';
 export * from './defs/index.js';
 export * from './model-registry.js';
@@ -56,10 +280,10 @@ export * from './providers/index.js';
 /** @jini-ai/agent-runtime — public barrel (agent-protocol/ half).
  * Re-exports the agent-protocol/ capability barrel's public surface (ACP +
  * pi-rpc subprocess protocol adapters over a shared JSON-line-stream core).
- * See src/agent-protocol/README.md and source-map.md for provenance.
+ * See src/agent-protocol/README.md and archived provenance ledger for provenance.
  *
  * Two of this barrel's exports collide by name with the `runtimes/`-ported
- * modules above and are aliased here (see source-map.md's "Barrel merge"
+ * modules above and are aliased here (see archived provenance ledger's "Barrel merge"
  * section for the full reasoning):
  * - `detectAcpModels` — the REAL ACP subprocess transport (spawns the CLI,
  *   performs the `initialize` + `session/new` JSON-RPC handshake). Kept

package/dist/index.js

@@ -2,7 +2,7 @@
  * @module @jini-ai/agent-runtime
  *
  * Public barrel. See `ADS-memory/reports/jini-port/extraction-plan.md` for the target
- * architecture and `source-map.md` for full provenance.
+ * architecture and `archived provenance ledger` for full provenance.
  *
  * This barrel merges two independently-ported trees:
  * - the flat `runtimes/` -> agent-runtime TypeScript source (`src/*.ts` +
@@ -14,8 +14,231 @@
  *
  * Two names are exported by both ported trees under the same identifier
  * and are aliased below to avoid a duplicate-export error; see
- * source-map.md's "Barrel merge (2026-07-18)" section for the full
+ * archived provenance ledger's "Barrel merge (2026-07-18)" section for the full
  * rationale.
+
+ * Archived provenance rationale:
+ * ### Design decisions (judgment calls)
+ *
+ * **1. The ACP subprocess transport (1744 lines) and pi-rpc transport (684 lines) are out of
+ * scope — `AcpModelProbe` is a fourth port beyond the anticipated trio + vela import.** The
+ * task brief named the coupled trio (PromptAugmenter/ArtifactTaxonomy/TelemetrySink) plus the
+ * single vela import in `detection.ts` as "the only real judgment-call work". In practice,
+ * `defs/shared.ts` also imports `detectAcpModels` from OD's top-level ACP transport module —
+ * the full ACP JSON-RPC handshake protocol (session/new, session/list_models, …), used by 8 of
+ * the 24 def literals (devin, hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe) as their
+ * `fetchModels` implementation. `r1-daemon.md` itself classifies OD's `agent-protocol/` (the
+ * ACP + pi-rpc subprocess layer, 17 files) as its OWN separate GENERIC-ENGINE extraction
+ * target, not part of `runtimes/`'s file scope — porting 2400+ lines of a distinct subsystem
+ * into this task would have blown "harvest wholesale" far past what was asked. So
+ * `detectAcpModels` becomes `AcpModelProbe` (interface + no-op default + module-level
+ * `setAcpModelProbe()` installer), mirroring the `AmrProfileResolver` pattern the brief already
+ * asked for. Every ACP-based def's `fetchModels` keeps calling `detectAcpModels(...)` unchanged
+ * (via `defs/shared.ts`'s re-export) — with the no-op probe installed, they degrade to "no live
+ * models" and fall back to `fallbackModels`, exactly like a real vela/ACP timeout would. Proven
+ * wired end-to-end in `ports.test.ts` (`setAcpModelProbe(stub)` then calling
+ * `devinAgentDef.fetchModels(...)` directly and asserting the stub was reached).
+ *
+ * **2. `env.ts` needed the same port treatment as the coupled trio, despite being listed as a
+ * "supporting generic file".** The real `runtimes/env/env.ts` reads OD's `app-config.js` (for
+ * an installation-id analytics identity env var, gated on a telemetry-consent flag), OD's
+ * `sandbox-mode.ts`, and a vela-specific profile-forwarding module, and hardcodes the origin
+ * product's own identity string as an `AMR_CLIENT_SOURCE` env value plus a product-prefixed
+ * data-dir-derived temp-home path. None of that is generic. `spawnEnvForAgent` keeps its real,
+ * generic behavior (proxy-aware merge via `@jini/platform`, OpenCode/MiMo
+ * project-config-discovery disabling, AMR's `HOME`/`VELA_OPENCODE_BIN` backfill) and gains two
+ * optional hooks — `perAgentEnv` and `sandboxOverlay` — so a host can re-attach its own
+ * vela/sandbox-specific behavior without this package needing to import OD's
+ * app-config/sandbox-mode/vela-profile modules. OD's AMR trace-env helper (a small function
+ * whose whole purpose was emitting a product-prefixed trace-correlation env triad) is dropped
+ * entirely, not ported — it is inherently OD/vela-adapter-owned and has no generic equivalent
+ * to keep.
+ *
+ * **3. `reasonix.ts`'s design-instructions constant is a real strip, not a comment reword.**
+ * Unlike every other def literal (pure declarative CLI-adapter config), OD's `reasonix.ts`
+ * injected a hardcoded system-prompt block via `env.REASONIX_ACP_SYSTEM_APPEND` that literally
+ * told the model it was running inside the host product and instructed it to wrap output in
+ * that product's own artifact-tag convention. That is genuine product-specific prompt content
+ * smuggled into what the task brief assumed was a pure literal. It is dropped; a host wanting
+ * equivalent behavior should compose it via `PromptAugmenter.systemOverlay` and merge the result
+ * into this def's `env.REASONIX_ACP_SYSTEM_APPEND` itself (the engine has no generic mechanism
+ * to know a given def has an env-based system-prompt hook — that's inherently a reasonix-specific
+ * integration detail the host must wire).
+ *
+ * **4. `registry/local-profiles.ts` (the user-configurable local-agent-profile-file loader) is
+ * deliberately not ported.** The task's own scope description for `registry.ts` names only
+ * "`BASE_AGENT_DEFS` array + dup-id guard + `getAgentDef(id)`" — it does not mention
+ * local-profile merging. The real file also turned out to be far more coupled than a
+ * "supporting generic file" would suggest: it reads a product-prefixed config-path override env
+ * var, falls back to a product-branded default path under the user's home directory, reads a
+ * product-prefixed data-dir env var, and depends on OD's daemon-level `sandbox-mode.ts`
+ * subsystem entirely outside this package's charter. Rather than either violate the explicit
+ * scope or half-port a coupled file, it's left out; `AGENT_DEFS` here is exactly
+ * `BASE_AGENT_DEFS`. Flagged as a real follow-up: a future task could reintroduce a de-branded,
+ * sandbox-free local-profile loader as an injected port (e.g. a `LocalProfileSource` interface)
+ * if a consumer needs runtime-configurable custom agent defs.
+ *
+ * **5. `amr/amr-model-probe.ts` (the other file in OD's `runtimes/amr/` subdir) is not ported;
+ * only `amr/amr-model-cache.ts` is.** `amr-model-probe.ts`'s `resolveAmrModelProbe` composes
+ * `launch`/`env`/`registry` (all in-scope) with OD's `app-config.js` (`readAppConfig`,
+ * persisted settings) and a vela-integration module's credential-revision reader (both
+ * out-of-scope OD subsystems) to build a cache key + spawn env for probing AMR's live model
+ * catalog. This is daemon-level composition glue, not a pure CLI-adapter concern, and the task
+ * brief never named `runtimes/amr/` in its explicit scope. `AmrModelLoadingCache` (the reusable
+ * generic caching *pattern*) is kept; the OD-app-config-coupled probe-composition function is
+ * not. A host wiring AMR needs to build its own equivalent of `resolveAmrModelProbe` using its
+ * own config/credential ports plus this package's `AmrModelLoadingCache` + `resolveAgentLaunch`
+ * + `spawnEnvForAgent`.
+ *
+ * **6. `chat-prompt-inputs.ts` is entirely OD-product prompt content, not partially generic —
+ * confirmed after reading the full 938-line file.** Beyond the design-system-selection
+ * functions r1b explicitly named (`resolveEffectiveDesignSystemSelection`,
+ * `designSystemIdFromPluginSnapshot`, `formatDesignFilesWorkspaceHint`), the file also contains
+ * comment-attachment rendering (OD's "attached preview comments" annotation feature), Codex
+ * image-generation prompt overrides (OD's media-generation feature), and a research-command-
+ * contract composer (OD's "research" feature) — every one of them product-specific, none of
+ * them a generic prompt-composition mechanism. Per the task's explicit instruction ("do NOT
+ * lift the OD logic itself"), none of it is ported; `PromptAugmenter` is the injection seam in
+ * full.
+ *
+ * ### Product-neutral seams (design decisions)
+ *
+ * The task brief identified four real OD coupling points to port-inject; a fifth (literal `promoted_by` strings) and a build-config note surfaced during the coverage-driven pass. Each below follows this codebase's existing DI/port convention (`packages/core/src/pack.ts`'s small explicit interfaces, `packages/daemon/archived provenance ledger`'s injected-collaborator framing) — a small named interface, a default no-op implementation, injected via caller options, not a kitchen-sink object.
+ *
+ * **1. `AccountFailureClassifier` (`acp/account-failure.ts`).** OD's `acp/updates.ts` imported `classifyAmrAccountFailure`/`amrAccountFailureDetails` directly from `../../integrations/vela-errors.js` — a real AMR/vela-branded text classifier with a hardcoded `https://open-design.ai/amr/wallet?source=open_design` recharge URL literal (read in full from `/tmp/od-source`). That URL alone makes the file impossible to port verbatim. The replacement is a two-method-shaped port (`AccountFailureClassifier.classify(text): AccountFailure | null`) with fields named generically (`code`/`message`/`action`/`actionUrl`, not AMR's field names) so any provider's classifier can satisfy it. `promotedAmrRetryStatusPayload`/`promotedAmrStderrPayload` (kept their AMR-referencing names, per the task brief's own framing of "the two call sites are `promotedAmrRetryStatusPayload(update)` and `promotedAmrStderrPayload(chunk)`" — AMR is a routing/vendor concept the task treated as out of scope to rename, unlike the literal `'open-design'` string) now take a `classifier` parameter defaulting to `noopAccountFailureClassifier` (always returns `null`). This reproduces "the feature doesn't exist" for any caller that doesn't inject a real classifier — verified by dedicated tests exercising both the no-op default and an injected matching classifier in `acp/updates.test.ts` and `acp/session.test.ts`. A future OD adapter package (not this task) would implement the real vela-backed classifier and inject it.
+ *
+ * **2. `ExecutionProfile` inlined (`acp/types.ts`).** OD's `acp/session.ts` imported `type ExecutionProfile from '@open-design/contracts'`. The real type, read from `/tmp/od-source/packages/contracts/src/execution-profile.ts`, is `export type ExecutionProfile = 'filesystem' | 'text_artifact';` plus one small helper function this port does not need (`executionProfileFromStreamFormat`, an OD-stream-format-specific mapper not used by `acp/session.ts` itself). Importing an entire external package for a two-value literal union would be the tail wagging the dog, so it's inlined as a local exported type instead.
+ *
+ * **3. Client-name / env-var de-branding.** Two literal `'open-design'`-prefixed defaults (`acp/session.ts`'s `clientName = 'open-design'` → `'agent-runtime'`; `acp/models.ts`'s `clientName = 'open-design-detect'` → `'agent-runtime-detect'`) and one hardcoded env var name (`acp/json.ts`'s `resolveAcpTimeoutMs` reading `env.OD_ACP_TIMEOUT_MS` → an optional `envVarName` parameter, default `'AGENT_RUNTIME_ACP_TIMEOUT_MS'`). All three are harmless-to-rename ACP protocol/runtime details (a handshake `clientInfo.name` value, a timeout knob), not behavior changes. **Extended beyond the task brief's explicit list**: three `promoted_by: 'open_design_acp...'` marker-string *values* (not just doc comments) found in `acp/rpc.ts` and `acp/updates.ts` during the audit — these don't match the literal grep patterns the task specified (`open-design` has a hyphen; the marker strings use an underscore, `open_design_acp`), but are clearly the same class of product-identity leak in spirit, so they were renamed too (`agent_runtime_acp`, `agent_runtime_acp_retry_status`, `agent_runtime_acp_stderr_retry_status`) and called out explicitly here rather than silently fixed.
+ *
+ * **4. `resolveAcpTimeoutMs`'s env var name.** Covered under seam 3 above; listed separately in the task brief as its own numbered item, so cross-referenced here for clarity.
+ *
+ * **5. Doc-comment / prose rewording.** "Open Design", `OD_ACP_STAGE_TIMEOUT_MS`, `OD_ACP_TIMEOUT_MS`, and `server.ts` (an OD-specific file path with no Jini equivalent) references in JSDoc/inline comments across `acp/constants.ts`, `acp/json.ts`, `acp/rpc.ts`, `acp/updates.ts`, and `acp/session.ts` were reworded to generic language (e.g., "a structured error object", "a host application may resolve its own branded environment variable"). The `text-suppression.ts` port additionally needed this treatment in its own new `@module` docblock (see next item) and one internal comment referencing this skill's coverage-discipline convention by a path that itself contains the substring `open-design` (`ADS-memory/reports/jini-port/skills/fixing-open-design.md`) — reworded to avoid the literal path.
+ *
+ * **6. `text-suppression.ts`'s two dropped dead functions.** `possibleDsmlArtifactOpenStart` and `possibleArtifactCloseStart` are declared in the origin file but never called anywhere in it (confirmed by `grep -n` across the full origin file — zero call sites, not exported). The task brief said "port this file verbatim," but keeping genuinely dead, unreachable, unexported code would force a choice between a contrived test asserting nothing real, or a coverage-suppression comment — both of which `ADS-memory/reports/jini-port/skills/fixing-open-design.md`'s Phase 6.5 explicitly rules out ("a hard-to-cover branch is a refactor signal, not something to suppress"). Dropped instead; this is the one deliberate "not quite verbatim" deviation in an otherwise byte-for-byte port of that file.
+ *
+ * **7. Four dead-branch removals in `acp/session.ts` and one in `core/json-line-stream.ts`'s `flush()`, plus three `noUncheckedIndexedAccess`-guard-to-non-null-assertion conversions across `core/json-line-stream.ts`, `pi-rpc/models.ts`, and `pi-rpc/session.ts`.** These surfaced only during the coverage-driven pass (Phase 6.5), not from the OD-coupling analysis — each is a genuinely unreachable branch given the *current* call graph, not a speculative "this could never happen" guess:
+ *    - `core/json-line-stream.ts`'s `flush()` had a defensive re-emit-and-clear on a leftover `pendingJson` candidate; proven dead because `pendingJson` is only ever retained when `classifyJsonCandidate` most recently judged it `'incomplete'`, and a 200,000-trial fuzz (random truncated valid-JSON fragments) found zero cases where `classifyJsonCandidate` says `'incomplete'` while `JSON.parse` on the identical string would actually succeed — so a bare re-attempt at end-of-stream could never succeed either.
+ *    - `core/json-line-stream.ts`'s `closeFrame` helper carried a `!current || current.kind !== kind` mismatch guard; proven dead because every one of its 4 call sites is already nested inside a branch that established the popped frame's kind, confirmed by a 2,000,000-trial adversarial fuzz (malformed bracket sequences) finding zero mismatches.
+ *    - `acp/session.ts`'s `failWithPayload` and `finishCleanPrompt` each carried their own `if (finished) return;` re-entry guard; both have call sites entirely nested inside the parser callback's own `if (aborted || finished) return;` at that callback's top, or (for the stderr-promotion call site) the stderr handler's own equivalent guard — so neither function can actually be invoked a second time once `finished` is true. **Contrast**: `fail()`'s own `if (finished) return;` guard was *kept*, because it has two call sites (`child.on('error', ...)` and `stdin.on('error', ...)`) with no pre-check of their own — genuinely reachable, and a real test (`acp/session.test.ts`) exercises it by emitting a stdin error followed by a child-process error.
+ *    - `acp/session.ts`'s parser callback had a second, inline `if (finished) return;` inside its RPC-error-handling block, fully redundant with the same callback's own top-of-function check three lines earlier (nothing between them can flip `finished`) — removed.
+ *    - `acp/session.ts`'s `emitVisibleTextDelta` carried an `if (!delta) return;` guard; all three call sites already guard against an empty delta before calling it (`if (flushedText) {...}`, `if (outputDelta) {...}`, and the plain-else branch which is only reached after an earlier `if (!toolCallStrippedDelta) return;` already ruled out emptiness).
+ *    - `pi-rpc/models.ts` (`if (line === undefined) continue;`, `if (provider === undefined || modelId === undefined) continue;`) and `pi-rpc/session.ts` (`changed[0]?.path ?? null`) each had a `noUncheckedIndexedAccess`-driven guard around an array index that the enclosing loop bound / length check already guarantees is defined — converted to a documented non-null assertion (`fixing-open-design.md` Phase 6.5's fourth classification bucket: "TS-required fallback with no real runtime path").
+ *
+ *    Every removal is accompanied by an inline comment in the source explaining the reachability proof, and none change observable behavior for any input reachable through the public API — verified by re-running the full test suite (450 tests) after each change.
+ *
+ * ## Barrel merge (2026-07-18)
+ *
+ * `packages/agent-runtime/` was independently built out from an empty stub on
+ * two separate branches: `port/agent-runtime-from-runtimes` (merged to `main`
+ * as PR #24, the "runtimes/" section above) and
+ * `port/agent-protocol-toolexecutor-daemoncore` (this PR, the
+ * "agent-protocol/" section above). Merging `main` into the latter conflicted
+ * on the shared package scaffolding (`package.json`, this file, `src/index.ts`,
+ * `tsconfig.json`, `vitest.config.ts`) since both branches independently
+ * created it — not on either side's actual ported content, which is disjoint
+ * (`src/agent-protocol/**` vs. everything else under `src/`).
+ *
+ * **`package.json`**: merged `dependencies` (`@jini/platform`, from the
+ * `runtimes/` port's `invocation.ts`/`executables.ts`/`env.ts`) and
+ * `devDependencies` (`@vitest/coverage-v8`, from the `agent-protocol/` port)
+ * into one list; kept the `runtimes/` port's `test:coverage` script.
+ *
+ * **`tsconfig.json`** / **`vitest.config.ts`**: both sides independently
+ * excluded `src/skills/**` (needed — one skill,
+ * `chat-motion-overlay`, ships a self-contained Remotion template with its own
+ * `.ts`/`.tsx` files that aren't part of this package's own compilation/test
+ * surface); only the `runtimes/` side also excluded `src/craft/**` (a no-op
+ * today since `craft/` is markdown-only, but kept for explicitness as content
+ * grows). Merged to exclude both directories in both files. `vitest.config.ts`
+ * also merged `include` (`src/**`, the broader of the two — the
+ * `agent-protocol/`-scoped `src/agent-protocol/**` from this PR was a subset)
+ * and merged the type-only-file coverage carve-outs (`src/types.ts` from the
+ * `runtimes/` port, `src/agent-protocol/acp/types.ts` from this PR) into one
+ * `exclude` list. Coverage `thresholds` differed (this PR: 99/99/99/99; the
+ * `runtimes/` port: 99.9/99.9/99.9/99.9) — set to 99 on all four metrics,
+ * matching the documented floor in `ADS-memory/reports/jini-port/skills/fixing-open-design.md`
+ * Phase 6.5 (">=99% ... 100% as the actual goal"), and verified against the
+ * actual merged coverage run (see this package's own CI/PR validation output
+ * for the authoritative merged numbers, same as the `runtimes/` section's own
+ * "Independent re-verification pass" above).
+ *
+ * **`src/index.ts`**: merged both barrels' export statements. Two real name
+ * collisions were found between the two ported trees (verified via a
+ * top-level `export (function|const|class|interface|type) <name>` scan across
+ * both trees, not just an alphabetical-ordering artifact of the merge) and
+ * resolved by aliasing rather than dropping either side:
+ *
+ * 1. **`detectAcpModels`.** This PR's `src/agent-protocol/acp/models.ts`
+ *    exports the REAL ACP subprocess transport: it spawns the CLI and performs
+ *    the actual `initialize` + `session/new` JSON-RPC handshake to fetch live
+ *    models. The `runtimes/` port's `src/acp-model-probe.ts` (see that
+ *    section's Design decision 1) *also* exports a function named
+ *    `detectAcpModels` — but it is an injectable, no-op-by-default seam
+ *    (`AcpModelProbe.detectModels`) that `defs/shared.ts` re-exports and 8 def
+ *    literals (devin, hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe) call
+ *    as their `fetchModels` implementation, because at the time that branch
+ *    was written the real ACP transport did not yet exist in this package (it
+ *    was a separate, not-yet-ported subsystem — see that section's Design
+ *    decision 1). Now that the real transport IS present, both are kept:
+ *    the plain `detectAcpModels` name is bound to the real transport (from
+ *    `agent-protocol/`, arguably the more generally useful public name for an
+ *    external consumer), and `acp-model-probe.ts`'s seam function is
+ *    re-exported as `probeAcpModels` instead. **Not touched**: `defs/shared.ts`
+ *    still imports its own `detectAcpModels` directly from
+ *    `./acp-model-probe.js` (a same-package file import, unaffected by the
+ *    barrel-level alias) — the 8 ACP-based def literals' `fetchModels` still
+ *    resolve to the no-op-by-default seam exactly as before this merge. Wiring
+ *    those defs' `fetchModels` to the real transport instead (i.e., calling
+ *    `setAcpModelProbe()` with an adapter over `agent-protocol`'s
+ *    `detectAcpModels`) is a real, valuable follow-up this merge deliberately
+ *    does not attempt — it is new integration work, not a conflict-resolution
+ *    choice, and needs its own scoped task with its own tests (the two
+ *    functions' request/response shapes are structurally similar but not
+ *    identical: `AcpModelProbeRequest`/`RuntimeModelOption` vs.
+ *    `DetectAcpModelsOptions`/`ModelOption`).
+ * 2. **`parsePiModels`.** Both ports independently lifted the identical OD
+ *    origin function (`apps/daemon/src/pi-rpc.ts#parsePiModels`, a pure
+ *    string-parsing function with no transport dependency) into two different
+ *    files: the `runtimes/` port's standalone `src/pi-models.ts` (used
+ *    internally by `defs/shared.ts` for the `pi` CLI's own model listing) and
+ *    this PR's `src/agent-protocol/pi-rpc/models.ts` (part of the
+ *    patch-mirrored `agent-protocol/` subtree, used internally by
+ *    `pi-rpc/session.ts`). Confirmed byte-for-logic-identical (same
+ *    line-parsing algorithm, same `DEFAULT_MODEL_OPTION` shape, same
+ *    dedup-by-`provider/modelId` behavior; only cosmetic differences — return
+ *    type name `PiModelOption` vs. `RuntimeModelOption`, and
+ *    non-null-assertion vs. `undefined`-check style for the
+ *    `noUncheckedIndexedAccess` guard). `pi-models.ts`'s copy keeps the plain
+ *    `parsePiModels` name (it is the one with real internal consumers reached
+ *    through this package's own barrel-adjacent re-export chain); the
+ *    `agent-protocol/pi-rpc` copy is re-exported as `parsePiRpcModels`
+ *    instead. Neither internal consumer (`defs/shared.ts`, `pi-rpc/session.ts`)
+ *    was touched — both import their own local copy by direct file path, not
+ *    through the package barrel, so the alias only affects the barrel's public
+ *    surface, not either port's internal behavior.
+ *    `src/index.test.ts` was extended (not just left as the pre-merge,
+ *    `agent-protocol/`-only assertions) to prove both aliases resolve to two
+ *    distinct, real functions (`not.toBe`) and that the two independent
+ *    `parsePiModels`/`parsePiRpcModels` ports still agree on output for the
+ *    same input, backing up the "verified byte-for-logic-identical" claim
+ *    above with an executable assertion rather than only a source-reading one.
+ *
+ * No other export names collided (`ModelOption` vs. `RuntimeModelOption`,
+ * `AttachAcpSessionOptions`, `AccountFailure`/`AccountFailureClassifier`, the
+ * 24 `*AgentDef` def-literal exports, etc. are all distinctly named across the
+ * two trees).
+ *
+ * **`packages/platform/src/index.ts`**: the two sides added disjoint modules
+ * (this PR's `home-expansion.ts`/`sandbox-env.ts`/`resource-paths.ts`/
+ * `terminal.ts`, from the "flat generic daemon primitives" part of this PR's
+ * scope, vs. `main`'s unrelated `download.ts` from a different, already-merged
+ * PR) — no name collisions; both sides' export blocks and module-doc bullet
+ * list entries were concatenated as-is.
+ *
+ * **`pnpm-lock.yaml`**: not hand-merged; `origin/main`'s version was accepted
+ * to resolve the conflict marker, then `CI=true pnpm install` was run from the
+ * repo root to regenerate it from the merged `package.json` files.
  */
 // Core contract + vendored diagnostic types.
 export * from './types.js';
@@ -41,6 +264,7 @@ export * from './prompt-budget.js';
 export * from './prompt-file.js';
 export * from './log-file.js';
 export * from './amr-model-cache.js';
+export * from './model-catalog-cache.js';
 // Registry + defs.
 export * from './registry.js';
 export * from './defs/index.js';
@@ -54,7 +278,7 @@ export * from './defs/index.js';
 // from `./types.js` rather than redefining a second, looser copy; its own
 // `ModelOption` is exported here as `ModelCatalogOption` since the plain
 // `ModelOption` name is already owned by `agent-protocol/acp/models.ts`'s
-// narrower ACP-probe shape re-exported below. See source-map.md.
+// narrower ACP-probe shape re-exported below. See archived provenance ledger.
 export * from './model-registry.js';
 // Stream parsers. Each handler's event union is exported alongside it — previously only
 // `Record<string, unknown>` was visible to a consumer outside this package, which is how a real
@@ -74,7 +298,7 @@ export * from './amr-profile-resolver.js';
 // is a no-op-by-default injectable seam (used internally by
 // `defs/shared.ts` for 8 ACP-based def literals so they don't need to
 // depend on the full ACP transport) — aliased to `probeAcpModels` here so
-// the real transport keeps the plain name. See source-map.md.
+// the real transport keeps the plain name. See archived provenance ledger.
 export { noopAcpModelProbe, setAcpModelProbe, detectAcpModels as probeAcpModels, } from './acp-model-probe.js';
 // `parsePiModels` is exported under its plain name from this standalone
 // module (it has real internal consumers in this package: `defs/shared.ts`
@@ -90,10 +314,10 @@ export * from './providers/index.js';
 /** @jini-ai/agent-runtime — public barrel (agent-protocol/ half).
  * Re-exports the agent-protocol/ capability barrel's public surface (ACP +
  * pi-rpc subprocess protocol adapters over a shared JSON-line-stream core).
- * See src/agent-protocol/README.md and source-map.md for provenance.
+ * See src/agent-protocol/README.md and archived provenance ledger for provenance.
  *
  * Two of this barrel's exports collide by name with the `runtimes/`-ported
- * modules above and are aliased here (see source-map.md's "Barrel merge"
+ * modules above and are aliased here (see archived provenance ledger's "Barrel merge"
  * section for the full reasoning):
  * - `detectAcpModels` — the REAL ACP subprocess transport (spawns the CLI,
  *   performs the `initialize` + `session/new` JSON-RPC handshake). Kept

package/dist/invocation.d.ts

@@ -1,5 +1,10 @@
 import type { RuntimeExecOptions } from './types.js';
-export declare function execAgentFile(command: string, args: string[], options?: RuntimeExecOptions): import("child_process").PromiseWithChild<{
+export declare function execAgentFile({ command, args }: {
+    command: string;
+    args: string[];
+}, { options }?: {
+    options?: RuntimeExecOptions;
+}): import("child_process").PromiseWithChild<{
     stdout: string | NonSharedBuffer;
     stderr: string | NonSharedBuffer;
 }>;

package/dist/invocation.js

@@ -7,7 +7,7 @@
  * `createCommandInvocation` now comes from `@jini-ai/platform` instead of the
  * OD workspace package it originally shipped from — the two are the same
  * function (platform was already verbatim-lifted into `@jini-ai/platform`,
- * see its `source-map.md`).
+ * see its `archived provenance ledger`).
  */
 import { execFile } from 'node:child_process';
 import os from 'node:os';
@@ -27,7 +27,7 @@ const execFileP = promisify(execFile);
 // running dev server. A probe writing a stray lockfile under the OS temp
 // dir is harmless. Actual agent runs spawn elsewhere with an explicit
 // project cwd and are unaffected.
-export function execAgentFile(command, args, options = {}) {
+export function execAgentFile({ command, args }, { options = {} } = {}) {
     const invocation = createCommandInvocation(options.env
         ? {
             command,

package/dist/json-event-stream.d.ts

@@ -1,8 +1,13 @@
 type StreamEvent = Record<string, unknown>;
 type StreamEventHandler = (event: StreamEvent) => void;
 type ParserKind = string;
-export declare function createJsonEventStreamHandler(kind: ParserKind, onEvent: StreamEventHandler): {
-    feed: (chunk: string) => void;
+export declare function createJsonEventStreamHandler({ kind, onEvent }: {
+    kind: ParserKind;
+    onEvent: StreamEventHandler;
+}): {
+    feed: ({ chunk }: {
+        chunk: string;
+    }) => void;
     flush: () => void;
 };
 export {};