Move adapter implementations into shared workspace packages

Extract claude-local and codex-local adapter code from cli/server/ui
into packages/adapters/ and packages/adapter-utils/. CLI, server, and
UI now import shared adapter logic instead of duplicating it. Removes
~1100 lines of duplicated code across packages. Register new packages
in pnpm workspace.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/adapter-utils/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@paperclip/adapter-utils",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

packages/adapter-utils/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  AdapterAgent,
+  AdapterRuntime,
+  UsageSummary,
+  AdapterExecutionResult,
+  AdapterInvocationMeta,
+  AdapterExecutionContext,
+  ServerAdapterModule,
+  TranscriptEntry,
+  StdoutLineParser,
+  CLIAdapterModule,
+  CreateConfigValues,
+} from "./types.js";

packages/adapter-utils/src/server-utils.ts

@@ -0,0 +1,250 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+
+export interface RunProcessResult {
+  exitCode: number | null;
+  signal: string | null;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+interface RunningProcess {
+  child: ChildProcess;
+  graceSec: number;
+}
+
+export const runningProcesses = new Map<string, RunningProcess>();
+export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+export const MAX_EXCERPT_BYTES = 32 * 1024;
+const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+
+export function parseObject(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value as Record<string, unknown>;
+}
+
+export function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+export function asNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+export function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+export function parseJson(value: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(value) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function appendWithCap(prev: string, chunk: string, cap = MAX_CAPTURE_BYTES) {
+  const combined = prev + chunk;
+  return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+
+export function resolvePathValue(obj: Record<string, unknown>, dottedPath: string) {
+  const parts = dottedPath.split(".");
+  let cursor: unknown = obj;
+
+  for (const part of parts) {
+    if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor)) {
+      return "";
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+
+  if (cursor === null || cursor === undefined) return "";
+  if (typeof cursor === "string") return cursor;
+  if (typeof cursor === "number" || typeof cursor === "boolean") return String(cursor);
+
+  try {
+    return JSON.stringify(cursor);
+  } catch {
+    return "";
+  }
+}
+
+export function renderTemplate(template: string, data: Record<string, unknown>) {
+  return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path) => resolvePathValue(data, path));
+}
+
+export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
+  const redacted: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    redacted[key] = SENSITIVE_ENV_KEY.test(key) ? "***REDACTED***" : value;
+  }
+  return redacted;
+}
+
+export function buildPaperclipEnv(agent: { id: string; companyId: string }): Record<string, string> {
+  const vars: Record<string, string> = {
+    PAPERCLIP_AGENT_ID: agent.id,
+    PAPERCLIP_COMPANY_ID: agent.companyId,
+  };
+  const apiUrl = process.env.PAPERCLIP_API_URL ?? `http://localhost:${process.env.PORT ?? 3100}`;
+  vars.PAPERCLIP_API_URL = apiUrl;
+  return vars;
+}
+
+export function defaultPathForPlatform() {
+  if (process.platform === "win32") {
+    return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";
+  }
+  return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
+}
+
+export function ensurePathInEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
+  if (typeof env.Path === "string" && env.Path.length > 0) return env;
+  return { ...env, PATH: defaultPathForPlatform() };
+}
+
+export async function ensureAbsoluteDirectory(cwd: string) {
+  if (!path.isAbsolute(cwd)) {
+    throw new Error(`Working directory must be an absolute path: "${cwd}"`);
+  }
+
+  let stats;
+  try {
+    stats = await fs.stat(cwd);
+  } catch {
+    throw new Error(`Working directory does not exist: "${cwd}"`);
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`Working directory is not a directory: "${cwd}"`);
+  }
+}
+
+export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  if (hasPathSeparator) {
+    const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+    try {
+      await fs.access(absolute, fsConstants.X_OK);
+    } catch {
+      throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    }
+    return;
+  }
+
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const dirs = pathValue.split(delimiter).filter(Boolean);
+  const windowsExt = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  for (const dir of dirs) {
+    for (const ext of windowsExt) {
+      const candidate = path.join(dir, process.platform === "win32" ? `${command}${ext}` : command);
+      try {
+        await fs.access(candidate, fsConstants.X_OK);
+        return;
+      } catch {
+        // continue scanning PATH
+      }
+    }
+  }
+
+  throw new Error(`Command not found in PATH: "${command}"`);
+}
+
+export async function runChildProcess(
+  runId: string,
+  command: string,
+  args: string[],
+  opts: {
+    cwd: string;
+    env: Record<string, string>;
+    timeoutSec: number;
+    graceSec: number;
+    onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+    onLogError?: (err: unknown, runId: string, message: string) => void;
+  },
+): Promise<RunProcessResult> {
+  const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
+
+  return new Promise<RunProcessResult>((resolve, reject) => {
+    const mergedEnv = ensurePathInEnv({ ...process.env, ...opts.env });
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      env: mergedEnv,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+
+    let timedOut = false;
+    let stdout = "";
+    let stderr = "";
+    let logChain: Promise<void> = Promise.resolve();
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!child.killed) {
+          child.kill("SIGKILL");
+        }
+      }, Math.max(1, opts.graceSec) * 1000);
+    }, Math.max(1, opts.timeoutSec) * 1000);
+
+    child.stdout?.on("data", (chunk) => {
+      const text = String(chunk);
+      stdout = appendWithCap(stdout, text);
+      logChain = logChain
+        .then(() => opts.onLog("stdout", text))
+        .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+    });
+
+    child.stderr?.on("data", (chunk) => {
+      const text = String(chunk);
+      stderr = appendWithCap(stderr, text);
+      logChain = logChain
+        .then(() => opts.onLog("stderr", text))
+        .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      const errno = (err as NodeJS.ErrnoException).code;
+      const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+      const msg =
+        errno === "ENOENT"
+          ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+          : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+      reject(new Error(msg));
+    });
+
+    child.on("close", (code, signal) => {
+      clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      void logChain.finally(() => {
+        resolve({
+          exitCode: code,
+          signal,
+          timedOut,
+          stdout,
+          stderr,
+        });
+      });
+    });
+  });
+}

packages/adapter-utils/src/types.ts

@@ -0,0 +1,113 @@
+// ---------------------------------------------------------------------------
+// Minimal adapter-facing interfaces (no drizzle dependency)
+// ---------------------------------------------------------------------------
+
+export interface AdapterAgent {
+  id: string;
+  companyId: string;
+  name: string;
+  adapterType: string | null;
+  adapterConfig: unknown;
+}
+
+export interface AdapterRuntime {
+  sessionId: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Execution types (moved from server/src/adapters/types.ts)
+// ---------------------------------------------------------------------------
+
+export interface UsageSummary {
+  inputTokens: number;
+  outputTokens: number;
+  cachedInputTokens?: number;
+}
+
+export interface AdapterExecutionResult {
+  exitCode: number | null;
+  signal: string | null;
+  timedOut: boolean;
+  errorMessage?: string | null;
+  usage?: UsageSummary;
+  sessionId?: string | null;
+  provider?: string | null;
+  model?: string | null;
+  costUsd?: number | null;
+  resultJson?: Record<string, unknown> | null;
+  summary?: string | null;
+  clearSession?: boolean;
+}
+
+export interface AdapterInvocationMeta {
+  adapterType: string;
+  command: string;
+  cwd?: string;
+  commandArgs?: string[];
+  env?: Record<string, string>;
+  prompt?: string;
+  context?: Record<string, unknown>;
+}
+
+export interface AdapterExecutionContext {
+  runId: string;
+  agent: AdapterAgent;
+  runtime: AdapterRuntime;
+  config: Record<string, unknown>;
+  context: Record<string, unknown>;
+  onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+  onMeta?: (meta: AdapterInvocationMeta) => Promise<void>;
+}
+
+export interface ServerAdapterModule {
+  type: string;
+  execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+  models?: { id: string; label: string }[];
+}
+
+// ---------------------------------------------------------------------------
+// UI types (moved from ui/src/adapters/types.ts)
+// ---------------------------------------------------------------------------
+
+export type TranscriptEntry =
+  | { kind: "assistant"; ts: string; text: string }
+  | { kind: "tool_call"; ts: string; name: string; input: unknown }
+  | { kind: "init"; ts: string; model: string; sessionId: string }
+  | { kind: "result"; ts: string; text: string; inputTokens: number; outputTokens: number; cachedTokens: number; costUsd: number; subtype: string; isError: boolean; errors: string[] }
+  | { kind: "stderr"; ts: string; text: string }
+  | { kind: "system"; ts: string; text: string }
+  | { kind: "stdout"; ts: string; text: string };
+
+export type StdoutLineParser = (line: string, ts: string) => TranscriptEntry[];
+
+// ---------------------------------------------------------------------------
+// CLI types (moved from cli/src/adapters/types.ts)
+// ---------------------------------------------------------------------------
+
+export interface CLIAdapterModule {
+  type: string;
+  formatStdoutEvent: (line: string, debug: boolean) => void;
+}
+
+// ---------------------------------------------------------------------------
+// UI config form values (moved from ui/src/components/AgentConfigForm.tsx)
+// ---------------------------------------------------------------------------
+
+export interface CreateConfigValues {
+  adapterType: string;
+  cwd: string;
+  promptTemplate: string;
+  model: string;
+  dangerouslySkipPermissions: boolean;
+  search: boolean;
+  dangerouslyBypassSandbox: boolean;
+  command: string;
+  args: string;
+  extraArgs: string;
+  envVars: string;
+  url: string;
+  bootstrapPrompt: string;
+  maxTurnsPerRun: number;
+  heartbeatEnabled: boolean;
+  intervalSec: number;
+}

packages/adapter-utils/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

packages/adapters/claude-local/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@paperclip/adapter-claude-local",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@paperclip/adapter-utils": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

packages/adapters/claude-local/src/cli/format-event.ts

@@ -0,0 +1,99 @@
+import pc from "picocolors";
+
+function asErrorText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return "";
+  const obj = value as Record<string, unknown>;
+  const message =
+    (typeof obj.message === "string" && obj.message) ||
+    (typeof obj.error === "string" && obj.error) ||
+    (typeof obj.code === "string" && obj.code) ||
+    "";
+  if (message) return message;
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return "";
+  }
+}
+
+export function printClaudeStreamEvent(raw: string, debug: boolean): void {
+  const line = raw.trim();
+  if (!line) return;
+
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    parsed = JSON.parse(line) as Record<string, unknown>;
+  } catch {
+    console.log(line);
+    return;
+  }
+
+  const type = typeof parsed.type === "string" ? parsed.type : "";
+
+  if (type === "system" && parsed.subtype === "init") {
+    const model = typeof parsed.model === "string" ? parsed.model : "unknown";
+    const sessionId = typeof parsed.session_id === "string" ? parsed.session_id : "";
+    console.log(pc.blue(`Claude initialized (model: ${model}${sessionId ? `, session: ${sessionId}` : ""})`));
+    return;
+  }
+
+  if (type === "assistant") {
+    const message =
+      typeof parsed.message === "object" && parsed.message !== null && !Array.isArray(parsed.message)
+        ? (parsed.message as Record<string, unknown>)
+        : {};
+    const content = Array.isArray(message.content) ? message.content : [];
+    for (const blockRaw of content) {
+      if (typeof blockRaw !== "object" || blockRaw === null || Array.isArray(blockRaw)) continue;
+      const block = blockRaw as Record<string, unknown>;
+      const blockType = typeof block.type === "string" ? block.type : "";
+      if (blockType === "text") {
+        const text = typeof block.text === "string" ? block.text : "";
+        if (text) console.log(pc.green(`assistant: ${text}`));
+      } else if (blockType === "tool_use") {
+        const name = typeof block.name === "string" ? block.name : "unknown";
+        console.log(pc.yellow(`tool_call: ${name}`));
+        if (block.input !== undefined) {
+          console.log(pc.gray(JSON.stringify(block.input, null, 2)));
+        }
+      }
+    }
+    return;
+  }
+
+  if (type === "result") {
+    const usage =
+      typeof parsed.usage === "object" && parsed.usage !== null && !Array.isArray(parsed.usage)
+        ? (parsed.usage as Record<string, unknown>)
+        : {};
+    const input = Number(usage.input_tokens ?? 0);
+    const output = Number(usage.output_tokens ?? 0);
+    const cached = Number(usage.cache_read_input_tokens ?? 0);
+    const cost = Number(parsed.total_cost_usd ?? 0);
+    const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";
+    const isError = parsed.is_error === true;
+    const resultText = typeof parsed.result === "string" ? parsed.result : "";
+    if (resultText) {
+      console.log(pc.green("result:"));
+      console.log(resultText);
+    }
+    const errors = Array.isArray(parsed.errors) ? parsed.errors.map(asErrorText).filter(Boolean) : [];
+    if (subtype.startsWith("error") || isError || errors.length > 0) {
+      console.log(pc.red(`claude_result: subtype=${subtype || "unknown"} is_error=${isError ? "true" : "false"}`));
+      if (errors.length > 0) {
+        console.log(pc.red(`claude_errors: ${errors.join(" | ")}`));
+      }
+    }
+    console.log(
+      pc.blue(
+        `tokens: in=${Number.isFinite(input) ? input : 0} out=${Number.isFinite(output) ? output : 0} cached=${Number.isFinite(cached) ? cached : 0} cost=$${Number.isFinite(cost) ? cost.toFixed(6) : "0.000000"}`,
+      ),
+    );
+    return;
+  }
+
+  if (debug) {
+    console.log(pc.gray(line));
+  }
+}

packages/adapters/claude-local/src/cli/index.ts

@@ -0,0 +1 @@
+export { printClaudeStreamEvent } from "./format-event.js";

packages/adapters/claude-local/src/index.ts

@@ -0,0 +1,8 @@
+export const type = "claude_local";
+export const label = "Claude Code (local)";
+
+export const models = [
+  { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
+  { id: "claude-sonnet-4-5-20250929", label: "Claude Sonnet 4.5" },
+  { id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5" },
+];

packages/adapters/claude-local/src/server/execute.ts

@@ -0,0 +1,197 @@
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclip/adapter-utils";
+import type { RunProcessResult } from "@paperclip/adapter-utils/server-utils";
+import {
+  asString,
+  asNumber,
+  asBoolean,
+  asStringArray,
+  parseObject,
+  parseJson,
+  buildPaperclipEnv,
+  redactEnvForLogs,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePathInEnv,
+  renderTemplate,
+  runChildProcess,
+} from "@paperclip/adapter-utils/server-utils";
+import { parseClaudeStreamJson, describeClaudeFailure, isClaudeUnknownSessionError } from "./parse.js";
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+  const { runId, agent, runtime, config, context, onLog, onMeta } = ctx;
+
+  const promptTemplate = asString(
+    config.promptTemplate,
+    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  );
+  const bootstrapTemplate = asString(config.bootstrapPromptTemplate, promptTemplate);
+  const command = asString(config.command, "claude");
+  const model = asString(config.model, "");
+  const maxTurns = asNumber(config.maxTurnsPerRun, 0);
+  const dangerouslySkipPermissions = asBoolean(config.dangerouslySkipPermissions, false);
+
+  const cwd = asString(config.cwd, process.cwd());
+  await ensureAbsoluteDirectory(cwd);
+  const envConfig = parseObject(config.env);
+  const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+  for (const [k, v] of Object.entries(envConfig)) {
+    if (typeof v === "string") env[k] = v;
+  }
+  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  await ensureCommandResolvable(command, cwd, runtimeEnv);
+
+  const timeoutSec = asNumber(config.timeoutSec, 1800);
+  const graceSec = asNumber(config.graceSec, 20);
+  const extraArgs = (() => {
+    const fromExtraArgs = asStringArray(config.extraArgs);
+    if (fromExtraArgs.length > 0) return fromExtraArgs;
+    return asStringArray(config.args);
+  })();
+
+  const sessionId = runtime.sessionId;
+  const template = sessionId ? promptTemplate : bootstrapTemplate;
+  const prompt = renderTemplate(template, {
+    company: { id: agent.companyId },
+    agent,
+    run: { id: runId, source: "on_demand" },
+    context,
+  });
+
+  const buildClaudeArgs = (resumeSessionId: string | null) => {
+    const args = ["--print", prompt, "--output-format", "stream-json", "--verbose"];
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
+    if (dangerouslySkipPermissions) args.push("--dangerously-skip-permissions");
+    if (model) args.push("--model", model);
+    if (maxTurns > 0) args.push("--max-turns", String(maxTurns));
+    if (extraArgs.length > 0) args.push(...extraArgs);
+    return args;
+  };
+
+  const parseFallbackErrorMessage = (proc: RunProcessResult) => {
+    const stderrLine =
+      proc.stderr
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean) ?? "";
+
+    if ((proc.exitCode ?? 0) === 0) {
+      return "Failed to parse claude JSON output";
+    }
+
+    return stderrLine
+      ? `Claude exited with code ${proc.exitCode ?? -1}: ${stderrLine}`
+      : `Claude exited with code ${proc.exitCode ?? -1}`;
+  };
+
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildClaudeArgs(resumeSessionId);
+    if (onMeta) {
+      await onMeta({
+        adapterType: "claude_local",
+        command,
+        cwd,
+        commandArgs: args.map((value, idx) => (idx === 1 ? `<prompt ${prompt.length} chars>` : value)),
+        env: redactEnvForLogs(env),
+        prompt,
+        context,
+      });
+    }
+
+    const proc = await runChildProcess(runId, command, args, {
+      cwd,
+      env,
+      timeoutSec,
+      graceSec,
+      onLog,
+    });
+
+    const parsedStream = parseClaudeStreamJson(proc.stdout);
+    const parsed = parsedStream.resultJson ?? parseJson(proc.stdout);
+    return { proc, parsedStream, parsed };
+  };
+
+  const toAdapterResult = (
+    attempt: {
+      proc: RunProcessResult;
+      parsedStream: ReturnType<typeof parseClaudeStreamJson>;
+      parsed: Record<string, unknown> | null;
+    },
+    opts: { fallbackSessionId: string | null; clearSessionOnMissingSession?: boolean },
+  ): AdapterExecutionResult => {
+    const { proc, parsedStream, parsed } = attempt;
+    if (proc.timedOut) {
+      return {
+        exitCode: proc.exitCode,
+        signal: proc.signal,
+        timedOut: true,
+        errorMessage: `Timed out after ${timeoutSec}s`,
+        clearSession: Boolean(opts.clearSessionOnMissingSession),
+      };
+    }
+
+    if (!parsed) {
+      return {
+        exitCode: proc.exitCode,
+        signal: proc.signal,
+        timedOut: false,
+        errorMessage: parseFallbackErrorMessage(proc),
+        resultJson: {
+          stdout: proc.stdout,
+          stderr: proc.stderr,
+        },
+        clearSession: Boolean(opts.clearSessionOnMissingSession),
+      };
+    }
+
+    const usage =
+      parsedStream.usage ??
+      (() => {
+        const usageObj = parseObject(parsed.usage);
+        return {
+          inputTokens: asNumber(usageObj.input_tokens, 0),
+          cachedInputTokens: asNumber(usageObj.cache_read_input_tokens, 0),
+          outputTokens: asNumber(usageObj.output_tokens, 0),
+        };
+      })();
+
+    const resolvedSessionId =
+      parsedStream.sessionId ??
+      (asString(parsed.session_id, opts.fallbackSessionId ?? "") || opts.fallbackSessionId);
+
+    return {
+      exitCode: proc.exitCode,
+      signal: proc.signal,
+      timedOut: false,
+      errorMessage:
+        (proc.exitCode ?? 0) === 0
+          ? null
+          : describeClaudeFailure(parsed) ?? `Claude exited with code ${proc.exitCode ?? -1}`,
+      usage,
+      sessionId: resolvedSessionId,
+      provider: "anthropic",
+      model: parsedStream.model || asString(parsed.model, model),
+      costUsd: parsedStream.costUsd ?? asNumber(parsed.total_cost_usd, 0),
+      resultJson: parsed,
+      summary: parsedStream.summary || asString(parsed.result, ""),
+      clearSession: Boolean(opts.clearSessionOnMissingSession && !resolvedSessionId),
+    };
+  };
+
+  const initial = await runAttempt(sessionId ?? null);
+  if (
+    sessionId &&
+    !initial.proc.timedOut &&
+    (initial.proc.exitCode ?? 0) !== 0 &&
+    initial.parsed &&
+    isClaudeUnknownSessionError(initial.parsed)
+  ) {
+    await onLog(
+      "stderr",
+      `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+    );
+    const retry = await runAttempt(null);
+    return toAdapterResult(retry, { fallbackSessionId: null, clearSessionOnMissingSession: true });
+  }
+
+  return toAdapterResult(initial, { fallbackSessionId: runtime.sessionId });
+}

packages/adapters/claude-local/src/server/index.ts

@@ -0,0 +1,2 @@
+export { execute } from "./execute.js";
+export { parseClaudeStreamJson, describeClaudeFailure, isClaudeUnknownSessionError } from "./parse.js";

packages/adapters/claude-local/src/server/parse.ts

@@ -0,0 +1,132 @@
+import type { UsageSummary } from "@paperclip/adapter-utils";
+import { asString, asNumber, parseObject, parseJson } from "@paperclip/adapter-utils/server-utils";
+
+export function parseClaudeStreamJson(stdout: string) {
+  let sessionId: string | null = null;
+  let model = "";
+  let finalResult: Record<string, unknown> | null = null;
+  const assistantTexts: string[] = [];
+
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const event = parseJson(line);
+    if (!event) continue;
+
+    const type = asString(event.type, "");
+    if (type === "system" && asString(event.subtype, "") === "init") {
+      sessionId = asString(event.session_id, sessionId ?? "") || sessionId;
+      model = asString(event.model, model);
+      continue;
+    }
+
+    if (type === "assistant") {
+      sessionId = asString(event.session_id, sessionId ?? "") || sessionId;
+      const message = parseObject(event.message);
+      const content = Array.isArray(message.content) ? message.content : [];
+      for (const entry of content) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
+        const block = entry as Record<string, unknown>;
+        if (asString(block.type, "") === "text") {
+          const text = asString(block.text, "");
+          if (text) assistantTexts.push(text);
+        }
+      }
+      continue;
+    }
+
+    if (type === "result") {
+      finalResult = event;
+      sessionId = asString(event.session_id, sessionId ?? "") || sessionId;
+    }
+  }
+
+  if (!finalResult) {
+    return {
+      sessionId,
+      model,
+      costUsd: null as number | null,
+      usage: null as UsageSummary | null,
+      summary: assistantTexts.join("\n\n").trim(),
+      resultJson: null as Record<string, unknown> | null,
+    };
+  }
+
+  const usageObj = parseObject(finalResult.usage);
+  const usage: UsageSummary = {
+    inputTokens: asNumber(usageObj.input_tokens, 0),
+    cachedInputTokens: asNumber(usageObj.cache_read_input_tokens, 0),
+    outputTokens: asNumber(usageObj.output_tokens, 0),
+  };
+  const costRaw = finalResult.total_cost_usd;
+  const costUsd = typeof costRaw === "number" && Number.isFinite(costRaw) ? costRaw : null;
+  const summary = asString(finalResult.result, assistantTexts.join("\n\n")).trim();
+
+  return {
+    sessionId,
+    model,
+    costUsd,
+    usage,
+    summary,
+    resultJson: finalResult,
+  };
+}
+
+function extractClaudeErrorMessages(parsed: Record<string, unknown>): string[] {
+  const raw = Array.isArray(parsed.errors) ? parsed.errors : [];
+  const messages: string[] = [];
+
+  for (const entry of raw) {
+    if (typeof entry === "string") {
+      const msg = entry.trim();
+      if (msg) messages.push(msg);
+      continue;
+    }
+
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      continue;
+    }
+
+    const obj = entry as Record<string, unknown>;
+    const msg = asString(obj.message, "") || asString(obj.error, "") || asString(obj.code, "");
+    if (msg) {
+      messages.push(msg);
+      continue;
+    }
+
+    try {
+      messages.push(JSON.stringify(obj));
+    } catch {
+      // skip non-serializable entry
+    }
+  }
+
+  return messages;
+}
+
+export function describeClaudeFailure(parsed: Record<string, unknown>): string | null {
+  const subtype = asString(parsed.subtype, "");
+  const resultText = asString(parsed.result, "").trim();
+  const errors = extractClaudeErrorMessages(parsed);
+
+  let detail = resultText;
+  if (!detail && errors.length > 0) {
+    detail = errors[0] ?? "";
+  }
+
+  const parts = ["Claude run failed"];
+  if (subtype) parts.push(`subtype=${subtype}`);
+  if (detail) parts.push(detail);
+  return parts.length > 1 ? parts.join(": ") : null;
+}
+
+export function isClaudeUnknownSessionError(parsed: Record<string, unknown>): boolean {
+  const resultText = asString(parsed.result, "").trim();
+  const allMessages = [resultText, ...extractClaudeErrorMessages(parsed)]
+    .map((msg) => msg.trim())
+    .filter(Boolean);
+
+  return allMessages.some((msg) =>
+    /no conversation found with session id|unknown session|session .* not found/i.test(msg),
+  );
+}

packages/adapters/claude-local/src/ui/build-config.ts

@@ -0,0 +1,40 @@
+import type { CreateConfigValues } from "@paperclip/adapter-utils";
+
+function parseCommaArgs(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseEnvVars(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.cwd) ac.cwd = v.cwd;
+  if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
+  if (v.model) ac.model = v.model;
+  ac.timeoutSec = 0;
+  ac.graceSec = 15;
+  const env = parseEnvVars(v.envVars);
+  if (Object.keys(env).length > 0) ac.env = env;
+  ac.maxTurnsPerRun = v.maxTurnsPerRun;
+  ac.dangerouslySkipPermissions = v.dangerouslySkipPermissions;
+  if (v.command) ac.command = v.command;
+  if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+  return ac;
+}

packages/adapters/claude-local/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseClaudeStdoutLine } from "./parse-stdout.js";
+export { buildClaudeLocalConfig } from "./build-config.js";

packages/adapters/claude-local/src/ui/parse-stdout.ts

@@ -0,0 +1,103 @@
+import type { TranscriptEntry } from "@paperclip/adapter-utils";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function errorText(value: unknown): string {
+  if (typeof value === "string") return value;
+  const rec = asRecord(value);
+  if (!rec) return "";
+  const msg =
+    (typeof rec.message === "string" && rec.message) ||
+    (typeof rec.error === "string" && rec.error) ||
+    (typeof rec.code === "string" && rec.code) ||
+    "";
+  if (msg) return msg;
+  try {
+    return JSON.stringify(rec);
+  } catch {
+    return "";
+  }
+}
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function parseClaudeStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const parsed = asRecord(safeJsonParse(line));
+  if (!parsed) {
+    return [{ kind: "stdout", ts, text: line }];
+  }
+
+  const type = typeof parsed.type === "string" ? parsed.type : "";
+  if (type === "system" && parsed.subtype === "init") {
+    return [
+      {
+        kind: "init",
+        ts,
+        model: typeof parsed.model === "string" ? parsed.model : "unknown",
+        sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "",
+      },
+    ];
+  }
+
+  if (type === "assistant") {
+    const message = asRecord(parsed.message) ?? {};
+    const content = Array.isArray(message.content) ? message.content : [];
+    const entries: TranscriptEntry[] = [];
+    for (const blockRaw of content) {
+      const block = asRecord(blockRaw);
+      if (!block) continue;
+      const blockType = typeof block.type === "string" ? block.type : "";
+      if (blockType === "text") {
+        const text = typeof block.text === "string" ? block.text : "";
+        if (text) entries.push({ kind: "assistant", ts, text });
+      } else if (blockType === "tool_use") {
+        entries.push({
+          kind: "tool_call",
+          ts,
+          name: typeof block.name === "string" ? block.name : "unknown",
+          input: block.input ?? {},
+        });
+      }
+    }
+    return entries.length > 0 ? entries : [{ kind: "stdout", ts, text: line }];
+  }
+
+  if (type === "result") {
+    const usage = asRecord(parsed.usage) ?? {};
+    const inputTokens = asNumber(usage.input_tokens);
+    const outputTokens = asNumber(usage.output_tokens);
+    const cachedTokens = asNumber(usage.cache_read_input_tokens);
+    const costUsd = asNumber(parsed.total_cost_usd);
+    const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";
+    const isError = parsed.is_error === true;
+    const errors = Array.isArray(parsed.errors) ? parsed.errors.map(errorText).filter(Boolean) : [];
+    const text = typeof parsed.result === "string" ? parsed.result : "";
+    return [{
+      kind: "result",
+      ts,
+      text,
+      inputTokens,
+      outputTokens,
+      cachedTokens,
+      costUsd,
+      subtype,
+      isError,
+      errors,
+    }];
+  }
+
+  return [{ kind: "stdout", ts, text: line }];
+}

packages/adapters/claude-local/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

packages/adapters/codex-local/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@paperclip/adapter-codex-local",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@paperclip/adapter-utils": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

packages/adapters/codex-local/src/cli/format-event.ts

@@ -0,0 +1,56 @@
+import pc from "picocolors";
+
+export function printCodexStreamEvent(raw: string, _debug: boolean): void {
+  const line = raw.trim();
+  if (!line) return;
+
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    parsed = JSON.parse(line) as Record<string, unknown>;
+  } catch {
+    console.log(line);
+    return;
+  }
+
+  const type = typeof parsed.type === "string" ? parsed.type : "";
+
+  if (type === "thread.started") {
+    const threadId = typeof parsed.thread_id === "string" ? parsed.thread_id : "";
+    console.log(pc.blue(`Codex thread started${threadId ? ` (session: ${threadId})` : ""}`));
+    return;
+  }
+
+  if (type === "item.completed") {
+    const item =
+      typeof parsed.item === "object" && parsed.item !== null && !Array.isArray(parsed.item)
+        ? (parsed.item as Record<string, unknown>)
+        : null;
+    if (item) {
+      const itemType = typeof item.type === "string" ? item.type : "";
+      if (itemType === "agent_message") {
+        const text = typeof item.text === "string" ? item.text : "";
+        if (text) console.log(pc.green(`assistant: ${text}`));
+      } else if (itemType === "tool_use") {
+        const name = typeof item.name === "string" ? item.name : "unknown";
+        console.log(pc.yellow(`tool_call: ${name}`));
+      }
+    }
+    return;
+  }
+
+  if (type === "turn.completed") {
+    const usage =
+      typeof parsed.usage === "object" && parsed.usage !== null && !Array.isArray(parsed.usage)
+        ? (parsed.usage as Record<string, unknown>)
+        : {};
+    const input = Number(usage.input_tokens ?? 0);
+    const output = Number(usage.output_tokens ?? 0);
+    const cached = Number(usage.cached_input_tokens ?? 0);
+    console.log(
+      pc.blue(`tokens: in=${input} out=${output} cached=${cached}`),
+    );
+    return;
+  }
+
+  console.log(line);
+}

packages/adapters/codex-local/src/cli/index.ts

@@ -0,0 +1 @@
+export { printCodexStreamEvent } from "./format-event.js";

packages/adapters/codex-local/src/index.ts

@@ -0,0 +1,8 @@
+export const type = "codex_local";
+export const label = "Codex (local)";
+
+export const models = [
+  { id: "o4-mini", label: "o4-mini" },
+  { id: "o3", label: "o3" },
+  { id: "codex-mini-latest", label: "Codex Mini" },
+];

packages/adapters/codex-local/src/server/execute.ts

@@ -0,0 +1,117 @@
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclip/adapter-utils";
+import {
+  asString,
+  asNumber,
+  asBoolean,
+  asStringArray,
+  parseObject,
+  buildPaperclipEnv,
+  redactEnvForLogs,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePathInEnv,
+  renderTemplate,
+  runChildProcess,
+} from "@paperclip/adapter-utils/server-utils";
+import { parseCodexJsonl } from "./parse.js";
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+  const { runId, agent, runtime, config, context, onLog, onMeta } = ctx;
+
+  const promptTemplate = asString(
+    config.promptTemplate,
+    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  );
+  const bootstrapTemplate = asString(config.bootstrapPromptTemplate, promptTemplate);
+  const command = asString(config.command, "codex");
+  const model = asString(config.model, "");
+  const search = asBoolean(config.search, false);
+  const bypass = asBoolean(config.dangerouslyBypassApprovalsAndSandbox, false);
+
+  const cwd = asString(config.cwd, process.cwd());
+  await ensureAbsoluteDirectory(cwd);
+  const envConfig = parseObject(config.env);
+  const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+  for (const [k, v] of Object.entries(envConfig)) {
+    if (typeof v === "string") env[k] = v;
+  }
+  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  await ensureCommandResolvable(command, cwd, runtimeEnv);
+
+  const timeoutSec = asNumber(config.timeoutSec, 1800);
+  const graceSec = asNumber(config.graceSec, 20);
+  const extraArgs = (() => {
+    const fromExtraArgs = asStringArray(config.extraArgs);
+    if (fromExtraArgs.length > 0) return fromExtraArgs;
+    return asStringArray(config.args);
+  })();
+
+  const sessionId = runtime.sessionId;
+  const template = sessionId ? promptTemplate : bootstrapTemplate;
+  const prompt = renderTemplate(template, {
+    company: { id: agent.companyId },
+    agent,
+    run: { id: runId, source: "on_demand" },
+    context,
+  });
+
+  const args = ["exec", "--json"];
+  if (search) args.unshift("--search");
+  if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
+  if (model) args.push("--model", model);
+  if (extraArgs.length > 0) args.push(...extraArgs);
+  if (sessionId) args.push("resume", sessionId, prompt);
+  else args.push(prompt);
+
+  if (onMeta) {
+    await onMeta({
+      adapterType: "codex_local",
+      command,
+      cwd,
+      commandArgs: args.map((value, idx) => {
+        if (!sessionId && idx === args.length - 1) return `<prompt ${prompt.length} chars>`;
+        if (sessionId && idx === args.length - 1) return `<prompt ${prompt.length} chars>`;
+        return value;
+      }),
+      env: redactEnvForLogs(env),
+      prompt,
+      context,
+    });
+  }
+
+  const proc = await runChildProcess(runId, command, args, {
+    cwd,
+    env,
+    timeoutSec,
+    graceSec,
+    onLog,
+  });
+
+  if (proc.timedOut) {
+    return {
+      exitCode: proc.exitCode,
+      signal: proc.signal,
+      timedOut: true,
+      errorMessage: `Timed out after ${timeoutSec}s`,
+    };
+  }
+
+  const parsed = parseCodexJsonl(proc.stdout);
+
+  return {
+    exitCode: proc.exitCode,
+    signal: proc.signal,
+    timedOut: false,
+    errorMessage: (proc.exitCode ?? 0) === 0 ? null : `Codex exited with code ${proc.exitCode ?? -1}`,
+    usage: parsed.usage,
+    sessionId: parsed.sessionId ?? runtime.sessionId,
+    provider: "openai",
+    model,
+    costUsd: null,
+    resultJson: {
+      stdout: proc.stdout,
+      stderr: proc.stderr,
+    },
+    summary: parsed.summary,
+  };
+}

packages/adapters/codex-local/src/server/index.ts

@@ -0,0 +1,2 @@
+export { execute } from "./execute.js";
+export { parseCodexJsonl } from "./parse.js";

packages/adapters/codex-local/src/server/parse.ts

@@ -0,0 +1,47 @@
+import { asString, asNumber, parseObject, parseJson } from "@paperclip/adapter-utils/server-utils";
+
+export function parseCodexJsonl(stdout: string) {
+  let sessionId: string | null = null;
+  const messages: string[] = [];
+  const usage = {
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    outputTokens: 0,
+  };
+
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const event = parseJson(line);
+    if (!event) continue;
+
+    const type = asString(event.type, "");
+    if (type === "thread.started") {
+      sessionId = asString(event.thread_id, sessionId ?? "") || sessionId;
+      continue;
+    }
+
+    if (type === "item.completed") {
+      const item = parseObject(event.item);
+      if (asString(item.type, "") === "agent_message") {
+        const text = asString(item.text, "");
+        if (text) messages.push(text);
+      }
+      continue;
+    }
+
+    if (type === "turn.completed") {
+      const usageObj = parseObject(event.usage);
+      usage.inputTokens = asNumber(usageObj.input_tokens, usage.inputTokens);
+      usage.cachedInputTokens = asNumber(usageObj.cached_input_tokens, usage.cachedInputTokens);
+      usage.outputTokens = asNumber(usageObj.output_tokens, usage.outputTokens);
+    }
+  }
+
+  return {
+    sessionId,
+    summary: messages.join("\n\n").trim(),
+    usage,
+  };
+}

packages/adapters/codex-local/src/ui/build-config.ts

@@ -0,0 +1,40 @@
+import type { CreateConfigValues } from "@paperclip/adapter-utils";
+
+function parseCommaArgs(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseEnvVars(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.cwd) ac.cwd = v.cwd;
+  if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
+  if (v.model) ac.model = v.model;
+  ac.timeoutSec = 0;
+  ac.graceSec = 15;
+  const env = parseEnvVars(v.envVars);
+  if (Object.keys(env).length > 0) ac.env = env;
+  ac.search = v.search;
+  ac.dangerouslyBypassApprovalsAndSandbox = v.dangerouslyBypassSandbox;
+  if (v.command) ac.command = v.command;
+  if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+  return ac;
+}

packages/adapters/codex-local/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseCodexStdoutLine } from "./parse-stdout.js";
+export { buildCodexLocalConfig } from "./build-config.js";

packages/adapters/codex-local/src/ui/parse-stdout.ts

@@ -0,0 +1,73 @@
+import type { TranscriptEntry } from "@paperclip/adapter-utils";
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const parsed = asRecord(safeJsonParse(line));
+  if (!parsed) {
+    return [{ kind: "stdout", ts, text: line }];
+  }
+
+  const type = typeof parsed.type === "string" ? parsed.type : "";
+
+  if (type === "thread.started") {
+    const threadId = typeof parsed.thread_id === "string" ? parsed.thread_id : "";
+    return [{
+      kind: "init",
+      ts,
+      model: "codex",
+      sessionId: threadId,
+    }];
+  }
+
+  if (type === "item.completed") {
+    const item = asRecord(parsed.item);
+    if (item) {
+      const itemType = typeof item.type === "string" ? item.type : "";
+      if (itemType === "agent_message") {
+        const text = typeof item.text === "string" ? item.text : "";
+        if (text) return [{ kind: "assistant", ts, text }];
+      }
+      if (itemType === "tool_use") {
+        return [{
+          kind: "tool_call",
+          ts,
+          name: typeof item.name === "string" ? item.name : "unknown",
+          input: item.input ?? {},
+        }];
+      }
+    }
+  }
+
+  if (type === "turn.completed") {
+    const usage = asRecord(parsed.usage) ?? {};
+    const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+    const outputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
+    const cachedTokens = typeof usage.cached_input_tokens === "number" ? usage.cached_input_tokens : 0;
+    return [{
+      kind: "result",
+      ts,
+      text: "",
+      inputTokens,
+      outputTokens,
+      cachedTokens,
+      costUsd: 0,
+      subtype: "",
+      isError: false,
+      errors: [],
+    }];
+  }
+
+  return [{ kind: "stdout", ts, text: line }];
+}

packages/adapters/codex-local/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}