@losclaws/cli 0.1.2 → 0.1.3

package/src/acp-runtime.js

@@ -0,0 +1,1083 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import readline from 'node:readline/promises';
+
+import * as acp from '@agentclientprotocol/sdk';
+
+import { CliError } from './errors.js';
+import { loadWorkshopState } from './workshop-local.js';
+
+const defaultOutputByteLimit = 1024 * 1024;
+const readOnlyToolKinds = new Set(['read', 'search', 'fetch', 'think', 'other']);
+const defaultFeedbackTimeoutMs = 30 * 60 * 1000;
+const defaultFeedbackPollIntervalMs = 3000;
+
+export async function runWorkshopAcpTask({ requestWorkshop, state, options }) {
+  const taskId = String(options.id || options.taskId || '').trim();
+  if (!taskId) {
+    throw new CliError('--id is required.');
+  }
+
+  const rootPath = path.resolve(options.root || process.cwd());
+  const localState = await loadWorkshopState(rootPath);
+  const detail = await requestWorkshop({
+    path: `/api/v1/tasks/${taskId}`,
+  });
+  // GET /tasks/{id} returns a task detail envelope ({ task, projectId, ... }).
+  // Tolerate a flat task object too (used by unit tests and older shapes).
+  const task = detail && typeof detail === 'object' && detail.task ? detail.task : detail;
+  const role = String(options.role || extractTaskRole(task) || localState.role || 'worker').trim() || 'worker';
+  const resolvedRuntime = resolveAcpRuntime({
+    task,
+    options,
+  });
+  const context = buildTaskPrompt({
+    task,
+    localState,
+    role,
+    extraMessage: options.message || '',
+    defaultPrompt: resolvedRuntime.runtime.defaultPrompt || '',
+    model: resolvedRuntime.runtime.model || '',
+  });
+  const taskVersion = asNumberOrNull(task?.version);
+
+  if (options.dryRun) {
+    return {
+      dryRun: true,
+      taskId,
+      role,
+      rootPath,
+      agent: {
+        name: resolvedRuntime.name,
+        command: resolvedRuntime.runtime.command,
+        args: resolvedRuntime.runtime.args,
+        model: resolvedRuntime.runtime.model || null,
+      },
+      resolvedFrom: resolvedRuntime.source,
+      taskVersion,
+      prompt: context.prompt,
+      artifactPaths: context.artifactPaths,
+      skillPaths: context.skillPaths,
+    };
+  }
+
+  const runDirectory = path.join(rootPath, '.losclaws', 'acp-runs');
+  await fs.mkdir(runDirectory, { recursive: true });
+  const runId = `${taskId}-${Date.now()}`;
+  const logPath = path.join(runDirectory, `${runId}.ndjson`);
+
+  const child = spawn(resolvedRuntime.runtime.command, resolvedRuntime.runtime.args, {
+    cwd: resolvedRuntime.runtime.cwd || rootPath,
+    env: {
+      ...process.env,
+      ...resolvedRuntime.runtime.env,
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  if (!child.stdin || !child.stdout || !child.stderr) {
+    throw new CliError(`Failed to launch coder "${resolvedRuntime.name}".`);
+  }
+
+  const bridge = new WorkshopTaskBridge({
+    requestWorkshop,
+    taskId,
+    version: taskVersion,
+    approvalPolicy: String(options.approvalPolicy || 'interactive'),
+    feedbackTimeoutMs: asNumberOrNull(options.feedbackTimeout) ?? defaultFeedbackTimeoutMs,
+  });
+  const client = new LosClawsAcpClient({
+    approvalPolicy: String(options.approvalPolicy || 'interactive'),
+    logPath,
+    bridge,
+    json: Boolean(options.json),
+  });
+
+  child.stderr.on('data', (chunk) => {
+    const message = chunk.toString('utf8');
+    if (message) {
+      process.stderr.write(message);
+      client.recordAgentStderr(message);
+    }
+  });
+
+  const stream = acp.ndJsonStream(
+    Writable.toWeb(child.stdin),
+    Readable.toWeb(child.stdout),
+  );
+  const connection = new acp.ClientSideConnection(() => client, stream);
+
+  try {
+    const initializeResult = await connection.initialize({
+      protocolVersion: acp.PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: {
+          readTextFile: true,
+          writeTextFile: true,
+        },
+        terminal: true,
+        elicitation: {
+          form: {},
+          url: {},
+        },
+      },
+      clientInfo: {
+        name: 'losclaws-cli',
+        title: 'LosClaws CLI',
+        version: '0.1.2',
+      },
+    });
+
+    const authMethodId = selectAuthMethodId({
+      initializeResult,
+      explicitAuthMethodId: options.authMethodId,
+      runtimeAuthMethodId: resolvedRuntime.runtime.authMethodId,
+    });
+    if (authMethodId) {
+      await connection.authenticate({ methodId: authMethodId });
+    }
+
+    const session = await openAcpSession({
+      connection,
+      initializeResult,
+      client,
+      task,
+      rootPath,
+      options,
+      runtime: resolvedRuntime.runtime,
+    });
+    const promptResult = await connection.prompt({
+      sessionId: session.sessionId,
+      prompt: [
+        {
+          type: 'text',
+          text: context.prompt,
+        },
+      ],
+    });
+
+    if (options.closeSession && supportsSessionClose(initializeResult)) {
+      await connection.closeSession({ sessionId: session.sessionId });
+    }
+
+    await bridge.flush();
+
+    return {
+      taskId,
+      role,
+      rootPath,
+      logPath,
+      resolvedFrom: resolvedRuntime.source,
+      agent: {
+        name: resolvedRuntime.name,
+        command: resolvedRuntime.runtime.command,
+        args: resolvedRuntime.runtime.args,
+        model: resolvedRuntime.runtime.model || null,
+      },
+      acp: {
+        protocolVersion: initializeResult.protocolVersion,
+        sessionId: session.sessionId,
+        stopReason: promptResult.stopReason,
+        agentInfo: initializeResult.agentInfo || null,
+      },
+      task: {
+        id: taskId,
+        version: bridge.version,
+      },
+      artifactPaths: context.artifactPaths,
+      skillPaths: context.skillPaths,
+    };
+  } finally {
+    await stopChildProcess(child);
+  }
+}
+
+export function buildTaskPrompt({ task, localState, role, extraMessage = '', defaultPrompt = '', model = '' }) {
+  const rootPath = localState.rootPath;
+  const taskTitle = String(task?.title || task?.name || task?.summary || task?.id || 'Workshop task');
+  const taskBody = firstString(
+    task?.instructions,
+    task?.prompt,
+    task?.description,
+    task?.goal,
+    task?.details,
+  );
+  const artifactPaths = selectTaskArtifactPaths(task, localState).map((relativePath) => path.join(rootPath, relativePath));
+  const skillPaths = localState.skills
+    .filter((entry) => entry.role === role)
+    .map((entry) => path.join(rootPath, entry.path));
+
+  const lines = [
+    `You are executing a ClawWorkshop task through ACP.`,
+    `Task ID: ${String(task?.id || '')}`,
+    `Role: ${role}`,
+    `Workspace root: ${rootPath}`,
+    `Task title: ${taskTitle}`,
+  ];
+
+  if (taskBody) {
+    lines.push('', 'Task instructions:', taskBody);
+  }
+  if (artifactPaths.length > 0) {
+    lines.push('', 'Use only these artifact paths unless the user explicitly expands scope:');
+    lines.push(...artifactPaths.map((entry) => `- ${entry}`));
+  }
+  if (skillPaths.length > 0) {
+    lines.push('', 'Relevant skill directories for this role:');
+    lines.push(...skillPaths.map((entry) => `- ${entry}`));
+  }
+  if (defaultPrompt) {
+    lines.push('', 'Agent runtime guidance:', defaultPrompt);
+  }
+  if (model) {
+    lines.push('', `Preferred model: ${model}`);
+  }
+  if (extraMessage) {
+    lines.push('', 'Additional operator instructions:', extraMessage);
+  }
+
+  return {
+    prompt: lines.join('\n'),
+    artifactPaths,
+    skillPaths,
+  };
+}
+
+// resolveAcpRuntime builds the coder launch spec. The server composes this in the
+// task payload (task.acp) from the project role configuration, the coder catalog,
+// and the assignee's uploaded inventory. CLI flags (--command/--args/--env/--model)
+// override individual fields for local debugging only.
+export function resolveAcpRuntime({ task, options = {} }) {
+  const descriptor = resolveServerAcpDescriptor(task);
+  const overrides = {
+    command: options.command,
+    args: options.args,
+    env: options.env,
+    model: options.model,
+  };
+
+  const command = String(overrides.command || descriptor?.command || '').trim();
+  if (!command) {
+    throw new CliError(
+      'The server returned no coder runtime for this task (task.acp is empty). ' +
+        'Run `losclaws workshop inspect` on the assignee and configure the project role ' +
+        '(coder + model) before running this task.',
+    );
+  }
+
+  const runtime = {
+    name: String(descriptor?.key || descriptor?.name || command),
+    title: String(descriptor?.title || ''),
+    command,
+    args: Array.isArray(overrides.args)
+      ? overrides.args.map((entry) => String(entry))
+      : Array.isArray(descriptor?.args)
+        ? descriptor.args.map((entry) => String(entry))
+        : [],
+    env: { ...normalizeEnvMap(descriptor?.env), ...normalizeEnvMap(overrides.env) },
+    cwd: String(descriptor?.cwd || ''),
+    authMethodId: String(descriptor?.authMethodId || ''),
+    mcpServers: Array.isArray(descriptor?.mcpServers) ? descriptor.mcpServers : [],
+    defaultPrompt: String(descriptor?.defaultPrompt || ''),
+    model: String(overrides.model || descriptor?.model || ''),
+    protocol: String(descriptor?.protocol || 'acp'),
+  };
+
+  return {
+    name: runtime.name,
+    runtime,
+    source: overrides.command ? 'cli-override' : 'server',
+  };
+}
+
+// resolveServerAcpDescriptor reads the server-composed coder launch spec from the
+// task payload. `task.acp` is the canonical field; a few legacy aliases are
+// tolerated for forward/backward compatibility.
+export function resolveServerAcpDescriptor(task) {
+  if (!task || typeof task !== 'object') {
+    return null;
+  }
+  const candidate = task.acp || task.acpConfig || task.coder || null;
+  if (!candidate || typeof candidate !== 'object') {
+    return null;
+  }
+  return candidate;
+}
+
+function normalizeEnvMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, String(entry)]));
+}
+
+function extractTaskRole(task) {
+  return String(task?.role || task?.assigneeRole || task?.assignee_role || task?.participantRole || '').trim();
+}
+
+function selectTaskArtifactPaths(task, localState) {
+  const explicitIds = [
+    ...(Array.isArray(task?.inputArtifacts) ? task.inputArtifacts : []),
+    ...(Array.isArray(task?.input_artifacts) ? task.input_artifacts : []),
+    ...(Array.isArray(task?.artifacts) ? task.artifacts : []),
+  ]
+    .map((entry) => String(entry?.id || entry?.artifactId || entry || '').trim())
+    .filter(Boolean);
+
+  const ids = new Set(explicitIds);
+  const candidates = ids.size > 0
+    ? localState.artifacts.filter((entry) => ids.has(entry.id))
+    : localState.artifacts;
+  return candidates.map((entry) => entry.relativePath).slice(0, 64);
+}
+
+function selectAuthMethodId({ initializeResult, explicitAuthMethodId, runtimeAuthMethodId }) {
+  const methods = Array.isArray(initializeResult.authMethods) ? initializeResult.authMethods : [];
+  if (explicitAuthMethodId) {
+    return explicitAuthMethodId;
+  }
+  if (runtimeAuthMethodId) {
+    return runtimeAuthMethodId;
+  }
+  if (methods.length === 1 && methods[0]?.id) {
+    return methods[0].id;
+  }
+  return '';
+}
+
+async function openAcpSession({ connection, initializeResult, client, task, rootPath, options, runtime }) {
+  const mcpServers = Array.isArray(runtime.mcpServers) ? runtime.mcpServers : [];
+  const additionalDirectories = [];
+
+  if (options.acpSessionId) {
+    if (supportsSessionResume(initializeResult)) {
+      const result = await connection.resumeSession({
+        sessionId: options.acpSessionId,
+        cwd: rootPath,
+        additionalDirectories,
+        mcpServers,
+      });
+      client.setSessionRoots(options.acpSessionId, [rootPath, ...additionalDirectories]);
+      return {
+        sessionId: options.acpSessionId,
+        details: result,
+      };
+    }
+    if (initializeResult.agentCapabilities?.loadSession) {
+      await connection.loadSession({
+        sessionId: options.acpSessionId,
+        cwd: rootPath,
+        additionalDirectories,
+        mcpServers,
+      });
+      client.setSessionRoots(options.acpSessionId, [rootPath, ...additionalDirectories]);
+      return {
+        sessionId: options.acpSessionId,
+        details: {},
+      };
+    }
+    throw new CliError('This ACP agent does not support loading or resuming existing sessions.');
+  }
+
+  const result = await connection.newSession({
+    cwd: rootPath,
+    additionalDirectories,
+    mcpServers,
+  });
+  client.setSessionRoots(result.sessionId, [rootPath, ...additionalDirectories]);
+  await client.recordLifecycle('session_opened', {
+    taskId: String(task?.id || ''),
+    sessionId: result.sessionId,
+  });
+  return result;
+}
+
+function supportsSessionResume(initializeResult) {
+  return Boolean(initializeResult.agentCapabilities?.sessionCapabilities?.resume);
+}
+
+function supportsSessionClose(initializeResult) {
+  return Boolean(initializeResult.agentCapabilities?.sessionCapabilities?.close);
+}
+
+function asNumberOrNull(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function firstString(...values) {
+  return values
+    .map((entry) => String(entry || '').trim())
+    .find(Boolean) || '';
+}
+
+class LosClawsAcpClient {
+  constructor({ approvalPolicy, logPath, bridge, json }) {
+    this.approvalPolicy = approvalPolicy;
+    this.logPath = logPath;
+    this.bridge = bridge;
+    this.json = json;
+    this.sessionRoots = new Map();
+    this.terminals = new Map();
+  }
+
+  setSessionRoots(sessionId, roots) {
+    this.sessionRoots.set(sessionId, roots.map((entry) => path.resolve(entry)));
+  }
+
+  async requestPermission(params) {
+    const outcome = await selectPermissionOutcome({
+      policy: this.approvalPolicy,
+      params,
+      bridge: this.bridge,
+    });
+    await this.recordLifecycle('permission', {
+      toolCallId: params.toolCall?.toolCallId,
+      outcome,
+    });
+    return {
+      outcome,
+    };
+  }
+
+  async sessionUpdate(params) {
+    await this.recordLifecycle('session_update', params);
+    await this.bridge.publishSessionUpdate(params);
+    printSessionUpdate(params, this.json);
+  }
+
+  async writeTextFile(params) {
+    const filePath = assertAllowedPath(params.sessionId, params.path, this.sessionRoots);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, params.content, 'utf8');
+    await this.recordLifecycle('write_text_file', params);
+    return {};
+  }
+
+  async readTextFile(params) {
+    const filePath = assertAllowedPath(params.sessionId, params.path, this.sessionRoots);
+    const content = await fs.readFile(filePath, 'utf8');
+    await this.recordLifecycle('read_text_file', params);
+    return { content };
+  }
+
+  async createTerminal(params) {
+    const sessionRoots = this.sessionRoots.get(params.sessionId) || [];
+    const cwd = params.cwd ? assertAllowedTerminalCwd(params.sessionId, params.cwd, this.sessionRoots) : sessionRoots[0];
+    const terminalId = `term_${randomUUID()}`;
+    const child = spawn(params.command, params.args || [], {
+      cwd,
+      env: {
+        ...process.env,
+        ...Object.fromEntries((params.env || []).map((entry) => [entry.name, entry.value])),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const terminal = {
+      id: terminalId,
+      output: '',
+      truncated: false,
+      outputByteLimit: params.outputByteLimit || defaultOutputByteLimit,
+      exitCode: null,
+      signal: null,
+      child,
+      waitPromise: null,
+    };
+    terminal.waitPromise = new Promise((resolve) => {
+      child.on('exit', (exitCode, signal) => {
+        terminal.exitCode = exitCode;
+        terminal.signal = signal;
+        resolve({
+          exitCode,
+          signal,
+        });
+      });
+    });
+    child.stdout.on('data', (chunk) => {
+      appendTerminalOutput(terminal, chunk.toString('utf8'));
+    });
+    child.stderr.on('data', (chunk) => {
+      appendTerminalOutput(terminal, chunk.toString('utf8'));
+    });
+    this.terminals.set(terminalId, terminal);
+    await this.recordLifecycle('terminal_create', {
+      terminalId,
+      command: params.command,
+      args: params.args || [],
+    });
+    return { terminalId };
+  }
+
+  async terminalOutput(params) {
+    const terminal = getTerminal(this.terminals, params.terminalId);
+    return {
+      output: terminal.output,
+      truncated: terminal.truncated,
+      ...(terminal.exitCode !== null || terminal.signal !== null
+        ? {
+            exitStatus: {
+              exitCode: terminal.exitCode,
+              signal: terminal.signal,
+            },
+          }
+        : {}),
+    };
+  }
+
+  async waitForTerminalExit(params) {
+    const terminal = getTerminal(this.terminals, params.terminalId);
+    return terminal.waitPromise;
+  }
+
+  async killTerminal(params) {
+    const terminal = getTerminal(this.terminals, params.terminalId);
+    terminal.child.kill();
+    return {};
+  }
+
+  async releaseTerminal(params) {
+    const terminal = getTerminal(this.terminals, params.terminalId);
+    if (terminal.exitCode === null && terminal.signal === null) {
+      terminal.child.kill();
+    }
+    this.terminals.delete(params.terminalId);
+    return {};
+  }
+
+  async unstable_createElicitation(params) {
+    const result = await handleElicitationRequest({
+      policy: this.approvalPolicy,
+      params,
+      bridge: this.bridge,
+    });
+    await this.recordLifecycle('elicitation', {
+      request: params,
+      response: result,
+    });
+    return result;
+  }
+
+  async unstable_completeElicitation(params) {
+    await this.recordLifecycle('elicitation_complete', params);
+  }
+
+  async recordAgentStderr(message) {
+    await this.recordLifecycle('agent_stderr', {
+      message,
+    });
+  }
+
+  async recordLifecycle(type, payload) {
+    await fs.appendFile(
+      this.logPath,
+      `${JSON.stringify({ timestamp: new Date().toISOString(), type, payload })}\n`,
+      'utf8',
+    );
+  }
+}
+
+// WorkshopTaskBridge maps coder activity onto real Workshop task endpoints.
+// Non-blocking session updates become typed worklog entries; blocking
+// permission/elicitation requests become structured feedback requests that the
+// bridge polls until a human answers on the web (the "remote" approval policy).
+class WorkshopTaskBridge {
+  constructor({ requestWorkshop, taskId, version, approvalPolicy, feedbackTimeoutMs }) {
+    this.requestWorkshop = requestWorkshop;
+    this.taskId = taskId;
+    this.version = version;
+    this.approvalPolicy = approvalPolicy;
+    this.feedbackTimeoutMs = feedbackTimeoutMs ?? defaultFeedbackTimeoutMs;
+  }
+
+  // publishSessionUpdate records a typed worklog entry. Best-effort: a failure
+  // (e.g. the task is momentarily not in_progress) must not crash the coder run.
+  async publishSessionUpdate(params) {
+    const update = params?.update || {};
+    const updateType = String(update.sessionUpdate || 'session_update').slice(0, 48);
+    const body = formatSessionUpdateBody(params) || updateType;
+    try {
+      await this.requestWorkshop({
+        method: 'POST',
+        path: `/api/v1/tasks/${this.taskId}/worklogs`,
+        body: {
+          updateType,
+          body: body.slice(0, 2000),
+          payload: update,
+        },
+      });
+    } catch (error) {
+      process.stderr.write(`losclaws: failed to record worklog (${updateType}): ${error.message}\n`);
+    }
+  }
+
+  // requestFeedbackAndWait opens a structured feedback request, then long-polls
+  // the task until a human submits a response on the web, returning that response.
+  // Throws on timeout so the caller can fall back to a safe default.
+  async requestFeedbackAndWait({ kind, prompt, options, requestSchema }) {
+    const body = {
+      expectedVersion: this.version ?? 0,
+      kind,
+      prompt: prompt || kind,
+    };
+    if (options !== undefined) {
+      body.options = options;
+    }
+    if (requestSchema !== undefined) {
+      body.requestSchema = requestSchema;
+    }
+    const created = await this.requestWorkshop({
+      method: 'POST',
+      path: `/api/v1/tasks/${this.taskId}/feedback-requests`,
+      body,
+    });
+    this.updateVersionFrom(created);
+
+    const deadline = Date.now() + this.feedbackTimeoutMs;
+    while (Date.now() < deadline) {
+      await delay(defaultFeedbackPollIntervalMs);
+      let detail;
+      try {
+        detail = await this.requestWorkshop({ path: `/api/v1/tasks/${this.taskId}` });
+      } catch (error) {
+        process.stderr.write(`losclaws: feedback poll failed: ${error.message}\n`);
+        continue;
+      }
+      const task = detail && detail.task ? detail.task : detail;
+      this.updateVersionFrom(task);
+      const session = detail?.feedbackSession || task?.feedbackSession || null;
+      if (session && session.status && session.status !== 'open') {
+        const entries = Array.isArray(session.entries) ? session.entries : [];
+        const last = entries.length > 0 ? entries[entries.length - 1] : null;
+        return {
+          status: session.status,
+          response: last?.response ?? null,
+          body: last?.body ?? '',
+        };
+      }
+    }
+    throw new CliError(`Timed out after ${Math.round(this.feedbackTimeoutMs / 1000)}s waiting for human feedback.`);
+  }
+
+  updateVersionFrom(value) {
+    const next = asNumberOrNull(value?.version ?? value?.task?.version);
+    if (next !== null) {
+      this.version = next;
+    }
+  }
+
+  async flush() {}
+}
+
+// formatSessionUpdateBody renders a concise human-readable line for a worklog
+// entry; the full structured payload is stored alongside it.
+function formatSessionUpdateBody(params) {
+  const update = params?.update || {};
+  switch (update.sessionUpdate) {
+    case 'agent_message_chunk':
+    case 'user_message_chunk':
+      return textFromContent(update.content);
+    case 'agent_thought_chunk':
+      return `(thinking) ${textFromContent(update.content)}`.trim();
+    case 'tool_call':
+      return `[tool] ${String(update.title || update.toolCallId || '')} (${String(update.status || 'pending')})`;
+    case 'tool_call_update':
+      return `[tool] ${String(update.toolCallId || '')} -> ${String(update.status || '')}`;
+    case 'plan':
+      return `[plan] ${(Array.isArray(update.entries) ? update.entries : []).length} step(s)`;
+    case 'usage_update':
+      return `[usage] ${String(update.used ?? '?')}/${String(update.size ?? '?')}`;
+    default:
+      return String(update.sessionUpdate || 'session_update');
+  }
+}
+
+function textFromContent(content) {
+  if (!content) {
+    return '';
+  }
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (typeof content.text === 'string') {
+    return content.text;
+  }
+  return '';
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function selectPermissionOutcome({ policy, params, bridge }) {
+  const options = Array.isArray(params.options) ? params.options : [];
+  if (options.length === 0) {
+    return { outcome: 'cancelled' };
+  }
+
+  const normalizedPolicy = String(policy || 'interactive');
+  if (normalizedPolicy === 'remote') {
+    return resolveRemotePermission({ params, options, bridge });
+  }
+  if (normalizedPolicy === 'auto-allow') {
+    return selectByKinds(options, ['allow_once', 'allow_always']) || selectFirstOption(options);
+  }
+  if (normalizedPolicy === 'auto-reject') {
+    return selectByKinds(options, ['reject_once', 'reject_always']) || selectFirstOption(options);
+  }
+  if (normalizedPolicy === 'read-only') {
+    if (readOnlyToolKinds.has(params.toolCall.kind || 'other')) {
+      return selectByKinds(options, ['allow_once', 'allow_always']) || selectFirstOption(options);
+    }
+    return selectByKinds(options, ['reject_once', 'reject_always']) || selectFirstOption(options);
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return selectPermissionOutcome({ policy: 'read-only', params });
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    console.log(`\nACP permission requested: ${params.toolCall.title}`);
+    options.forEach((option, index) => {
+      console.log(`  ${index + 1}. ${option.name} (${option.kind})`);
+    });
+    while (true) {
+      const answer = await rl.question('Choose an option: ');
+      const index = Number(answer.trim());
+      if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+        return {
+          outcome: 'selected',
+          optionId: options[index - 1].optionId,
+        };
+      }
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function selectByKinds(options, kinds) {
+  const match = options.find((entry) => kinds.includes(entry.kind));
+  if (!match) {
+    return null;
+  }
+  return {
+    outcome: 'selected',
+    optionId: match.optionId,
+  };
+}
+
+function selectFirstOption(options) {
+  return {
+    outcome: 'selected',
+    optionId: options[0].optionId,
+  };
+}
+
+// resolveRemotePermission posts the coder's permission request to the server as a
+// single_select feedback request and blocks until a human answers on the web. On
+// timeout or a declined request it falls back to a safe reject.
+async function resolveRemotePermission({ params, options, bridge }) {
+  if (!bridge) {
+    return selectByKinds(options, ['reject_once', 'reject_always']) || selectFirstOption(options);
+  }
+  const promptOptions = options.map((option) => ({
+    optionId: option.optionId,
+    name: option.name,
+    kind: option.kind,
+  }));
+  try {
+    const result = await bridge.requestFeedbackAndWait({
+      kind: 'single_select',
+      prompt: String(params.toolCall?.title || 'The coder is requesting permission to proceed.'),
+      options: promptOptions,
+    });
+    const optionId = extractSelectedOptionId(result, options);
+    if (!optionId) {
+      return { outcome: 'cancelled' };
+    }
+    return { outcome: 'selected', optionId };
+  } catch (error) {
+    process.stderr.write(`losclaws: ${error.message} Falling back to reject.\n`);
+    return selectByKinds(options, ['reject_once', 'reject_always']) || { outcome: 'cancelled' };
+  }
+}
+
+// extractSelectedOptionId maps a human's structured response back to a valid ACP
+// permission optionId. Accepts {optionId}, a bare option id/name, or an index.
+function extractSelectedOptionId(result, options) {
+  const valid = new Set(options.map((option) => option.optionId));
+  const response = result?.response;
+  const candidates = [];
+  if (response && typeof response === 'object') {
+    candidates.push(response.optionId, response.value, response.selected, response.choice);
+  } else if (response !== undefined && response !== null) {
+    candidates.push(response);
+  }
+  candidates.push(result?.body);
+  for (const candidate of candidates) {
+    const value = String(candidate ?? '').trim();
+    if (value && valid.has(value)) {
+      return value;
+    }
+    const byName = options.find((option) => option.name === value);
+    if (byName) {
+      return byName.optionId;
+    }
+  }
+  return '';
+}
+
+async function handleElicitationRequest({ policy, params, bridge }) {
+  if (String(policy || '') === 'remote' && bridge) {
+    return resolveRemoteElicitation({ params, bridge });
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return buildDefaultElicitationResponse(params);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    console.log(`\nACP agent input requested: ${params.message}`);
+    if (params.mode === 'url') {
+      console.log(`Open this URL to continue: ${params.url}`);
+      const answer = (await rl.question('Press Enter to accept, or type "decline" / "cancel": ')).trim().toLowerCase();
+      if (answer === 'decline') {
+        return { action: 'decline' };
+      }
+      if (answer === 'cancel') {
+        return { action: 'cancel' };
+      }
+      return { action: 'accept' };
+    }
+
+    const content = {};
+    const properties = params.requestedSchema?.properties || {};
+    for (const [key, schema] of Object.entries(properties)) {
+      const label = schema.title || key;
+      const defaultValue = schema.default;
+      if (schema.type === 'boolean') {
+        const answer = await rl.question(`${label} [${defaultValue ? 'Y/n' : 'y/N'}]: `);
+        content[key] = answer.trim() ? /^y(es)?$/i.test(answer.trim()) : Boolean(defaultValue);
+        continue;
+      }
+      if (schema.type === 'array') {
+        const choices = normalizeEnumChoices(schema.items?.anyOf || schema.items?.enum || []);
+        choices.forEach((entry, index) => {
+          console.log(`  ${index + 1}. ${entry.title}`);
+        });
+        const answer = await rl.question(`${label} (comma-separated numbers): `);
+        const indexes = answer
+          .split(',')
+          .map((entry) => Number(entry.trim()))
+          .filter((entry) => Number.isInteger(entry) && entry >= 1 && entry <= choices.length);
+        content[key] = indexes.map((entry) => choices[entry - 1].value);
+        continue;
+      }
+      const choices = normalizeEnumChoices(schema.oneOf || schema.enum || []);
+      if (choices.length > 0) {
+        choices.forEach((entry, index) => {
+          console.log(`  ${index + 1}. ${entry.title}`);
+        });
+        const answer = await rl.question(`${label}${defaultValue !== undefined ? ` [${defaultValue}]` : ''}: `);
+        const index = Number(answer.trim());
+        content[key] =
+          Number.isInteger(index) && index >= 1 && index <= choices.length
+            ? choices[index - 1].value
+            : defaultValue ?? choices[0].value;
+        continue;
+      }
+      const answer = await rl.question(`${label}${defaultValue !== undefined ? ` [${defaultValue}]` : ''}: `);
+      content[key] = coerceScalarValue(schema.type, answer.trim(), defaultValue);
+    }
+    return {
+      action: 'accept',
+      content,
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+// resolveRemoteElicitation posts the coder's elicitation to the server as a
+// form/url feedback request and blocks until a human answers on the web.
+async function resolveRemoteElicitation({ params, bridge }) {
+  const kind = params.mode === 'url' ? 'url' : 'form';
+  const requestSchema = params.mode === 'url'
+    ? { url: String(params.url || '') }
+    : { schema: params.requestedSchema || {} };
+  try {
+    const result = await bridge.requestFeedbackAndWait({
+      kind,
+      prompt: String(params.message || 'The coder is requesting input.'),
+      requestSchema,
+    });
+    const response = result?.response;
+    if (response && typeof response === 'object') {
+      if (typeof response.action === 'string') {
+        return response;
+      }
+      return { action: 'accept', content: response };
+    }
+    if (kind === 'url') {
+      return { action: 'accept' };
+    }
+    return { action: 'decline' };
+  } catch (error) {
+    process.stderr.write(`losclaws: ${error.message} Declining elicitation.\n`);
+    return params.mode === 'url' ? { action: 'decline' } : { action: 'cancel' };
+  }
+}
+
+function buildDefaultElicitationResponse(params) {
+  if (params.mode === 'url') {
+    return { action: 'decline' };
+  }
+  const properties = params.requestedSchema?.properties || {};
+  const content = {};
+  for (const [key, schema] of Object.entries(properties)) {
+    if (schema.default !== undefined) {
+      content[key] = schema.default;
+    }
+  }
+  if (Object.keys(content).length === 0) {
+    return { action: 'decline' };
+  }
+  return {
+    action: 'accept',
+    content,
+  };
+}
+
+function normalizeEnumChoices(rawChoices) {
+  if (!Array.isArray(rawChoices)) {
+    return [];
+  }
+
+  return rawChoices.map((entry) =>
+    typeof entry === 'string'
+      ? { value: entry, title: entry }
+      : { value: entry.const, title: entry.title || entry.const },
+  );
+}
+
+function coerceScalarValue(type, value, defaultValue) {
+  if (!value) {
+    return defaultValue ?? '';
+  }
+  if (type === 'integer' || type === 'number') {
+    return Number(value);
+  }
+  return value;
+}
+
+function appendTerminalOutput(terminal, chunk) {
+  terminal.output += chunk;
+  const byteLength = Buffer.byteLength(terminal.output, 'utf8');
+  if (byteLength <= terminal.outputByteLimit) {
+    return;
+  }
+  terminal.truncated = true;
+  let output = terminal.output;
+  while (Buffer.byteLength(output, 'utf8') > terminal.outputByteLimit) {
+    output = output.slice(Math.max(1, Math.floor(output.length / 8)));
+  }
+  terminal.output = output;
+}
+
+function getTerminal(terminals, terminalId) {
+  const terminal = terminals.get(terminalId);
+  if (!terminal) {
+    throw new CliError(`Unknown ACP terminal: ${terminalId}`);
+  }
+  return terminal;
+}
+
+function assertAllowedPath(sessionId, filePath, sessionRoots) {
+  const absolutePath = path.resolve(filePath);
+  const roots = sessionRoots.get(sessionId) || [];
+  if (roots.length > 0 && !roots.some((root) => isInsideRoot(absolutePath, root))) {
+    throw new CliError(`ACP file access is outside the allowed roots: ${absolutePath}`);
+  }
+  return absolutePath;
+}
+
+function assertAllowedTerminalCwd(sessionId, cwd, sessionRoots) {
+  return assertAllowedPath(sessionId, cwd, sessionRoots);
+}
+
+function isInsideRoot(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function printSessionUpdate(params, json) {
+  if (json) {
+    // Stream progress to stderr so stdout carries only the final JSON result.
+    process.stderr.write(`${JSON.stringify({ event: 'session/update', data: params })}\n`);
+    return;
+  }
+
+  const update = params.update;
+  if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
+    console.log(update.content.text);
+    return;
+  }
+  if (update.sessionUpdate === 'tool_call') {
+    console.log(`[tool] ${update.title} (${update.status})`);
+    return;
+  }
+  if (update.sessionUpdate === 'tool_call_update') {
+    console.log(`[tool] ${update.toolCallId} -> ${update.status}`);
+    return;
+  }
+  if (update.sessionUpdate === 'plan') {
+    console.log('[plan]');
+    return;
+  }
+  if (update.sessionUpdate === 'usage_update') {
+    console.log(`[usage] ${update.used}/${update.size}`);
+  }
+}
+
+async function stopChildProcess(child) {
+  if (child.stdin && !child.stdin.destroyed) {
+    child.stdin.end();
+  }
+
+  const waitForExit = new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    child.once('exit', resolve);
+    child.once('close', resolve);
+  });
+
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill();
+  }
+
+  const timeout = setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGKILL');
+    }
+  }, 1000);
+
+  await waitForExit;
+  clearTimeout(timeout);
+}