@aibolabs/acp-adapter 0.0.0-stage → 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chldu2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @aibolabs/acp-adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic [Agent Client Protocol](https://agentclientprotocol.com) client for Aibo session providers.
+Part of the host SDK from 0.1.2 (`worker` from 0.1.3, option approvals from 0.1.4, form elicitation
+from 0.1.5, package-owned launch from 0.1.6, `parameterScope` from 0.1.7, usage mapping from 0.1.8): plugins declaring `hostSdk` import it at runtime and
+keep it as a development dependency only (see [host SDK](https://github.com/chldu2000/aibo/blob/main/docs/host-sdk.md)).
+
+| Entry | Contents |
+| --- | --- |
+| `@aibolabs/acp-adapter/transport` | `AcpTransport`: NDJSON JSON-RPC to the agent process, bounded frames (8 MiB, 32 MiB prompts), write backpressure, stderr tail, timeouts; every failure settles pending requests |
+| `@aibolabs/acp-adapter/session` | `AcpSession`: initialize/authenticate, new/load, mode and model selection confirmed by the agent, prompts, messages, reasoning, tools, permission requests, cancellation and recovery; `usage_update` and per-turn prompt usage map to the Aibo usage snapshot (`contextTokens`/`contextWindow`, accumulated input/output/total; host SDK 0.1.8) |
+| `@aibolabs/acp-adapter/config` | Parsing of ACP session config options into models, reasoning levels and context windows |
+| `@aibolabs/acp-adapter/image-input` | Validation of host image descriptors into ACP image content blocks |
+| `@aibolabs/acp-adapter/worker` | `serveAcpAgent`: a Runtime 2.1 Worker driven by `plugin.json` plus `acp.json`, or by a code extension; host-tool MCP bridge included |
+
+## Configuration-only plugins
+
+`acp.json` (schema `aibo.acp-agent/v1`) holds `label`, `command` (an `executable` declared in
+`plugin.json` `executableDependencies`), optional `args`, and `modes` mapping Aibo's `ask`, `plan` and `edit` to
+native mode IDs; `edit` is the write mode, and `auto` (SDK 0.1.4) is a second write mode for controls whose
+profile sets `approvalReviewer: "auto-review"`. Optional: `authMethodId`, `clientMeta`, `persistsEmptySessions`
+(default `true`) and `requestPrefix`. The host manifest schema does not allow plugin fields, so this file is
+read only by the Worker; an invalid one stops it before the Runtime handshake. Recovery data uses
+`<pluginId>.recovery`, optional features use the manifest's `<pluginId>.<feature>` operations, and profiles follow
+`agent-managed` execution. Declaring `hostTools` and `aibo.session.tool.respond` connects Aibo's host tools through
+the SDK MCP bridge. See `aibo-plugins/plugins/acp-template`.
+
+`approvalOptions` (SDK 0.1.4) lists native permission options as `{ optionId, toolKind?, label?, sessionControl?, contextReset? }`.
+`label` replaces the agent's text on the approval card; `toolKind` limits the entry to requests for that ACP tool kind.
+`sessionControl` names a `plugin.json` session control that some control lists in `transitions`: the option is offered
+even outside a write mode, and choosing it lets the host commit that control before the agent is answered.
+The Worker rejects entries whose control is undeclared, unmapped in `modes`, or not a transition target, and requires
+the `{ requestId, optionId }` form of `approval.respond`.
+
+`elicitation: true` (SDK 0.1.5; `extension.elicitation` in code) declares ACP form elicitation and claims
+`user-input.respond`, which the manifest must declare. Each form field becomes one host question: selects and
+booleans as options, strings and numbers as validated free text, a multi-select as a single pick, and a
+`_askUserQuestionCustomAnswer` companion as the question's "other" input. Forms the host cannot express
+(nested objects, more than 8 fields, duplicate labels, `url` mode) are cancelled without asking. `contextReset: true` (only with `sessionControl`) marks an
+option after which the agent continues in a fresh context under the same session; the host records it and notes
+on the first later resume that the restored context may predate the reset. The agent's mode report for a committed switch is adopted
+and the turn continues; any other mode change during a turn fails it, and the host mode is restored before the next prompt.
+
+Mode switching uses the agent's mode config option when it returns one, and the standard `session/set_mode`
+request when it only exposes the session modes API. Reasoning and context-window capabilities are claimed only
+when the agent returned those options, unless the extension sets `parameterizedPicker` (Cursor exposes
+parameters per model).
+
+## Writing a provider
+
+An `AcpSession` is configured with an extension object. Required fields:
+
+- `label`: agent name used in error messages (`Cursor` gives `Cursor session is not ready`).
+- `command` / `args`: the agent executable, spawned without a shell in the trusted workspace.
+- `recoverySchema`, `namespace`: recovery data schema and namespace of `extension.updated` events.
+- `writableMode`: the native mode that may run write-authorized turns.
+- `validateExecutionProfile(profile, permissions)`: maps the host execution profile to a native mode.
+
+Optional hooks cover agent differences: `authMethodId`, `clientMeta`, `persistsEmptySessions`, `parameterizedPicker`,
+`commandCategory`, `parameterized`, `subagentFromTool`, `handleRequest` and `handleNotification`
+for vendor methods. Hooks receive a narrow session surface (`event`, `respond`, `await`,
+`updateSubagent`, `subagents`, `turnId`, `sessionId`); the session keeps all other state private.
+
+Client file and terminal capabilities are advertised as unsupported, and only `allow_once` /
+`reject_once` permission options are selected: the host approves each request, and persistent
+agent-side grants are never chosen on the user's behalf. The Cursor plugin in `aibo-plugins`
+is the reference extension.
+
+With `approvalOptions: true` (the Worker sets it when the manifest's `approval.respond` declares
+`optionId`), `approval.requested` carries `options: [{ id, kind: 'allow' | 'reject' }]` for those once options, and
+`respondApproval(requestId, { optionId })` answers with one of them; any other option ID is rejected.
+Extension approvals receive `{ optionId }` instead of `accept` / `cancel`.
+
+`BASE_CAPABILITIES` is a candidate list: `session.resume` is returned only when initialize
+advertises `loadSession: true`. An agent without load support can still create and run sessions;
+restoring a persisted session fails explicitly rather than creating a replacement.
+Vendor questions are not part of the default capability set. An extension implementing question
+requests through `handleRequest` and `await` must add `user-input.respond` to its `capabilities`.
+
+## Package-owned ACP runtime (host SDK 0.1.6)
+
+Instead of an external `command`, a configuration-only plugin can declare:
+
+```json
+{ "launch": { "kind": "node", "entry": "vendor/node_modules/example-acp/dist/index.js" } }
+```
+
+This is a fragment of `acp.json`; label, schema and modes remain required. `command` and `launch`
+are mutually exclusive. `args` are passed after the package entry. The entry is resolved against
+`plugin.json`, checked to remain inside the package, and started with `process.execPath` (the Node
+resolved for the Worker: a local installation, a manual selection or the Aibo-managed download). The child's working directory remains the user workspace. Missing entries fail startup.
+No shell, npm, npx or global executable is needed. External `command` still requires an executable
+manifest dependency. A package launch only needs the Node runtime dependency, plus any genuine external
+tools it uses. Declare `hostSdk >=0.1.6`; ship the locked production dependency graph and platform assets.
+`extensionFromConfig` accepts a third `manifestUrl` argument for package launches.
+
+## Sequential model parameters (host SDK 0.1.7)
+
+Declare `"parameterScope": "current-model"` in `acp.json`, or `parameterScope: 'current-model'`
+in the extension. Use the new `model.select` output contract variant requiring this field.
+The adapter returns it on list and set; options still belong only to the current model.
+The host selects and confirms a model before offering its reasoning options. This adapter does
+not accept `all-models` in acp.json because ACP session configuration is not a complete matrix.
+Omission preserves legacy behavior. Require hostSdk >=0.1.7 for this declaration.

package/config.d.ts

@@ -0,0 +1,8 @@
+export type AcpSelectOption = { value: string; name?: string; description?: string; tokens?: number };
+export declare function selectValues(config: unknown): AcpSelectOption[];
+export declare function modelParameters(configs: readonly unknown[], model: string | undefined): {
+  levels: { id: string; label: string; values: { id: string; value: string }[] }[];
+  current: string | null;
+  context: { id: string; currentValue: string } | null;
+  contextWindows: { id: string; label: string; description?: string; tokens?: number }[];
+};

package/config.mjs

@@ -0,0 +1,25 @@
+// ACP values remain opaque. In particular, labels are not token counts.
+export function selectValues(config) {
+  return (Array.isArray(config?.options) ? config.options : []).flatMap(option => Array.isArray(option?.options) ? option.options : [option])
+    .filter(option => typeof option?.value === 'string' && option.value.length);
+}
+export function modelParameters(configs, model) {
+  const valid = configs.filter(config => config?.type === 'select' && typeof config.id === 'string' && typeof config.currentValue === 'string' && selectValues(config).length);
+  const thoughts = valid.filter(config => config.category === 'thought_level' || (!config.category && ['effort', 'reasoning', 'reasoning_effort', 'thought_level', 'thinking'].includes(config.id)));
+  const contexts = valid.filter(config => config.category === 'model_config' && ['context', 'context_window', 'context_size'].includes(config.id));
+  let combinations = thoughts.length ? [{ values: [], labels: [] }] : [];
+  for (const config of thoughts) {
+    if (combinations.length * selectValues(config).length > 128) { combinations = []; break; }
+    combinations = combinations.flatMap(previous => selectValues(config).map(option => ({
+      values: [...previous.values, { id: config.id, value: option.value }],
+      labels: [...previous.labels, thoughts.length > 1 ? `${config.name || config.id}: ${option.name || option.value}` : option.name || option.value],
+    })));
+  }
+  const levels = combinations.map(({ values, labels }) => ({ id: JSON.stringify([model, values]), label: labels.join(' · '), values }));
+  const current = levels.find(level => level.values.every(value => thoughts.find(config => config.id === value.id)?.currentValue === value.value))?.id ?? null;
+  const context = contexts.length === 1 ? contexts[0] : null;
+  return { levels, current, context, contextWindows: selectValues(context).map(option => ({ id: option.value, label: option.name || option.value,
+    ...(option.description ? { description: option.description } : {}),
+    ...(Number.isSafeInteger(option.tokens) && option.tokens > 0 ? { tokens: option.tokens } : {}),
+  })) };
+}

package/elicitation.mjs

@@ -0,0 +1,125 @@
+// ACP form elicitation (`elicitation/create`, mode `form`) mapped onto host questions. The host
+// question model is one answer per question: an option label, or free text when `isOther` is set.
+// Schemas that model cannot express faithfully return null and the request is cancelled.
+import { pluginError } from './session.mjs';
+
+export const MAX_QUESTIONS = 8;
+const MAX_OPTIONS = 32;
+// Cross-agent marker for a free-text "custom answer" companion to a select question
+// (claude-agent-acp's AskUserQuestion bridge; intentionally not vendor-namespaced).
+const CUSTOM_ANSWER = '_askUserQuestionCustomAnswer';
+const YES = '是', NO = '否';
+
+const text = (value, max) => typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : null;
+
+function choices(values) {
+  if (!Array.isArray(values) || !values.length || values.length > MAX_OPTIONS) return null;
+  const options = values.map(value => value && typeof value === 'object' && !Array.isArray(value)
+    ? { value: value.const, label: text(value.title, 200) ?? (typeof value.const === 'string' ? value.const : null), description: text(value.description, 500) }
+    : { value, label: typeof value === 'string' ? value : null, description: null });
+  if (options.some(option => typeof option.value !== 'string' || !option.label)) return null;
+  // Answers come back as labels, so labels must identify exactly one value.
+  if (new Set(options.map(option => option.label)).size !== options.length) return null;
+  return options;
+}
+
+function field(schema) {
+  const s = schema && typeof schema === 'object' ? schema : {};
+  if (s.type === 'string' && (s.oneOf || s.enum)) {
+    const options = choices(s.oneOf ?? s.enum);
+    return options && { kind: 'choice', options };
+  }
+  if (s.type === 'array') {
+    const items = s.items && typeof s.items === 'object' ? s.items : {};
+    const options = choices(items.anyOf ?? items.oneOf ?? items.enum);
+    // The host submits one answer per question; a form that needs more than one pick cannot be met.
+    if (!options || (s.minItems ?? 0) > 1) return null;
+    return { kind: 'multi', options };
+  }
+  if (s.type === 'boolean') return { kind: 'boolean', options: [{ value: true, label: YES, description: null }, { value: false, label: NO, description: null }] };
+  if (s.type === 'string') return { kind: 'text' };
+  if (s.type === 'number' || s.type === 'integer') return { kind: s.type };
+  return null;
+}
+
+/**
+ * Maps an elicitation form to host questions and an `answer` encoder, or returns null when the
+ * schema cannot be represented. `answer` receives host answers (`{ [questionId]: [value] }`) and
+ * returns the ACP accept response; invalid answers throw `invalid_input` and leave the request pending.
+ */
+export function elicitationForm(params) {
+  const schema = params?.requestedSchema;
+  const message = text(params?.message, 4_000);
+  if (!schema || schema.type !== 'object' || !schema.properties || typeof schema.properties !== 'object' || !message) return null;
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const entries = Object.entries(schema.properties);
+  const companions = new Map();
+  for (const [key, property] of entries) {
+    const target = property?._meta?.[CUSTOM_ANSWER]?.questionId;
+    if (typeof target === 'string' && target !== key && schema.properties[target] && property.type === 'string') companions.set(target, key);
+  }
+  const companionKeys = new Set(companions.values());
+  const fields = [];
+  for (const [key, property] of entries) {
+    if (companionKeys.has(key)) continue;
+    const parsed = field(property);
+    if (!parsed) return null;
+    fields.push({ key, schema: property, required: required.has(key), companion: companions.get(key), ...parsed });
+  }
+  if (!fields.length || fields.length > MAX_QUESTIONS) return null;
+  const single = fields.length === 1;
+  // The host question card has no form-level text, so the message leads the first question.
+  const questions = fields.map((f, index) => {
+    const title = text(f.schema.title, 120), description = text(f.schema.description, 2_000);
+    const own = single ? description : description ?? title ?? f.key;
+    let question = index === 0 ? (own ? `${message}\n\n${own}` : message) : own;
+    if (f.kind === 'multi') question += '\n\n（可多选；aibo 目前每题只能选择一项）';
+    return {
+      id: f.key, header: title, question,
+      options: (f.options ?? []).map(({ label, description }) => ({ label, description })),
+      isOther: !f.options || f.companion !== undefined,
+    };
+  });
+
+  function answer(answers) {
+    if (!answers || typeof answers !== 'object' || Object.keys(answers).some(id => !fields.some(f => f.key === id))) throw pluginError('invalid_input', 'Answer names an unknown question');
+    const content = {};
+    for (const f of fields) {
+      const values = answers[f.key];
+      const value = Array.isArray(values) && values.length === 1 && typeof values[0] === 'string' ? values[0].trim() : Array.isArray(values) && values.length === 0 ? '' : null;
+      if (value === null) throw pluginError('invalid_input', `Question ${f.key} takes one answer`);
+      if (!value) { if (f.required) throw pluginError('invalid_input', `Question ${f.key} is required`); continue; }
+      const option = f.options?.find(candidate => candidate.label === value);
+      if (option) { content[f.key] = f.kind === 'multi' ? [option.value] : option.value; continue; }
+      if (f.companion) {
+        // Typed text answers through the companion field; a required select still needs a pick.
+        if (f.required) throw pluginError('invalid_input', `Question ${f.key} requires one of its options`);
+        content[f.companion] = value; continue;
+      }
+      if (f.options) throw pluginError('invalid_input', `Question ${f.key} requires one of its options`);
+      if (f.kind === 'text') { content[f.key] = checkText(f, value); continue; }
+      content[f.key] = checkNumber(f, value);
+    }
+    return { action: 'accept', content };
+  }
+  return { title: single ? null : message, questions, answer };
+}
+
+function checkText(f, value) {
+  const s = f.schema, invalid = () => pluginError('invalid_input', `Question ${f.key} answer does not match its format`);
+  if ((s.minLength !== undefined && value.length < s.minLength) || (s.maxLength !== undefined && value.length > s.maxLength)) throw invalid();
+  if (s.format === 'email' && !/^[^\s@]+@[^\s@]+$/.test(value)) throw invalid();
+  if (s.format === 'uri' && !URL.canParse(value)) throw invalid();
+  if (s.format === 'date' && !/^\d{4}-\d{2}-\d{2}$/.test(value)) throw invalid();
+  if (s.format === 'date-time' && Number.isNaN(Date.parse(value))) throw invalid();
+  return value;
+}
+
+function checkNumber(f, value) {
+  const s = f.schema, number = Number(value);
+  if (!/^-?\d+(\.\d+)?(e[+-]?\d+)?$/i.test(value) || !Number.isFinite(number) || (f.kind === 'integer' && !Number.isInteger(number))
+    || (s.minimum !== undefined && number < s.minimum) || (s.maximum !== undefined && number > s.maximum)) {
+    throw pluginError('invalid_input', `Question ${f.key} needs ${f.kind === 'integer' ? 'an integer' : 'a number'}${s.minimum !== undefined || s.maximum !== undefined ? ` in range ${s.minimum ?? '-∞'}–${s.maximum ?? '∞'}` : ''}`);
+  }
+  return number;
+}

package/image-input.d.ts

@@ -0,0 +1,2 @@
+/** Validates host image descriptors and returns ACP image content blocks. `label` names the agent in errors. */
+export declare function imageInput(attachments?: readonly unknown[], supported?: boolean, label?: string): { type: 'image'; mimeType: string; data: string }[];

package/image-input.mjs

@@ -0,0 +1,34 @@
+import { openSync, fstatSync, readSync, closeSync, constants } from 'node:fs';
+import { isAbsolute } from 'node:path';
+const MAX_IMAGE = 10 * 1024 * 1024, MAX_TOTAL = 20 * 1024 * 1024;
+const invalid = message => Object.assign(new Error(message), { kind:'invalid_input' });
+/** Only host-expanded image descriptors contain paths; ordinary references stay in prompt text. */
+/** `label` names the agent in error messages. */
+export function imageInput(attachments = [], supported = false, label = 'ACP') {
+  if (!Array.isArray(attachments)) throw invalid(`Invalid ${label} attachments`);
+  const images = attachments.filter(item => {
+    if (!item || typeof item.attachmentId !== 'string' || (item.type !== undefined && item.type !== 'image')) throw invalid(`Invalid ${label} attachment descriptor`);
+    return item.type === 'image';
+  });
+  if (images.length && !supported) throw Object.assign(new Error(`This ${label} CLI does not advertise image input`), { kind:'unsupported' });
+  if (images.length > 8) throw invalid('At most 8 images can be sent together');
+  let total = 0;
+  return images.map(item => {
+    if (typeof item.path !== 'string' || !isAbsolute(item.path) || !['image/png','image/jpeg','image/gif','image/webp'].includes(item.mimeType)) throw invalid(`Invalid ${label} image descriptor`);
+    const fd = openSync(item.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || !stat.size || stat.size > MAX_IMAGE || (total += stat.size) > MAX_TOTAL) throw invalid('Image size limit exceeded (10 MiB per image, 20 MiB total)');
+      const bytes = Buffer.alloc(stat.size);
+      let offset = 0;
+      while (offset < bytes.length) { const count = readSync(fd, bytes, offset, bytes.length-offset, offset); if (!count) throw invalid('Image changed while reading'); offset += count; }
+      if (fstatSync(fd).size !== stat.size) throw invalid('Image changed while reading');
+      const valid = item.mimeType === 'image/png' ? bytes.subarray(0,8).equals(Buffer.from('89504e470d0a1a0a','hex'))
+        : item.mimeType === 'image/jpeg' ? bytes.subarray(0,3).equals(Buffer.from('ffd8ff','hex'))
+        : item.mimeType === 'image/gif' ? ['GIF87a','GIF89a'].includes(bytes.subarray(0,6).toString())
+        : bytes.subarray(0,4).toString() === 'RIFF' && bytes.subarray(8,12).toString() === 'WEBP';
+      if (!valid) throw invalid('Image bytes do not match the declared media type');
+      return { type:'image', mimeType:item.mimeType, data:bytes.toString('base64') };
+    } finally { closeSync(fd); }
+  });
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from './session.js';
+export * from './transport.js';
+export * from './config.js';
+export * from './image-input.js';

package/index.mjs

@@ -0,0 +1,4 @@
+export { AcpSession, BASE_CAPABILITIES, pluginError, object, bounded } from './session.mjs';
+export { AcpTransport } from './transport.mjs';
+export { modelParameters, selectValues } from './config.mjs';
+export { imageInput } from './image-input.mjs';

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@aibolabs/acp-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.8",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chldu2000/aibo.git",
+    "directory": "packages/acp-adapter"
+  },
+  "type": "module",
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "session.mjs",
+    "session.d.ts",
+    "transport.mjs",
+    "transport.d.ts",
+    "config.mjs",
+    "config.d.ts",
+    "image-input.mjs",
+    "image-input.d.ts",
+    "elicitation.mjs",
+    "worker.mjs",
+    "worker.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    },
+    "./session": {
+      "types": "./session.d.ts",
+      "import": "./session.mjs"
+    },
+    "./transport": {
+      "types": "./transport.d.ts",
+      "import": "./transport.mjs"
+    },
+    "./config": {
+      "types": "./config.d.ts",
+      "import": "./config.mjs"
+    },
+    "./image-input": {
+      "types": "./image-input.d.ts",
+      "import": "./image-input.mjs"
+    },
+    "./worker": {
+      "types": "./worker.d.ts",
+      "import": "./worker.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@aibolabs/capability-runtime": "0.1.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/session.d.ts

@@ -0,0 +1,83 @@
+import type { AcpTransport } from './transport.js';
+
+export declare const BASE_CAPABILITIES: readonly string[];
+export declare function pluginError(kind: string, message: string): Error & { kind: string };
+export declare function object(value: unknown): Record<string, any>;
+export declare function bounded(value: unknown, max?: number): string;
+
+/** The narrow session surface extension hooks may use. */
+export type AcpSessionHooks = {
+  readonly label: string;
+  readonly sessionId: string | null | undefined;
+  readonly turnId: string | null | undefined;
+  readonly subagents: Map<string, Record<string, any>>;
+  event(type: string, payload: unknown, correlation?: unknown): void;
+  respond(id: string | number, result: unknown): void;
+  /** Registers a pending interaction; answers `cancelled` and returns false once 32 are waiting. */
+  await(requestId: string, rpcId: string | number, interaction:
+    | { kind: 'question'; answer(answers: unknown): unknown; [key: string]: unknown }
+    | { kind: string; approve(decision: 'accept' | 'cancel'): unknown; [key: string]: unknown }): boolean;
+  updateSubagent(subagent: Record<string, any>, changes?: Record<string, any>): void;
+};
+
+export type AcpExtension = {
+  /** Agent name used in error messages; the transport uses `${label} ACP`. */
+  label: string;
+  command: string;
+  args?: string[];
+  clientName?: string;
+  clientMeta?: Record<string, unknown>;
+  /** When set, the agent must advertise it and `authenticate` runs before new/load. */
+  authMethodId?: string;
+  recoverySchema: string;
+  /** Namespace of `extension.updated` events for unrecognized updates. */
+  namespace: string;
+  requestPrefix?: string;
+  /** Candidate capabilities, narrowed by native negotiation. Declare user-input.respond only with a question handler. */
+  capabilities?: readonly string[];
+  /** Native mode that performs writes; only it may run write-authorized turns. */
+  writableMode: string;
+  /** All native modes that may run write-authorized turns (for example Manual and Auto); defaults to `[writableMode]`. */
+  writableModes?: readonly string[];
+  persistsEmptySessions?: boolean;
+  /** SDK 0.1.7: parameters are discovered after selecting a model. */
+  parameterScope?: 'current-model';
+  validateExecutionProfile(profile: unknown, permissions: readonly string[]): { mode: string; profile: Record<string, any> };
+  commandCategory?(command: Record<string, any>): string;
+  parameterized?(config: Record<string, any>, result: Record<string, any>): boolean;
+  /** Approval events carry `options` and replies select one by `optionId` (approval.respond option variant). */
+  approvalOptions?: boolean;
+  /**
+   * Native options shown with a host label, optionally scoped to an ACP tool kind. An option with
+   * `sessionControl` is offered even outside writable modes; the host commits that control before the
+   * agent is answered, and the matching `current_mode_update` to `mode` is adopted with `profile`.
+   * Any other native mode change during a turn fails the turn. `contextReset` marks options after
+   * which the agent continues in a fresh context under the same native session.
+   */
+  /** Declare ACP form elicitation and ask its questions through `user-input.respond`. */
+  elicitation?: boolean;
+  approvalChoices?: readonly { optionId: string; toolKind?: string; label?: string; sessionControl?: string; contextReset?: boolean; mode?: string; profile?: Record<string, unknown> }[];
+  /** The agent exposes parameters per model: claim reasoning and context-window even when the current model has none. */
+  parameterizedPicker?: boolean;
+  subagentFromTool?(update: Record<string, any>): { name: string; task: string; activity: string; [key: string]: unknown } | null;
+  handleRequest?(session: AcpSessionHooks, message: Record<string, any>, params: Record<string, any>, requestId: string): boolean;
+  handleNotification?(session: AcpSessionHooks, message: Record<string, any>): boolean;
+};
+
+export declare class AcpSession {
+  constructor(options: { extension: AcpExtension; transportFactory?: (options: { cwd: string }) => AcpTransport; emit?: (event: unknown) => void; pluginVersion?: string; cancelGraceMs?: number; commandWaitMs?: number });
+  readonly sessionId: string | null | undefined;
+  hostToolsRegistered?: boolean;
+  open(options: { mode: 'create' | 'resume'; workspaceId: string; workspacePath: string; executionProfile: unknown; recovery?: unknown; permissions: readonly string[]; mcpServers?: unknown[]; hostMcpTools?: { providerIdentifier: string; toolName: string }[] }): Promise<{ nativeSessionId: string; recovery: unknown; capabilities: string[] }>;
+  prompt(options: { text: string; turnId: string; attachments?: unknown[]; additionalInstructions?: string; writable?: boolean }): Promise<{ status: 'completed' | 'interrupted' | 'failed'; recovery: unknown }>;
+  cancel(): Promise<{ accepted: true }>;
+  respondApproval(requestId: string, answer: 'accept' | 'cancel' | { optionId: string }): { resolved: true; recovery: unknown; capabilities: string[] };
+  respondUserInput(requestId: string, answers: unknown): { resolved: true; recovery: unknown; capabilities: string[] };
+  capabilities(): string[];
+  commands(): Promise<{ commands: Record<string, any>[] }>;
+  configure(kind: 'reasoning' | 'context', input: Record<string, any>): Promise<Record<string, any>>;
+  models(input: Record<string, any>): Promise<Record<string, any>>;
+  snapshot(): { nativeSessionId: string; recovery: unknown; capabilities: string[] };
+  recovery(): unknown;
+  close(): Promise<{ accepted: true }>;
+}