@anhlp/alp-runtime 0.0.0-stage → 0.0.1-beta.4

package/src/claude-transport.ts

@@ -0,0 +1,938 @@
+import { writablePath } from './permission-path.js';
+import { accessSync, constants, existsSync, mkdirSync, realpathSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { optionalRead, claudeUsage } from './runtime-context.js';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { PIN_KINDS } from './board.js';
+import { claudeToolDetail, resultText } from './tool-detail.js';
+import { CLOSE_REASONS, GATE_KINDS, TASK_STATUSES, TASK_TYPES } from '@anhlp/alp-core/tasks';
+import { commandDecision } from '@anhlp/alp-core/permissions';
+
+// Keep the Claude SDK behind the runtime boundary. Paseo inspects static
+// imports while compiling plugin entrypoints, including their declaration
+// graph; the SDK is a daemon-only optional runtime dependency.
+const CLAUDE_SDK = ['@anthropic-ai', 'claude-agent-sdk'].join('/');
+
+type SDKUserMessage = any;
+type SDKMessage = any;
+type ClaudeQuery = AsyncGenerator<SDKMessage, void> & {
+  supportedModels(): Promise<Array<{ value: string; displayName: string; description: string; supportedEffortLevels?: string[] }>>;
+  usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(options: { skipBehaviors: boolean }): Promise<any>;
+  getContextUsage(options: { detail: 'summary' | 'full' }): Promise<any>;
+  interrupt(): Promise<unknown>;
+  setPermissionMode(mode: 'default' | 'acceptEdits' | 'bypassPermissions'): Promise<void>;
+  close(): void;
+  initializationResult?(): Promise<unknown>;
+};
+
+// Zod mirrors of the provider's dynamic tool schemas; the provider validates again.
+const handoffList = z.array(z.string().min(1)).max(100).optional();
+const taskIds = z.array(z.string().min(1)).max(50).optional();
+const taskLinks = z.object({ blockedBy: taskIds, related: taskIds, parent: z.string().min(1).optional() }).strict().optional();
+export const toolShapes: Record<string, Record<string, z.ZodType>> = {
+  alp_delegate: {
+    agent: z.string().min(1),
+    task: z.string().min(1).max(32_000),
+    model: z.string().min(1).optional(),
+    thinking: z.string().min(1).optional(),
+    modelReason: z.string().min(1).optional(),
+    mode: z.enum(['read-only', 'workspace-write', 'full-access']).optional(),
+    isolation: z.enum(['shared', 'worktree']).optional(),
+    writeRoot: z.string().min(1).optional(),
+    wait: z.boolean().optional(),
+    etaMinutes: z.number().int().min(1).max(1440).optional(),
+    taskId: z.string().min(1).optional(),
+    continueFrom: z.string().min(1).optional(),
+  },
+  alp_merge: {
+    assignmentId: z.string().min(1),
+    skipVerify: z.string().min(1).max(2000).optional(),
+  },
+  alp_verify: {
+    taskId: z.string().min(1).optional(),
+  },
+  alp_recall: {
+    assignmentId: z.string().min(1).optional(),
+    taskId: z.string().min(1).optional(),
+    question: z.string().min(1).max(4000),
+  },
+  alp_lesson: {
+    scope: z.enum(['project', 'user']),
+    lesson: z.string().min(1).max(600),
+  },
+  alp_skill: {
+    name: z.string().min(1),
+    description: z.string().min(1).max(300),
+    body: z.string().min(1).max(20_000),
+    roles: z.array(z.string().min(1)).min(1).max(10),
+    lessons: z.array(z.string().min(1).max(600)).max(50).optional(),
+    replace: z.boolean().optional(),
+    requestId: z.string().min(1).max(100).optional(),
+  },
+  alp_issue: {
+    action: z.enum(['search', 'create', 'comment']),
+    target: z.enum(['project', 'alp']),
+    query: z.string().min(1).max(200).optional(),
+    requestId: z.string().min(1).max(100).optional(),
+    title: z.string().min(1).max(200).optional(),
+    body: z.string().min(1).max(20_000).optional(),
+    issue: z.number().int().positive().optional(),
+    labels: z.array(z.string().min(1).max(50)).max(10).optional(),
+  },
+  alp_schedule: {
+    action: z.enum(['create', 'list', 'get', 'cancel']),
+    dueAt: z.string().min(1).max(80).optional(),
+    prompt: z.string().min(1).max(8000).optional(),
+    requestId: z.string().min(1).max(200).optional(),
+    id: z.string().min(1).optional(),
+    status: z.enum(['pending', 'delivered', 'failed', 'cancelled']).optional(),
+  },
+  alp_task: {
+    action: z.enum(['create', 'update', 'link', 'start', 'close', 'reopen', 'gate', 'clear', 'pour', 'formulas', 'show', 'list', 'ready']),
+    id: z.string().min(1).optional(),
+    title: z.string().min(1).max(200).optional(),
+    description: z.string().max(8000).optional(),
+    type: z.enum(TASK_TYPES as [string, ...string[]]).optional(),
+    priority: z.number().int().min(0).max(4).optional(),
+    labels: z.array(z.string().min(1).max(50)).max(10).optional(),
+    paths: z.array(z.string().min(1)).max(50).optional(),
+    parent: z.string().min(1).optional(),
+    blockedBy: taskIds,
+    discoveredFrom: z.string().min(1).optional(),
+    add: taskLinks,
+    remove: taskLinks,
+    reason: z.enum(CLOSE_REASONS as [string, ...string[]]).optional(),
+    kind: z.enum(GATE_KINDS as [string, ...string[]]).optional(),
+    until: z.string().min(1).optional(),
+    ref: z.string().min(1).optional(),
+    gate: z.string().min(1).optional(),
+    formula: z.string().min(1).optional(),
+    vars: z.record(z.string(), z.string()).optional(),
+    summary: z.string().min(1).max(2000).optional(),
+    unverified: z.string().min(1).max(2000).optional(),
+    note: z.string().min(1).max(2000).optional(),
+    status: z.enum(TASK_STATUSES as [string, ...string[]]).optional(),
+    label: z.string().min(1).optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  alp_discard: {
+    assignmentId: z.string().min(1),
+  },
+  alp_cancel: {
+    assignmentId: z.string().min(1),
+    reason: z.string().optional(),
+  },
+  alp_pin: {
+    kind: z.enum(PIN_KINDS),
+    body: z.string().min(1),
+    paths: z.array(z.string().min(1)).optional(),
+  },
+  alp_board: {
+    kinds: z.array(z.enum(PIN_KINDS)).optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  alp_unpin: {
+    pinId: z.string().min(1),
+  },
+  alp_wait: {
+    assignments: z.array(z.string().min(1)).max(32).optional(),
+    timeoutMs: z.number().int().positive().optional(),
+  },
+  alp_send: {
+    to: z.string().min(1),
+    kind: z.enum(['answer', 'note', 'steer']),
+    body: z.string().min(1).max(8000),
+    replyTo: z.string().min(1).optional(),
+  },
+  alp_ask: {
+    question: z.string().min(1).max(8000),
+    to: z.enum(['parent', 'user']).optional(),
+    options: z.array(z.string().min(1).max(200)).max(10).optional(),
+  },
+  alp_handoff: {
+    outcome: z.enum(['complete', 'partial', 'blocked', 'reconsider']),
+    summary: z.string().min(1),
+    candidate: handoffList,
+    scope: handoffList,
+    verification: handoffList,
+    risks: handoffList,
+    discovered: handoffList,
+    ownership: z.string().optional(),
+    // ALP checks that the result follows from the criteria and findings (ALPD §38).
+    verdict: z.object({
+      result: z.enum(['pass', 'pass_with_findings', 'fail', 'blocked']),
+      criteria: z.array(z.object({ criterion: z.string().min(1), result: z.enum(['pass', 'fail', 'not_checked']), evidence: z.string().min(1) }).strict()).min(1).max(50),
+      findings: z.array(z.object({ severity: z.enum(['critical', 'high', 'medium', 'low']), where: z.string().min(1), problem: z.string().min(1), fix: z.string().min(1).optional() }).strict()).max(100).optional(),
+    }).strict().optional(),
+  },
+};
+
+type Listener = (method: string, params: any) => void;
+type RequestHandler = (method: string, params: any) => Promise<unknown>;
+
+type NativeConfig = {
+  cwd: string;
+  model: string;
+  sandbox: string;
+  developerInstructions: string;
+  mcpServers: Record<string, any>;
+  thinking: string;
+  dynamicTools: Array<{
+    name: string;
+    description: string;
+  }>;
+  ephemeral?: boolean;
+  threadId?: string;
+  /** The session's permission profile: rules Claude enforces itself, in every permission mode. */
+  permissions?: PermissionRules | null;
+  /** The OS sandbox for Bash, when ALP chose one. */
+  floor?: 'read-only' | 'workspace-write';
+  /** The context window the session works in before Claude compacts it, in tokens; absent: the model's (ALPD §57). */
+  context?: number;
+  /** The agent's skills, each a SKILL.md, loaded as Claude Code skills alp:<name> (ALPD §59). */
+  skills?: Array<{ name: string; path: string }>;
+};
+
+/** The plugin name ALP's skills are loaded under, so Claude Code calls them alp:<name>. */
+export const SKILL_PLUGIN = 'alp';
+
+/**
+ * A Claude Code plugin in `directory` holding the given skills, linked to their own
+ * directories so an edit to a skill reaches the next session (ALPD §59).
+ */
+export function skillPlugin(directory: string, skills: Array<{ name: string; path: string }>) {
+  rmSync(directory, { recursive: true, force: true });
+  mkdirSync(path.join(directory, '.claude-plugin'), { recursive: true });
+  mkdirSync(path.join(directory, 'skills'));
+  writeFileSync(path.join(directory, '.claude-plugin', 'plugin.json'), JSON.stringify({ name: SKILL_PLUGIN, description: "The agent's ALP skills" }));
+  for (const skill of skills) symlinkSync(path.dirname(skill.path), path.join(directory, 'skills', skill.name), 'dir');
+  return directory;
+}
+
+type PermissionRules = {
+  allow: string[]; ask?: string[]; deny: string[]; beyondMode?: 'refuse' | 'ask';
+  /** The OS sandbox ALP puts Bash in, and the directory it may write besides temp files. */
+  floor?: 'read-only' | 'workspace-write'; floorRoot?: string;
+};
+
+/** Whether Claude Code can sandbox Bash here: Seatbelt on macOS, bubblewrap and socat on Linux. ALP_CLAUDE_SANDBOX=0 turns it off, =1 claims it (tests). */
+export function claudeSandboxAvailable() {
+  if (process.env.ALP_CLAUDE_SANDBOX === '0') return false;
+  if (process.env.ALP_CLAUDE_SANDBOX === '1') return true;
+  if (process.platform === 'darwin') return existsSync('/usr/bin/sandbox-exec');
+  if (process.platform !== 'linux') return false;
+  const onPath = (name: string) => (process.env.PATH ?? '').split(path.delimiter).some(dir => dir && existsSync(path.join(dir, name)));
+  return onPath('bwrap') && onPath('socat');
+}
+
+const WRITERS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+/** What ALP asks the user for a permission Claude would otherwise not have. */
+/** One turn-input part as Claude's: text, or a data-URL image as a base64 image block. */
+export function claudeContent(part: any) {
+  const image = part?.type === 'image' && typeof part.url === 'string' ? /^data:(image\/(?:png|jpeg|gif|webp));base64,([A-Za-z0-9+/]+={0,2})$/.exec(part.url) : null;
+  if (part?.type === 'image' && !image) throw new Error('Claude takes images as inline base64 PNG, JPEG, GIF or WebP only');
+  return image ? { type: 'image', source: { type: 'base64', media_type: image[1], data: image[2] } } : { type: 'text', text: part.text };
+}
+
+export type PermissionRequest = { tool: string; input: Record<string, unknown>; reason: 'rule' | 'mode'; rule?: string };
+export type PermissionAnswer = { allow: boolean; always?: boolean; message?: string };
+
+/** The rule an "always allow" adds: Claude's own suggestion, else the exact command or path. */
+function suggestedRule(tool: string, input: Record<string, unknown>, suggestions: any) {
+  const suggestion = (Array.isArray(suggestions) ? suggestions : []).find((entry: any) => entry?.type === 'addRules' && entry.behavior === 'allow' && entry.rules?.length);
+  const rule = suggestion?.rules[0];
+  if (rule?.toolName) return rule.ruleContent ? `${rule.toolName}(${rule.ruleContent})` : rule.toolName;
+  if (tool === 'Bash' && typeof input.command === 'string' && !input.command.includes(')')) return `Bash(${input.command})`;
+  if (typeof input.file_path === 'string' && !input.file_path.includes(')')) return `${tool}(${input.file_path})`;
+  return undefined;
+}
+
+class InputQueue implements AsyncIterable<SDKUserMessage> {
+  private values: SDKUserMessage[] = [];
+  private waiters: Array<(value: IteratorResult<SDKUserMessage>) => void> = [];
+  private ended = false;
+
+  push(value: SDKUserMessage) {
+    if (this.ended) throw new Error('Claude input is closed');
+    const waiter = this.waiters.shift();
+    if (waiter) waiter({ value, done: false });
+    else this.values.push(value);
+  }
+
+  close() {
+    this.ended = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage> {
+    return {
+      next: () => {
+        const value = this.values.shift();
+        if (value) return Promise.resolve({ value, done: false });
+        if (this.ended) {
+          return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+      },
+    };
+  }
+}
+
+/** Claude's permission mode for an ALP mode; full-access skips every permission check. */
+export const claudePermissionMode = (sandbox: string) => sandbox === 'read-only' ? 'default' : sandbox === 'full-access' ? 'bypassPermissions' : 'acceptEdits';
+
+export function claudePermissions(sandbox: string, currentSandbox?: () => string, rules?: PermissionRules | null, ask?: (request: PermissionRequest) => Promise<PermissionAnswer>) {
+  const readOnly = sandbox === 'read-only';
+  // A skill only adds instructions; what they lead to is checked as itself (ALPD §59).
+  const readers = ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Skill'];
+  return {
+    // Plan mode permits writes to plan files and requires ExitPlanMode approval.
+    // Fixed read-only callers restrict the tool surface; live sessions keep
+    // tools available and consult the current sandbox at the permission gate.
+    permissionMode: claudePermissionMode(sandbox),
+    // Lets a live session switch to full-access later; it bypasses nothing by itself.
+    allowDangerouslySkipPermissions: true,
+    ...(readOnly && !currentSandbox ? { tools: [...readers, ...(rules?.floor === 'read-only' ? ['Bash'] : [])] } : {}),
+    // Allow rules run without asking, even in a read-only session; deny rules hold even with full access.
+    ...(rules?.allow.length ? { allowedTools: rules.allow } : {}),
+    disallowedTools: ['Agent', 'Task', 'TeamCreate', 'EnterPlanMode', 'ExitPlanMode', ...(rules?.deny ?? [])],
+    // Ask rules make Claude consult canUseTool in every mode, which asks the user.
+    ...(rules?.ask?.length ? { settings: { permissions: { ask: rules.ask } } } : {}),
+    // The floor: Bash runs in the OS sandbox, which writes only the workspace (or nothing, read-only) and temp files, offline.
+    // A command leaves it only with dangerouslyDisableSandbox, which Claude allows itself for allow rules and asks canUseTool otherwise.
+    ...(rules?.floor ? { sandbox: { enabled: true, autoAllowBashIfSandboxed: false, allowUnsandboxedCommands: true, ...(rules.floor === 'read-only' && rules.floorRoot ? { filesystem: { denyWrite: [rules.floorRoot] } } : {}) } } : {}),
+    canUseTool: async (name: string, input: Record<string, unknown>, context?: { decisionReasonType?: string; suggestions?: unknown }) => {
+      const mode = currentSandbox ? currentSandbox() : sandbox;
+      const leaving = Boolean(rules?.floor) && name === 'Bash' && input.dangerouslyDisableSandbox === true;
+      // Inside a read-only floor the OS keeps Bash from writing, so it may run.
+      const sandboxed = rules?.floor === 'read-only' && name === 'Bash' && !leaving;
+      const beyond = (mode === 'read-only' && !readers.includes(name) && !name.startsWith('mcp__alp__') && !sandboxed) ||
+        // With a floor, file tools write only the workspace and temp files, like Bash.
+        (Boolean(rules?.floor && rules.floorRoot) && WRITERS.includes(name) && !writablePath(name === 'NotebookEdit' ? input.notebook_path : input.file_path, rules!.floorRoot!)) ||
+        (leaving && mode !== 'full-access');
+      if (leaving && typeof input.command === 'string' && rules) {
+        const decision = commandDecision(rules, input.command);
+        if (decision === 'deny') return { behavior: 'deny', message: 'A deny rule of your permission profile covers it' };
+        if (decision === 'allow') return { behavior: 'allow', updatedInput: input };
+        if (decision === 'ask' && ask) context = { ...context, decisionReasonType: 'rule' };
+      }
+      const reason = context?.decisionReasonType === 'rule' && (rules?.ask?.length || leaving) ? 'rule' : beyond && rules?.beyondMode === 'ask' ? 'mode' : undefined;
+      if (reason && ask) {
+        const rule = reason === 'mode' ? suggestedRule(name, input, context?.suggestions) : undefined;
+        const answer = await ask({ tool: name, input, reason, ...(rule ? { rule } : {}) });
+        if (!answer.allow) return { behavior: 'deny', message: answer.message ?? 'The user did not allow it' };
+        const [, toolName, ruleContent] = /^([^(]+)(?:\((.*)\))?$/s.exec(rule ?? '') ?? [];
+        // The read-only floor would refuse the very write the user just allowed: run that command outside it.
+        const approved = sandboxed && reason === 'rule' ? { ...input, dangerouslyDisableSandbox: true } : input;
+        return { behavior: 'allow', updatedInput: approved, ...(answer.always && toolName ? { updatedPermissions: [{ type: 'addRules', rules: [{ toolName, ...(ruleContent ? { ruleContent } : {}) }], behavior: 'allow', destination: 'session' }] } : {}) };
+      }
+      if (leaving && beyond) return { behavior: 'deny', message: 'Bash runs inside the sandbox; leaving it needs an allow rule in your permission profile' };
+      if (beyond) return { behavior: 'deny', message: mode === 'read-only' ? 'ALP session is read-only' : 'Outside your workspace' };
+      return { behavior: 'allow', updatedInput: input };
+    },
+  };
+}
+
+/** Whether Claude's last rate limit report means requests are refused: rejected, with no overage to fall back on. */
+export const claudeLimited = (info?: { status: string; overageStatus?: string }) =>
+  info?.status === 'rejected' && info.overageStatus !== 'allowed' && info.overageStatus !== 'allowed_warning';
+
+/** How long a resume waits for Claude to start before it goes on (ClaudeTransport.booted). */
+const BOOT_MS = 15_000;
+
+/**
+ * A Claude session's main chain, read from its transcript by the Agent SDK: user and assistant entries
+ * in order, with their transcript uuids. Found under `dir`'s project, else in any project (a session
+ * resumed or forked from another directory). Empty when the session has no transcript yet.
+ */
+export async function claudeChain(sessionId: string, dir?: string): Promise<Array<{ uuid: string; type: 'user' | 'assistant'; toolResult?: boolean }>> {
+  const { getSessionMessages } = await import(CLAUDE_SDK);
+  let messages: any[] = dir ? await getSessionMessages(sessionId, { dir }) : [];
+  if (!messages.length) messages = await getSessionMessages(sessionId);
+  return messages.filter(message => (message.type === 'user' || message.type === 'assistant') && typeof message.uuid === 'string').map(message => {
+    const content = message.message?.content;
+    const toolResult = message.type === 'user' && Array.isArray(content) && content.length > 0 && content.every((block: any) => block?.type === 'tool_result');
+    return { uuid: message.uuid, type: message.type, ...(toolResult ? { toolResult: true } : {}) };
+  });
+}
+
+/** Maps Claude Agent SDK streaming sessions to the normalized runtime protocol. */
+export class ClaudeTransport {
+  private listeners = new Set<Listener>();
+  private failures = new Set<(error: Error) => void>();
+  private requestHandler?: RequestHandler;
+  /** Whether the workspace had a .claude directory before a sandboxed session started. */
+  private claudeDirectory?: boolean;
+  private input = new InputQueue();
+  private query?: ClaudeQuery;
+  private pump?: Promise<void>;
+  private config?: NativeConfig;
+  private threadId = '';
+  private activeTurn?: string;
+  private closed = false;
+  private assistantText = new Map<string, { blocks: Map<number, { text: string; final: boolean }>; seen: Set<string> }>();
+  private streamingMessage?: string;
+  private toolCalls = new Map<string, { name: string; command: string; input: unknown }>();
+  /** The last rate limit Claude reported, and whether the running turn hit one. */
+  private rateLimit?: { status: string; resetsAt?: number; overageStatus?: string; rateLimitType?: string; utilization?: number };
+  private limitedTurn = false;
+  /** The model's context window and the fill at which Claude compacts it, as Claude reports them (ALPD §57). */
+  private contextWindow?: number;
+  private compactAt?: number;
+  /** The compaction running now, from its start to its boundary. */
+  private compaction?: string;
+  /** The plugin directory that loads the agent's skills, removed on close. */
+  private skillDirectory?: string;
+  /** Whether a turn ran in this process; before one, an error result is a boot refusal. */
+  private turnsStarted = false;
+  /** Rejects when the process fails, for a resume that waits for Claude to start. */
+  private bootFailure?: Promise<never>;
+  private rejectBoot?: (error: Error) => void;
+  private bootError?: Error;
+
+  constructor(
+    private readonly command: string,
+    private readonly cwd: string,
+    private readonly env: NodeJS.ProcessEnv,
+  ) {
+    if (!path.isAbsolute(command)) {
+      const names = process.platform === 'win32' && !path.extname(command) ? [command, `${command}.exe`] : [command];
+      const candidates = (env.PATH ?? '').split(path.delimiter).filter(Boolean).flatMap(directory => names.map(name => path.resolve(directory, name)));
+      const executable = candidates.find(candidate => {
+        try { accessSync(candidate, constants.X_OK); return statSync(candidate).isFile(); } catch { return false; }
+      });
+      if (!executable) throw new Error('Claude executable not found on PATH; set ALP_CLAUDE_BIN to an absolute native executable');
+      this.command = realpathSync(executable);
+    }
+    if (/\.(cmd|bat|ps1)$/i.test(this.command)) {
+      throw new Error('Claude executable must be a native binary, not a shell launcher');
+    }
+  }
+
+  async orchestrationContext() {
+    const [catalog, usage] = await Promise.all([
+      optionalRead(async () => this.query ? this.query.supportedModels() : undefined),
+      // Without a session yet, a short-lived Claude process answers (ALPD §58); it takes a second or two.
+      this.query
+        ? optionalRead(async () => this.query!.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true }))
+        : optionalRead(() => this.probeUsage(), 15_000),
+    ]);
+    return { runtime: 'claude', observedAt: new Date().toISOString(), catalogAvailable: Array.isArray(catalog),
+      models: (catalog ?? []).map(model => ({ id: `claude:${model.value}`, label: model.displayName,
+        description: model.description, thinking: model.supportedEffortLevels })), usage: claudeUsage(usage) };
+  }
+  async initialize() {}
+
+  /** The plan's usage windows before a session starts, from a Claude process that sends no prompt and is closed after. */
+  private async probeUsage() {
+    if (this.closed) return undefined;
+    const { query } = await import(CLAUDE_SDK);
+    const probe = query({ prompt: new InputQueue(), options: { cwd: this.cwd, env: this.env, settingSources: [], persistSession: false, strictMcpConfig: true, mcpServers: {}, pathToClaudeCodeExecutable: this.command } }) as ClaudeQuery;
+    try {
+      return await probe.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true });
+    } finally {
+      probe.close();
+    }
+  }
+
+  onNotification(listener: Listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onFailure(listener: (error: Error) => void) {
+    this.failures.add(listener);
+    return () => this.failures.delete(listener);
+  }
+
+  onRequest(handler: RequestHandler) {
+    this.requestHandler = handler;
+  }
+
+  async request(method: string, params: any): Promise<any> {
+    if (this.closed) throw new Error('Runtime is closed');
+
+    if (method === 'session/configure') {
+      if (!this.query || !this.config) throw new Error('Claude thread is not initialized');
+      await this.query.setPermissionMode(claudePermissionMode(params.sandbox));
+      this.config.sandbox = params.sandbox;
+      return {};
+    }
+
+    if (method === 'thread/chain') return { entries: await claudeChain(params.threadId, params.cwd ?? this.cwd) };
+
+    if (method === 'thread/delete') {
+      const { deleteSession } = await import(CLAUDE_SDK);
+      await deleteSession(params.threadId, params.cwd ? { dir: params.cwd } : {});
+      return {};
+    }
+
+    if (method === 'thread/start' || method === 'thread/resume' || method === 'thread/fork') {
+      this.clearAssistantText();
+      const { base, requireHistory, ...config } = params as NativeConfig & { base?: { threadId: string; at?: string }; requireHistory?: boolean };
+      this.config = config as NativeConfig;
+      this.threadId =
+        method === 'thread/resume' ? params.threadId : randomUUID();
+      // A fork resumes the thread's history under a new id, leaving the thread itself unchanged.
+      const from = method === 'thread/start' ? undefined
+        : method === 'thread/resume' ? await this.resumeFrom(params.threadId, base, requireHistory)
+        : { resume: params.threadId, fork: true };
+      await this.start(from);
+      // A resume Claude refuses at boot (a missing session, a cut it cannot make) fails this request, not a later turn.
+      if (method === 'thread/resume' && (base || requireHistory)) await this.booted();
+      return {
+        thread: { id: this.threadId, turns: [] },
+        cwd: this.cwd,
+        model: params.model,
+        reasoningEffort: params.thinking,
+      };
+    }
+
+    if (method === 'turn/start' || method === 'turn/steer') {
+      if (!this.query) throw new Error('Claude thread is not initialized');
+      const turnId = method === 'turn/steer'
+        ? params.expectedTurnId
+        : randomUUID();
+      if (method === 'turn/start') {
+        this.clearAssistantText();
+        this.activeTurn = turnId;
+        this.turnsStarted = true;
+      }
+      this.input.push({
+        type: 'user',
+        message: {
+          role: 'user',
+          content: params.input.map(claudeContent),
+        },
+        parent_tool_use_id: null,
+        // A turn's prompt entry in the transcript carries the turn's id, so ALP can cut the conversation at it (§12.7).
+        uuid: method === 'turn/start' ? turnId : randomUUID(),
+        session_id: this.threadId,
+      });
+      return method === 'turn/start' ? { turn: { id: turnId } } : {};
+    }
+
+    if (method === 'turn/interrupt') {
+      this.streamingMessage = undefined;
+      await this.query?.interrupt();
+      return {};
+    }
+
+    throw new Error(`Unsupported Claude runtime operation '${method}'`);
+  }
+
+  /**
+   * How a resume starts. With a base, a session whose transcript does not exist yet is made from the
+   * base's conversation cut at `at` (a fork or rewind, §12.7): Claude writes it, under this session's
+   * id, only when its first prompt runs. Otherwise, the session's own transcript.
+   */
+  private async resumeFrom(threadId: string, base?: { threadId: string; at?: string }, requireHistory?: boolean) {
+    const own = base || requireHistory ? await claudeChain(threadId, this.config!.cwd) : [];
+    if (!base || own.length) {
+      if (requireHistory && !own.length) throw new Error(`Claude session ${threadId} not found`);
+      return { resume: threadId, fork: false };
+    }
+    const source = await claudeChain(base.threadId, this.config!.cwd);
+    if (!source.length) throw new Error(`Claude session ${base.threadId} not found`);
+    if (base.at && !source.some(entry => entry.uuid === base.at)) throw new Error(`Claude session ${base.threadId} has no entry ${base.at}`);
+    return { resume: base.threadId, fork: true, at: base.at };
+  }
+
+  /**
+   * Waits until Claude has started: its answer to the SDK's initialize request, or the failure that
+   * ends it first. Past BOOT_MS ALP goes on, as any resume does, and a later refusal fails the session.
+   */
+  private async booted() {
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        this.query!.initializationResult?.().then(() => undefined, () => undefined),
+        this.bootFailure,
+        new Promise<void>(resolve => { timer = setTimeout(resolve, BOOT_MS); }),
+      ]);
+    } finally { clearTimeout(timer); }
+    // A refusal can arrive with the answer itself; let the stream deliver it.
+    await new Promise(resolve => setImmediate(resolve));
+    if (this.bootError) throw this.bootError;
+  }
+
+  private async start(from?: { resume: string; fork: boolean; at?: string }) {
+    const { createSdkMcpServer, query, tool } = await import(CLAUDE_SDK);
+    const config = this.config!;
+    const mcpServers = this.convertMcp(config.mcpServers);
+
+    if (config.dynamicTools.length) {
+      const tools = config.dynamicTools.map(definition => {
+        const base = toolShapes[definition.name];
+        if (!base) throw new Error(`Unsupported ALP tool '${definition.name}'`);
+        // A role's definition may offer fewer actions (alp_task) and fewer fields than the full shape.
+        const schema = (definition as { inputSchema?: { properties?: Record<string, { enum?: string[] }> } }).inputSchema?.properties;
+        const actions = schema?.action?.enum;
+        const shape = Object.fromEntries(Object.entries(base)
+          .filter(([key]) => !schema || key in schema)
+          .map(([key, value]) => [key, key === 'action' && actions?.length ? z.enum(actions as [string, ...string[]]) : value]));
+        return tool(definition.name, definition.description, shape, async (args: Record<string, unknown>) => {
+          if (!this.requestHandler || !this.activeTurn) {
+            return {
+              content: [{ type: 'text', text: 'ALP tools are unavailable' }],
+              isError: true,
+            };
+          }
+          const callId = `claude-tool-${randomUUID()}`;
+          this.emit('item/started', {
+            threadId: this.threadId,
+            item: {
+              type: 'dynamicToolCall',
+              id: callId,
+              callId,
+              tool: definition.name,
+              arguments: args,
+              status: 'inProgress',
+            },
+          });
+          const result: any = await this.requestHandler('item/tool/call', {
+            threadId: this.threadId,
+            turnId: this.activeTurn,
+            callId,
+            namespace: null,
+            tool: definition.name,
+            arguments: args,
+          });
+          this.emit('item/completed', {
+            threadId: this.threadId,
+            item: {
+              type: 'dynamicToolCall',
+              id: callId,
+              callId,
+              tool: definition.name,
+              arguments: args,
+              status: result?.success === false ? 'failed' : 'completed',
+              success: result?.success !== false,
+              contentItems: result?.contentItems ?? [],
+            },
+          });
+          return {
+            content: (result?.contentItems ?? []).map((item: any) => ({
+              type: 'text' as const,
+              text: item.text ?? JSON.stringify(item),
+            })),
+            isError: result?.success === false,
+          };
+        });
+      });
+      mcpServers.alp = createSdkMcpServer({
+        name: 'alp',
+        version: '0.0.0',
+        tools,
+      });
+    }
+
+    if (config.floor) this.claudeDirectory ??= existsSync(path.join(config.cwd, '.claude'));
+    const rules = config.permissions || config.floor ? { allow: [], deny: [], ...config.permissions, ...(config.floor ? { floor: config.floor, floorRoot: config.cwd } : {}) } : null;
+    const { settings: ruleSettings, ...permissions } = claudePermissions(config.sandbox, () => config.sandbox, rules,
+      async request => (this.requestHandler ? await this.requestHandler('item/permission/request', request) as PermissionAnswer : { allow: false, message: 'No one can approve it' }));
+    const settings = { ...(config.thinking === 'ultracode' ? { ultracode: true } : {}), ...(config.context ? { autoCompactWindow: config.context } : {}), ...ruleSettings };
+    // The agent's skills as Claude Code's own, so Claude lists them with their descriptions and calls them with Skill.
+    const plugins: Array<{ type: 'local'; path: string; skipMcpDiscovery: boolean }> = [];
+    if (config.skills?.length) {
+      try {
+        this.skillDirectory ??= path.join(os.tmpdir(), 'alp-skills', randomUUID());
+        plugins.push({ type: 'local', path: skillPlugin(this.skillDirectory, config.skills), skipMcpDiscovery: true });
+      } catch {
+        // The skills stay listed in the instructions by file.
+      }
+    }
+    const options = {
+      cwd: config.cwd,
+      env: this.env,
+      model: config.model,
+      effort: ['none', 'off', 'ultracode'].includes(config.thinking) ? undefined : config.thinking,
+      thinking: ['none', 'off'].includes(config.thinking) ? { type: 'disabled' } : { type: 'adaptive' },
+      systemPrompt: config.developerInstructions,
+      ...permissions,
+      ...(Object.keys(settings).length ? { settings } : {}),
+      mcpServers,
+      strictMcpConfig: true,
+      settingSources: [],
+      ...(plugins.length ? { plugins } : {}),
+      persistSession: !config.ephemeral,
+      promptSuggestions: false,
+      includePartialMessages: true,
+      ...(from ? { resume: from.resume, ...(from.fork ? { forkSession: true, sessionId: this.threadId } : {}), ...(from.at ? { resumeSessionAt: from.at } : {}) } : { sessionId: this.threadId }),
+      // Explicit native path avoids SDK optional binaries inside Electron app.asar.
+      pathToClaudeCodeExecutable: this.command,
+    };
+
+    this.bootFailure = new Promise<never>((_, reject) => { this.rejectBoot = reject; });
+    this.bootFailure.catch(() => {});
+    this.query = query({ prompt: this.input, options }) as ClaudeQuery;
+    this.pump = this.consume(this.query).catch((error) => this.fail(error));
+    void this.measureContext();
+  }
+
+  /** Reads the window and the compaction threshold Claude resolved for this session, before any turn. */
+  private async measureContext() {
+    // The first read waits for Claude to start; a reply from usage lets ALP guess meanwhile.
+    const usage: any = await optionalRead(async () => this.query?.getContextUsage({ detail: 'summary' }), 60_000);
+    if (!usage) return;
+    const window = usage.rawMaxTokens ?? usage.maxTokens;
+    if (typeof window === 'number' && window > 0) this.contextWindow = window;
+    this.compactAt = usage.isAutoCompactEnabled !== false && typeof usage.autoCompactThreshold === 'number' && usage.autoCompactThreshold > 0 ? usage.autoCompactThreshold : undefined;
+  }
+
+  private convertMcp(values: Record<string, any>) {
+    const result: Record<string, any> = {};
+    for (const [name, value] of Object.entries(values)) {
+      result[name] = value.url
+        ? {
+            type: 'http',
+            url: value.url,
+            headers: value.http_headers ?? {},
+          }
+        : {
+            type: 'stdio',
+            command: value.command,
+            args: value.args ?? [],
+            env: value.env ?? {},
+          };
+    }
+    return result;
+  }
+
+  private async consume(stream: ClaudeQuery) {
+    for await (const message of stream) this.handle(message);
+    if (!this.closed) this.fail(new Error('Claude session exited'));
+  }
+
+  private handle(message: SDKMessage) {
+    if (this.closed) return;
+    if (message.type === 'rate_limit_event') {
+      this.rateLimit = message.rate_limit_info;
+      this.emit('account/rateLimits/updated', { claude: message.rate_limit_info });
+      return;
+    }
+    // Claude starts a turn by itself when a background task it ran ends (ALPD §56). Adopt it, so
+    // ALP's tools work in it and its end is reported like any other turn's.
+    const streamStart = message.type === 'stream_event' && message.event?.type === 'message_start';
+    if ((message.type === 'assistant' || streamStart) && !message.parent_tool_use_id && !this.activeTurn) {
+      this.activeTurn = randomUUID();
+      this.emit('turn/started', { threadId: this.threadId, turn: { id: this.activeTurn } });
+    }
+    if (message.type === 'stream_event') {
+      if (message.parent_tool_use_id) return;
+      const event = message.event;
+      if (event.type === 'message_start') {
+        this.streamingMessage = event.message.id;
+      } else if (event.type === 'message_stop') {
+        this.streamingMessage = undefined;
+      } else if (this.streamingMessage) {
+        const id = this.streamingMessage;
+        const state = this.assistantState(id);
+        let delta: string | undefined;
+        if (event.type === 'content_block_start' && event.content_block.type === 'text') {
+          state.blocks.set(event.index, { text: event.content_block.text, final: false });
+          delta = event.content_block.text;
+        } else if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+          const block = state.blocks.get(event.index);
+          if (block && !block.final) {
+            block.text += event.delta.text;
+            delta = event.delta.text;
+          }
+        }
+        if (delta) this.emit('item/agentMessage/delta', { threadId: this.threadId, turnId: this.activeTurn, itemId: id, delta });
+      }
+      return;
+    }
+    if (message.type === 'assistant' && message.error === 'rate_limit') this.limitedTurn = true;
+    // The model Claude Code says it runs this query with (its init message), so ALP can show it took a configured one (§12.9).
+    if (message.type === 'system' && message.subtype === 'init' && typeof (message as any).model === 'string') this.emit('alp/nativeModel', { threadId: this.threadId, model: (message as any).model });
+    // A compaction, reported as Codex reports one: a contextCompaction item from start to end (ALPD §57).
+    if (message.type === 'system' && (message.subtype === 'status' || message.subtype === 'compact_boundary')) {
+      const system = message as any;
+      if (system.subtype === 'status' && system.status === 'compacting' && !this.compaction) {
+        this.compaction = randomUUID();
+        this.emit('item/started', { threadId: this.threadId, turnId: this.activeTurn, item: { type: 'contextCompaction', id: this.compaction } });
+      } else if (system.subtype === 'status' && system.compact_result === 'failed') {
+        this.emit('item/completed', { threadId: this.threadId, turnId: this.activeTurn, item: { type: 'contextCompaction', id: this.compaction ?? randomUUID(), status: 'failed', error: system.compact_error } });
+        this.compaction = undefined;
+      } else if (system.subtype === 'compact_boundary') {
+        const meta = system.compact_metadata ?? {};
+        this.emit('item/completed', {
+          threadId: this.threadId, turnId: this.activeTurn,
+          item: { type: 'contextCompaction', id: this.compaction ?? randomUUID(), status: 'completed', trigger: meta.trigger, preTokens: meta.pre_tokens, postTokens: meta.post_tokens },
+        });
+        this.compaction = undefined;
+      }
+      return;
+    }
+    // How full the context is, reported as Codex does: the tokens of the latest model call against the window.
+    // Until Claude has said what its window is, ALP does not guess one (ALPD §57).
+    const usage = message.type === 'assistant' && !message.parent_tool_use_id ? (message.message as any).usage : undefined;
+    if (usage) {
+      const totalTokens = (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.output_tokens ?? 0);
+      const last = { totalTokens, inputTokens: usage.input_tokens ?? 0, cachedInputTokens: usage.cache_read_input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0 };
+      this.emit('thread/tokenUsage/updated', {
+        threadId: this.threadId, turnId: this.activeTurn,
+        tokenUsage: { last, total: last, modelContextWindow: this.contextWindow ?? null, ...(this.compactAt ? { autoCompactTokens: this.compactAt } : {}) },
+      });
+    }
+    if (message.type === 'result') {
+      // The session's cost so far, as Claude counts it; a viewer shows it with the context meter.
+      const cost = (message as any).total_cost_usd;
+      if (typeof cost === 'number' && Number.isFinite(cost) && cost >= 0) this.emit('thread/tokenUsage/updated', { threadId: this.threadId, turnId: this.activeTurn, tokenUsage: { totalCostUsd: cost } });
+      const windows = Object.values((message as any).modelUsage ?? {}).map((entry: any) => entry?.contextWindow).filter((value): value is number => typeof value === 'number' && value > 0);
+      // Only when it was not measured: the measured window may be the setting's, smaller than the model's.
+      if (windows.length && !this.compactAt) this.contextWindow = Math.max(...windows);
+    }
+    if (message.type === 'assistant' && !message.parent_tool_use_id) {
+      const id = message.message.id;
+      const state = this.assistantState(id);
+      if (message.uuid && state.seen.has(message.uuid)) return;
+      if (message.uuid) state.seen.add(message.uuid);
+      for (const block of message.message.content as any[]) {
+        if (block.type === 'text') {
+          // SDK 0.3.292 delivers one authoritative assistant event per completed
+          // block, sharing message.id. Replace that block's draft, never append
+          // the final text to its streamed draft or replace earlier final blocks.
+          const pending = [...state.blocks.entries()].sort(([a], [b]) => a - b).find(([, value]) => !value.final);
+          const index = pending?.[0] ?? Math.max(-1, ...state.blocks.keys()) + 1;
+          state.blocks.set(index, { text: block.text, final: true });
+          this.emit('item/completed', {
+            threadId: this.threadId,
+            item: { type: 'agentMessage', id, text: [...state.blocks.entries()].sort(([a], [b]) => a - b).map(([, block]) => block.text).join('') },
+          });
+        } else if (block.type === 'tool_use') {
+          const command = block.name === 'Bash'
+            ? String(block.input?.command ?? '')
+            : `${block.name} ${JSON.stringify(block.input ?? {})}`;
+          this.toolCalls.set(block.id, { name: block.name, command, input: block.input });
+          // The command stays what skill use, copy escapes and the journal read; the typed detail rides along.
+          const detail = claudeToolDetail(block.name, block.input);
+          this.emit('item/started', {
+            threadId: this.threadId,
+            item: {
+              type: 'commandExecution',
+              id: block.id,
+              command,
+              cwd: this.cwd,
+              status: 'inProgress',
+              aggregatedOutput: '',
+              ...(detail ? { tool: block.name, detail } : {}),
+            },
+          });
+        }
+      }
+      return;
+    }
+
+    if (message.type === 'user') {
+      const content = Array.isArray(message.message.content)
+        ? message.message.content as any[]
+        : [];
+      // The SDK's structured output belongs to the message's one tool result.
+      const results = content.filter(block => block.type === 'tool_result');
+      const structured = results.length === 1 ? (message as any).tool_use_result : undefined;
+      for (const block of results) {
+        const call = this.toolCalls.get(block.tool_use_id);
+        if (!call) continue;
+        const output = typeof block.content === 'string'
+          ? block.content
+          : JSON.stringify(block.content ?? '');
+        const text = resultText(block.content);
+        const detail = claudeToolDetail(call.name, call.input, { text, structured, error: Boolean(block.is_error) });
+        this.emit('item/completed', {
+          threadId: this.threadId,
+          item: {
+            type: 'commandExecution',
+            id: block.tool_use_id,
+            command: call.command,
+            cwd: this.cwd,
+            status: block.is_error ? 'failed' : 'completed',
+            exitCode: block.is_error ? 1 : 0,
+            aggregatedOutput: output,
+            ...(detail ? { tool: call.name, detail, ...(block.is_error ? { error: text } : {}) } : {}),
+          },
+        });
+        this.toolCalls.delete(block.tool_use_id);
+      }
+      return;
+    }
+
+    // Before any turn, an error result is Claude refusing to start the session (a resume it rejected).
+    // The SDK then ends the stream with this error, which fails the transport as before.
+    if (message.type === 'result' && message.is_error && !this.activeTurn && !this.turnsStarted) {
+      this.refuseBoot(new Error(message.errors?.length ? message.errors.join('; ') : 'Claude refused to start the session'));
+      return;
+    }
+    if (message.type === 'result') this.clearAssistantText();
+    if (message.type === 'result' && this.activeTurn) {
+      const turnId = this.activeTurn;
+      this.activeTurn = undefined;
+      // A usage limit ends the turn with an error message or a failed result; report it as Codex does.
+      const limited = this.limitedTurn || (message.is_error && claudeLimited(this.rateLimit));
+      this.limitedTurn = false;
+      const failed = message.is_error || limited;
+      this.emit('turn/completed', {
+        threadId: this.threadId,
+        turn: {
+          id: turnId,
+          status: failed ? 'failed' : 'completed',
+          ...(failed
+            ? { error: {
+              message: limited ? `Claude usage limit reached${this.rateLimit?.resetsAt ? `; resets ${new Date(this.rateLimit.resetsAt * 1000).toISOString()}` : ''}` : 'errors' in message && message.errors?.length ? message.errors.join('; ') : 'Claude turn failed',
+              ...(limited ? { codexErrorInfo: 'usageLimitExceeded', ...(this.rateLimit?.resetsAt ? { resetsAt: this.rateLimit.resetsAt } : {}) } : {}),
+            } }
+            : {}),
+        },
+      });
+    }
+  }
+
+  private refuseBoot(error: Error) {
+    this.bootError ??= error;
+    this.rejectBoot?.(error);
+  }
+
+  private emit(method: string, params: any) {
+    for (const listener of this.listeners) listener(method, params);
+  }
+
+  private assistantState(id: string) {
+    let state = this.assistantText.get(id);
+    if (!state) this.assistantText.set(id, state = { blocks: new Map(), seen: new Set() });
+    return state;
+  }
+
+  private clearAssistantText() {
+    this.streamingMessage = undefined;
+    this.assistantText.clear();
+  }
+
+  private fail(value: unknown) {
+    if (this.closed) return;
+    this.clearAssistantText();
+    const error = value instanceof Error ? value : new Error(String(value));
+    this.refuseBoot(error);
+    for (const listener of this.failures) listener(error);
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.clearAssistantText();
+    this.input.close();
+    this.query?.close();
+    await this.pump?.catch(() => {});
+    this.listeners.clear();
+    this.failures.clear();
+    if (this.skillDirectory) rmSync(this.skillDirectory, { recursive: true, force: true });
+    // Claude's sandbox leaves an empty .claude/.cc-writes in the workspace; remove what it created.
+    if (this.claudeDirectory === false && this.config) {
+      for (const directory of ['.claude/.cc-writes', '.claude']) { try { rmdirSync(path.join(this.config.cwd, directory)); } catch {} }
+    }
+  }
+}