@aibolabs/acp-adapter 0.0.0-stage → 0.1.8

package/transport.d.ts

@@ -0,0 +1,15 @@
+export type AcpMessage = { jsonrpc: '2.0'; id?: string | number; method?: string; params?: unknown; result?: unknown; error?: { code: number; message: string; data?: unknown } };
+export declare class AcpTransport {
+  constructor(options: { command: string; args?: string[]; cwd?: string; spawnProcess?: typeof import('node:child_process').spawn; requestTimeoutMs?: number; label?: string });
+  readonly label: string;
+  readonly closed: boolean;
+  readonly stderr: string;
+  start(): this;
+  onRequest(handler: (message: AcpMessage) => boolean | void): () => void;
+  onNotification(handler: (message: AcpMessage) => void): () => void;
+  request(method: string, params: unknown, timeoutMs?: number): Promise<any>;
+  notify(method: string, params: unknown): void;
+  respond(id: string | number, result: unknown): void;
+  respondError(id: string | number, code: number, message: string): void;
+  close(options?: { forceAfterMs?: number }): Promise<void>;
+}

package/transport.mjs

@@ -0,0 +1,191 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_PROMPT_BYTES = 32 * 1024 * 1024;
+const MAX_STDERR_BYTES = 64 * 1024;
+
+/**
+ * NDJSON JSON-RPC transport to an ACP agent process. Bounded frames, write backpressure
+ * and a stderr tail; every failure settles pending requests and emits `transport/closed`.
+ * `label` names the agent in error messages (for example "Cursor ACP").
+ */
+export class AcpTransport {
+  constructor({ command, args = [], cwd, spawnProcess = spawn, requestTimeoutMs = 30_000, label = 'ACP' } = {}) {
+    if (typeof command !== 'string' || !command) throw new Error('ACP transport requires an agent command');
+    this.label = label;
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+    this.spawnProcess = spawnProcess;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.requestHandlers = new Set();
+    this.notificationHandlers = new Set();
+    this.stderr = '';
+    this.closed = false;
+    this.decoder = new StringDecoder('utf8');
+    this.readBuffer = '';
+    this.writeQueue = [];
+    this.queuedWriteBytes = 0;
+    this.writePaused = false;
+  }
+
+  start() {
+    if (this.child) throw new Error(`${this.label} process already started`);
+    const child = this.spawnProcess(this.command, this.args, {
+      cwd: this.cwd,
+      env: process.env,
+      shell: false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child = child;
+    child.stdout.on('data', chunk => this.#receiveData(chunk));
+    child.stdout.once('end', () => {
+      const tail = this.decoder.end();
+      if (tail) this.#receiveData(tail);
+      if (!this.closed && this.readBuffer.length) this.#receiveLine(this.readBuffer.replace(/\r$/, ''));
+      this.readBuffer = '';
+      if (!this.closed) this.#finish(new Error(`${this.label} stdout closed`));
+    });
+    child.stdout.once('error', error => this.#finish(error));
+    child.stdin.once('error', error => this.#finish(error));
+    child.stdin.on('drain', () => this.#flushWrites());
+    child.stderr.on('data', chunk => {
+      this.stderr = `${this.stderr}${String(chunk)}`.slice(-MAX_STDERR_BYTES);
+    });
+    child.once('error', error => this.#finish(error));
+    child.once('exit', (code, signal) => {
+      const detail = this.stderr.trim().slice(-2_000);
+      this.#finish(new Error(`${this.label} exited (${signal ?? code ?? 'unknown'})${detail ? `: ${detail}` : ''}`), false);
+    });
+    return this;
+  }
+
+  onRequest(handler) { this.requestHandlers.add(handler); return () => this.requestHandlers.delete(handler); }
+  onNotification(handler) { this.notificationHandlers.add(handler); return () => this.notificationHandlers.delete(handler); }
+
+  request(method, params, timeoutMs = this.requestTimeoutMs) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${this.label} ${method} timed out`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, method });
+      try { this.#write({ jsonrpc: '2.0', id, method, params }); }
+      catch (error) { clearTimeout(timer); this.pending.delete(id); reject(error); }
+    });
+  }
+
+  notify(method, params) { this.#write({ jsonrpc: '2.0', method, params }); }
+  respond(id, result) { this.#write({ jsonrpc: '2.0', id, result }); }
+  respondError(id, code, message) { this.#write({ jsonrpc: '2.0', id, error: { code, message } }); }
+
+  async close({ forceAfterMs = 2_000 } = {}) {
+    if (!this.child || this.closed) return;
+    this.closed = true;
+    this.readBuffer = '';
+    this.writeQueue.length = 0;
+    this.queuedWriteBytes = 0;
+    this.child.stdin.end();
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    this.child.kill('SIGTERM');
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { this.child?.kill('SIGKILL'); resolve(); }, forceAfterMs);
+      this.child?.once('exit', () => { clearTimeout(timer); resolve(); });
+    });
+    this.#rejectPending(new Error(`${this.label} transport closed`));
+  }
+
+  #write(message) {
+    if (!this.child || this.closed || !this.child.stdin.writable) throw new Error(`${this.label} transport is not writable`);
+    const frame = `${JSON.stringify(message)}\n`;
+    const bytes = Buffer.byteLength(frame);
+    const limit = message.method === 'session/prompt' ? MAX_PROMPT_BYTES : MAX_FRAME_BYTES;
+    if (bytes > limit) throw new Error(`${this.label} frame exceeds ${limit / 1024 / 1024} MiB`);
+    if (this.writePaused) {
+      if (this.queuedWriteBytes + bytes > MAX_PROMPT_BYTES) throw new Error(`${this.label} write queue exceeds 32 MiB`);
+      this.writeQueue.push(frame);
+      this.queuedWriteBytes += bytes;
+      return;
+    }
+    this.writePaused = !this.child.stdin.write(frame);
+  }
+
+  #flushWrites() {
+    if (this.closed || !this.child?.stdin.writable) return;
+    this.writePaused = false;
+    while (!this.writePaused && this.writeQueue.length) {
+      const frame = this.writeQueue.shift();
+      this.queuedWriteBytes -= Buffer.byteLength(frame);
+      this.writePaused = !this.child.stdin.write(frame);
+    }
+  }
+
+  #receiveData(chunk) {
+    if (this.closed) return;
+    this.readBuffer += typeof chunk === 'string' ? chunk : this.decoder.write(chunk);
+    if (Buffer.byteLength(this.readBuffer) > MAX_FRAME_BYTES && !this.readBuffer.includes('\n')) {
+      this.#finish(new Error(`${this.label} frame exceeds 8 MiB`));
+      return;
+    }
+    let newline;
+    while (!this.closed && (newline = this.readBuffer.indexOf('\n')) >= 0) {
+      const line = this.readBuffer.slice(0, newline).replace(/\r$/, '');
+      this.readBuffer = this.readBuffer.slice(newline + 1);
+      this.#receiveLine(line);
+    }
+    if (!this.closed && Buffer.byteLength(this.readBuffer) > MAX_FRAME_BYTES) this.#finish(new Error(`${this.label} frame exceeds 8 MiB`));
+  }
+
+  #receiveLine(line) {
+    if (Buffer.byteLength(line) > MAX_FRAME_BYTES) return this.#finish(new Error(`${this.label} frame exceeds 8 MiB`));
+    let message;
+    try { message = JSON.parse(line); }
+    catch { return this.#finish(new Error(`${this.label} emitted malformed JSON`)); }
+    if (message?.jsonrpc !== '2.0') return this.#finish(new Error(`${this.label} emitted an invalid JSON-RPC envelope`));
+    if (message.id !== undefined && message.method === undefined) {
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(Object.assign(new Error(message.error.message ?? `${pending.method} failed`), { code: message.error.code, data: message.error.data }));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (typeof message.method !== 'string') return;
+    if (message.id !== undefined) {
+      try {
+        for (const handler of this.requestHandlers) if (handler(message) === true) return;
+      } catch (error) {
+        this.respondError(message.id, -32603, String(error?.message ?? error).slice(0, 2_000));
+        return;
+      }
+      this.respondError(message.id, -32601, 'Method not found');
+      return;
+    }
+    try { for (const handler of this.notificationHandlers) handler(message); }
+    catch (error) { this.#finish(error instanceof Error ? error : new Error(String(error))); }
+  }
+
+  #finish(error, terminate = true) {
+    if (this.closed && !this.pending.size) return;
+    this.closed = true;
+    this.readBuffer = '';
+    this.writeQueue.length = 0;
+    this.queuedWriteBytes = 0;
+    if (terminate && this.child && this.child.exitCode === null && this.child.signalCode === null) this.child.kill('SIGTERM');
+    this.#rejectPending(error);
+    for (const handler of this.notificationHandlers) {
+      try { handler({ jsonrpc: '2.0', method: 'transport/closed', params: { message: error.message } }); }
+      catch { /* transport is already terminal */ }
+    }
+  }
+
+  #rejectPending(error) {
+    for (const request of this.pending.values()) { clearTimeout(request.timer); request.reject(error); }
+    this.pending.clear();
+  }
+}

package/worker.d.ts

@@ -0,0 +1,26 @@
+import type { AcpExtension, AcpSession } from './session.js';
+
+export declare const ACP_AGENT_SCHEMA: 'aibo.acp-agent/v1';
+/** Contents of a configuration-only plugin's `acp.json`. */
+export type AcpAgentConfig = {
+  schema: 'aibo.acp-agent/v1';
+  label: string;
+  /** Must name an `executable` entry of plugin.json `executableDependencies`. */
+  command?: string;
+  /** SDK 0.1.6: plugin-relative JS entry, executed by the Worker's private Node. Mutually exclusive with command. */
+  launch?: { kind: 'node'; entry: string };
+  args?: string[];
+  /** Native mode IDs for host interaction modes; `edit` is the write mode. */
+  modes: { ask?: string; plan?: string; edit?: string };
+  authMethodId?: string;
+  clientMeta?: Record<string, unknown>;
+  persistsEmptySessions?: boolean;
+  /** SDK 0.1.7: parameters are discovered after selecting a model. */
+  parameterScope?: 'current-model';
+  requestPrefix?: string;
+};
+export declare function acpAgentConfig(config: unknown, manifest: Record<string, any>): AcpAgentConfig & { args: string[] };
+export declare function agentManagedProfile(label: string, modes: AcpAgentConfig['modes']): AcpExtension['validateExecutionProfile'];
+export declare function extensionFromConfig(config: AcpAgentConfig & { args: string[] }, manifest: Record<string, any>, manifestUrl?: URL): AcpExtension;
+export declare function settingsInstructions(label: string): (settings: unknown) => string;
+export declare function serveAcpAgent(options: { manifestUrl: URL; configUrl?: URL; extension?: AcpExtension; additionalInstructions?: (settings: unknown) => string }): AcpSession;

package/worker.mjs

@@ -0,0 +1,253 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { serveCapability } from '@aibolabs/capability-runtime/stdio';
+import { createHostToolChannel, hostToolDefinitions, createHostToolMcpBridge } from '@aibolabs/capability-runtime/host-tools';
+import { AcpSession, BASE_CAPABILITIES, object, pluginError } from './session.mjs';
+
+export const ACP_AGENT_SCHEMA = 'aibo.acp-agent/v1';
+// `auto` is the edit mode reviewed by the agent's own classifier (approvalReviewer auto-review).
+const INTERACTIONS = ['ask', 'plan', 'edit', 'auto'];
+
+/**
+ * Validates a plugin's `acp.json` against its manifest. Invalid configuration stops the Worker
+ * before the Runtime handshake, so the host reports a startup failure instead of a broken session.
+ */
+export function acpAgentConfig(config, manifest) {
+  const c = object(config);
+  const fail = message => { throw new Error(`Invalid acp.json: ${message}`); };
+  if (c.schema !== ACP_AGENT_SCHEMA) fail(`schema must be ${ACP_AGENT_SCHEMA}`);
+  if (typeof c.label !== 'string' || !c.label.trim() || c.label.length > 64) fail('label must be 1-64 characters');
+  const dependencies = Array.isArray(manifest.executableDependencies) ? manifest.executableDependencies : [];
+  // An external command or a plugin-owned JS entry, never both.
+  if (c.launch !== undefined) {
+    const launch = object(c.launch);
+    if (c.command !== undefined || launch.kind !== 'node' || Object.keys(launch).some(key => !['kind', 'entry'].includes(key))) fail('launch must be { kind: node, entry } without command');
+    if (typeof launch.entry !== 'string' || launch.entry.length > 1024 || /[\\\\:\x00-\x1f]/.test(launch.entry)
+        || launch.entry.split('/').some(part => !part || part === '.' || part === '..' || /[. ]$/.test(part))
+        || !/\.(mjs|cjs|js)$/.test(launch.entry)) fail('launch.entry must be a package-relative JavaScript path');
+  } else if (typeof c.command !== 'string' || !dependencies.some(entry => entry?.kind === 'executable' && entry.name === c.command)) fail('command must name an executable declared in plugin.json executableDependencies');
+  const args = c.args ?? [];
+  if (!Array.isArray(args) || args.length > 32 || !args.every(arg => typeof arg === 'string' && arg.length <= 1024)) fail('args must be at most 32 strings');
+  const modes = object(c.modes);
+  const mapped = INTERACTIONS.filter(interaction => modes[interaction] !== undefined);
+  if (!mapped.length || Object.keys(modes).some(key => !INTERACTIONS.includes(key)) || !mapped.every(interaction => typeof modes[interaction] === 'string' && modes[interaction])) fail('modes must map ask, plan, edit or auto to native mode IDs');
+  if (c.authMethodId !== undefined && (typeof c.authMethodId !== 'string' || !c.authMethodId)) fail('authMethodId must be a non-empty string');
+  if (c.clientMeta !== undefined && (!c.clientMeta || typeof c.clientMeta !== 'object' || Array.isArray(c.clientMeta) || JSON.stringify(c.clientMeta).length > 8192)) fail('clientMeta must be an object under 8 KiB');
+  if (c.parameterScope !== undefined && c.parameterScope !== 'current-model') fail('parameterScope must be current-model for ACP session options');
+  if (c.persistsEmptySessions !== undefined && typeof c.persistsEmptySessions !== 'boolean') fail('persistsEmptySessions must be a boolean');
+  if (c.requestPrefix !== undefined && !/^[a-z][a-z0-9-]{0,31}$/.test(c.requestPrefix)) fail('requestPrefix must be a lowercase identifier');
+  if (c.elicitation !== undefined && c.elicitation !== true) fail('elicitation must be true when present');
+  const contribution = manifest.contributions?.find(entry => entry.kind === 'capabilityProvider' && entry.scope === 'session');
+  // Answering elicitations is the manifest's user-input.respond operation; without it the agent is never asked.
+  if (c.elicitation && !contribution?.operations?.some(operation => operation.capability?.id === `${manifest.pluginId}.user-input.respond`)) fail('elicitation requires the user-input.respond operation in plugin.json');
+  const approvalOptions = c.approvalOptions ?? [];
+  const controls = manifest.contributions?.find(entry => entry.kind === 'capabilityProvider' && entry.scope === 'session')?.sessionControls ?? [];
+  if (!Array.isArray(approvalOptions) || approvalOptions.length > 16) fail('approvalOptions must be at most 16 entries');
+  for (const entry of approvalOptions) {
+    const option = object(entry);
+    if (Object.keys(option).some(key => !['optionId', 'toolKind', 'label', 'sessionControl', 'contextReset'].includes(key))) fail('approvalOptions entries take optionId, toolKind, label, sessionControl and contextReset');
+    if (option.contextReset !== undefined && (option.contextReset !== true || option.sessionControl === undefined)) fail('approvalOptions contextReset must be true and needs a sessionControl');
+    if (typeof option.optionId !== 'string' || !option.optionId || option.optionId.length > 256) fail('approvalOptions optionId must be a native option ID');
+    if (option.toolKind !== undefined && (typeof option.toolKind !== 'string' || !option.toolKind)) fail('approvalOptions toolKind must be an ACP tool kind');
+    if (option.label !== undefined && (typeof option.label !== 'string' || !option.label.trim() || option.label.length > 80)) fail('approvalOptions label must be 1-80 characters');
+    if (option.label === undefined && option.sessionControl === undefined) fail('approvalOptions entries need a label or a sessionControl');
+    if (option.sessionControl !== undefined) {
+      const control = controls.find(candidate => candidate.id === option.sessionControl);
+      if (!control) fail(`approvalOptions sessionControl ${option.sessionControl} is not declared in plugin.json`);
+      if (!modes[controlInteraction(control.profile)]) fail(`approvalOptions sessionControl ${option.sessionControl} has no mapped native mode`);
+      if (!controls.some(candidate => candidate.transitions?.includes(option.sessionControl))) fail(`no session control declares a transition to ${option.sessionControl}`);
+    }
+  }
+  return { ...c, args, modes, approvalOptions };
+}
+
+/** The `modes` key a session control profile runs in: Auto is edit reviewed by the agent. */
+function controlInteraction(profile) {
+  const p = object(profile);
+  return p.interactionMode === 'edit' && p.approvalReviewer === 'auto-review' ? 'auto' : p.interactionMode;
+}
+
+/**
+ * Host execution profiles for agent-managed providers: the native mode owns file, command and
+ * network permissions; edit asks the user on request, ask/plan are read-only without approvals.
+ */
+export function agentManagedProfile(label, modes) {
+  return (profile, permissions) => {
+    const p = object(profile);
+    if (p.schema !== 'aibo.execution-profile/v1') throw pluginError('invalid_input', `${label} requires execution profile v1`);
+    const mode = modes[controlInteraction(p)];
+    if (!mode) throw pluginError('invalid_input', `${label} requires a supported interaction mode`);
+    if (!permissions.includes('workspace.read')) throw pluginError('permission_denied', `${label} requires workspace.read`);
+    if (p.model != null && (typeof p.model !== 'string' || !p.model.trim())) throw pluginError('invalid_input', `${label} model must be a non-empty reference`);
+    if (p.reasoningEffort != null && (typeof p.reasoningEffort !== 'string' || !p.reasoningEffort)) throw pluginError('invalid_input', `${label} reasoning selection must be a non-empty ID`);
+    if (p.interactionMode === 'edit') {
+      if (p.filesystemPolicy !== 'agent-managed' || p.commandPolicy !== 'agent-managed') throw pluginError('unsupported', `${label} edit mode requires provider-managed file and command permissions`);
+      if (!['user', 'auto-review'].includes(p.approvalReviewer) || p.approvalPolicy !== 'on-request') throw pluginError('unsupported', `${label} edit mode requires on-request approval`);
+    } else if (p.filesystemPolicy !== 'read-only' || p.commandPolicy !== 'disabled' || p.approvalPolicy !== 'never' || p.approvalReviewer !== 'none') {
+      throw pluginError('unsupported', `${label} ask and plan modes require read-only files, disabled commands, and no approvals`);
+    }
+    if (p.networkPolicy !== 'agent-managed') throw pluginError('unsupported', `${label} requires provider-managed network permissions`);
+    return { mode, profile: p };
+  };
+}
+
+/** Builds the session extension a configuration-only plugin runs with. */
+export function extensionFromConfig(config, manifest, manifestUrl) {
+  let command = config.command, args = config.args;
+  if (config.launch) {
+    if (!manifestUrl) throw new Error('Package launch requires manifestUrl');
+    const root = realpathSync(path.dirname(fileURLToPath(manifestUrl)));
+    const entry = realpathSync(path.join(root, config.launch.entry));
+    const relative = path.relative(root, entry);
+    if (relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative) || !statSync(entry).isFile()) throw new Error('ACP launch entry escapes plugin package');
+    command = process.execPath;
+    args = [entry, ...args];
+  }
+  return {
+    label: config.label,
+    command,
+    args,
+    authMethodId: config.authMethodId,
+    clientMeta: config.clientMeta,
+    parameterScope: config.parameterScope,
+    persistsEmptySessions: config.persistsEmptySessions ?? true,
+    requestPrefix: config.requestPrefix ?? 'acp',
+    recoverySchema: `${manifest.pluginId}.recovery`,
+    namespace: manifest.pluginId,
+    capabilities: BASE_CAPABILITIES,
+    // A plugin without an edit mapping never runs write-authorized turns.
+    writableMode: config.modes.edit ?? null,
+    writableModes: [config.modes.edit, config.modes.auto].filter(Boolean),
+    validateExecutionProfile: agentManagedProfile(config.label, config.modes),
+    approvalChoices: approvalChoices(config, manifest),
+    elicitation: config.elicitation === true,
+  };
+}
+
+/** Resolves `approvalOptions` to the native mode and profile patch each session-control effect selects. */
+function approvalChoices(config, manifest) {
+  const controls = manifest.contributions.find(entry => entry.kind === 'capabilityProvider' && entry.scope === 'session')?.sessionControls ?? [];
+  return (config.approvalOptions ?? []).map(({ optionId, toolKind, label, sessionControl, contextReset }) => {
+    const control = sessionControl && controls.find(candidate => candidate.id === sessionControl);
+    return { optionId, toolKind, label, ...(control ? { sessionControl, contextReset: contextReset === true, mode: config.modes[controlInteraction(control.profile)], profile: control.profile } : {}) };
+  });
+}
+
+/** Per-turn additional instructions from the optional `additionalInstructions` setting. */
+export function settingsInstructions(label) {
+  return settings => {
+    if (settings == null) return '';
+    const value = object(settings), values = object(value.values);
+    if (value.schema !== 'aibo.agent-settings/v1' || value.version !== 1) throw pluginError('invalid_input', `${label} received invalid agent settings`);
+    if (values.additionalInstructions === undefined) return '';
+    if (typeof values.additionalInstructions !== 'string' || values.additionalInstructions.length > 8_000) throw pluginError('invalid_input', `${label} received invalid agent settings`);
+    return values.additionalInstructions;
+  };
+}
+
+/**
+ * Serves an ACP agent as an Aibo Runtime 2.1 session provider. Optional features use the
+ * manifest's `<pluginId>.<feature>` capability IDs. Configuration-only plugins pass `configUrl`
+ * (`acp.json`); plugins with agent-specific code pass their own `extension`.
+ */
+export function serveAcpAgent({ manifestUrl, configUrl, extension, additionalInstructions }) {
+  const manifest = JSON.parse(readFileSync(manifestUrl, 'utf8'));
+  const contribution = manifest.contributions.find(entry => entry.kind === 'capabilityProvider' && entry.scope === 'session');
+  if (!contribution) throw new Error('plugin.json has no session capability provider');
+  const configured = extension ?? extensionFromConfig(acpAgentConfig(JSON.parse(readFileSync(configUrl, 'utf8')), manifest), manifest, manifestUrl);
+  // The declared approval.respond variant decides how approvals are answered: by option or by decision.
+  const approvalOperation = contribution.operations.find(operation => operation.capability.id === `${manifest.pluginId}.approval.respond`);
+  const active = { ...configured, approvalOptions: approvalOperation?.inputSchema?.properties?.optionId !== undefined };
+  if (configured.approvalChoices?.length && !active.approvalOptions) throw new Error('Invalid acp.json: approvalOptions require the { requestId, optionId } approval.respond input');
+  const label = active.label, feature = name => `${manifest.pluginId}.${name}`;
+  const instructions = additionalInstructions ?? settingsInstructions(label);
+  let owner, bridge;
+  const hostTools = createHostToolChannel();
+  const session = new AcpSession({ extension: active, pluginVersion: manifest.version, emit(event) { owner?.tools.emit(event); } });
+  async function closeBridge() { const old = bridge; bridge = undefined; session.hostToolsRegistered = false; await old?.close(); }
+
+  function inputOf(request) {
+    if (!request.input || typeof request.input !== 'object' || Array.isArray(request.input)) throw Object.assign(new Error('Object input required'), { kind: 'invalid_input' });
+    return request.input;
+  }
+  function contextOf(request) {
+    const context = request.context;
+    if (request.scope?.kind !== 'session' || typeof request.scope.id !== 'string' || !request.scope.id || typeof context?.workspaceId !== 'string' || !context.workspaceId || typeof context.workspacePath !== 'string' || !context.workspacePath || !Array.isArray(context.permissions) || !context.permissions.includes('workspace.read')) {
+      throw Object.assign(new Error(`${label} requires a trusted session workspace`), { kind: 'permission_denied' });
+    }
+    return context;
+  }
+  async function commandDirectory() {
+    const output = await session.commands();
+    return { ...output, recovery: session.recovery(), capabilities: session.capabilities(),
+      commands: output.commands.map(command => ({ ...command, insertionText: `/${command.name} ` })),
+    };
+  }
+
+  async function invoke(request, tools) {
+    if (owner) throw Object.assign(new Error(`${label} session invocation already running`), { kind: 'busy' });
+    const context = contextOf(request);
+    const input = inputOf(request);
+    const abort = () => { if (request.capability === 'aibo.session.turn' || request.capability === 'aibo.session.turn.write') void session.cancel(); };
+    tools.signal.addEventListener('abort', abort, { once: true });
+    let endHostTools = () => {};
+    owner = { request, tools };
+    try {
+      endHostTools = hostTools.begin(request, tools, () => session.sessionId);
+      if (request.capability === 'aibo.session.open') {
+        const definitions = hostToolDefinitions(context);
+        if (definitions.length && !bridge) {
+          bridge = await createHostToolMcpBridge({ definitions, call: hostTools.call });
+          const previousName = input.recovery?.data?.hostMcpServerName;
+          if (input.mode === 'resume' && /^aibo-[a-f0-9]{16}$/.test(previousName ?? '')) bridge.configuration.name = previousName;
+        }
+        const mcpServers = bridge ? [{ ...bridge.configuration, env: Object.entries(bridge.configuration.env).map(([name, value]) => ({ name, value })) }] : [];
+        try {
+          await session.open({ mode: input.mode, workspaceId: context.workspaceId, workspacePath: context.workspacePath, executionProfile: input.executionProfile, recovery: input.recovery, permissions: context.permissions, mcpServers,
+            hostMcpTools: bridge ? definitions.filter(tool => tool.annotations?.readOnlyHint === true && tool.annotations?.destructiveHint === false).map(tool => ({ providerIdentifier: bridge.configuration.name, toolName: tool.name })) : [] });
+          // ACP may initialize/list MCP tools lazily when the first prompt starts.
+          // Successful session/new or session/load registers this session's servers.
+          session.hostToolsRegistered = !!bridge;
+          return session.snapshot();
+        } catch (error) { await session.close(); await closeBridge(); throw error; }
+      }
+      if (request.capability === feature('command.list')) return await commandDirectory();
+      if (request.capability === feature('model.reasoning')) return await session.configure('reasoning', input);
+      if (request.capability === feature('model.context-window')) return await session.configure('context', input);
+      if (request.capability === feature('model.select')) return await session.models(input);
+      if (request.capability === 'aibo.session.close') { try { return await session.close(); } finally { await closeBridge(); } }
+      if (request.capability === 'aibo.session.turn' || request.capability === 'aibo.session.turn.write') {
+        if (!context.turnId || typeof input.text !== 'string' || !input.text.trim()) throw Object.assign(new Error(`${label} turn requires text and turn identity`), { kind: 'invalid_input' });
+        if (request.capability.endsWith('.write') && !context.permissions.includes('workspace.write')) throw Object.assign(new Error(`${label} write turn requires workspace.write`), { kind: 'permission_denied' });
+        const writable = request.capability.endsWith('.write');
+        return await session.prompt({ text: input.text, attachments: input.attachments, turnId: context.turnId, additionalInstructions: instructions(context.settings), writable });
+      }
+      throw Object.assign(new Error(`Unsupported ${label} capability`), { kind: 'unsupported' });
+    } finally {
+      endHostTools();
+      tools.signal.removeEventListener('abort', abort);
+      owner = undefined;
+    }
+  }
+
+  async function control(request, { invocation }) {
+    if (!owner || owner.request.invocationId !== invocation.invocationId) throw Object.assign(new Error(`No matching ${label} invocation`), { kind: 'invalid_input' });
+    const input = inputOf(request);
+    if (request.capability === 'aibo.session.tool.respond') return hostTools.respond(input);
+    if (request.capability === feature('command.list')) return await commandDirectory();
+    if (request.capability.startsWith(feature('model.'))) throw Object.assign(new Error(`${label} model configuration requires an idle session`), { kind: 'busy' });
+    if (request.capability === 'aibo.session.cancel') return session.cancel();
+    if (request.capability === feature('approval.respond')) return session.respondApproval(input.requestId, input.optionId !== undefined ? { optionId: input.optionId } : input.decision);
+    if (request.capability === feature('user-input.respond')) return session.respondUserInput(input.requestId, input.answers);
+    throw Object.assign(new Error(`Unsupported ${label} control`), { kind: 'unsupported' });
+  }
+
+  serveCapability({
+    protocol: '2.1', pluginId: manifest.pluginId, pluginVersion: manifest.version, contributionId: contribution.id,
+    operations: contribution.operations.map(operation => ({ capability: operation.capability.id, version: operation.capability.version, operationId: operation.id })),
+    invoke, control,
+  });
+  process.stdin.on('end', () => { void session.close(); void closeBridge(); });
+  return session;
+}