@mono-agent/agent-runtime 0.17.1 → 0.18.1

package/src/ai/types.js

@@ -16,13 +16,13 @@
 // documents the values active runtimes currently produce.
 
 /**
- * @typedef {"claude" | "pi" | "codex" | "opencode" | (string & {})} RuntimeSdkId
+ * @typedef {"claude" | "pi" | "codex" | "opencode" | "acp" | (string & {})} RuntimeSdkId
  * Canonical active runtime id. See ACTIVE_RUNTIME_KINDS (model-refs.js) for
  * the enforced-at-runtime vocabulary.
  */
 
 /**
- * @typedef {"claude" | "claude-code" | "codex-app" | "opencode-app" | "pi" | (string & {})} RuntimeBridgeId
+ * @typedef {"claude" | "claude-code" | "codex-app" | "opencode-app" | "pi" | "acp-stdio" | (string & {})} RuntimeBridgeId
  * Registry bridge id (distinct from RuntimeSdkId: a single sdk can be served
  * by more than one bridge, e.g. sdk "claude" is served by both the "claude"
  * SDK bridge and the "claude-code" CLI bridge). See
@@ -133,7 +133,7 @@
  * @typedef {Object} RuntimeRunOptions
  * The options object a host passes to `createRuntime(host).run(systemPrompt, options)`.
  * @property {RuntimeModelRef} model                     Resolved model reference; see parseRuntimeModelReference.
- * @property {string} [executionMode]                     "sdk" (default) or "cli"; selects which bridge variant handles the model.
+ * @property {"sdk"|"cli"|"acp"} [executionMode]       "sdk" (default), "cli", or "acp"; selects which bridge variant handles the model.
  * @property {string} [sessionId]                         Host conversation/session key for resumable bridges.
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
  * @property {typeof import("@anthropic-ai/claude-agent-sdk").query} [claudeAgentQuery] Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
@@ -163,6 +163,9 @@
  * @property {RuntimeToolLimits} [toolLimits] Typed per-run tool-output limits (supported replacement for the deprecated `settings` tool keys).
  * @property {RuntimeCompactionPolicy} [compaction] Typed per-run compaction policy (supported replacement for the deprecated `settings` compaction keys).
  * @property {RuntimePromptOverrides} [prompts] Per-run prompt-fragment overrides (run wins over the host default).
+ * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Per-run ACP profile resolver; wins over the host default.
+ * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Per-run ACP permission/elicitation callback; wins over the host default.
+ * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
  * @property {{backend?: "auto"|"searxng"|"keyless", endpoint?: string}} [webSearchConfig] Run-scoped WebSearch backend configuration.
  * @property {{render?: "never"|"auto", browserCommand?: string}} [webFetchConfig] Run-scoped WebFetch extraction/render configuration.
  * @property {"sequential"|"safe-parallel"} [piToolExecutionMode] Pi built-in tool scheduling mode. Safe parallelism is the default.
@@ -180,7 +183,7 @@
 
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
+ *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "acpSessionTokenKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
  *   & {runtimeBrand: import('../runtime-brand.js').RuntimeBrand, toolContext?: import('../agent/tools/shared/tool-context.js').ToolContext, observerHub: {emit: (event: RuntimeEvent) => void, flush: () => Promise<void>}}
  * } RuntimeRequest
  * The request shape a bridge's `execute(systemPrompt, req)` receives as its
@@ -360,6 +363,9 @@
  * @property {*} [runtimeBrand] See resolveRuntimeBrand (runtime-brand.js); accepts a partial RuntimeBrand.
  * @property {(parsed: {sdk: (string|null), provider?: string, model: string}) => (import('./cost.js').NormalizedPricing|null)} [resolveCustomPricing] See resolvePricing (ai/cost.js).
  * @property {import('../pi-auth.js').PiApiKeyResolver} [resolvePiApiKey] See createPiOAuthApiKeyResolver (pi-auth.js) for a ready-made implementation.
+ * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Default ACP profile resolver; a per-run callback wins.
+ * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Default ACP interaction callback; a per-run callback wins.
+ * @property {Uint8Array} [acpSessionTokenKey] Default host-owned 32-byte key for confidential authenticated ACP session handles.
  * @property {(artifact: {filename: string, buffer: Buffer, toolName: string, toolUseId: (string|null)}) => (string|null)} [persistArtifact]
  * @property {(record: CompactionRecordedPayload) => void} [onCompactionRecorded]
  * @property {(payload: ApprovalRequestPayload) => Promise<ApprovalDecision>} [onToolApprovalRequest]
@@ -395,4 +401,4 @@
  * @property {() => Promise<void>} disposeAllSessions
  */
 
-export const PROVIDER_KIND_VALUES = ["claude", "pi", "codex", "opencode"];
+export const PROVIDER_KIND_VALUES = ["claude", "pi", "codex", "opencode", "acp"];

package/src/runtime.js

@@ -8,8 +8,8 @@
 // method that resolves the right provider bridge based on `options.model` +
 // `options.executionMode`.
 //
-// The runtime registry contains a static table for the five built-in bridges
-// (claude-sdk, claude-cli, pi-native, codex-app, opencode-app) and lazily imports
+// The runtime registry contains a static table for the six built-in bridges
+// (ACP, Claude SDK/CLI, Pi-native, Codex app-server, OpenCode app-server) and lazily imports
 // the matching implementation only when a run selects it. Hosts that need finer
 // control can keep using the named exports (resolveRuntimeBridge,
 // generateClaudeResponse, etc.) directly.
@@ -53,6 +53,9 @@ import { instrumentLiveInputAppliedEvents } from "./ai/runtime/live-input-events
 const HOST_KEYS = [
   "resolveCustomPricing",
   "resolvePiApiKey",
+  "resolveAcpProfile",
+  "onAcpInteractionRequest",
+  "acpSessionTokenKey",
   "persistArtifact",
   "onCompactionRecorded",
   "onToolApprovalRequest",

package/types/ai/failure.d.ts

@@ -75,7 +75,7 @@ export function createStderrTail({ limit }?: {
 /**
  * @typedef {"spawn" | "timeout" | "stall" | "context_limit" | "usage_limit" | "invalid_result"
  *   | "invalid_delegation" | "tool_failure" | "provider_unavailable"
- *   | "provider_unavailable_exhausted" | "provider_auth"
+ *   | "provider_unavailable_exhausted" | "provider_auth" | "provider_protocol"
  *   | "skipped_capability_mismatch" | "cancelled" | "cancelled_user"
  *   | "cancelled_shutdown" | "cancelled_signal" | "abandoned"
  *   | "session_not_found" | "session_busy" | (string & {})} FailureKind
@@ -123,4 +123,4 @@ export type RetryableProviderFailureInfo = {
  * Hosts (e.g. worklab's coordinator) validate against `FAILURE_KINDS` and may
  * define additional kinds — accepting them at the type level is deliberate.
  */
-export type FailureKind = "spawn" | "timeout" | "stall" | "context_limit" | "usage_limit" | "invalid_result" | "invalid_delegation" | "tool_failure" | "provider_unavailable" | "provider_unavailable_exhausted" | "provider_auth" | "skipped_capability_mismatch" | "cancelled" | "cancelled_user" | "cancelled_shutdown" | "cancelled_signal" | "abandoned" | "session_not_found" | "session_busy" | (string & {});
+export type FailureKind = "spawn" | "timeout" | "stall" | "context_limit" | "usage_limit" | "invalid_result" | "invalid_delegation" | "tool_failure" | "provider_unavailable" | "provider_unavailable_exhausted" | "provider_auth" | "provider_protocol" | "skipped_capability_mismatch" | "cancelled" | "cancelled_user" | "cancelled_shutdown" | "cancelled_signal" | "abandoned" | "session_not_found" | "session_busy" | (string & {});

package/types/ai/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./runtime/model-refs.js";
 export * from "./runtime/registry.js";
+export * from "./providers/acp-public.js";
 export { createSessionRegistry, disposeAllProviderSessions, disposeProviderSession, invalidateProviderSession, refreshProviderSession, syncProviderSession } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
+export { generateAcpResponse, acpRuntimeBridge } from "./providers/acp.js";
 export { getPiBuiltinModel, listPiBuiltinModels, loginPiOAuth, reasoningLevelsForPiModel, resolvePiOAuthApiKey } from "./pi-interop.js";
 export { CLAUDE_SDK_CATALOG_VERSION, createClaudeSdkDiscoveryIsolation, curatedClaudeSdkModels, discoverClaudeSdkModels, normalizeClaudeSdkCatalog, normalizeClaudeSdkModelId } from "./providers/claude-sdk-discovery.js";
 export { buildCapabilitiesUsed, toolCompactionAppliedFromWarnings, UNKNOWN_CAPABILITY } from "./runtime/capabilities-used.js";

package/types/ai/providers/acp-client.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Open and initialize one owned ACP v1 stdio bridge process.
+ * @param {string} profileId
+ * @param {AcpClientHostOptions & {operation?: string}} options
+ */
+export function connectAcpProfile(profileId: string, options: AcpClientHostOptions & {
+    operation?: string;
+}): Promise<{
+    profileId: string;
+    descriptor: AcpProfileDescriptor & {
+        args: string[];
+        env: Record<string, string>;
+        configurationOwner: "client" | "agent";
+        workspaceOwner: "client" | "agent";
+        mcpOwner: "client" | "agent";
+        process: {
+            startupTimeoutMs: number;
+            requestTimeoutMs: number;
+            shutdownGraceMs: number;
+            killGraceMs: number;
+            stderrTailBytes: number;
+            maxLineBytes: number;
+        };
+    };
+    initializeResult: any;
+    clientCapabilities: {
+        fs: {
+            readTextFile: boolean;
+            writeTextFile: boolean;
+        };
+        terminal: boolean;
+    };
+    hasCapability: (name: any) => boolean;
+    onSessionUpdate: (sessionId: any, listener: any) => () => void;
+    request: (method: string, params: any, requestOptions?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        label?: string;
+    }) => Promise<any>;
+    authenticate(methodId: any): Promise<any>;
+    logout(): Promise<any>;
+    newSession(params: any): Promise<any>;
+    loadSession(params: any): Promise<any>;
+    resumeSession(params: any): Promise<any>;
+    closeSession(sessionId: any): Promise<any>;
+    listSessions(params?: {}): Promise<any>;
+    deleteSession(sessionId: any): Promise<any>;
+    setSessionMode(sessionId: any, modeId: any): Promise<any>;
+    setSessionConfigOption(sessionId: any, configId: any, value: any): Promise<any>;
+    cancel(sessionId: any): Promise<void>;
+    prompt(sessionId: any, prompt: any, promptOptions?: {}): Promise<any>;
+    close: () => Promise<void>;
+}>;
+/** @param {string} profileId @param {AcpClientHostOptions} options */
+export function probeAcpProfile(profileId: string, options: AcpClientHostOptions): Promise<{
+    profileId: string;
+    protocolVersion: any;
+    agentInfo: any;
+    agentCapabilities: any;
+    authMethods: any;
+}>;
+/** @param {string} profileId @param {string} methodId @param {AcpClientHostOptions} options */
+export function authenticateAcpProfile(profileId: string, methodId: string, options: AcpClientHostOptions): Promise<{
+    profileId: string;
+    methodId: string;
+    authenticated: boolean;
+}>;
+/** @param {string} profileId @param {AcpClientHostOptions} options */
+export function logoutAcpProfile(profileId: string, options: AcpClientHostOptions): Promise<{
+    profileId: string;
+    loggedOut: boolean;
+}>;
+/**
+ * @param {string} profileId
+ * @param {{cwd?: string|null, cursor?: string|null}} [request]
+ * @param {AcpClientHostOptions} [options]
+ * @returns {Promise<AcpSessionListResult>}
+ */
+export function listAcpSessions(profileId: string, request?: {
+    cwd?: string | null;
+    cursor?: string | null;
+}, options?: AcpClientHostOptions): Promise<AcpSessionListResult>;
+/** @param {string} providerSessionId @param {AcpClientHostOptions} options */
+export function deleteAcpSession(providerSessionId: string, options: AcpClientHostOptions): Promise<{
+    profileId: string;
+    providerSessionId: string;
+    deleted: boolean;
+}>;
+/**
+ * Product-neutral description of one ACP stdio agent profile. The environment
+ * is exact/minimal: agent-runtime never spreads process.env into the child.
+ */
+export type AcpProfileDescriptor = {
+    command: string;
+    args?: ReadonlyArray<string>;
+    cwd?: string;
+    env?: Record<string, string>;
+    configurationOwner?: "client" | "agent";
+    workspaceOwner?: "client" | "agent";
+    mcpOwner?: "client" | "agent";
+    /**
+     * Absolute canonical workspace path; required for agent-owned workspaces.
+     */
+    workspacePath?: string;
+    capabilityPolicy?: {
+        filesystem?: {
+            readTextFile?: boolean;
+            writeTextFile?: boolean;
+        };
+        terminal?: boolean;
+        auth?: {
+            terminal?: boolean;
+        };
+        elicitation?: {
+            form?: boolean;
+            url?: boolean;
+        };
+        sessionConfig?: {
+            boolean?: boolean;
+        };
+        mcp?: {
+            stdio?: boolean;
+            http?: boolean;
+            sse?: boolean;
+        };
+    };
+    sessionConfig?: {
+        additionalDirectories?: ReadonlyArray<string>;
+        mcpServers?: ReadonlyArray<Record<string, unknown>>;
+        resumeStrategy?: "auto" | "load" | "resume";
+        modeId?: string;
+        configOptions?: Record<string, string | boolean>;
+    };
+    clientCallbacks?: {
+        requestPermission?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").RequestPermissionRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").RequestPermissionResponse> | import("@agentclientprotocol/sdk").RequestPermissionResponse;
+        createElicitation?: (request: AcpHostElicitationPayload, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").CreateElicitationResponse> | import("@agentclientprotocol/sdk").CreateElicitationResponse;
+        readTextFile?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").ReadTextFileRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").ReadTextFileResponse> | import("@agentclientprotocol/sdk").ReadTextFileResponse;
+        writeTextFile?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").WriteTextFileRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").WriteTextFileResponse> | import("@agentclientprotocol/sdk").WriteTextFileResponse;
+        createTerminal?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").CreateTerminalRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").CreateTerminalResponse> | import("@agentclientprotocol/sdk").CreateTerminalResponse;
+        terminalOutput?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").TerminalOutputRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").TerminalOutputResponse> | import("@agentclientprotocol/sdk").TerminalOutputResponse;
+        waitForTerminalExit?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").WaitForTerminalExitRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").WaitForTerminalExitResponse> | import("@agentclientprotocol/sdk").WaitForTerminalExitResponse;
+        killTerminal?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").KillTerminalRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").KillTerminalResponse> | import("@agentclientprotocol/sdk").KillTerminalResponse;
+        releaseTerminal?: (request: AcpHostSessionPayload<import("@agentclientprotocol/sdk").ReleaseTerminalRequest>, context: AcpCallbackContext) => Promise<import("@agentclientprotocol/sdk").ReleaseTerminalResponse> | import("@agentclientprotocol/sdk").ReleaseTerminalResponse;
+        sessionUpdate?: (notification: AcpHostSessionPayload<import("@agentclientprotocol/sdk").SessionNotification>, context: AcpCallbackContext) => Promise<void> | void;
+        elicitationComplete?: (notification: Omit<import("@agentclientprotocol/sdk").CompleteElicitationNotification, "_meta">, context: AcpCallbackContext) => Promise<void> | void;
+    };
+    process?: {
+        startupTimeoutMs?: number;
+        requestTimeoutMs?: number;
+        shutdownGraceMs?: number;
+        killGraceMs?: number;
+        stderrTailBytes?: number;
+        maxLineBytes?: number;
+    };
+    /**
+     * Opaque host metadata; never returned in diagnostics.
+     */
+    metadata?: Record<string, unknown>;
+};
+export type AcpCallbackContext = {
+    profileId: string;
+    operation: string;
+    /**
+     * Opaque profile-bound session handle when the callback is session-scoped.
+     */
+    providerSessionId?: string;
+    signal?: AbortSignal;
+    requestId?: unknown;
+    hostContext?: Record<string, unknown>;
+};
+export type WithoutSessionId<T> = T extends unknown ? Omit<T, "sessionId"> : never;
+export type AcpHostSessionPayload<T> = T extends unknown ? Omit<T, "sessionId" | "_meta"> : never;
+export type AcpHostElicitationPayload = WithoutSessionId<import("@agentclientprotocol/sdk").CreateElicitationRequest> & Pick<import("@agentclientprotocol/sdk").CreateElicitationRequest, "message" | "mode">;
+export type AcpListedSession = {
+    /**
+     * Opaque runtime handle for resume/delete.
+     */
+    providerSessionId: string;
+    cwd: string;
+    additionalDirectories?: ReadonlyArray<string>;
+    title?: string | null;
+    updatedAt?: string | null;
+};
+export type AcpSessionListResult = {
+    profileId: string;
+    sessions: AcpListedSession[];
+    /**
+     * Opaque runtime cursor; pass it back unchanged.
+     */
+    nextCursor: string | null;
+};
+export type AcpPermissionInteractionPayload = WithoutSessionId<import("@agentclientprotocol/sdk").RequestPermissionRequest>;
+/**
+ * `CreateElicitationRequest` includes a future-mode string index signature.
+ * Plain `Omit` preserves that openness but widens its named common fields to
+ * unknown, so restore the protocol's concrete common-field types explicitly.
+ */
+export type AcpElicitationInteractionPayload = WithoutSessionId<import("@agentclientprotocol/sdk").CreateElicitationRequest> & Pick<import("@agentclientprotocol/sdk").CreateElicitationRequest, "message" | "mode" | "_meta">;
+export type AcpInteractionRequest = {
+    kind: "permission";
+    profileId: string;
+    payload: AcpPermissionInteractionPayload;
+} | {
+    kind: "elicitation";
+    profileId: string;
+    payload: AcpElicitationInteractionPayload;
+};
+export type AcpClientHostOptions = {
+    resolveAcpProfile: (profileId: string, context?: Record<string, unknown>) => Promise<AcpProfileDescriptor | null | undefined> | AcpProfileDescriptor | null | undefined;
+    onAcpInteractionRequest?: (request: AcpInteractionRequest, context?: AcpCallbackContext) => Promise<unknown> | unknown;
+    sandbox?: import("../../agent/sandbox-seam.js").RuntimeSandbox;
+    sandboxPolicy?: import("../../agent/sandbox-seam.js").SandboxPolicy;
+    sandboxEngine?: import("../../agent/sandbox-seam.js").RuntimeSandboxEngine;
+    cwd?: string;
+    signal?: AbortSignal;
+    context?: Record<string, unknown>;
+    /**
+     * Host-owned 32-byte key required by operations that emit or consume opaque session handles.
+     */
+    acpSessionTokenKey?: Uint8Array;
+};
+import { AcpClientError } from "./acp-session-tokens.js";
+import { encodeAcpProviderSessionId } from "./acp-session-tokens.js";
+import { validateAcpProfileId } from "./acp-session-tokens.js";
+import { validateAcpProviderSessionId } from "./acp-session-tokens.js";
+import { PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
+export { AcpClientError, encodeAcpProviderSessionId, validateAcpProfileId, validateAcpProviderSessionId, PROTOCOL_VERSION as ACP_PROTOCOL_VERSION };

package/types/ai/providers/acp-privacy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ACP protocol session ids are connection state, not host-facing metadata.
+ * Remove their canonical keys, discard extension metadata, and redact copies
+ * embedded by an agent in otherwise public strings.
+ *
+ * @param {unknown} value
+ * @param {ReadonlyArray<unknown>} [rawSecrets]
+ * @returns {{value: any, truncated: boolean}}
+ */
+export function sanitizeAcpHostValueWithStatus(value: unknown, rawSecrets?: ReadonlyArray<unknown>): {
+    value: any;
+    truncated: boolean;
+};
+/**
+ * Compatibility wrapper for callback/list surfaces that intentionally accept
+ * a bounded representation. Protocol normalization should use the status form
+ * above so it can fail explicitly instead of consuming partial data.
+ *
+ * @param {unknown} value
+ * @param {ReadonlyArray<unknown>} [rawSecrets]
+ * @returns {any}
+ */
+export function sanitizeAcpHostValue(value: unknown, rawSecrets?: ReadonlyArray<unknown>): any;
+/** @param {unknown} value @returns {string|null} */
+export function ownAcpSessionUpdateKind(value: unknown): string | null;

package/types/ai/providers/acp-public.d.ts

@@ -0,0 +1,7 @@
+export type AcpProfileDescriptor = import("./acp-client.js").AcpProfileDescriptor;
+export type AcpCallbackContext = import("./acp-client.js").AcpCallbackContext;
+export type AcpInteractionRequest = import("./acp-client.js").AcpInteractionRequest;
+export type AcpClientHostOptions = import("./acp-client.js").AcpClientHostOptions;
+export type AcpListedSession = import("./acp-client.js").AcpListedSession;
+export type AcpSessionListResult = import("./acp-client.js").AcpSessionListResult;
+export { ACP_PROTOCOL_VERSION, AcpClientError, authenticateAcpProfile, deleteAcpSession, listAcpSessions, logoutAcpProfile, probeAcpProfile, validateAcpProfileId, validateAcpProviderSessionId } from "./acp-client.js";

package/types/ai/providers/acp-session-tokens.d.ts

@@ -0,0 +1,41 @@
+/** @param {string} profileId @returns {string} */
+export function validateAcpProfileId(profileId: string): string;
+/** @param {unknown} key @returns {Buffer} */
+export function validateAcpSessionTokenKey(key: unknown): Buffer;
+/** @param {string} profileId @param {string} sessionId @param {Uint8Array} key */
+export function encodeAcpProviderSessionId(profileId: string, sessionId: string, key: Uint8Array): string;
+/**
+ * Internal protocol-state decoder. This module is not a package export.
+ * @param {string} providerSessionId
+ * @param {Uint8Array} key
+ */
+export function decodeAcpProviderSessionId(providerSessionId: string, key: Uint8Array): {
+    profileId: string;
+    sessionId: string;
+};
+/**
+ * Validate an opaque provider-session handle and its profile binding without
+ * exposing the remote agent's protocol session id.
+ *
+ * @param {string} providerSessionId
+ * @param {string} expectedProfileId
+ * @param {Uint8Array} key Host-owned 32-byte ACP session-token key.
+ * @returns {string}
+ */
+export function validateAcpProviderSessionId(providerSessionId: string, expectedProfileId: string, key: Uint8Array): string;
+/** @param {string} profileId @param {string} cursor @param {Uint8Array} key */
+export function encodeAcpSessionCursor(profileId: string, cursor: string, key: Uint8Array): string;
+/** @param {string} profileId @param {unknown} cursor @param {Uint8Array} key */
+export function decodeAcpSessionCursor(profileId: string, cursor: unknown, key: Uint8Array): string;
+export class AcpClientError extends Error {
+    /**
+     * @param {string} code
+     * @param {string} message
+     * @param {Record<string, unknown>} [details]
+     */
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+    code: string;
+    details: {
+        code: string;
+    };
+}

package/types/ai/providers/acp-transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Open one SDK connection inside an async context that strips payload-bearing
+ * SDK console arguments. The SDK starts its detached receive loop during
+ * `connect`, so descendants retain this scope without muting concurrent host
+ * work or other ACP connections.
+ *
+ * @template {{closed: Promise<unknown>}} T
+ * @param {() => T} connect
+ * @returns {T}
+ */
+export function connectWithSafeAcpSdkDiagnostics<T extends {
+    closed: Promise<unknown>;
+}>(connect: () => T): T;
+/**
+ * @param {unknown} value
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function normalizeAcpMaxLineBytes(value: unknown, fallback?: number): number;
+/**
+ * Build the Stream shape consumed by @agentclientprotocol/sdk from a child
+ * process's stdin/stdout. Both inbound and outbound payloads are capped.
+ *
+ * @param {{stdin: import('node:stream').Writable|null, stdout: import('node:stream').Readable|null}} child
+ * @param {{maxLineBytes?: number}} [options]
+ * @returns {{readable: ReadableStream<any>, writable: WritableStream<any>}}
+ */
+export function createBoundedAcpStdioStream(child: {
+    stdin: import("node:stream").Writable | null;
+    stdout: import("node:stream").Readable | null;
+}, options?: {
+    maxLineBytes?: number;
+}): {
+    readable: ReadableStream<any>;
+    writable: WritableStream<any>;
+};
+export class AcpTransportError extends Error {
+    /**
+     * @param {string} code
+     * @param {string} message
+     */
+    constructor(code: string, message: string);
+    code: string;
+}
+export const ACP_DEFAULT_MAX_LINE_BYTES: number;

package/types/ai/providers/acp.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Runtime bridge for one ACP v1 profile turn.
+ * @param {string} systemPrompt
+ * @param {any} req
+ */
+export function generateAcpResponse(systemPrompt: string, req: any): Promise<{
+    text: string;
+    thinking: string;
+    events: any[];
+    usage: {
+        total_tokens: any;
+        context_window: any;
+        cost: any;
+    } | {
+        total_tokens?: undefined;
+        context_window?: undefined;
+        cost?: undefined;
+    };
+    durationMs: number;
+    numTurns: number;
+    model: any;
+    effort: any;
+    sdk: string;
+    cancelled: boolean;
+    error: string;
+    failureKind: string;
+    providerSessionId: string;
+    runtimeWarnings: any[];
+    diagnostics: {
+        acp_protocol_version: any;
+        acp_profile_id: any;
+        acp_session_id_encoded: boolean;
+        acp_stop_reason: any;
+        acp_resume_method: string;
+        acp_mode_applied: boolean;
+        acp_config_options_applied: any[];
+    };
+    capabilitiesUsed: {
+        session_resume: boolean;
+        session_load: boolean;
+        session_config: boolean;
+        mcp: boolean;
+    };
+    structuredResult: any;
+    structuredResultSource: any;
+    errorDetails?: undefined;
+} | {
+    text: string;
+    thinking: string;
+    events: any[];
+    usage: {
+        total_tokens?: undefined;
+        context_window?: undefined;
+        cost?: undefined;
+    };
+    durationMs: number;
+    numTurns: number;
+    model: any;
+    effort: any;
+    sdk: string;
+    cancelled: boolean;
+    error: any;
+    errorDetails: {
+        acp_error_code: any;
+    };
+    failureKind: string;
+    providerSessionId: string;
+    runtimeWarnings: any[];
+    diagnostics: {
+        acp_profile_id: string;
+        acp_session_id_encoded: boolean;
+        acp_stop_reason: string;
+        acp_protocol_version?: undefined;
+        acp_resume_method?: undefined;
+        acp_mode_applied?: undefined;
+        acp_config_options_applied?: undefined;
+    };
+    capabilitiesUsed: {
+        session_resume?: undefined;
+        session_load?: undefined;
+        session_config?: undefined;
+        mcp?: undefined;
+    };
+    structuredResult: any;
+    structuredResultSource: any;
+}>;
+export namespace acpRuntimeBridge {
+    export let id: string;
+    export let kind: string;
+    export let capabilities: any;
+    export function supports(ref: any, options: any): boolean;
+    export { generateAcpResponse as execute };
+}

package/types/ai/runtime/capabilities.d.ts

@@ -55,6 +55,27 @@ export namespace RUNTIME_CAPABILITIES {
         let runtime_3: string;
         export { runtime_3 as runtime };
     }
+    namespace acp {
+        let structured_output_2: boolean;
+        export { structured_output_2 as structured_output };
+        let supports_session_resume_5: boolean;
+        export { supports_session_resume_5 as supports_session_resume };
+        let supports_mcp_2: boolean;
+        export { supports_mcp_2 as supports_mcp };
+        let supports_skills_2: boolean;
+        export { supports_skills_2 as supports_skills };
+        let supports_builtin_tools_1: boolean;
+        export { supports_builtin_tools_1 as supports_builtin_tools };
+        let supports_live_input_2: boolean;
+        export { supports_live_input_2 as supports_live_input };
+        let supports_native_subagents_3: boolean;
+        export { supports_native_subagents_3 as supports_native_subagents };
+        let supports_request_tool_environment_2: boolean;
+        export { supports_request_tool_environment_2 as supports_request_tool_environment };
+        export { TOOL_POLICY_ALLOW_ALL_ONLY as tool_policy };
+        let runtime_4: string;
+        export { runtime_4 as runtime };
+    }
 }
 import { TOOL_POLICY_PROJECTED } from "./tool-policy.js";
 import { TOOL_POLICY_ALLOW_ALL_ONLY } from "./tool-policy.js";