@jini-ai/agent-runtime 0.1.0

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

@@ -0,0 +1,107 @@
+/** @module agent-protocol/acp/rpc
+ * JSON-RPC 2.0 send helpers, error-shape parsers, usage normaliser, and
+ * permission-outcome selector for the ACP protocol layer. Depends on
+ * acp/types and acp/json; consumed by acp/session.ts and acp/models.ts.
+ */
+import type { JsonRpcId, RpcWritable } from './types.js';
+/**
+ * Writes a JSON-RPC 2.0 request frame to `writable` as a single newline-terminated
+ * line. Used to send ACP method calls (e.g. `initialize`, `session/new`,
+ * `session/prompt`) to an agent subprocess's stdin.
+ *
+ * @param writable - The agent's stdin (or equivalent writable).
+ * @param id - The JSON-RPC request id used to correlate the response.
+ * @param method - The RPC method name.
+ * @param params - The method parameter payload (any JSON-serialisable value).
+ */
+export declare function sendRpc(writable: RpcWritable, id: JsonRpcId, method: string, params: unknown): void;
+/**
+ * Writes a JSON-RPC 2.0 result response frame to `writable`. Used to reply to
+ * incoming `session/request_permission` calls from an ACP agent.
+ *
+ * @param writable - The agent's stdin (or equivalent writable).
+ * @param id - The id from the incoming request being answered.
+ * @param result - The result payload to include in the response.
+ */
+export declare function sendRpcResult(writable: RpcWritable, id: JsonRpcId, result: unknown): void;
+/**
+ * Type guard that returns `true` when `value` is a valid JSON-RPC id
+ * (a `number` or `string`). Used before replying to incoming requests.
+ */
+export declare function isJsonRpcId(value: unknown): value is JsonRpcId;
+/**
+ * Extracts a human-readable error message from a raw JSON-RPC response object
+ * that contains an `error` field. Returns an empty string when the response
+ * is not an error frame, allowing callers to use it as a truthy check.
+ *
+ * @param raw - A parsed JSON-RPC response object (unknown shape).
+ * @returns A non-empty error message string, or `''` when not an error response.
+ */
+export declare function rpcErrorMessage(raw: unknown): string;
+/**
+ * Extracts the structured `data` field from a JSON-RPC error response's `error`
+ * object, if present. Used to retrieve typed failure details (e.g. `retryable`,
+ * vendor-specific error codes) without throwing.
+ *
+ * @param raw - A parsed JSON-RPC response object (unknown shape).
+ * @returns The `error.data` value, or `undefined` when absent.
+ */
+export declare function rpcErrorData(raw: unknown): unknown;
+/**
+ * Reads the `retryable` boolean from a structured RPC error `data` payload.
+ * Returns `undefined` when the field is absent so callers can distinguish
+ * "explicitly false" from "not present" and apply their own default.
+ *
+ * @param data - The value of `error.data` extracted via `rpcErrorData`.
+ */
+export declare function rpcErrorRetryable(data: unknown): boolean | undefined;
+/**
+ * Promotes an opencode `ROLE_MARKER_HALLUCINATION` error embedded in an ACP
+ * JSON-RPC `error.data` payload into a canonical, structured error object.
+ * Returns `null` when the data payload does not match the expected shape.
+ * Exists so callers can surface a vendor-specific failure with a structured
+ * error code rather than a bare generic message.
+ *
+ * @param data - The `error.data` field from a JSON-RPC error response.
+ * @param fallbackMessage - Used when the payload's `message` field is blank.
+ * @returns A structured error payload, or `null` when not applicable.
+ */
+export declare function promotedOpenCodeSessionErrorPayload(data: unknown, fallbackMessage: string): {
+    message: string;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+        details: {
+            promoted_by: string;
+        };
+    };
+} | null;
+/** Normalised token-usage counters extracted from an ACP session result for downstream analytics and cost tracking. */
+export interface FormattedUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cached_read_tokens?: number;
+    thought_tokens?: number;
+    total_tokens?: number;
+}
+/**
+ * Normalises an ACP agent's raw `usage` object (camelCase keys) into the
+ * snake_case `FormattedUsage` shape used by the daemon event stream. Returns
+ * `null` when the input is not a recognisable usage object or has no known
+ * fields.
+ *
+ * @param usage - The raw `result.usage` value from a `session/prompt` response.
+ * @returns A `FormattedUsage` object with at least one field, or `null`.
+ */
+export declare function formatUsage(usage: unknown): FormattedUsage | null;
+/**
+ * Selects the best permission-outcome `optionId` to reply with when an ACP
+ * agent sends a `session/request_permission` request. Prefers
+ * `approve_for_session`, then `allow_always`, then `allow_once`.
+ *
+ * @param options - The `params.options` array from the incoming permission request.
+ * @returns The chosen `optionId` string, or `null` when no approvable option is found.
+ */
+export declare function choosePermissionOutcome(options: unknown): string | null;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/agent-protocol/acp/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../../src/agent-protocol/acp/rpc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAInG;AACD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAEzF;AACD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AACD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAepD;AACD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIlD;AACD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAGpE;AACD;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM;;;;;;;;;;SAyBzF;AACD,uHAAuH;AACvH,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AACD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAYjE;AACD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CASvE"}

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

@@ -0,0 +1,162 @@
+import { asObject } from './json.js';
+/**
+ * Writes a JSON-RPC 2.0 request frame to `writable` as a single newline-terminated
+ * line. Used to send ACP method calls (e.g. `initialize`, `session/new`,
+ * `session/prompt`) to an agent subprocess's stdin.
+ *
+ * @param writable - The agent's stdin (or equivalent writable).
+ * @param id - The JSON-RPC request id used to correlate the response.
+ * @param method - The RPC method name.
+ * @param params - The method parameter payload (any JSON-serialisable value).
+ */
+export function sendRpc(writable, id, method, params) {
+    writable.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+}
+/**
+ * Writes a JSON-RPC 2.0 result response frame to `writable`. Used to reply to
+ * incoming `session/request_permission` calls from an ACP agent.
+ *
+ * @param writable - The agent's stdin (or equivalent writable).
+ * @param id - The id from the incoming request being answered.
+ * @param result - The result payload to include in the response.
+ */
+export function sendRpcResult(writable, id, result) {
+    writable.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+}
+/**
+ * Type guard that returns `true` when `value` is a valid JSON-RPC id
+ * (a `number` or `string`). Used before replying to incoming requests.
+ */
+export function isJsonRpcId(value) {
+    return typeof value === 'number' || typeof value === 'string';
+}
+/**
+ * Extracts a human-readable error message from a raw JSON-RPC response object
+ * that contains an `error` field. Returns an empty string when the response
+ * is not an error frame, allowing callers to use it as a truthy check.
+ *
+ * @param raw - A parsed JSON-RPC response object (unknown shape).
+ * @returns A non-empty error message string, or `''` when not an error response.
+ */
+export function rpcErrorMessage(raw) {
+    const obj = asObject(raw);
+    const error = asObject(obj?.error);
+    if (!obj || !error) {
+        return '';
+    }
+    const message = typeof error.message === 'string'
+        ? error.message
+        : typeof error.code === 'number'
+            ? String(error.code)
+            : 'json-rpc error';
+    return typeof obj.id === 'number'
+        ? `json-rpc id ${obj.id}: ${message}`
+        : message;
+}
+/**
+ * Extracts the structured `data` field from a JSON-RPC error response's `error`
+ * object, if present. Used to retrieve typed failure details (e.g. `retryable`,
+ * vendor-specific error codes) without throwing.
+ *
+ * @param raw - A parsed JSON-RPC response object (unknown shape).
+ * @returns The `error.data` value, or `undefined` when absent.
+ */
+export function rpcErrorData(raw) {
+    const obj = asObject(raw);
+    const error = asObject(obj?.error);
+    return error && 'data' in error ? error.data : undefined;
+}
+/**
+ * Reads the `retryable` boolean from a structured RPC error `data` payload.
+ * Returns `undefined` when the field is absent so callers can distinguish
+ * "explicitly false" from "not present" and apply their own default.
+ *
+ * @param data - The value of `error.data` extracted via `rpcErrorData`.
+ */
+export function rpcErrorRetryable(data) {
+    const details = asObject(data);
+    return typeof details?.retryable === 'boolean' ? details.retryable : undefined;
+}
+/**
+ * Promotes an opencode `ROLE_MARKER_HALLUCINATION` error embedded in an ACP
+ * JSON-RPC `error.data` payload into a canonical, structured error object.
+ * Returns `null` when the data payload does not match the expected shape.
+ * Exists so callers can surface a vendor-specific failure with a structured
+ * error code rather than a bare generic message.
+ *
+ * @param data - The `error.data` field from a JSON-RPC error response.
+ * @param fallbackMessage - Used when the payload's `message` field is blank.
+ * @returns A structured error payload, or `null` when not applicable.
+ */
+export function promotedOpenCodeSessionErrorPayload(data, fallbackMessage) {
+    const details = asObject(data);
+    if (details?.kind !== 'opencode_session_error' ||
+        details.source !== 'opencode' ||
+        details.code !== 'ROLE_MARKER_HALLUCINATION') {
+        return null;
+    }
+    const message = typeof details.message === 'string' && details.message.trim()
+        ? details.message.trim()
+        : fallbackMessage;
+    return {
+        message,
+        error: {
+            code: 'ROLE_MARKER_HALLUCINATION',
+            message,
+            retryable: typeof details.retryable === 'boolean' ? details.retryable : true,
+            details: {
+                ...details,
+                promoted_by: 'agent_runtime_acp',
+            },
+        },
+    };
+}
+/**
+ * Normalises an ACP agent's raw `usage` object (camelCase keys) into the
+ * snake_case `FormattedUsage` shape used by the daemon event stream. Returns
+ * `null` when the input is not a recognisable usage object or has no known
+ * fields.
+ *
+ * @param usage - The raw `result.usage` value from a `session/prompt` response.
+ * @returns A `FormattedUsage` object with at least one field, or `null`.
+ */
+export function formatUsage(usage) {
+    const src = asObject(usage);
+    if (!src)
+        return null;
+    const out = {};
+    if (typeof src.inputTokens === 'number')
+        out.input_tokens = src.inputTokens;
+    if (typeof src.outputTokens === 'number')
+        out.output_tokens = src.outputTokens;
+    if (typeof src.cachedReadTokens === 'number') {
+        out.cached_read_tokens = src.cachedReadTokens;
+    }
+    if (typeof src.thoughtTokens === 'number')
+        out.thought_tokens = src.thoughtTokens;
+    if (typeof src.totalTokens === 'number')
+        out.total_tokens = src.totalTokens;
+    return Object.keys(out).length > 0 ? out : null;
+}
+/**
+ * Selects the best permission-outcome `optionId` to reply with when an ACP
+ * agent sends a `session/request_permission` request. Prefers
+ * `approve_for_session`, then `allow_always`, then `allow_once`.
+ *
+ * @param options - The `params.options` array from the incoming permission request.
+ * @returns The chosen `optionId` string, or `null` when no approvable option is found.
+ */
+export function choosePermissionOutcome(options) {
+    const list = Array.isArray(options) ? options : [];
+    const approveForSession = list.find((option) => option?.optionId === 'approve_for_session');
+    if (approveForSession)
+        return 'approve_for_session';
+    const allowAlways = list.find((option) => option?.kind === 'allow_always');
+    if (allowAlways?.optionId)
+        return allowAlways.optionId;
+    const allowOnce = list.find((option) => option?.kind === 'allow_once');
+    if (allowOnce?.optionId)
+        return allowOnce.optionId;
+    return null;
+}
+//# sourceMappingURL=rpc.js.map

package/dist/agent-protocol/acp/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../../src/agent-protocol/acp/rpc.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,55 @@
+/**
+ * Loose descriptor for a single MCP server entry as supplied by a caller.
+ * All fields are typed `unknown` so the builder can safely normalise them
+ * without trusting the caller's type discipline.
+ */
+export interface AcpMcpServerInput {
+    type?: unknown;
+    name?: unknown;
+    command?: unknown;
+    args?: unknown;
+    env?: unknown;
+}
+/**
+ * Options accepted by `buildAcpSessionNewParams` controlling optional MCP
+ * server injection and the env-field wire format used by the target agent.
+ */
+export interface AcpSessionOptions {
+    mcpServers?: AcpMcpServerInput[];
+    envFormat?: 'array' | 'map';
+}
+/**
+ * Builds the params object for an ACP `session/new` JSON-RPC call. Resolves
+ * `cwd` to an absolute path and normalises each MCP server entry's `env` field
+ * between `'array'` format (`[{name, value}]`, default, used by Hermes/Kimi)
+ * and `'map'` format (`{"KEY": "val"}`, used by reasonix and standard MCP).
+ *
+ * MCP is optional — omit `mcpServers` to run without it. Never auto-installs
+ * or mutates user/global MCP config.
+ *
+ * @param cwd - The working directory to pass to the ACP agent subprocess.
+ * @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): {
+    cwd: string;
+    mcpServers: {
+        type: string;
+        name: string;
+        command: string;
+        args: any[];
+        env: any;
+    }[];
+};
+/**
+ * Assembles the `prompt` array for a `session/prompt` ACP call. Always
+ * includes a leading `{ type: 'text', text: prompt }` block, followed by
+ * one `{ type: 'resource_link', uri: imagePath }` block per non-empty image
+ * path. Empty or non-string paths are silently skipped.
+ *
+ * @param prompt - The text prompt to send as the first block.
+ * @param imagePaths - Optional image attachment paths to append.
+ * @returns An array of prompt blocks ready for inclusion in `session/prompt` params.
+ */
+export declare function buildPromptBlocks(prompt: string, imagePaths: string[]): Array<Record<string, string>>;
+//# sourceMappingURL=session-params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-params.d.ts","sourceRoot":"","sources":["../../../src/agent-protocol/acp/session-params.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AACD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAIjC,SAAS,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;CAC7B;AACD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,SAAmB,EAAE,GAAE,iBAAsB;;;;;;;;;EA2ChH;AACD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOrG"}

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

@@ -0,0 +1,81 @@
+/** @module agent-protocol/acp/session-params
+ * Builds the `session/new` parameter object and prompt blocks sent to an ACP
+ * agent subprocess at session start. Handles MCP server descriptor normalisation
+ * and env-format conversion (array vs map). Consumed by acp/session.ts and
+ * acp/models.ts; depends only on Node path.
+ */
+import path from 'node:path';
+/**
+ * Builds the params object for an ACP `session/new` JSON-RPC call. Resolves
+ * `cwd` to an absolute path and normalises each MCP server entry's `env` field
+ * between `'array'` format (`[{name, value}]`, default, used by Hermes/Kimi)
+ * and `'map'` format (`{"KEY": "val"}`, used by reasonix and standard MCP).
+ *
+ * MCP is optional — omit `mcpServers` to run without it. Never auto-installs
+ * or mutates user/global MCP config.
+ *
+ * @param cwd - The working directory to pass to the ACP agent subprocess.
+ * @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' } = {}) {
+    const servers = Array.isArray(mcpServers) ? mcpServers : [];
+    const wantsMap = envFormat === 'map';
+    return {
+        cwd: path.resolve(cwd),
+        // MCP is an optional compatibility layer. Default to no MCP servers so ACP
+        // agents can run through the skill + CLI path without MCP support. Do not
+        // auto-install or mutate user/global MCP config; callers must pass an
+        // explicit per-session MCP descriptor when a compatible agent supports it.
+        mcpServers: servers.map((s) => {
+            const rawEnv = s?.env;
+            // Already a plain object — pass through in map mode, convert to
+            // array in array mode (e.g. live-artifacts MCP from
+            // buildLiveArtifactsMcpServersForAgent which already respects
+            // acpMcpEnvFormat).
+            const isPlainObject = rawEnv && typeof rawEnv === 'object' && !Array.isArray(rawEnv);
+            if (wantsMap && isPlainObject) {
+                return {
+                    type: typeof s?.type === 'string' ? s.type : 'stdio',
+                    name: typeof s?.name === 'string' ? s.name : '',
+                    command: typeof s?.command === 'string' ? s.command : '',
+                    args: Array.isArray(s?.args) ? s.args : [],
+                    env: rawEnv,
+                };
+            }
+            const envArr = Array.isArray(rawEnv) ? rawEnv : [];
+            const env = wantsMap
+                ? Object.fromEntries(envArr.map((e) => [e?.name ?? '', e?.value ?? '']))
+                : isPlainObject
+                    ? Object.entries(rawEnv).map(([name, value]) => ({ name, value }))
+                    : envArr;
+            return {
+                type: typeof s?.type === 'string' ? s.type : 'stdio',
+                name: typeof s?.name === 'string' ? s.name : '',
+                command: typeof s?.command === 'string' ? s.command : '',
+                args: Array.isArray(s?.args) ? s.args : [],
+                env,
+            };
+        }),
+    };
+}
+/**
+ * Assembles the `prompt` array for a `session/prompt` ACP call. Always
+ * includes a leading `{ type: 'text', text: prompt }` block, followed by
+ * one `{ type: 'resource_link', uri: imagePath }` block per non-empty image
+ * path. Empty or non-string paths are silently skipped.
+ *
+ * @param prompt - The text prompt to send as the first block.
+ * @param imagePaths - Optional image attachment paths to append.
+ * @returns An array of prompt blocks ready for inclusion in `session/prompt` params.
+ */
+export function buildPromptBlocks(prompt, imagePaths) {
+    const blocks = [{ type: 'text', text: prompt }];
+    for (const imagePath of imagePaths) {
+        if (typeof imagePath !== 'string' || imagePath.trim().length === 0)
+            continue;
+        blocks.push({ type: 'resource_link', uri: imagePath });
+    }
+    return blocks;
+}
+//# sourceMappingURL=session-params.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-params.js","sourceRoot":"","sources":["../../../src/agent-protocol/acp/session-params.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,101 @@
+import type { ExecutionProfile } from './types.js';
+import type { JsonRpcId, JsonObject, 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. */
+export interface AcpPermissionOption {
+    readonly optionId: string;
+    readonly kind?: string;
+    readonly name?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * The complete, host-auditable context for an ACP agent's request to perform
+ * one of *its own* tool calls. Selecting an option authorizes or rejects the
+ * agent's native tool execution; it is intentionally distinct from Jini's
+ * `ToolExecutor`, which only executes Jini-registered delegated tools.
+ */
+export interface AcpPermissionRequest {
+    readonly requestId: JsonRpcId;
+    readonly sessionId: string | null;
+    readonly toolCall: JsonObject | null;
+    readonly options: readonly AcpPermissionOption[];
+    /** Original ACP request parameters for forward-compatible audit storage. */
+    readonly rawParams: JsonObject;
+}
+/** A host's response to an {@link AcpPermissionRequest}. */
+export type AcpPermissionDecision = {
+    readonly outcome: 'selected';
+    readonly optionId: string;
+} | {
+    readonly outcome: 'cancelled';
+};
+/**
+ * Injected ACP authorization seam. It may be async so a host can persist an
+ * audit record or await an interactive policy decision before replying.
+ */
+export type AcpPermissionHandler = (request: AcpPermissionRequest) => AcpPermissionDecision | Promise<AcpPermissionDecision>;
+/** Public state/abort handle returned by {@link attachAcpSession}. */
+export interface AcpSessionController {
+    hasFatalError(): boolean;
+    getDurableSessionId(): string | null;
+    completedSuccessfully(): boolean;
+    abort(): void;
+}
+/**
+ * Options for `attachAcpSession`. All fields except `child`, `prompt`, and
+ * `send` are optional and carry sensible defaults.
+ */
+export interface AttachAcpSessionOptions {
+    child: AcpChildProcess;
+    prompt: string;
+    cwd?: string;
+    model?: string | null;
+    imagePaths?: string[];
+    mcpServers?: AcpMcpServerInput[];
+    envFormat?: 'array' | 'map';
+    send: (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
+     * on its first permission request; a runnable ACP host injects a policy
+     * that records and selects an offered option.
+     */
+    onPermissionRequest?: AcpPermissionHandler;
+    clientName?: string;
+    clientVersion?: string;
+    stageTimeoutMs?: number;
+    executionProfile?: ExecutionProfile;
+    modelUnavailableErrorCode?: 'AMR_MODEL_UNAVAILABLE';
+    accountFailureClassifier?: AccountFailureClassifier;
+    resumeSessionId?: string | null;
+    onCliReady?: () => void;
+    onSessionInit?: () => void;
+}
+/**
+ * Attaches an ACP protocol session to an already-spawned child process and
+ * drives the full JSON-RPC conversation from handshake to prompt completion.
+ *
+ * Sequence:
+ * 1. Sends `initialize` to confirm the protocol version.
+ * 2. Sends `session/new` (or `session/load` when `resumeSessionId` is set).
+ * 3. Optionally sends `session/set_model` when a non-default model is requested.
+ * 4. Sends `session/prompt` with the user's prompt and any image attachments.
+ * 5. Streams `session/update` events to the `send` callback, translating:
+ *    - `agent_thought_chunk` → `thinking_start` / `thinking_delta`
+ *    - `agent_message_chunk` → `text_delta` (with DSML and tool-call text suppression)
+ *    - `tool_call` / `tool_call_update` → deferred `tool_use` / `tool_result` pairs
+ *    - status updates → `agent.status` events
+ * 6. Handles `session/request_permission` calls through an injected policy,
+ *    failing closed when no policy is supplied.
+ * 7. On prompt completion, flushes suppression buffers, emits usage, and closes stdin.
+ *
+ * Returns a controller object that the caller may use to query session state
+ * and to abort the in-progress turn.
+ *
+ * @param options - See `AttachAcpSessionOptions` for all fields.
+ * @returns A controller with `hasFatalError`, `getDurableSessionId`,
+ *   `completedSuccessfully`, and `abort` methods.
+ */
+export declare function attachAcpSession({ child, prompt, cwd, model, imagePaths, mcpServers, envFormat, send, clientName, clientVersion, stageTimeoutMs, executionProfile, modelUnavailableErrorCode, accountFailureClassifier, resumeSessionId, onPermissionRequest, onCliReady, onSessionInit, }: AttachAcpSessionOptions): AcpSessionController;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/agent-protocol/acp/session.ts"],"names":[],"mappings":"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"}