@mono-agent/agent-runtime 0.18.0 → 0.18.1

package/MIGRATION.md

@@ -63,7 +63,23 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.18.x
+## 0.18.1
+
+- ACP provider-session ids and session-list cursors are now confidential,
+  authenticated v2 handles. Hosts must persist one exact 32-byte binary
+  `acpSessionTokenKey` and pass it to ACP task runs, list/delete helpers, and
+  `validateAcpProviderSessionId(value, expectedProfileId, key)`. A changed or
+  missing key fails before profile resolution or process spawn. Existing v1
+  handles are rejected; discard them and obtain fresh v2 handles. Preserve the
+  complete returned value for resume, pagination, validation, and delete, but
+  do not compare ciphertexts for equality or parse/substitute the remote
+  agent's raw session id or cursor.
+- Payload-bearing diagnostics from the pinned ACP SDK are scoped to the owned
+  ACP receive loop and reduced to content-free labels. Malformed or hostile
+  agent notifications cannot copy elicitation values or URL secrets into
+  process-wide console diagnostics.
+
+## 0.18.0
 
 - `acp:<profile-id>` is now a canonical runtime model reference when paired
   with `executionMode: "acp"`. Hosts must provide `resolveAcpProfile`; profiles

package/README.md

@@ -615,19 +615,30 @@ transport frame is too structurally complex for the bounded host sanitizer,
 the turn fails explicitly as `provider_protocol` instead of emitting a partial
 tool, plan, or message event.
 
-ACP provider-session ids and list cursors are opaque, profile-bound runtime
-handles. Preserve them byte-for-byte and pass them back only to the matching
-high-level resume, list, validation, or delete operation; raw protocol session
-ids, cursors, and transport connections are private runtime state. Under the
-default `auto` recovery policy, the client prefers `session/resume`, then
-`session/load`, and finally a fresh session when neither capability is
-advertised. Explicit `resume` or `load` policies fail closed if missing. Stable
-usage comes from the latest typed `usage_update` notification; unstable
-`PromptResponse.usage` is ignored.
+ACP provider-session ids and list cursors are confidential, authenticated v2
+handles bound to their token kind and profile. The host must supply an exact
+32-byte binary `acpSessionTokenKey` for every task run, list, validation, and
+delete operation. Call
+`validateAcpProviderSessionId(handle, expectedProfileId, key)` at untrusted
+ingress. Keep the key stable and secret across host restarts; changing it
+invalidates every outstanding handle. Legacy `acp:v1:` and `acp-cursor:v1:`
+values are rejected.
+
+Preserve each returned handle byte-for-byte and pass it back only to the
+matching high-level resume, list, validation, or delete operation. Encryption
+uses a fresh nonce, so two handles for the same remote id are not equality
+keys. Raw protocol session ids, cursors, token keys, and transport connections
+remain private runtime state and are omitted from profile resolver context,
+callbacks, and diagnostics. Under the default `auto` recovery policy, the
+client prefers `session/resume`, then `session/load`, and finally a fresh
+session when neither capability is advertised. Explicit `resume` or `load`
+policies fail closed if missing. Stable usage comes from the latest typed
+`usage_update` notification; unstable `PromptResponse.usage` is ignored.
 
 ### `createRuntime(host)`
 
-Pass host-level integration once at boot. All keys are optional.
+Pass host-level integration once at boot. Keys are optional unless the selected
+backend contract requires them.
 
 ```js
 createRuntime({
@@ -636,6 +647,7 @@ createRuntime({
   resolvePiApiKey,         // async (provider) => string | undefined
   resolveAcpProfile,       // async (profileId, context) => AcpProfileDescriptor
   onAcpInteractionRequest, // async permission/elicitation fallback callback
+  acpSessionTokenKey,      // Uint8Array(32), required for ACP task/session-handle operations
   persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
   onCompactionRecorded,    // (compactionRow) => void — fired when the pi bridge
                            // runs an automatic compaction (proactive or reactive
@@ -751,6 +763,7 @@ Per-call options (a non-exhaustive selection):
 | `onEvent` | `(event) => void` | Fired for every runtime event (assistant text, tool calls/results, applied live input, runtime warnings, structured output). |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
+| `acpSessionTokenKey` | `Uint8Array(32)` | Required for ACP task runs when not bound at `createRuntime()`; keep it secret and stable across restarts. |
 | `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/ai/providers/acp-client.js

@@ -8,6 +8,7 @@ import { passthroughSandbox } from "../../agent/sandbox-seam.js";
 import {
   ACP_DEFAULT_MAX_LINE_BYTES,
   AcpTransportError,
+  connectWithSafeAcpSdkDiagnostics,
   createBoundedAcpStdioStream,
   normalizeAcpMaxLineBytes,
 } from "./acp-transport.js";
@@ -20,10 +21,12 @@ import {
   encodeAcpSessionCursor,
   validateAcpProfileId,
   validateAcpProviderSessionId,
+  validateAcpSessionTokenKey,
 } from "./acp-session-tokens.js";
 
 const OWNERS = new Set(["client", "agent"]);
 const RESUME_STRATEGIES = new Set(["auto", "load", "resume"]);
+const TOKEN_FREE_OPERATIONS = new Set(["probe", "authenticate", "logout"]);
 const DEFAULT_PROCESS_POLICY = Object.freeze({
   startupTimeoutMs: 10_000,
   requestTimeoutMs: 60_000,
@@ -135,6 +138,7 @@ const DEFAULT_PROCESS_POLICY = Object.freeze({
  * @property {string} [cwd]
  * @property {AbortSignal} [signal]
  * @property {Record<string, unknown>} [context]
+ * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key required by operations that emit or consume opaque session handles.
  */
 
 export {
@@ -527,6 +531,9 @@ export async function connectAcpProfile(profileId, options) {
   validateAcpProfileId(profileId);
   throwIfAborted(options?.signal);
   const operation = options?.operation || "connect";
+  const sessionTokenKey = TOKEN_FREE_OPERATIONS.has(operation)
+    ? undefined
+    : validateAcpSessionTokenKey(options?.acpSessionTokenKey);
   const descriptor = await resolveProfile(profileId, { ...options, operation });
   throwIfAborted(options?.signal);
   const capabilities = clientCapabilities(descriptor);
@@ -575,7 +582,13 @@ export async function connectAcpProfile(profileId, options) {
   const safeCallbackContext = (context, rawSessionId) => ({
     ...context,
     ...(typeof rawSessionId === "string"
-      ? { providerSessionId: encodeAcpProviderSessionId(profileId, rawSessionId) }
+      ? {
+          providerSessionId: encodeAcpProviderSessionId(
+            profileId,
+            rawSessionId,
+            /** @type {Uint8Array} */ (sessionTokenKey),
+          ),
+        }
       : {}),
     ...(context.requestId === undefined
       ? {}
@@ -696,9 +709,11 @@ export async function connectAcpProfile(profileId, options) {
 
   let connection;
   try {
-    connection = app.connect(createBoundedAcpStdioStream(child, {
-      maxLineBytes: descriptor.process.maxLineBytes,
-    }));
+    connection = connectWithSafeAcpSdkDiagnostics(() => app.connect(
+      createBoundedAcpStdioStream(child, {
+        maxLineBytes: descriptor.process.maxLineBytes,
+      }),
+    ));
   } catch (error) {
     child.kill("SIGTERM");
     const exited = await waitForExit(exitPromise, descriptor.process.killGraceMs);
@@ -1010,15 +1025,15 @@ function validateMcpServers(servers, descriptor, initializeResult) {
   });
 }
 
-/** @param {string} profileId @param {any} request */
-function protocolSessionListRequest(profileId, request) {
+/** @param {string} profileId @param {any} request @param {Uint8Array} key */
+function protocolSessionListRequest(profileId, request, key) {
   if (!request || typeof request !== "object" || Array.isArray(request)) {
     throw new AcpClientError("invalid_request", "ACP session/list request must be an object.");
   }
   const { cursor, _meta: _meta, ...rest } = request;
   return {
     ...rest,
-    ...(cursor == null ? {} : { cursor: decodeAcpSessionCursor(profileId, cursor) }),
+    ...(cursor == null ? {} : { cursor: decodeAcpSessionCursor(profileId, cursor, key) }),
   };
 }
 
@@ -1090,18 +1105,23 @@ export async function logoutAcpProfile(profileId, options) {
  * @returns {Promise<AcpSessionListResult>}
  */
 export async function listAcpSessions(profileId, request = {}, options = /** @type {any} */ ({})) {
-  const protocolRequest = protocolSessionListRequest(profileId, request);
-  const connection = await connectAcpProfile(profileId, { ...options, operation: "list_sessions" });
+  const key = validateAcpSessionTokenKey(options?.acpSessionTokenKey);
+  const protocolRequest = protocolSessionListRequest(profileId, request, key);
+  const connection = await connectAcpProfile(profileId, {
+    ...options,
+    operation: "list_sessions",
+    acpSessionTokenKey: key,
+  });
   try {
     const result = await connection.listSessions(protocolRequest);
     return {
       profileId,
       sessions: (result.sessions || []).map((session) => ({
         ...sanitizeAcpHostValue(session, [session.sessionId, result.nextCursor]),
-        providerSessionId: encodeAcpProviderSessionId(profileId, session.sessionId),
+        providerSessionId: encodeAcpProviderSessionId(profileId, session.sessionId, key),
       })),
       nextCursor: typeof result.nextCursor === "string"
-        ? encodeAcpSessionCursor(profileId, result.nextCursor)
+        ? encodeAcpSessionCursor(profileId, result.nextCursor, key)
         : null,
     };
   } finally {
@@ -1111,8 +1131,13 @@ export async function listAcpSessions(profileId, request = {}, options = /** @ty
 
 /** @param {string} providerSessionId @param {AcpClientHostOptions} options */
 export async function deleteAcpSession(providerSessionId, options) {
-  const { profileId, sessionId } = decodeAcpProviderSessionId(providerSessionId);
-  const connection = await connectAcpProfile(profileId, { ...options, operation: "delete_session" });
+  const key = validateAcpSessionTokenKey(options?.acpSessionTokenKey);
+  const { profileId, sessionId } = decodeAcpProviderSessionId(providerSessionId, key);
+  const connection = await connectAcpProfile(profileId, {
+    ...options,
+    operation: "delete_session",
+    acpSessionTokenKey: key,
+  });
   try {
     await connection.deleteSession(sessionId);
     return { profileId, providerSessionId, deleted: true };

package/src/ai/providers/acp-session-tokens.js

@@ -1,16 +1,31 @@
 // @ts-check
 
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+
 const PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
 const MAX_PROFILE_ID_LENGTH = 128;
 const MAX_RAW_TOKEN_BYTES = 4_096;
-const MAX_ENCODED_TOKEN_LENGTH = Math.ceil(MAX_RAW_TOKEN_BYTES * 4 / 3);
-const PROVIDER_SESSION_PREFIX = "acp:v1:";
-const SESSION_CURSOR_PREFIX = "acp-cursor:v1:";
+const TOKEN_KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+const MAX_SEALED_TOKEN_BYTES = NONCE_BYTES + MAX_RAW_TOKEN_BYTES + AUTH_TAG_BYTES;
+const MAX_ENCODED_TOKEN_LENGTH = Math.ceil(MAX_SEALED_TOKEN_BYTES * 4 / 3);
+const PROVIDER_SESSION_PREFIX = "acp:v2:";
+const SESSION_CURSOR_PREFIX = "acp-cursor:v2:";
 const MAX_PROVIDER_SESSION_ID_LENGTH = PROVIDER_SESSION_PREFIX.length
   + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
 const MAX_SESSION_CURSOR_LENGTH = SESSION_CURSOR_PREFIX.length
   + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
+const TOKEN_DOMAIN = Buffer.from("mono-agent/acp-session-token", "utf8");
+const TOKEN_VERSION = Buffer.from("v2", "utf8");
+const HKDF_SALT = Buffer.from("mono-agent/acp-session-token/v2/hkdf", "utf8");
+const ENCRYPTION_INFO = Buffer.from("mono-agent/acp-session-token/v2/encryption", "utf8");
 
 export class AcpClientError extends Error {
   /**
@@ -45,46 +60,187 @@ function requiredTokenString(value, code, label) {
   return value;
 }
 
-/** @param {string} encoded @param {string} code @param {string} label */
-function decodeToken(encoded, code, label) {
-  if (!BASE64URL_RE.test(encoded)) throw new AcpClientError(code, `Invalid ${label} encoding.`);
-  const bytes = Buffer.from(encoded, "base64url");
-  if (bytes.length === 0 || bytes.toString("base64url") !== encoded) {
-    throw new AcpClientError(code, `Non-canonical ${label} encoding.`);
+/**
+ * The token key is binary on purpose: accepting textual secrets here would
+ * make encoding, truncation, and cross-host persistence ambiguous.
+ * @param {unknown} value
+ */
+function sessionTokenKey(value) {
+  if (!(value instanceof Uint8Array) || value.byteLength !== TOKEN_KEY_BYTES) {
+    throw new AcpClientError(
+      "invalid_token_key",
+      `ACP session token key must be exactly ${TOKEN_KEY_BYTES} bytes.`,
+    );
   }
-  if (bytes.length > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError(code, `${label} exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+
+/** @param {unknown} key @returns {Buffer} */
+export function validateAcpSessionTokenKey(key) {
+  return Buffer.from(sessionTokenKey(key));
+}
+
+/** @param {ReadonlyArray<Uint8Array>} parts */
+function frame(parts) {
+  const size = parts.reduce((total, part) => total + 4 + part.byteLength, 0);
+  const result = Buffer.allocUnsafe(size);
+  let offset = 0;
+  for (const part of parts) {
+    result.writeUInt32BE(part.byteLength, offset);
+    offset += 4;
+    Buffer.from(part.buffer, part.byteOffset, part.byteLength).copy(result, offset);
+    offset += part.byteLength;
   }
+  return result;
+}
+
+/** @param {"session"|"cursor"} kind @param {string} profileId */
+function tokenAad(kind, profileId) {
+  return frame([
+    TOKEN_DOMAIN,
+    TOKEN_VERSION,
+    Buffer.from(kind, "utf8"),
+    Buffer.from(profileId, "utf8"),
+  ]);
+}
+
+/** @param {Uint8Array} key */
+function encryptionKey(key) {
+  const rawKey = Buffer.from(sessionTokenKey(key));
   try {
-    return requiredTokenString(new TextDecoder("utf-8", { fatal: true }).decode(bytes), code, label);
-  } catch (error) {
-    if (error instanceof AcpClientError) throw error;
-    throw new AcpClientError(code, `${label} is not valid UTF-8.`);
+    return Buffer.from(hkdfSync("sha256", rawKey, HKDF_SALT, ENCRYPTION_INFO, TOKEN_KEY_BYTES));
+  } finally {
+    rawKey.fill(0);
   }
 }
 
-/** @param {string} profileId @param {string} sessionId */
-export function encodeAcpProviderSessionId(profileId, sessionId) {
+/** @param {string} profileId @param {string} raw @param {string} code @param {string} label */
+function rawTokenBytes(profileId, raw, code, label) {
   validateAcpProfileId(profileId);
-  requiredTokenString(sessionId, "invalid_session_id", "ACP session id");
-  if (Buffer.byteLength(sessionId, "utf8") > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError("invalid_session_id", `ACP session id exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  requiredTokenString(raw, code, label);
+  const plaintext = Buffer.from(raw, "utf8");
+  if (plaintext.byteLength > MAX_RAW_TOKEN_BYTES) {
+    throw new AcpClientError(code, `${label} exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
   }
-  return `${PROVIDER_SESSION_PREFIX}${profileId}:${Buffer.from(sessionId, "utf8").toString("base64url")}`;
+  return plaintext;
 }
 
-/** Internal protocol-state decoder. This module is not a package export. @param {string} providerSessionId */
-export function decodeAcpProviderSessionId(providerSessionId) {
-  if (typeof providerSessionId !== "string") {
-    throw new AcpClientError("invalid_session_id", "ACP provider session id must be a string.");
+/**
+ * @param {"session"|"cursor"} kind
+ * @param {string} profileId
+ * @param {string} raw
+ * @param {Uint8Array} key
+ * @param {string} code
+ * @param {string} label
+ */
+function sealToken(kind, profileId, raw, key, code, label) {
+  const plaintext = rawTokenBytes(profileId, raw, code, label);
+  const aad = tokenAad(kind, profileId);
+  const nonce = randomBytes(NONCE_BYTES);
+  const derivedKey = encryptionKey(key);
+  let cipher;
+  try {
+    cipher = createCipheriv("aes-256-gcm", derivedKey, nonce);
+  } finally {
+    derivedKey.fill(0);
   }
-  if (providerSessionId.length > MAX_PROVIDER_SESSION_ID_LENGTH) {
-    throw new AcpClientError("invalid_session_id", "ACP provider session id exceeds the supported length.");
+  cipher.setAAD(aad);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("base64url");
+}
+
+/** @param {string} profileId @param {string} code @param {string} label */
+function tokenProfileId(profileId, code, label) {
+  try {
+    return validateAcpProfileId(profileId);
+  } catch {
+    throw new AcpClientError(code, `Invalid ${label}.`);
   }
-  const match = /^acp:v1:([^:]+):([^:]+)$/.exec(providerSessionId);
+}
+
+/**
+ * @param {string} encoded
+ * @param {string} code
+ * @param {string} label
+ */
+function sealedTokenBytes(encoded, code, label) {
+  if (!BASE64URL_RE.test(encoded)) throw new AcpClientError(code, `Invalid ${label}.`);
+  const sealed = Buffer.from(encoded, "base64url");
+  if (sealed.toString("base64url") !== encoded
+    || sealed.byteLength <= NONCE_BYTES + AUTH_TAG_BYTES
+    || sealed.byteLength > MAX_SEALED_TOKEN_BYTES) {
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+  return sealed;
+}
+
+/**
+ * @param {"session"|"cursor"} kind
+ * @param {string} profileId
+ * @param {string} encoded
+ * @param {Uint8Array} key
+ * @param {string} code
+ * @param {string} label
+ */
+function openToken(kind, profileId, encoded, key, code, label) {
+  const sealed = sealedTokenBytes(encoded, code, label);
+  const aad = tokenAad(kind, profileId);
+  const nonce = sealed.subarray(0, NONCE_BYTES);
+  const ciphertext = sealed.subarray(NONCE_BYTES, -AUTH_TAG_BYTES);
+  const authTag = sealed.subarray(-AUTH_TAG_BYTES);
+  const derivedKey = encryptionKey(key);
+  let decipher;
+  try {
+    decipher = createDecipheriv("aes-256-gcm", derivedKey, nonce);
+  } finally {
+    derivedKey.fill(0);
+  }
+  let plaintext;
+  try {
+    decipher.setAAD(aad);
+    decipher.setAuthTag(authTag);
+    plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+  try {
+    return requiredTokenString(
+      new TextDecoder("utf-8", { fatal: true }).decode(plaintext),
+      code,
+      label,
+    );
+  } catch (error) {
+    if (error instanceof AcpClientError) throw error;
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+}
+
+/** @param {string} profileId @param {string} sessionId @param {Uint8Array} key */
+export function encodeAcpProviderSessionId(profileId, sessionId, key) {
+  const encoded = sealToken("session", profileId, sessionId, key, "invalid_session_id", "ACP session id");
+  return `${PROVIDER_SESSION_PREFIX}${profileId}:${encoded}`;
+}
+
+/**
+ * Internal protocol-state decoder. This module is not a package export.
+ * @param {string} providerSessionId
+ * @param {Uint8Array} key
+ */
+export function decodeAcpProviderSessionId(providerSessionId, key) {
+  if (typeof providerSessionId !== "string" || providerSessionId.length > MAX_PROVIDER_SESSION_ID_LENGTH) {
+    throw new AcpClientError("invalid_session_id", "Invalid ACP provider session id.");
+  }
+  const match = /^acp:v2:([^:]+):([^:]+)$/.exec(providerSessionId);
   if (!match) throw new AcpClientError("invalid_session_id", "Invalid ACP provider session id.");
-  const profileId = validateAcpProfileId(match[1]);
-  const sessionId = decodeToken(match[2], "invalid_session_id", "ACP session id");
+  const profileId = tokenProfileId(match[1], "invalid_session_id", "ACP provider session id");
+  const sessionId = openToken(
+    "session",
+    profileId,
+    match[2],
+    key,
+    "invalid_session_id",
+    "ACP provider session id",
+  );
   return { profileId, sessionId };
 }
 
@@ -94,36 +250,33 @@ export function decodeAcpProviderSessionId(providerSessionId) {
  *
  * @param {string} providerSessionId
  * @param {string} expectedProfileId
+ * @param {Uint8Array} key Host-owned 32-byte ACP session-token key.
  * @returns {string}
  */
-export function validateAcpProviderSessionId(providerSessionId, expectedProfileId) {
+export function validateAcpProviderSessionId(providerSessionId, expectedProfileId, key) {
   const profileId = validateAcpProfileId(expectedProfileId);
-  const decoded = decodeAcpProviderSessionId(providerSessionId);
+  const decoded = decodeAcpProviderSessionId(providerSessionId, key);
   if (decoded.profileId !== profileId) {
     throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
   }
   return providerSessionId;
 }
 
-/** @param {string} profileId @param {string} cursor */
-export function encodeAcpSessionCursor(profileId, cursor) {
-  validateAcpProfileId(profileId);
-  requiredTokenString(cursor, "invalid_cursor", "ACP session cursor");
-  if (Buffer.byteLength(cursor, "utf8") > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError("invalid_cursor", `ACP session cursor exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
-  }
-  return `${SESSION_CURSOR_PREFIX}${profileId}:${Buffer.from(cursor, "utf8").toString("base64url")}`;
+/** @param {string} profileId @param {string} cursor @param {Uint8Array} key */
+export function encodeAcpSessionCursor(profileId, cursor, key) {
+  const encoded = sealToken("cursor", profileId, cursor, key, "invalid_cursor", "ACP session cursor");
+  return `${SESSION_CURSOR_PREFIX}${profileId}:${encoded}`;
 }
 
-/** @param {string} profileId @param {unknown} cursor */
-export function decodeAcpSessionCursor(profileId, cursor) {
+/** @param {string} profileId @param {unknown} cursor @param {Uint8Array} key */
+export function decodeAcpSessionCursor(profileId, cursor, key) {
   validateAcpProfileId(profileId);
   if (typeof cursor !== "string" || cursor.length > MAX_SESSION_CURSOR_LENGTH) {
     throw new AcpClientError("invalid_cursor", "ACP session cursor must be an opaque cursor returned by listAcpSessions.");
   }
-  const match = /^acp-cursor:v1:([^:]+):([^:]+)$/.exec(cursor);
-  if (!match || match[1] !== profileId) {
+  const match = /^acp-cursor:v2:([^:]+):([^:]+)$/.exec(cursor);
+  if (!match || tokenProfileId(match[1], "invalid_cursor", "ACP session cursor") !== profileId) {
     throw new AcpClientError("invalid_cursor", "ACP session cursor is invalid for this profile.");
   }
-  return decodeToken(match[2], "invalid_cursor", "ACP session cursor");
+  return openToken("cursor", profileId, match[2], key, "invalid_cursor", "ACP session cursor");
 }

package/src/ai/providers/acp-transport.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { AsyncLocalStorage } from "node:async_hooks";
+
 // Strict, bounded ACP v1 newline transport for an owned stdio child process.
 // The SDK's stock ndJsonStream intentionally tolerates malformed input and its
 // line buffer is unbounded, which is a poor fit for a long-lived host boundary.
@@ -7,6 +9,101 @@
 const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
 const MAX_MAX_LINE_BYTES = 16 * 1024 * 1024;
 
+// @agentclientprotocol/sdk 1.3.0 sends the trailing arguments of these
+// diagnostics directly to console. Those values include raw JSON-RPC payloads
+// (and, for malformed notifications, Zod error details derived from them).
+// Preserve the useful classification while dropping payload-bearing details.
+const ACP_SDK_PAYLOAD_DIAGNOSTICS = Object.freeze({
+  error: new Set([
+    "Invalid message",
+    "Error handling notification",
+    "Got response to unknown request",
+    "Failed to parse JSON message:",
+    "ACP connection router stopped unexpectedly:",
+  ]),
+  warn: new Set([
+    "Skipping JSON line that is not an object:",
+  ]),
+});
+const acpSdkDiagnosticScope = new AsyncLocalStorage();
+let activeAcpSdkDiagnosticGuards = 0;
+/** @type {null|{
+ *   originalError: typeof console.error,
+ *   originalWarn: typeof console.warn,
+ *   guardedError: typeof console.error,
+ *   guardedWarn: typeof console.warn,
+ * }} */
+let acpSdkConsoleGuard = null;
+
+function installAcpSdkConsoleGuard() {
+  activeAcpSdkDiagnosticGuards += 1;
+  if (acpSdkConsoleGuard) return;
+
+  const originalError = console.error;
+  const originalWarn = console.warn;
+  /** @type {typeof console.error} */
+  const guardedError = (...args) => {
+    const contentFree = args[0];
+    if (acpSdkDiagnosticScope.getStore() === true
+      && typeof contentFree === "string"
+      && ACP_SDK_PAYLOAD_DIAGNOSTICS.error.has(contentFree)) {
+      Reflect.apply(originalError, console, [contentFree]);
+      return;
+    }
+    Reflect.apply(originalError, console, args);
+  };
+  /** @type {typeof console.warn} */
+  const guardedWarn = (...args) => {
+    const contentFree = args[0];
+    if (acpSdkDiagnosticScope.getStore() === true
+      && typeof contentFree === "string"
+      && ACP_SDK_PAYLOAD_DIAGNOSTICS.warn.has(contentFree)) {
+      Reflect.apply(originalWarn, console, [contentFree]);
+      return;
+    }
+    Reflect.apply(originalWarn, console, args);
+  };
+
+  acpSdkConsoleGuard = { originalError, originalWarn, guardedError, guardedWarn };
+  console.error = guardedError;
+  console.warn = guardedWarn;
+}
+
+function releaseAcpSdkConsoleGuard() {
+  activeAcpSdkDiagnosticGuards = Math.max(0, activeAcpSdkDiagnosticGuards - 1);
+  if (activeAcpSdkDiagnosticGuards !== 0 || !acpSdkConsoleGuard) return;
+  const guard = acpSdkConsoleGuard;
+  acpSdkConsoleGuard = null;
+  if (console.error === guard.guardedError) console.error = guard.originalError;
+  if (console.warn === guard.guardedWarn) console.warn = guard.originalWarn;
+}
+
+/**
+ * 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(connect) {
+  installAcpSdkConsoleGuard();
+  let connection;
+  try {
+    connection = acpSdkDiagnosticScope.run(true, connect);
+  } catch (error) {
+    releaseAcpSdkConsoleGuard();
+    throw error;
+  }
+  void Promise.resolve(connection.closed).then(
+    releaseAcpSdkConsoleGuard,
+    releaseAcpSdkConsoleGuard,
+  );
+  return connection;
+}
+
 export class AcpTransportError extends Error {
   /**
    * @param {string} code

package/src/ai/providers/acp.js

@@ -11,6 +11,7 @@ import {
   decodeAcpProviderSessionId,
   encodeAcpProviderSessionId,
   validateAcpProviderSessionId,
+  validateAcpSessionTokenKey,
 } from "./acp-session-tokens.js";
 import {
   ownAcpSessionUpdateKind,
@@ -288,8 +289,8 @@ function selectValues(options) {
   return values;
 }
 
-/** @param {any} connection @param {any} descriptor @param {any} req @param {string} profileId @param {(notification:any)=>void} onUpdate */
-async function openSession(connection, descriptor, req, profileId, onUpdate) {
+/** @param {any} connection @param {any} descriptor @param {any} req @param {string} profileId @param {Uint8Array} key @param {(notification:any)=>void} onUpdate */
+async function openSession(connection, descriptor, req, profileId, key, onUpdate) {
   const cwd = workspaceFor(descriptor, req);
   const config = sessionConfig(descriptor);
   const baseRequest = { cwd, ...config };
@@ -297,7 +298,7 @@ async function openSession(connection, descriptor, req, profileId, onUpdate) {
     const response = await connection.newSession(baseRequest);
     return { sessionId: response.sessionId, response, resumed: false, resumeMethod: null };
   }
-  const decoded = decodeAcpProviderSessionId(req.providerSessionId);
+  const decoded = decodeAcpProviderSessionId(req.providerSessionId, key);
   if (decoded.profileId !== profileId) {
     throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
   }
@@ -369,8 +370,13 @@ export async function generateAcpResponse(systemPrompt, req) {
   let setup = null;
   let configuration = { modeApplied: false, configOptionsApplied: [] };
   try {
+    const sessionTokenKey = validateAcpSessionTokenKey(req?.acpSessionTokenKey);
     if (req?.providerSessionId != null) {
-      providerSessionId = validateAcpProviderSessionId(req.providerSessionId, profileId);
+      providerSessionId = validateAcpProviderSessionId(
+        req.providerSessionId,
+        profileId,
+        sessionTokenKey,
+      );
     }
     connection = await connectAcpProfile(profileId, {
       resolveAcpProfile: req.resolveAcpProfile,
@@ -382,6 +388,7 @@ export async function generateAcpResponse(systemPrompt, req) {
       signal: req.abortSignal,
       context: { operation: "run", model: reference },
       operation: "run",
+      acpSessionTokenKey: sessionTokenKey,
     });
     capture({
       type: "capabilities_resolved",
@@ -395,9 +402,18 @@ export async function generateAcpResponse(systemPrompt, req) {
     const onUpdate = (notification) => {
       for (const event of normalizeUpdate(notification, state)) capture(event);
     };
-    setup = await openSession(connection, connection.descriptor, req, profileId, onUpdate);
+    setup = await openSession(
+      connection,
+      connection.descriptor,
+      req,
+      profileId,
+      sessionTokenKey,
+      onUpdate,
+    );
     sessionId = setup.sessionId;
-    providerSessionId = encodeAcpProviderSessionId(profileId, sessionId);
+    providerSessionId = setup.resumed && providerSessionId
+      ? providerSessionId
+      : encodeAcpProviderSessionId(profileId, sessionId, sessionTokenKey);
     configuration = await applyClientConfiguration(
       connection,
       sessionId,

package/src/ai/types.js

@@ -165,6 +165,7 @@
  * @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.
@@ -182,7 +183,7 @@
 
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "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
@@ -364,6 +365,7 @@
  * @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]

package/src/runtime.js

@@ -55,6 +55,7 @@ const HOST_KEYS = [
   "resolvePiApiKey",
   "resolveAcpProfile",
   "onAcpInteractionRequest",
+  "acpSessionTokenKey",
   "persistArtifact",
   "onCompactionRecorded",
   "onToolApprovalRequest",

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

@@ -214,6 +214,10 @@ export type AcpClientHostOptions = {
     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";

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

@@ -1,9 +1,15 @@
 /** @param {string} profileId @returns {string} */
 export function validateAcpProfileId(profileId: string): string;
-/** @param {string} profileId @param {string} sessionId */
-export function encodeAcpProviderSessionId(profileId: string, sessionId: string): string;
-/** Internal protocol-state decoder. This module is not a package export. @param {string} providerSessionId */
-export function decodeAcpProviderSessionId(providerSessionId: 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;
 };
@@ -13,13 +19,14 @@ export function decodeAcpProviderSessionId(providerSessionId: string): {
  *
  * @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): string;
-/** @param {string} profileId @param {string} cursor */
-export function encodeAcpSessionCursor(profileId: string, cursor: string): string;
-/** @param {string} profileId @param {unknown} cursor */
-export function decodeAcpSessionCursor(profileId: string, cursor: unknown): 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

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

@@ -1,3 +1,16 @@
+/**
+ * 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]

package/types/ai/types.d.ts

@@ -136,6 +136,7 @@
  * @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.
@@ -152,7 +153,7 @@
  */
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "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
@@ -322,6 +323,7 @@
  * @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]
@@ -642,6 +644,10 @@ export type RuntimeRunOptions = {
      * Per-run ACP permission/elicitation callback; wins over the host default.
      */
     onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
+    /**
+     * Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
+     */
+    acpSessionTokenKey?: Uint8Array;
     /**
      * Run-scoped WebSearch backend configuration.
      */
@@ -698,7 +704,7 @@ export type RuntimeRunOptions = {
  * createRuntime), and the per-run observerHub (onEvent is overridden to the
  * hub's emit). `systemPrompt` is passed positionally, not folded into this object.
  */
-export type RuntimeRequest = RuntimeRunOptions & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools"> & {
+export type RuntimeRequest = RuntimeRunOptions & 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: {
@@ -975,6 +981,10 @@ export type AgentRuntimeHostOptions = {
      * Default ACP interaction callback; a per-run callback wins.
      */
     onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
+    /**
+     * Default host-owned 32-byte key for confidential authenticated ACP session handles.
+     */
+    acpSessionTokenKey?: Uint8Array;
     persistArtifact?: (artifact: {
         filename: string;
         buffer: Buffer;