@controlflow-ai/daemon 0.1.0

package/README.md

@@ -0,0 +1,360 @@
+# pal
+
+Small Bun demo for the Lock idea: a local message server, a daemon that connects a computer, and CLI surfaces for humans, agents, and Lark bots.
+
+## Architecture
+
+| Component | Script | Role | Default endpoint |
+|-----------|--------|------|------------------|
+| **Server** | `bun run server` | Message platform, control API, web workbench, Lark websocket host | `http://127.0.0.1:4127` |
+| **Daemon** | `bun run daemon` | Connects one computer, claims deliveries for assigned agents, runs coding-agent CLIs | local API `http://127.0.0.1:4137` |
+| **Console** | `bun run console -- ...` | Admin CLI that talks directly to the Server | Server API |
+| **CLI** | `bun run cli -- ...` | Agent/human CLI that talks through the local Daemon | Daemon local API |
+
+The current preferred model is computer-first: provision a computer, start one daemon with the provisioned API key, then assign agents to that computer. The daemon can run with zero agents and periodically reconciles assignments from the server, so newly assigned agents start without a daemon restart and removed agents stop being registered for new work.
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+bun install
+```
+
+For disposable local smoke tests, keep state isolated:
+
+```bash
+export PAL_HOME=/tmp/pal-demo
+```
+
+### 2. Start Server
+
+```bash
+bun run server
+```
+
+Server listens on `http://127.0.0.1:4127/` by default. Change the bind address with `PAL_HOST` and the port with `PAL_PORT`:
+
+```bash
+PAL_HOST=0.0.0.0 PAL_PORT=4127 bun run server
+```
+
+When clients or daemons connect through a non-default address, pass `--server <url>` or set `PAL_SERVER` / `LOCK_SERVER_URL` to the reachable URL.
+
+### 3. Provision a Computer
+
+```bash
+curl -s -X POST http://127.0.0.1:4127/api/computers/provision \
+  -H 'content-type: application/json' \
+  -d '{"name":"Local Demo","server_url":"http://127.0.0.1:4127"}'
+```
+
+The response includes a `computer.id`, an `api_key`, and a packaged daemon command. For a source checkout, start the local Bun daemon with the returned key:
+
+```bash
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_...
+```
+
+If no agents are assigned yet, the daemon stays connected, heartbeats the computer, and waits for assignments.
+
+### 4. Create and Assign an Agent
+
+Use `agents onboard` to create/update an agent and optionally assign it to the provisioned computer:
+
+```bash
+bun run console -- agents onboard \
+  --key codex \
+  --name "Codex Agent" \
+  --runtime codex \
+  --computer-id machine_...
+```
+
+If the daemon is already running with the same API key, it will discover the `codex` assignment on a later heartbeat and begin claiming deliveries for it. Restarting is not required.
+
+You can also do the two steps separately:
+
+```bash
+bun run console -- agents create --key codex --name "Codex Agent" --runtime codex --desc "Main coding agent"
+curl -s -X POST http://127.0.0.1:4127/api/agents/codex/assignment \
+  -H 'content-type: application/json' \
+  -d '{"computer_id":"machine_..."}'
+```
+
+### 5. Send a Message
+
+```bash
+# Through the local daemon
+bun run cli -- send --room general --from alice --to codex "hello"
+
+# Directly to the server
+bun run console -- send --chat general --from alice --to codex "hello"
+```
+
+## Console Commands
+
+Console connects to the server directly and is intended for administration.
+
+### Agents
+
+```bash
+# List agents
+bun run console -- agents list [--json]
+
+# Create or update an agent record
+bun run console -- agents create --key <agent-key> --name <display-name> [--runtime neeko|coco|codex] [--desc <description>]
+
+# Create/update an agent and optionally assign it to a computer
+bun run console -- agents onboard --key <agent-key> --name <display-name> [--runtime codex] [--desc <description>] [--computer-id <machine-id>]
+
+# Update only the runtime
+bun run console -- agents update --key <agent-key> --runtime neeko|coco|codex
+```
+
+`codex` is the validated runtime for the current demo environment. Do not use `neeko` or `coco` until their binaries and adapters are available on the runtime host.
+
+### Lark Bots
+
+```bash
+# Configure a bot, resolve its bot open_id, bind it to an agent, and ask the running server to reload Lark
+bun run console -- lark setup --app-id <app-id> --app-secret <app-secret> --label <name> --agent <agent-key>
+
+# Configure a bot and create/update the bound agent in one command
+bun run console -- lark setup \
+  --app-id <app-id> \
+  --app-secret <app-secret> \
+  --label <name> \
+  --agent codex \
+  --create-agent \
+  --agent-name "Codex" \
+  --runtime codex \
+  --computer-id <machine-id>
+
+# List configured bots; secrets are redacted
+bun run console -- lark list
+
+# View recent raw Lark events
+bun run console -- lark events --limit 20
+
+# Send a message through a configured bot
+bun run console -- lark send --app-id <app-id> --to <receive_id> [--to-type chat_id|open_id|union_id|email|user_id] "Hello"
+```
+
+`lark setup` writes `~/.pal/lark.json` or `PAL_LARK_CONFIG` with mode `0600`. By default it calls `POST /api/lark/reload` on the running server after a successful write. Use `--no-reload` when you want to edit or validate the file first, then trigger reload manually:
+
+```bash
+curl -s -X POST http://127.0.0.1:4127/api/lark/reload
+```
+
+Reload scans the config explicitly. If the file is invalid, the server keeps existing Lark websocket listeners running and returns an error instead of dropping them.
+
+The older `bun run console -- lark daemon ...` command still exists for standalone Lark testing, but normal server operation now hosts Lark websocket clients inside `bun run server`.
+
+### Messages and Runs
+
+```bash
+# Health check
+bun run console -- health
+
+# List rooms/chats
+bun run console -- chats [--json]
+
+# View messages
+bun run console -- messages [--chat general] [--parent 1] [--after 0] [--limit 50] [--q text] [--json]
+
+# View an agent inbox
+bun run console -- inbox --agent codex [--after 0] [--limit 50] [--json]
+
+# List runs
+bun run console -- runs [--json]
+
+# Control a run
+bun run console -- run-action <run-id> kill
+bun run console -- run-action <run-id> restart
+```
+
+## CLI Commands
+
+CLI connects through the local daemon. It is the surface used by coding agents and local operators once the daemon is running.
+
+### Rooms, Topics, and Messages
+
+```bash
+# Send a message
+bun run cli -- send --room general --from alice [--to codex] "Task completed"
+
+# Reply to an existing message
+bun run cli -- send --room general --from codex --parent 1 "Reply content"
+
+# Send file content as a message
+bun run cli -- send --room general --from codex --file /path/to/message.txt
+
+# List rooms and members
+bun run cli -- rooms list [--json]
+bun run cli -- rooms members --room general [--json]
+
+# Invite an agent to a room with a delivery mode
+bun run cli -- rooms invite --room general --agent codex [--mode mentions|all|periodic|muted|off]
+
+# Create a topic inside a room
+bun run cli -- topics create --room general "Investigation"
+
+# List or show messages
+bun run cli -- messages list [--room general] [--topic 1] [--after 0] [--limit 50] [--q text] [--json]
+bun run cli -- messages show <message-id> [--json]
+
+# Start a simple agent-to-agent debate workflow
+bun run cli -- debate start --chat general --a codex --b reviewer [--turns 6] "Topic"
+```
+
+### Artifacts
+
+```bash
+# Upload an HTML file through the daemon to the server
+bun run cli -- http file /path/to/report.html --mime text/html --title "Report"
+
+# Upload with a TTL in seconds
+bun run cli -- http file /path/to/data.json --mime application/json --ttl 3600
+```
+
+### Query and Control
+
+```bash
+bun run cli -- health
+bun run cli -- chats [--json]
+bun run cli -- runs [--json]
+bun run cli -- run-action <run-id> kill
+bun run cli -- run-action <run-id> restart
+```
+
+## Daemon Commands
+
+```bash
+# Preferred computer-first startup
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_...
+
+# Equivalent env-var startup
+PAL_API_KEY=sk_machine_... bun run daemon -- --server http://127.0.0.1:4127
+
+# Custom polling interval and daemon local API port
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_... --interval 3000 --local-port 4137
+
+# Dry run: claim and record runs without executing the agent runtime
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_... --dry-run
+
+# Legacy explicit-agent startup using a computer id/secret instead of an API key
+bun run daemon -- --agent codex --computer-id hm-media-demo --computer-secret pal-demo-computer-secret --cwd /path/to/workspace
+
+# One-shot processing for tests or scripts
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_... --once
+```
+
+The daemon creates one local API for CLI calls, connects the computer to the server, heartbeats the connection, reconciles assigned agents, claims pending deliveries for currently assigned agents, and starts one runtime process per claimed delivery. It can stay online with no assigned agents. Runs have no default timeout; use run actions to kill or restart them.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PAL_HOME` | `~/.pal` | Runtime home for DB, daemon state, Lark config, and agent homes |
+| `PAL_DB` | `$PAL_HOME/lock.sqlite` | SQLite database path |
+| `PAL_HOST` | `127.0.0.1` | Server bind host used by `bun run server`; set `0.0.0.0` to listen on all interfaces |
+| `PAL_PORT` | `4127` | Server bind port used by `bun run server` |
+| `PAL_SERVER` | `http://127.0.0.1:4127` | Reachable server URL for console/daemon clients; update this when `PAL_HOST`/`PAL_PORT` change client access |
+| `LOCK_SERVER_URL` | - | Alternate server URL env read before `PAL_SERVER` |
+| `PAL_API_KEY` | - | Provisioned computer API key for daemon startup |
+| `PAL_AGENT` | - | Optional legacy explicit agent for daemon startup |
+| `PAL_COMPUTER_ID` | - | Legacy computer id when not using `PAL_API_KEY` |
+| `PAL_COMPUTER_SECRET` | - | Legacy computer secret when not using `PAL_API_KEY` |
+| `LOCK_DAEMON_URL` | `http://127.0.0.1:4137` | Local daemon API URL used by `bun run cli` |
+| `LOCK_DAEMON_TOKEN` | token file fallback | Local daemon API bearer token |
+| `PAL_LARK_CONFIG` | `$PAL_HOME/lark.json` | Lark bot credential file |
+| `PAL_OWNER_LARK_UNION_ID` | - | Optional Lark sender allowlist for business ingest |
+| `PAL_LARK_ACTION_REACTION_EMOJI` | `Typing` | Reaction added when Lark delivery is created |
+
+## Runtime Semantics
+
+- Rooms are the primary conversation container; `chat` remains as a compatibility alias in several APIs.
+- Agents receive deliveries through room subscriptions, direct recipients, or Lark bot bindings.
+- A daemon starts one agent run for each claimed delivery.
+- Runs do not have a default timeout. Agents can work as long as needed.
+- A visible chat reply is just a message, not run completion.
+- A run completes only when the agent exits normally, fails when it exits non-zero, or is explicitly killed/restarted.
+- Restart kills the current process and starts a fresh run for the same message.
+
+## HTTP API
+
+Common read and room APIs:
+
+- `GET /`
+- `GET /health`
+- `GET /api/chats`
+- `GET /api/rooms`
+- `POST /api/rooms`
+- `GET /api/rooms/<room-id-or-name>/members`
+- `GET /api/rooms/<room-id-or-name>/mentionables`
+- `POST /api/rooms/<room-id-or-name>/agents`
+- `POST /api/rooms/<room-id-or-name>/topics`
+- `GET /api/messages?chat=general&after=0&limit=50`
+- `GET /api/messages/<id>`
+- `POST /api/messages`
+- `GET /api/inbox?agent=codex&after=0&limit=50`
+
+Computer, daemon, and delivery APIs:
+
+- `POST /api/computers/provision`
+- `POST /api/computers/connect`
+- `POST /api/computers/<computer-id>/heartbeat`
+- `POST /api/daemons`
+- `GET /api/deliveries?agent=codex&status=pending&limit=50`
+- `POST /api/deliveries`
+- `POST /api/deliveries/<delivery-id>/claim`
+- `POST /api/deliveries/<delivery-id>/ack`
+- `POST /api/deliveries/<delivery-id>/fail`
+
+Agent, session, run, artifact, and Lark APIs:
+
+- `GET /api/agents`
+- `POST /api/agents`
+- `POST /api/agents/onboard`
+- `PATCH /api/agents/<key>`
+- `POST /api/agents/<key>/assignment`
+- `GET /api/sessions`
+- `POST /api/sessions`
+- `GET /api/sessions/<session-id>/runs`
+- `POST /api/sessions/<session-id>/runtime-session`
+- `GET /api/runs`
+- `POST /api/runs`
+- `GET /api/runs/<id>`
+- `POST /api/runs/<id>/pid`
+- `POST /api/runs/<id>/finish`
+- `POST /api/runs/<id>/kill`
+- `POST /api/runs/<id>/restart`
+- `GET /api/artifacts`
+- `POST /api/artifacts`
+- `POST /api/artifacts/cleanup`
+- `POST /api/artifacts/<artifact-id>/revoke`
+- `GET /api/workbench/artifacts`
+- `POST /api/lark/reload`
+
+Example message body:
+
+```json
+{
+  "room": "general",
+  "sender": "alice",
+  "recipient": "codex",
+  "content": "hello"
+}
+```
+
+Example agent onboarding body:
+
+```json
+{
+  "agent_key": "codex",
+  "display_name": "Codex Agent",
+  "runtime": "codex",
+  "computer_id": "machine_..."
+}
+```
+
+This is intentionally not a production architecture. It is a single-node demo to validate the workflow before adding richer routing, auth, WebSocket delivery, UI, or multi-agent adapters.

package/bin/console.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/console.ts';

package/bin/daemon.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/daemon.ts';

package/bin/pal.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/cli.ts';

package/bin/server.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/server.ts';

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@controlflow-ai/daemon",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "server": "bun run src/server.ts",
+    "daemon": "bun run src/daemon.ts",
+    "cli": "bun run src/cli.ts",
+    "console": "bun run src/console.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check": "bun run typecheck && bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.59.0"
+  },
+  "bin": {
+    "daemon": "bin/daemon.js",
+    "pal-daemon": "bin/daemon.js",
+    "pal": "bin/pal.js",
+    "pal-server": "bin/server.js",
+    "pal-console": "bin/console.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent-runtime.ts

@@ -0,0 +1,285 @@
+import type { Message, RoomParticipant, RunAction } from './types.js';
+import { join } from 'node:path';
+import { sanitizeProviderIds } from './provider-identity.js';
+
+export interface AgentRuntimeRunInput {
+  agent: string;
+  serverUrl: string;
+  message: Message;
+  cwd: string;
+  agentHome?: string;
+  projectCwd?: string;
+  extraArgs: string[];
+  localDaemonUrl?: string;
+  localDaemonToken?: string;
+  runtimeSessionId?: string | null;
+  roomParticipants?: RoomParticipant[];
+  recentMessages?: Message[];
+  dryRun?: boolean;
+  privateCliBinDir?: string;
+  palCliCommand?: string;
+  signal?: AbortSignal;
+  onStart?: (pid: number | null) => Promise<void>;
+  getAction?: () => Promise<RunAction | null>;
+}
+
+export function formatRoomParticipantContext(participants: RoomParticipant[] | undefined): string {
+  if (!participants || participants.length === 0) {
+    return '\nRoom participants: no local participant snapshot is available yet.';
+  }
+  const lines = participants.slice(0, 50).map((p) => {
+    const participant = sanitizeProviderIds(p.participant_id);
+    const name = p.display_name ? ` (${sanitizeProviderIds(p.display_name)})` : '';
+    return `- ${p.kind}: ${participant}${name}, source=${p.source}`;
+  });
+  const suffix = participants.length > 50 ? `\n- ... ${participants.length - 50} more participants omitted` : '';
+  return `\nRoom participants:\n${lines.join('\n')}${suffix}`;
+}
+
+export function formatRecentMessageContext(messages: Message[] | undefined, currentMessageId: number): string {
+  if (!messages || messages.length === 0) {
+    return '\nRecent room history: no local message history is available yet.';
+  }
+  const lines = messages.slice(-12).map((message) => {
+    const marker = message.id === currentMessageId ? ' current' : '';
+    const parent = message.parent_id === null ? '' : ` parent=${message.parent_id}`;
+    const recipient = message.recipient ? ` to=@${sanitizeProviderIds(message.recipient)}` : '';
+    const sender = sanitizeProviderIds(message.sender);
+    const content = sanitizeProviderIds(message.content).replace(/\s+/g, ' ').trim().slice(0, 500);
+    return `- [${message.id}${marker}] @${sender}${recipient}${parent}: ${content}`;
+  });
+  const omitted = messages.length > 12 ? `\n- ... ${messages.length - 12} older messages omitted` : '';
+  return `\nRecent room history:\n${lines.join('\n')}${omitted}`;
+}
+
+export function runtimeCwd(input: AgentRuntimeRunInput): string {
+  return input.agentHome ?? input.cwd;
+}
+
+export function runtimeProjectCwd(input: AgentRuntimeRunInput): string {
+  return input.projectCwd ?? input.cwd;
+}
+
+export function buildPalPrompt(input: AgentRuntimeRunInput): string {
+  const palCli = input.palCliCommand ?? 'pal';
+  const thread = input.message.parent_id === null ? '' : `\nTopic parent message id: ${input.message.parent_id}`;
+  const recipient = input.message.recipient ? `\nRecipient: @${sanitizeProviderIds(input.message.recipient)}` : '';
+  const agentHome = runtimeCwd(input);
+  const projectCwd = runtimeProjectCwd(input);
+  const chatName = sanitizeProviderIds(input.message.chat_name);
+  const sender = sanitizeProviderIds(input.message.sender);
+  const content = sanitizeProviderIds(input.message.content);
+
+  return `You are ${input.agent}, a long-running PAL coding agent connected to the pal chat server.
+
+PAL is a multi-agent chat platform where humans and agents collaborate through rooms and topics.
+
+Workspace contract:
+- Your current working directory is your persistent PAL agent home: ${agentHome}
+- Your cwd is for identity, memory, recovery state, scratch files, and durable local notes.
+- Your cwd is not the project repository.
+- The project workspace for source inspection, code changes, tests, and Git work is: ${projectCwd}
+
+Startup recovery:
+- Read MEMORY.md in your cwd first when it exists.
+- Follow its recovery order and read only the referenced state/kb files you need.
+- Keep durable agent memory in your agent home, not in the project repository.
+
+A new chat message arrived.
+
+Message id: ${input.message.id}
+Chat: #${chatName}${thread}
+Sender: @${sender}${recipient}
+${formatRoomParticipantContext(input.roomParticipants)}
+${formatRecentMessageContext(input.recentMessages, input.message.id)}
+Content:
+${content}
+
+Communication rules:
+- Use the PAL CLI for any reply that should be visible in chat.
+- Reply to the same chat/topic unless the user explicitly asks otherwise.
+- Avoid acknowledgment-only replies; send a visible message only when it provides a result, blocker, decision request, ownership signal, or useful progress.
+- Report only work you actually did.
+- Store PAL handles such as user:pal_user_ab12cd34 in durable memory. Never store provider-native IDs such as Feishu/Lark open_id, chat_id, message_id, or app_id values.
+
+Commands:
+- Send a reply to the same chat: ${palCli} send --chat ${chatName} --from ${input.agent} <message>
+- Send a message to another agent and trigger that agent's runtime: ${palCli} send --chat ${chatName} --from ${input.agent} --to <agent-key> <message>
+- Reply in this topic: ${palCli} send --chat ${chatName} --parent ${input.message.parent_id ?? input.message.id} --from ${input.agent} <message>
+- List rooms: ${palCli} rooms list
+- View room members: ${palCli} rooms members --room ${chatName}
+- Read recent chat messages: ${palCli} messages list --room ${chatName}
+- Show one message: ${palCli} messages show <message-id>
+
+Finish naturally when the task is done. There is no fixed timeout for this run.`;
+}
+
+export interface AgentRuntimeRunResult {
+  output: string;
+  exitCode: number | null;
+  stoppedByAction: RunAction | null;
+  runtimeSessionId?: string | null;
+}
+
+export type AgentRuntimeProtocol = 'json-stream' | 'acp';
+
+export interface AgentRuntimeCapabilities {
+  protocol: AgentRuntimeProtocol;
+  resume: 'runtime-session-id' | 'adapter-session-id' | 'none';
+  busyDeliveryMode: 'queue' | 'direct' | 'notification' | 'none';
+  supportsMcp: boolean;
+}
+
+export interface AgentRuntime {
+  readonly name: string;
+  readonly capabilities: AgentRuntimeCapabilities;
+  /** Build the prompt text fed to the agent CLI. */
+  buildPrompt(input: AgentRuntimeRunInput): string;
+  /** Build the CLI argument array (excluding the command name itself). */
+  buildArgs(input: AgentRuntimeRunInput): string[];
+  /** The executable command name (e.g. "neeko", "coco", "codex"). */
+  readonly command: string;
+  /** Return the working directory for the agent process. Defaults to input.agentHome ?? input.cwd. */
+  buildCwd?(input: AgentRuntimeRunInput): string;
+  /** Parse stdout/stderr from the agent process. Defaults to trimmed stdout + stderr. */
+  parseOutput?(input: { stdout: string; stderr: string; input: AgentRuntimeRunInput }): { output: string; runtimeSessionId?: string | null };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function processGroupSignal(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try { process.kill(pid, signal); } catch { /* already exited */ }
+  }
+}
+
+async function stopProcess(proc: ReturnType<typeof Bun.spawn>): Promise<number | null> {
+  processGroupSignal(proc.pid, 'SIGTERM');
+  const graceful = await Promise.race([
+    proc.exited.then((exitCode) => ({ exited: true as const, exitCode })),
+    sleep(2000).then(() => ({ exited: false as const })),
+  ]);
+
+  if (graceful.exited) return graceful.exitCode;
+
+  processGroupSignal(proc.pid, 'SIGKILL');
+  proc.kill('SIGKILL');
+  return await Promise.race([
+    proc.exited,
+    sleep(500).then(() => null),
+  ]);
+}
+
+async function waitForExitOrAction(
+  proc: ReturnType<typeof Bun.spawn>,
+  input: AgentRuntimeRunInput,
+): Promise<Pick<AgentRuntimeRunResult, 'exitCode' | 'stoppedByAction'>> {
+  const pollMs = 1000;
+
+  while (true) {
+    const waiters: Array<Promise<{ type: 'exit'; exitCode: number } | { type: 'abort' } | { type: 'tick' }>> = [
+      proc.exited.then((exitCode) => ({ type: 'exit' as const, exitCode })),
+      sleep(pollMs).then(() => ({ type: 'tick' as const })),
+    ];
+    if (input.signal) {
+      waiters.push(new Promise<{ type: 'abort' }>((resolve) => {
+        if (input.signal!.aborted) {
+          resolve({ type: 'abort' });
+          return;
+        }
+        input.signal!.addEventListener('abort', () => resolve({ type: 'abort' }), { once: true });
+      }));
+    }
+    const result = await Promise.race(waiters);
+
+    if (result.type === 'exit') {
+      return { exitCode: result.exitCode, stoppedByAction: null };
+    }
+    if (result.type === 'abort') {
+      return { exitCode: await stopProcess(proc), stoppedByAction: 'kill' };
+    }
+
+    const action = await input.getAction?.();
+    if (action) {
+      return { exitCode: await stopProcess(proc), stoppedByAction: action };
+    }
+  }
+}
+
+/** Spawn an agent runtime process and manage its lifecycle. */
+export async function runAgentRuntime(
+  runtime: AgentRuntime,
+  input: AgentRuntimeRunInput,
+): Promise<AgentRuntimeRunResult> {
+  const prompt = runtime.buildPrompt(input);
+  const args = runtime.buildArgs(input);
+  const procCwd = runtime.buildCwd?.(input) ?? runtimeCwd(input);
+  console.log(`[${runtime.name}] run agent=${input.agent} chat=${input.message.chat_name} message=${input.message.id} cwd=${procCwd} projectCwd=${runtimeProjectCwd(input)} dryRun=${input.dryRun} extraArgs=[${input.extraArgs.join(', ')}]`);
+
+  if (input.dryRun) {
+    console.log(`[${runtime.name}] dry-run mode, skipping spawn`);
+    const [subcommand, ...restArgs] = args;
+    const renderedArgs = [
+      subcommand,
+      ...restArgs.map((arg) => JSON.stringify(arg)),
+    ].filter(Boolean).join(' ');
+    await input.onStart?.(null);
+    return {
+      output: `[dry-run] ${runtime.command}${renderedArgs ? ` ${renderedArgs}` : ''}`,
+      exitCode: 0,
+      stoppedByAction: null,
+      runtimeSessionId: input.runtimeSessionId ?? null,
+    };
+  }
+
+  const env = {
+    ...process.env,
+    PAL_SERVER: input.serverUrl,
+    PAL_AGENT: input.agent,
+    ...(input.localDaemonUrl ? { LOCK_DAEMON_URL: input.localDaemonUrl } : {}),
+    ...(input.localDaemonToken ? { LOCK_DAEMON_TOKEN: input.localDaemonToken } : {}),
+    ...(input.privateCliBinDir ? { PAL_CLI: join(input.privateCliBinDir, 'pal'), PATH: `${input.privateCliBinDir}:${process.env.PATH ?? ''}` } : {}),
+  };
+  console.log(`[${runtime.name}] spawning: ${runtime.command} ${args.map((a) => JSON.stringify(a)).join(' ')}`);
+  const proc = Bun.spawn([runtime.command, ...args], {
+    cwd: procCwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    detached: true,
+    env,
+  });
+
+  console.log(`[${runtime.name}] spawned pid=${proc.pid}`);
+  await input.onStart?.(proc.pid);
+  const status = await waitForExitOrAction(proc, input);
+  console.log(`[${runtime.name}] process exited exitCode=${status.exitCode} stoppedByAction=${status.stoppedByAction ?? '-'}`);
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+
+  const parsed = runtime.parseOutput?.({ stdout, stderr, input }) ?? {
+    output: [stdout.trim(), stderr.trim()].filter(Boolean).join('\n'),
+    runtimeSessionId: input.runtimeSessionId ?? null,
+  };
+  const output = parsed.output;
+  console.log(`[${runtime.name}] output length=${output.length}`);
+  return { output, runtimeSessionId: parsed.runtimeSessionId ?? input.runtimeSessionId ?? null, ...status };
+}
+
+export type RuntimeDriver = AgentRuntime;
+
+/** @deprecated Use AgentRuntimeRunInput instead. */
+export type CodingAgentRunInput = AgentRuntimeRunInput;
+/** @deprecated Use AgentRuntimeRunResult instead. */
+export type CodingAgentRunResult = AgentRuntimeRunResult;
+/** @deprecated Use AgentRuntime instead. */
+export type CodingAgentRuntime = AgentRuntime;
+
+/** @deprecated Use runAgentRuntime instead. */
+export const runCodingAgent = runAgentRuntime;