@jini-ai/agent-runtime 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# @jini-ai/agent-runtime
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Use isolated provider and cache subpaths, including ./providers/sse-decode for browsers; core clock/redaction and canonical platform address classifiers replace local contracts. Unloaded bundled skill/craft documents are archived outside the package.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+### Fixes
+
+- Align parser parity and default-option fixtures with current argument objects and exact optional-property contracts. Preserve manifest fixture tuples and type Google continuation mocks with checked request bodies for strict indexed access.
+- Omit the probe environment's absent proxy override so the existing system-proxy default remains active.
+
+### BREAKING — canonical OAuth, redaction and network primitives
+
+- Provider PKCE uses the main OAuth API, explicitly retaining 64-byte verifier entropy; normalized tokens are adapted to the existing persisted provider wire DTO. Main OAuth now guards/bounds fixed-issuer HTTP and returns typed errors; deriveCodeChallenge validates RFC verifiers.
+- Remove runtime classifier/redactor exports and local implementations. Import hostname policies from `@jini-ai/platform/net` and `redactSecrets({ input }, { exactSecrets })` from core. Conservative masking keeps model/request identifiers and uses categorized markers; diagnostics never opt into opaque-run masking.
+- Model catalog clocks use core `Clock.nowMs()`; ACP unknown-value records are named `UnknownRecord`, not JSON objects.
+- Callback payload caches use the main bounded store while retaining exclusive TTL and unref timer behavior. Neutralize host-settings wording and host identity comments. Drop the conversion report from published files; the document remains for later relocation.
+
+
+- Preserve host environment customization after CLI housekeeping; correct the hook documentation.
+- Keep DNS resolver injection required and reject lookup failures or empty answers instead of allowing unpinned fallback.
+- Validate model catalogue variants with an explicit `TypeError` before trimming.
+- Tag ACP failures before resume acknowledgement with `error.details.kind: 'resume_failed'`, preserving original codes and nesting original details under `cause`.
+
+- Add `./providers/tool-turn` with injected provider adapters, normalized tool results and termination reasons, and Gemini schema adaptation. Existing provider loops and exports are preserved.
+- Add `./model-catalog/cache` for instance-owned live discovery, TTL success/failure caching, tenant-safe key tuples, and injected clock/merge ports. Share the single-flight loader with the existing AMR cache.
+- Complete the runtime subpaths (`./providers/tool-turn`, `./model-catalog/cache`, and `./providers/sse-decode`) with runtime metadata, declaration mappings, root barrel exports for turns/cache, and API documentation. The cache and SSE decoder can be imported independently in universal runtimes; the provider adapters and root require Node.
+- Delegate provider PKCE and pending authorization primitives to `@jini-ai/oauth`, retaining provider contracts and wire formats.
+- **BREAKING:** Convert existing public runtime/provider helpers, session factories, cache constructors and methods, runtime-definition callbacks, custom DNS/HTTP/event ports, and stream-feed methods to `(requiredArgs, optionalArgs)` objects. Required inputs are in the first object; optional controls are in the second. Update hosts and port implementations together using `API-CONVERSION-w7.md`. Existing export names and package version are retained; no positional compatibility adapters are provided. React props and upstream standard-library callable contracts are unchanged.
+- **BREAKING:** `AcpModelProbe.detectModels` now separates required `{ bin, args }` from optional probe controls, matching `detectAcpModels` and its `probeAcpModels` alias. Custom probes must read environment, timeout, client identity and default model from the second object.
+
+## 0.2.1
+
+### Patch Changes
+
+- Add top-level `main`/`types` fields alongside the existing `exports` map. A consumer on
+  TypeScript's classic `moduleResolution: "node"` (node10) — which ignores `package.json#exports`
+  entirely — could not resolve this package's types at all (`TS2307: Cannot find module`) even
+  after the previous exports-map fix restored `require()` at runtime; type resolution and runtime
+  resolution are separate algorithms. Verified against a real external consumer (whose
+  tsconfig uses this legacy resolution mode): adding these two fields, with its tsconfig completely
+  unchanged, made the error disappear. Also fixes absolute-path `require()` (distinct from a bare
+  specifier, which already worked) for the same reason — `main` was previously absent.
+
+  Purely additive: every modern resolver (Node's own runtime `exports` resolution, TypeScript's
+  `bundler`/`node16`/`nodenext`) prefers `exports` over `main`/`types` when both are present, so
+  this changes nothing for a consumer already on a modern resolver.
+
+- Updated dependencies
+  - @jini-ai/platform@0.1.2
+
+## 0.2.0
+
+### Minor Changes
+
+- Add a `"default"` export condition to every published package's `exports` map — every one of
+  them lacked it, which meant `require()` failed with `ERR_PACKAGE_PATH_NOT_EXPORTED` for any
+  CommonJS consumer (found via a real external integration attempt; Node needs `require(esm)`
+  support, i.e. Node >=22.12, for this to resolve).
+
+  `@jini-ai/agent-runtime`:
+
+  - **New**: `RuntimeBuildOptions.permissionMode` (`'bypass' | 'restricted'`) lets a caller opt a
+    run OUT of the auto-approve-every-permission-prompt flag every def with one
+    (`bypassPermissions` / `--yolo` / `--dangerously-skip-permissions`) previously pushed
+    unconditionally, with no way to turn it off. Omitting it keeps today's default (bypass)
+    behavior unchanged.
+  - **New**: `ClaudeStreamEvent`, `CopilotStreamEvent`, and `QoderEvent` are now real exported
+    discriminated unions instead of `Record<string, unknown>` — a real external consumer guessed a
+    nonexistent field name (`event.text` instead of the actual `event.delta`) against the old
+    untyped sink and silently lost every streamed token with no compile or runtime error.
+  - Fixed a doc/implementation mismatch in `claude-stream.ts`: the module doc claimed `tool_result`
+    events carry `{ tool_use_id, content, is_error }`; the actual emitted shape is
+    `{ toolUseId, content, isError }`.
+
+  `@jini-ai/daemon`: `AgentExecutorRunInput.permissionMode` forwards the new
+  `RuntimeBuildOptions.permissionMode` through to `buildArgs`, so a host can actually reach the new
+  opt-out from the daemon's real run-input surface, not just from `@jini-ai/agent-runtime` in
+  isolation.
+
+  `@jini-ai/agentic`: `setAtPointer` no longer throws on a malformed (e.g. missing leading `/`)
+  `updateDataModel` path — degrades to a no-op like its sibling `getAtPointer`, matching this
+  package's own "a bad binding must not crash the renderer" contract. That path is agent-authored
+  wire data with no error boundary above it in any host, so the uncaught throw could unmount an
+  entire chat UI from ~40 bytes of malformed input.
+
+  `@jini-ai/chat-react`: a local (client-resolved) A2UI button action is no longer a silent no-op —
+  `A2uiSurfaceCard` now surfaces the resolved value. New `ExtEventErrorBoundary` confines a
+  `kind: 'ext'` event group's renderer to its own card instead of letting a render/effect-phase
+  throw from agent-controlled content unmount the whole chat root (there was no error boundary
+  anywhere in this package or its hosts before this).
+
+- 0d15314: Add a neutral Composer footer slot for host-owned controls, forward an optional host-selected model through every AgentExecutor runtime transport, expose daemon-owned live agent/model discovery with an explicit rescan route, and recognize Claude Code's partial-stream `message_delta` turn boundary so successful stream-json runs close cleanly.
+
+### Patch Changes
+
+- Updated dependencies
+  - @jini-ai/platform@0.1.1

package/README.md

@@ -5,10 +5,10 @@ generation: brand-agnostic craft knowledge and portable skill packages
 (both product-neutral per root `AGENTS.md`) plus a real TypeScript runtime
 surface — the `runtimes/` -> agent-runtime adapter registry/detection/
 launch/stream-parser port and the `agent-protocol/` ACP + pi-rpc subprocess
-transport (see `src/index.ts`'s own header comment and `source-map.md`'s
+transport (see `src/index.ts`'s own header comment and the archived provenance ledger's
 "Barrel merge" section for the full inventory), plus `src/model-registry.ts`
 below. This top-level blurb has historically lagged that TS surface's
-growth — treat `src/index.ts` and `source-map.md` as the source of truth
+growth — treat `src/index.ts` and the archived provenance ledger as the source of truth
 for what's actually implemented.
 
 ## `src/model-registry.ts`
@@ -22,22 +22,39 @@ model-catalogue cache key, model-choice normalization against a live
 catalogue) for any consumer building a "pick a model/agent" UI — e.g.
 `@jini-ai/chat-react`'s `features/model-picker/` slice. Distinct from
 `src/registry.ts` (the static `BASE_AGENT_DEFS` CLI-adapter catalog). See
-`source-map.md` for full provenance.
+the archived provenance ledger for full provenance.
 
-## `src/craft/`
+## Archived craft and skill content
 
-Universal UI-craft rulebooks (typography, color, motion, accessibility,
-forms, RTL, anti-AI-slop, …) that a skill can opt into via a
-`craft.requires` front-matter array. See `src/craft/README.md` for the
-full mechanism and `source-map.md` for provenance.
+The former craft rulebooks and portable skill documents are archived with the extraction records. No runtime loader or build asset-copy step reads them, so they are outside this package's distributable surface. Source execution code and provider/cache APIs remain described below.
 
-## `src/skills/`
+## Runtime APIs and subpaths
 
-160 portable Skill packages ported from OD's 162-skill catalog (2 excluded
-as OD-internal — see `source-map.md`), each a `SKILL.md` + optional
-`assets/`/`scripts/`/`references/`. Frontmatter uses the same flat
-`craft.requires`/`design_system.requires`/`mode`/etc. key convention as
-`src/craft/`, not OD's original nested `od:` block. No TypeScript lives
-inside `src/skills/` itself — this directory is content only; the
-package's TypeScript runtime surface lives at `src/`'s top level, see
-above.
+Public functions, constructors, stream methods and custom ports use at most two
+argument objects: required inputs first, optional controls second. Existing
+names are retained, but positional callers must migrate together with their
+port implementations. See [API.md](https://github.com/AINSEP/Jini/blob/main/packages/agent-runtime/API.md) for current examples and
+[API.md](https://github.com/AINSEP/Jini/blob/main/packages/agent-runtime/API.md) for the current public contracts.
+
+Omit optional properties to use their defaults; exact optional-property types
+exclude explicitly assigned `undefined`. Model parsers accept `{ stdout }`.
+
+| Import | Runtime | Surface |
+| --- | --- | --- |
+| `@jini-ai/agent-runtime` | Node | CLI registry, launch/detection, protocols, providers, tool turns and caches |
+| `@jini-ai/agent-runtime/providers/tool-turn` | Node | Provider-neutral tool turns, replaceable adapters, Gemini schema helpers |
+| `@jini-ai/agent-runtime/model-catalog/cache` | Universal | Instance-owned discovery cache and model union |
+| `@jini-ai/agent-runtime/providers/sse-decode` | Universal | Inbound SSE frame decoder over an async iterable |
+
+Browser consumers import the universal subpaths directly. The package root and
+provider adapters load Node modules. Provider PKCE adapters delegate protocol
+operations to `@jini-ai/oauth`; the host still owns endpoint policy, credentials,
+callback handling and persistence. None of these entries selects a site layout.
+
+## Design decisions
+
+- [Provider adapters preserve native continuation and tool events](docs/decisions/DR-001-provider-native-tool-lifecycle.md).
+
+Provider network predicates now live in `@jini-ai/platform/net`; secret redaction lives in `@jini-ai/core` and takes `{ input }` with `{ exactSecrets }`. Runtime no longer re-exports those utilities. Core's conservative policy retains model/request identifiers and returns categorized redaction markers. Model catalog hosts pass core `Clock` (`nowMs()`); ACP transport values use `UnknownRecord` to avoid claiming validated JSON.
+
+PKCE providers pass `{ verifierBytes: 64 }` to the main OAuth API. Fixed-issuer token operations use its URL guard, bounded parser, timeout, redirect refusal and typed errors; the runtime maps normalized tokens into its existing persisted provider DTO. Pending callbacks use the main storage factory with an explicit exclusive expiry option and an unref scheduler. The cache is bounded to the main 256-entry default. The conversion report remains in the repository for relocation and is excluded from package files.

package/dist/acp-model-probe.d.ts

@@ -15,7 +15,7 @@
  * separate subsystem.
  *
  * So `detectAcpModels` becomes an injectable port: an `AcpModelProbe` with
- * a single `detectModels(request)` method, matching the real call shape
+ * a single `detectModels(requiredArgs, optionalArgs)` method, matching the real call shape
  * every ACP-based def literal already uses. The default implementation is
  * a no-op that resolves to `[]`, which makes `detection.ts`'s `fetchModels`
  * step treat the live-fetch as "returned nothing" and fall back to the
@@ -38,11 +38,13 @@ export interface AcpModelProbeRequest {
     defaultModelOption?: RuntimeModelOption;
 }
 export interface AcpModelProbe {
-    detectModels(request: AcpModelProbeRequest): Promise<RuntimeModelOption[]>;
+    detectModels(requiredArgs: Pick<AcpModelProbeRequest, 'bin' | 'args'>, optionalArgs?: Omit<AcpModelProbeRequest, 'bin' | 'args'>): Promise<RuntimeModelOption[]>;
 }
 export declare const noopAcpModelProbe: AcpModelProbe;
 /** Install the real ACP transport (or a test double). Pass `null` to restore the no-op default. */
-export declare function setAcpModelProbe(probe: AcpModelProbe | null): void;
+export declare function setAcpModelProbe({ probe }: {
+    probe: AcpModelProbe | null;
+}): void;
 /** Drop-in replacement for OD's `detectAcpModels` — delegates to whatever probe is currently installed. */
-export declare function detectAcpModels(request: AcpModelProbeRequest): Promise<RuntimeModelOption[]>;
+export declare function detectAcpModels(requiredArgs: Pick<AcpModelProbeRequest, "bin" | "args">, optionalArgs?: Omit<AcpModelProbeRequest, "bin" | "args">): Promise<RuntimeModelOption[]>;
 //# sourceMappingURL=acp-model-probe.d.ts.map

package/dist/acp-model-probe.js

@@ -5,11 +5,11 @@ export const noopAcpModelProbe = {
 };
 let activeAcpModelProbe = noopAcpModelProbe;
 /** Install the real ACP transport (or a test double). Pass `null` to restore the no-op default. */
-export function setAcpModelProbe(probe) {
+export function setAcpModelProbe({ probe }) {
     activeAcpModelProbe = probe ?? noopAcpModelProbe;
 }
 /** Drop-in replacement for OD's `detectAcpModels` — delegates to whatever probe is currently installed. */
-export async function detectAcpModels(request) {
-    return activeAcpModelProbe.detectModels(request);
+export async function detectAcpModels(requiredArgs, optionalArgs = {}) {
+    return activeAcpModelProbe.detectModels(requiredArgs, optionalArgs);
 }
 //# sourceMappingURL=acp-model-probe.js.map

package/dist/agent-protocol/acp/account-failure.d.ts

@@ -4,7 +4,7 @@
  * actionable error. OD's real implementation classifies vela/AMR-branded
  * failure text against a hardcoded, product-branded recharge URL — that
  * adapter is product-specific and must not live in this package (see
- * source-map.md for the full account of what was left behind and why).
+ * archived provenance ledger for the full account of what was left behind and why).
  * Callers inject their own `AccountFailureClassifier` through
  * `AttachAcpSessionOptions.accountFailureClassifier`; the default
  * `noopAccountFailureClassifier` always returns `null`, which reproduces the
@@ -32,7 +32,9 @@ export interface AccountFailure {
  * `null` when the text does not match a known account-failure pattern.
  */
 export interface AccountFailureClassifier {
-    classify(text: string): AccountFailure | null;
+    classify(requiredArgs: {
+        text: string;
+    }): AccountFailure | null;
 }
 /**
  * Default no-op classifier used when a caller does not inject a real one.

package/dist/agent-protocol/acp/account-failure.js

@@ -4,7 +4,7 @@
  * actionable error. OD's real implementation classifies vela/AMR-branded
  * failure text against a hardcoded, product-branded recharge URL — that
  * adapter is product-specific and must not live in this package (see
- * source-map.md for the full account of what was left behind and why).
+ * archived provenance ledger for the full account of what was left behind and why).
  * Callers inject their own `AccountFailureClassifier` through
  * `AttachAcpSessionOptions.accountFailureClassifier`; the default
  * `noopAccountFailureClassifier` always returns `null`, which reproduces the

package/dist/agent-protocol/acp/json.d.ts

@@ -4,7 +4,7 @@
  * performs no I/O; depends only on acp/types and acp/constants.
  * Consumed by acp/rpc.ts, acp/session.ts, acp/models.ts, and acp/updates.ts.
  */
-import type { JsonObject } from './types.js';
+import type { UnknownRecord } from './types.js';
 /** Default environment variable name `resolveAcpTimeoutMs` reads when the
  * caller does not supply its own. A host application with its own branded
  * env var naming convention should pass its own name explicitly rather than
@@ -32,14 +32,14 @@ export declare function errorMessage(err: unknown): string;
  */
 export declare function resolveAcpTimeoutMs(env: NodeJS.ProcessEnv, fallbackMs: number, envVarName?: string): number;
 /**
- * Coerces an unknown value to a `JsonObject` if it is a non-null, non-array
+ * Coerces an unknown value to a `UnknownRecord` if it is a non-null, non-array
  * plain object, or returns `null` otherwise. The primary guard used throughout
  * the ACP layer before accessing named properties on parsed JSON frames.
  *
  * @param value - Any value from a JSON parse result.
- * @returns The value cast as `JsonObject`, or `null` when the cast is unsafe.
+ * @returns The value cast as `UnknownRecord`, or `null` when the cast is unsafe.
  */
-export declare function asObject(value: unknown): JsonObject | null;
+export declare function asObject(value: unknown): UnknownRecord | null;
 /**
  * Returns a short diagnostic string describing the JSON kind of `value`:
  * `'array'`, `'null'`, or the result of `typeof`. Used to build
@@ -50,7 +50,7 @@ export declare function asObject(value: unknown): JsonObject | null;
 export declare function acpValueKind(value: unknown): string;
 /**
  * Returns a sorted array of own string keys from `value` if it is a
- * `JsonObject`, or an empty array otherwise. Used to snapshot object
+ * `UnknownRecord`, or an empty array otherwise. Used to snapshot object
  * structure for diagnostic payloads without risking a throw.
  *
  * @param value - Any value from a parsed ACP update object.
@@ -78,5 +78,5 @@ export declare function extractAcpTextValue(value: unknown, depth?: number): str
  * @param update - A parsed ACP `session/update` params object.
  * @returns The first non-empty text string, or `null` when none is present.
  */
-export declare function extractAcpUpdateText(update: JsonObject): string | null;
+export declare function extractAcpUpdateText(update: UnknownRecord): string | null;
 //# sourceMappingURL=json.d.ts.map

package/dist/agent-protocol/acp/json.js

@@ -33,12 +33,12 @@ export function resolveAcpTimeoutMs(env, fallbackMs, envVarName = DEFAULT_ACP_TI
     return Math.min(MAX_TIMEOUT_MS, Math.max(0, Math.floor(raw)));
 }
 /**
- * Coerces an unknown value to a `JsonObject` if it is a non-null, non-array
+ * Coerces an unknown value to a `UnknownRecord` if it is a non-null, non-array
  * plain object, or returns `null` otherwise. The primary guard used throughout
  * the ACP layer before accessing named properties on parsed JSON frames.
  *
  * @param value - Any value from a JSON parse result.
- * @returns The value cast as `JsonObject`, or `null` when the cast is unsafe.
+ * @returns The value cast as `UnknownRecord`, or `null` when the cast is unsafe.
  */
 export function asObject(value) {
     return value && typeof value === 'object' ? value : null;
@@ -59,7 +59,7 @@ export function acpValueKind(value) {
 }
 /**
  * Returns a sorted array of own string keys from `value` if it is a
- * `JsonObject`, or an empty array otherwise. Used to snapshot object
+ * `UnknownRecord`, or an empty array otherwise. Used to snapshot object
  * structure for diagnostic payloads without risking a throw.
  *
  * @param value - Any value from a parsed ACP update object.

package/dist/agent-protocol/acp/models.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from './types.js';
+import type { UnknownRecord } from './types.js';
 /** A single model entry exposed to the daemon's model-selection UI and to `session/set_model` calls. */
 export interface ModelOption {
     id: string;
@@ -37,7 +37,7 @@ export declare function normalizeConfigOptionToken(value: unknown): string;
  * @param option - A single item from the `configOptions` array.
  * @param configId - The trimmed `id` field of that item.
  */
-export declare function isModelConfigOption(option: JsonObject, configId: string): boolean;
+export declare function isModelConfigOption(option: UnknownRecord, configId: string): boolean;
 /**
  * Scans the `configOptions` array from an ACP `session/new` result and returns
  * the first entry that passes `isModelConfigOption`. Returns `null` when no
@@ -72,7 +72,12 @@ export declare function normalizeModelConfigOptions(configOptions: unknown, defa
  * @param configOptions - Optional `result.configOptions` for the config-option path.
  * @returns A deduplicated array of `ModelOption` items.
  */
-export declare function normalizeModels(models: unknown, defaultModelOption: ModelOption, configOptions?: unknown): ModelOption[];
+export declare function normalizeModels({ models, defaultModelOption }: {
+    models: unknown;
+    defaultModelOption: ModelOption;
+}, { configOptions }?: {
+    configOptions?: unknown;
+}): ModelOption[];
 /**
  * Returns `true` for JSON-RPC error codes that indicate a model-selection
  * failure from which the session can recover by falling back to the default
@@ -88,7 +93,7 @@ export declare function modelSelectionErrorIsRecoverable(code: unknown): boolean
  *
  * @param result - The parsed `result` object from a session handshake response.
  */
-export declare function currentModelFromSessionResult(result: JsonObject): string | null;
+export declare function currentModelFromSessionResult(result: UnknownRecord): string | null;
 /**
  * Probes a running ACP binary by spawning it, performing the
  * `initialize` → `session/new` handshake, and reading the model list from the
@@ -108,5 +113,5 @@ export declare function currentModelFromSessionResult(result: JsonObject): strin
  * @param options.defaultModelOption - Fallback option prepended to the result list.
  * @returns A promise resolving to the available `ModelOption[]`.
  */
-export declare function detectAcpModels({ bin, args, cwd, env, timeoutMs, clientName, clientVersion, defaultModelOption, }: DetectAcpModelsOptions): Promise<ModelOption[]>;
+export declare function detectAcpModels(requiredArgs: Pick<DetectAcpModelsOptions, "bin" | "args">, optionalArgs?: Omit<DetectAcpModelsOptions, "bin" | "args">): Promise<ModelOption[]>;
 //# sourceMappingURL=models.d.ts.map

package/dist/agent-protocol/acp/models.js

@@ -123,7 +123,7 @@ export function normalizeModelConfigOptions(configOptions, defaultModelOption) {
  * @param configOptions - Optional `result.configOptions` for the config-option path.
  * @returns A deduplicated array of `ModelOption` items.
  */
-export function normalizeModels(models, defaultModelOption, configOptions) {
+export function normalizeModels({ models, defaultModelOption }, { configOptions } = {}) {
     const configModels = normalizeModelConfigOptions(configOptions, defaultModelOption);
     if (configModels && configModels.models.length > 1) {
         return configModels.models;
@@ -190,7 +190,8 @@ export function currentModelFromSessionResult(result) {
  * @param options.defaultModelOption - Fallback option prepended to the result list.
  * @returns A promise resolving to the available `ModelOption[]`.
  */
-export async function detectAcpModels({ bin, args, cwd = process.cwd(), env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, clientName = 'agent-runtime-detect', clientVersion = 'runtime-adapter', defaultModelOption = { id: 'default', label: 'Default (CLI config)' }, }) {
+export async function detectAcpModels(requiredArgs, optionalArgs = {}) {
+    const { bin, args, cwd = process.cwd(), env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, clientName = 'agent-runtime-detect', clientVersion = 'runtime-adapter', defaultModelOption = { id: 'default', label: 'Default (CLI config)' }, } = { ...optionalArgs, ...requiredArgs };
     const effectiveTimeoutMs = resolveAcpTimeoutMs(env, timeoutMs);
     return await new Promise((resolve, reject) => {
         const child = spawn(bin, args, {
@@ -232,38 +233,38 @@ export async function detectAcpModels({ bin, args, cwd = process.cwd(), env = pr
         };
         const sendSessionNew = () => {
             expectedId = nextId;
-            writeRpc(nextId, 'session/new', buildAcpSessionNewParams(cwd));
+            writeRpc(nextId, 'session/new', buildAcpSessionNewParams({ cwd: cwd }));
             nextId += 1;
         };
-        const parser = createJsonLineStream((raw) => {
-            const obj = asObject(raw);
-            const error = asObject(obj?.error);
-            const result = asObject(obj?.result);
-            const rpcErr = rpcErrorMessage(raw);
-            if (rpcErr) {
-                // JSON-RPC -32603 "Internal error" during model detection:
-                // If this is for the current expected-id (initialize/session/new),
-                // it's a real probe failure — reject immediately.
-                // Otherwise it's cleanup noise — suppress it.
-                if (error?.code === -32603 && obj?.id !== expectedId)
+        const parser = createJsonLineStream({ onMessage: ({ message: raw }) => {
+                const obj = asObject(raw);
+                const error = asObject(obj?.error);
+                const result = asObject(obj?.result);
+                const rpcErr = rpcErrorMessage(raw);
+                if (rpcErr) {
+                    // JSON-RPC -32603 "Internal error" during model detection:
+                    // If this is for the current expected-id (initialize/session/new),
+                    // it's a real probe failure — reject immediately.
+                    // Otherwise it's cleanup noise — suppress it.
+                    if (error?.code === -32603 && obj?.id !== expectedId)
+                        return;
+                    fail(rpcErr);
                     return;
-                fail(rpcErr);
-                return;
-            }
-            if (obj?.id !== expectedId || !result)
-                return;
-            if (expectedId === 1) {
-                sendSessionNew();
-                return;
-            }
-            if (expectedId === 2) {
-                const models = normalizeModels(result.models, defaultModelOption, result.configOptions);
-                finish(resolve, models);
-                if (!child.killed)
-                    child.kill('SIGTERM');
-            }
-        });
-        child.stdout.on('data', (chunk) => parser.feed(chunk));
+                }
+                if (obj?.id !== expectedId || !result)
+                    return;
+                if (expectedId === 1) {
+                    sendSessionNew();
+                    return;
+                }
+                if (expectedId === 2) {
+                    const models = normalizeModels({ models: result.models, defaultModelOption: defaultModelOption }, { configOptions: result.configOptions });
+                    finish(resolve, models);
+                    if (!child.killed)
+                        child.kill('SIGTERM');
+                }
+            } });
+        child.stdout.on('data', (chunk) => parser.feed({ chunk: chunk }));
         child.stdout.on('close', () => parser.flush());
         child.stdin.on('error', (err) => fail(`stdin error: ${err.message}`));
         child.stderr.on('data', (chunk) => {

package/dist/agent-protocol/acp/session-params.d.ts

@@ -31,7 +31,9 @@ export interface AcpSessionOptions {
  * @param options - Optional MCP server list and env-format selector.
  * @returns The `session/new` params object ready for JSON-RPC serialisation.
  */
-export declare function buildAcpSessionNewParams(cwd: string, { mcpServers, envFormat }?: AcpSessionOptions): {
+export declare function buildAcpSessionNewParams({ cwd }: {
+    cwd: string;
+}, options?: AcpSessionOptions): {
     cwd: string;
     mcpServers: {
         type: string;

package/dist/agent-protocol/acp/session-params.js

@@ -18,7 +18,8 @@ import path from 'node:path';
  * @param options - Optional MCP server list and env-format selector.
  * @returns The `session/new` params object ready for JSON-RPC serialisation.
  */
-export function buildAcpSessionNewParams(cwd, { mcpServers, envFormat = 'array' } = {}) {
+export function buildAcpSessionNewParams({ cwd }, options = {}) {
+    const { mcpServers, envFormat = 'array' } = options;
     const servers = Array.isArray(mcpServers) ? mcpServers : [];
     const wantsMap = envFormat === 'map';
     return {

package/dist/agent-protocol/acp/session.d.ts

@@ -1,6 +1,6 @@
 import type { ExecutionProfile } from './types.js';
 import { type ArtifactTextSuppressor } from './text-suppression.js';
-import type { JsonRpcId, JsonObject, AcpChildProcess } from './types.js';
+import type { JsonRpcId, UnknownRecord, AcpChildProcess } from './types.js';
 import { type AcpMcpServerInput } from './session-params.js';
 import { type AccountFailureClassifier } from './account-failure.js';
 /** One option offered by an ACP agent for a pending tool permission request. */
@@ -19,10 +19,10 @@ export interface AcpPermissionOption {
 export interface AcpPermissionRequest {
     readonly requestId: JsonRpcId;
     readonly sessionId: string | null;
-    readonly toolCall: JsonObject | null;
+    readonly toolCall: UnknownRecord | null;
     readonly options: readonly AcpPermissionOption[];
     /** Original ACP request parameters for forward-compatible audit storage. */
-    readonly rawParams: JsonObject;
+    readonly rawParams: UnknownRecord;
 }
 /** A host's response to an {@link AcpPermissionRequest}. */
 export type AcpPermissionDecision = {
@@ -55,7 +55,10 @@ export interface AttachAcpSessionOptions {
     imagePaths?: string[];
     mcpServers?: AcpMcpServerInput[];
     envFormat?: 'array' | 'map';
-    send: (event: string, payload: unknown) => void;
+    send: (requiredArgs: {
+        event: string;
+        payload: unknown;
+    }) => void;
     /**
      * Receives every native ACP tool-permission request before the agent can
      * execute it. Omit it only when the host intends the session to fail closed
@@ -113,7 +116,10 @@ export declare function createAcpSessionState(): AcpSessionState;
  * construct a fake one with `vi.fn()` stubs for the callbacks.
  */
 export interface AcpSessionEffects {
-    send: (event: string, payload: unknown) => void;
+    send: (requiredArgs: {
+        event: string;
+        payload: unknown;
+    }) => void;
     fail: (message: string, options?: {
         forceModelUnavailable?: boolean;
         details?: unknown;
@@ -127,7 +133,7 @@ export interface AcpSessionEffects {
     emitVisibleTextDelta: (delta: string) => void;
     noteArtifactTextSuppression: (reason: string) => void;
     noteToolCallTextSuppression: (reason: string) => void;
-    emitAcpRawShapeDiagnostic: (update: JsonObject) => void;
+    emitAcpRawShapeDiagnostic: (update: UnknownRecord) => void;
     toolCallTextSuppressor: ArtifactTextSuppressor;
     runStartedAt: number;
     modelUnavailableErrorCode?: 'AMR_MODEL_UNAVAILABLE' | undefined;
@@ -149,20 +155,20 @@ export interface AcpSessionEffects {
 export declare function handleRpcError({ state, effects, obj, error, rpcErr, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
-    error: JsonObject | null;
+    obj: UnknownRecord;
+    error: UnknownRecord | null;
     rpcErr: string;
 }): void;
 /** Promotes an AMR retry-status `session/update` into a structured account-failure error, if the classifier matches. Returns `true` when it did (and thus failed the session). */
 export declare function tryPromoteAmrRetryStatus({ effects, update, }: {
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): boolean;
 /** Translates an `agent_thought_chunk` update into `thinking_start` (once) / `thinking_delta` events. */
 export declare function handleThoughtChunkUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Strips tool-call XML from a raw message delta via the session's tool-call text suppressor, noting the suppression reason. */
 export declare function stripToolCallText({ effects, delta }: {
@@ -208,31 +214,31 @@ export declare function applyDsmlArtifactSuppression({ state, effects, suppresso
 export declare function handleMessageChunkUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 export declare function mirrorArtifactWriteToolEvent({ state, effects, update, toolCallId, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
     toolCallId: string | null;
 }): void;
 /** Arms the DSML artifact suppressor when a tool_call/tool_call_update completes an artifact write, or disarms it once its owning write call terminally fails. */
 export declare function updateDsmlSuppressorForToolCall({ state, update, toolCallId, }: {
     state: AcpSessionState;
-    update: JsonObject;
+    update: UnknownRecord;
     toolCallId: string | null;
 }): void;
 /** Translates a `tool_call` / `tool_call_update` update: tracks it as real turn output, mirrors artifact writes, and manages DSML suppressor arming. */
 export declare function handleToolCallUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Top-level `session/update` dispatcher: emits a generic status for non-streaming update kinds, then routes to the matching per-kind handler. */
 export declare function handleSessionUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Handles the `initialize` ack: sends `session/load` (resume) or `session/new` (fresh). */
 export declare function handleInitializeAck({ state, effects }: {
@@ -248,33 +254,33 @@ export declare function triggerSetModelIfNeeded({ state, effects, }: {
 export declare function handleSessionNewAck({ state, effects, result, rawLine, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
     rawLine: string;
 }): void;
 /** Handles the `session/prompt` ack: fails a turn that reported model activity but produced no visible output, otherwise flushes and finishes cleanly. */
 export declare function handlePromptResult({ state, effects, result, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
 }): void;
 /** Whether an incoming result frame is the ack for an in-flight `session/set_model` (or `set_config_option`) request. */
 export declare function isModelSetAckExpected({ state, effects, obj, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
+    obj: UnknownRecord;
 }): boolean;
 /** Handles the `session/set_model` (or `set_config_option`) ack: records the confirmed model and sends the prompt. */
 export declare function handleModelSetAck({ state, effects, result, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
 }): void;
 /** Top-level JSON-RPC result dispatcher, keyed by which request `expectedId`/`promptRequestId` is currently outstanding. */
 export declare function routeResultById({ state, effects, obj, result, rawLine, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
-    result: JsonObject | null;
+    obj: UnknownRecord;
+    result: UnknownRecord | null;
     rawLine: string;
 }): void;
 /**
@@ -302,5 +308,5 @@ export declare function routeResultById({ state, effects, obj, result, rawLine,
  * @returns A controller with `hasFatalError`, `getDurableSessionId`,
  *   `completedSuccessfully`, and `abort` methods.
  */
-export declare function attachAcpSession(options: AttachAcpSessionOptions): AcpSessionController;
+export declare function attachAcpSession(requiredArgs: Pick<AttachAcpSessionOptions, "child" | "prompt" | "send">, optionalArgs?: Omit<AttachAcpSessionOptions, "child" | "prompt" | "send">): AcpSessionController;
 //# sourceMappingURL=session.d.ts.map