Merge branch 'master' into add-gpt-5-4-xhigh-effort

packages/adapter-utils/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @paperclipai/adapter-utils
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/adapter-utils/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-utils",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapter-utils"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapter-utils/src/billing.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { inferOpenAiCompatibleBiller } from "./billing.js";
+
+describe("inferOpenAiCompatibleBiller", () => {
+  it("returns openrouter when OPENROUTER_API_KEY is present", () => {
+    expect(
+      inferOpenAiCompatibleBiller({ OPENROUTER_API_KEY: "sk-or-123" } as NodeJS.ProcessEnv, "openai"),
+    ).toBe("openrouter");
+  });
+
+  it("returns openrouter when OPENAI_BASE_URL points at OpenRouter", () => {
+    expect(
+      inferOpenAiCompatibleBiller(
+        { OPENAI_BASE_URL: "https://openrouter.ai/api/v1" } as NodeJS.ProcessEnv,
+        "openai",
+      ),
+    ).toBe("openrouter");
+  });
+
+  it("returns fallback when no OpenRouter markers are present", () => {
+    expect(
+      inferOpenAiCompatibleBiller(
+        { OPENAI_BASE_URL: "https://api.openai.com/v1" } as NodeJS.ProcessEnv,
+        "openai",
+      ),
+    ).toBe("openai");
+  });
+});

packages/adapter-utils/src/billing.ts

@@ -0,0 +1,20 @@
+function readEnv(env: NodeJS.ProcessEnv, key: string): string | null {
+  const value = env[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function inferOpenAiCompatibleBiller(
+  env: NodeJS.ProcessEnv,
+  fallback: string | null = "openai",
+): string | null {
+  const explicitOpenRouterKey = readEnv(env, "OPENROUTER_API_KEY");
+  if (explicitOpenRouterKey) return "openrouter";
+
+  const baseUrl =
+    readEnv(env, "OPENAI_BASE_URL") ??
+    readEnv(env, "OPENAI_API_BASE") ??
+    readEnv(env, "OPENAI_API_BASE_URL");
+  if (baseUrl && /openrouter\.ai/i.test(baseUrl)) return "openrouter";
+
+  return fallback;
+}

packages/adapter-utils/src/index.ts

@@ -3,6 +3,7 @@ export type {
   AdapterRuntime,
   UsageSummary,
   AdapterBillingType,
+  AdapterRuntimeServiceReport,
   AdapterExecutionResult,
   AdapterInvocationMeta,
   AdapterExecutionContext,
@@ -11,13 +12,42 @@ export type {
   AdapterEnvironmentTestStatus,
   AdapterEnvironmentTestResult,
   AdapterEnvironmentTestContext,
+  AdapterSkillSyncMode,
+  AdapterSkillState,
+  AdapterSkillOrigin,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+  AdapterSkillContext,
   AdapterSessionCodec,
   AdapterModel,
   HireApprovedPayload,
   HireApprovedHookResult,
   ServerAdapterModule,
+  QuotaWindow,
+  ProviderQuotaResult,
   TranscriptEntry,
   StdoutLineParser,
   CLIAdapterModule,
   CreateConfigValues,
 } from "./types.js";
+export type {
+  SessionCompactionPolicy,
+  NativeContextManagement,
+  AdapterSessionManagement,
+  ResolvedSessionCompactionPolicy,
+} from "./session-compaction.js";
+export {
+  ADAPTER_SESSION_MANAGEMENT,
+  LEGACY_SESSIONED_ADAPTER_TYPES,
+  getAdapterSessionManagement,
+  readSessionCompactionOverride,
+  resolveSessionCompactionPolicy,
+  hasSessionCompactionThresholds,
+} from "./session-compaction.js";
+export {
+  REDACTED_HOME_PATH_USER,
+  redactHomePathUserSegments,
+  redactHomePathUserSegmentsInValue,
+  redactTranscriptEntryPaths,
+} from "./log-redaction.js";
+export { inferOpenAiCompatibleBiller } from "./billing.js";

packages/adapter-utils/src/log-redaction.ts

@@ -0,0 +1,96 @@
+import type { TranscriptEntry } from "./types.js";
+
+export const REDACTED_HOME_PATH_USER = "*";
+
+export interface HomePathRedactionOptions {
+  enabled?: boolean;
+}
+
+function maskHomePathUserSegment(value: string) {
+  const trimmed = value.trim();
+  if (!trimmed) return REDACTED_HOME_PATH_USER;
+  return `${trimmed[0]}${"*".repeat(Math.max(1, Array.from(trimmed).length - 1))}`;
+}
+
+const HOME_PATH_PATTERNS = [
+  {
+    regex: /\/Users\/([^/\\\s]+)/g,
+    replace: (_match: string, user: string) => `/Users/${maskHomePathUserSegment(user)}`,
+  },
+  {
+    regex: /\/home\/([^/\\\s]+)/g,
+    replace: (_match: string, user: string) => `/home/${maskHomePathUserSegment(user)}`,
+  },
+  {
+    regex: /([A-Za-z]:\\Users\\)([^\\/\s]+)/g,
+    replace: (_match: string, prefix: string, user: string) => `${prefix}${maskHomePathUserSegment(user)}`,
+  },
+] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export function redactHomePathUserSegments(text: string, opts?: HomePathRedactionOptions): string {
+  if (opts?.enabled === false) return text;
+  let result = text;
+  for (const pattern of HOME_PATH_PATTERNS) {
+    result = result.replace(pattern.regex, pattern.replace);
+  }
+  return result;
+}
+
+export function redactHomePathUserSegmentsInValue<T>(value: T, opts?: HomePathRedactionOptions): T {
+  if (typeof value === "string") {
+    return redactHomePathUserSegments(value, opts) as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactHomePathUserSegmentsInValue(entry, opts)) as T;
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  const redacted: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    redacted[key] = redactHomePathUserSegmentsInValue(entry, opts);
+  }
+  return redacted as T;
+}
+
+export function redactTranscriptEntryPaths(entry: TranscriptEntry, opts?: HomePathRedactionOptions): TranscriptEntry {
+  switch (entry.kind) {
+    case "assistant":
+    case "thinking":
+    case "user":
+    case "stderr":
+    case "system":
+    case "stdout":
+      return { ...entry, text: redactHomePathUserSegments(entry.text, opts) };
+    case "tool_call":
+      return {
+        ...entry,
+        name: redactHomePathUserSegments(entry.name, opts),
+        input: redactHomePathUserSegmentsInValue(entry.input, opts),
+      };
+    case "tool_result":
+      return { ...entry, content: redactHomePathUserSegments(entry.content, opts) };
+    case "init":
+      return {
+        ...entry,
+        model: redactHomePathUserSegments(entry.model, opts),
+        sessionId: redactHomePathUserSegments(entry.sessionId, opts),
+      };
+    case "result":
+      return {
+        ...entry,
+        text: redactHomePathUserSegments(entry.text, opts),
+        subtype: redactHomePathUserSegments(entry.subtype, opts),
+        errors: entry.errors.map((error) => redactHomePathUserSegments(error, opts)),
+      };
+    default:
+      return entry;
+  }
+}

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

@@ -1,6 +1,10 @@
 import { spawn, type ChildProcess } from "node:child_process";
-import { constants as fsConstants, promises as fs } from "node:fs";
+import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
 import path from "node:path";
+import type {
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "./types.js";
 
 export interface RunProcessResult {
   exitCode: number | null;
@@ -8,6 +12,8 @@ export interface RunProcessResult {
   timedOut: boolean;
   stdout: string;
   stderr: string;
+  pid: number | null;
+  startedAt: string | null;
 }
 
 interface RunningProcess {
@@ -15,6 +21,11 @@ interface RunningProcess {
   graceSec: number;
 }
 
+interface SpawnTarget {
+  command: string;
+  args: string[];
+}
+
 type ChildProcessWithEvents = ChildProcess & {
   on(event: "error", listener: (err: Error) => void): ChildProcess;
   on(
@@ -27,6 +38,88 @@ 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;
+const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
+  "../../skills",
+  "../../../../../skills",
+];
+
+export interface PaperclipSkillEntry {
+  key: string;
+  runtimeName: string;
+  source: string;
+  required?: boolean;
+  requiredReason?: string | null;
+}
+
+export interface InstalledSkillTarget {
+  targetPath: string | null;
+  kind: "symlink" | "directory" | "file";
+}
+
+interface PersistentSkillSnapshotOptions {
+  adapterType: string;
+  availableEntries: PaperclipSkillEntry[];
+  desiredSkills: string[];
+  installed: Map<string, InstalledSkillTarget>;
+  skillsHome: string;
+  locationLabel?: string | null;
+  installedDetail?: string | null;
+  missingDetail: string;
+  externalConflictDetail: string;
+  externalDetail: string;
+  warnings?: string[];
+}
+
+function normalizePathSlashes(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+function isMaintainerOnlySkillTarget(candidate: string): boolean {
+  return normalizePathSlashes(candidate).includes("/.agents/skills/");
+}
+
+function skillLocationLabel(value: string | null | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function buildManagedSkillOrigin(entry: { required?: boolean }): Pick<
+  AdapterSkillEntry,
+  "origin" | "originLabel" | "readOnly"
+> {
+  if (entry.required) {
+    return {
+      origin: "paperclip_required",
+      originLabel: "Required by Paperclip",
+      readOnly: false,
+    };
+  }
+  return {
+    origin: "company_managed",
+    originLabel: "Managed by Paperclip",
+    readOnly: false,
+  };
+}
+
+function resolveInstalledEntryTarget(
+  skillsHome: string,
+  entryName: string,
+  dirent: Dirent,
+  linkedPath: string | null,
+): InstalledSkillTarget {
+  const fullPath = path.join(skillsHome, entryName);
+  if (dirent.isSymbolicLink()) {
+    return {
+      targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
+      kind: "symlink",
+    };
+  }
+  if (dirent.isDirectory()) {
+    return { targetPath: fullPath, kind: "directory" };
+  }
+  return { targetPath: fullPath, kind: "file" };
+}
 
 export function parseObject(value: unknown): Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -90,6 +183,16 @@ 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 joinPromptSections(
+  sections: Array<string | null | undefined>,
+  separator = "\n\n",
+) {
+  return sections
+    .map((value) => (typeof value === "string" ? value.trim() : ""))
+    .filter(Boolean)
+    .join(separator);
+}
+
 export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
   const redacted: Record<string, string> = {};
   for (const [key, value] of Object.entries(env)) {
@@ -98,6 +201,33 @@ export function redactEnvForLogs(env: Record<string, string>): Record<string, st
   return redacted;
 }
 
+export function buildInvocationEnvForLogs(
+  env: Record<string, string>,
+  options: {
+    runtimeEnv?: NodeJS.ProcessEnv | Record<string, string>;
+    includeRuntimeKeys?: string[];
+    resolvedCommand?: string | null;
+    resolvedCommandEnvKey?: string;
+  } = {},
+): Record<string, string> {
+  const merged: Record<string, string> = { ...env };
+  const runtimeEnv = options.runtimeEnv ?? {};
+
+  for (const key of options.includeRuntimeKeys ?? []) {
+    if (key in merged) continue;
+    const value = runtimeEnv[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    merged[key] = value;
+  }
+
+  const resolvedCommand = options.resolvedCommand?.trim();
+  if (resolvedCommand) {
+    merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = resolvedCommand;
+  }
+
+  return redactEnvForLogs(merged);
+}
+
 export function buildPaperclipEnv(agent: { id: string; companyId: string }): Record<string, string> {
   const resolveHostForUrl = (rawHost: string): string => {
     const host = rawHost.trim();
@@ -125,6 +255,82 @@ export function defaultPathForPlatform() {
   return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
 }
 
+function windowsPathExts(env: NodeJS.ProcessEnv): string[] {
+  return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+}
+
+async function pathExists(candidate: string) {
+  try {
+    await fs.access(candidate, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveCommandPath(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string | null> {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  if (hasPathSeparator) {
+    const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+    return (await pathExists(absolute)) ? absolute : null;
+  }
+
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const dirs = pathValue.split(delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
+  const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
+
+  for (const dir of dirs) {
+    const candidates =
+      process.platform === "win32"
+        ? hasExtension
+          ? [path.join(dir, command)]
+          : exts.map((ext) => path.join(dir, `${command}${ext}`))
+        : [path.join(dir, command)];
+    for (const candidate of candidates) {
+      if (await pathExists(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+export async function resolveCommandForLogs(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string> {
+  return (await resolveCommandPath(command, cwd, env)) ?? command;
+}
+
+function quoteForCmd(arg: string) {
+  if (!arg.length) return '""';
+  const escaped = arg.replace(/"/g, '""');
+  return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
+}
+
+async function resolveSpawnTarget(
+  command: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): Promise<SpawnTarget> {
+  const resolved = await resolveCommandPath(command, cwd, env);
+  const executable = resolved ?? command;
+
+  if (process.platform !== "win32") {
+    return { command: executable, args };
+  }
+
+  if (/\.(cmd|bat)$/i.test(executable)) {
+    const shell = env.ComSpec || process.env.ComSpec || "cmd.exe";
+    const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
+    return {
+      command: shell,
+      args: ["/d", "/s", "/c", commandLine],
+    };
+  }
+
+  return { command: executable, args };
+}
+
 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;
@@ -168,37 +374,375 @@ export async function ensureAbsoluteDirectory(
   }
 }
 
-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;
+export async function resolvePaperclipSkillsDir(
+  moduleDir: string,
+  additionalCandidates: string[] = [],
+): Promise<string | null> {
+  const candidates = [
+    ...PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES.map((relativePath) => path.resolve(moduleDir, relativePath)),
+    ...additionalCandidates.map((candidate) => path.resolve(candidate)),
+  ];
+  const seenRoots = new Set<string>();
+
+  for (const root of candidates) {
+    if (seenRoots.has(root)) continue;
+    seenRoots.add(root);
+    const isDirectory = await fs.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
+    if (isDirectory) return root;
   }
 
-  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(";")
-    : [""];
+  return null;
+}
 
-  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
+export async function listPaperclipSkillEntries(
+  moduleDir: string,
+  additionalCandidates: string[] = [],
+): Promise<PaperclipSkillEntry[]> {
+  const root = await resolvePaperclipSkillsDir(moduleDir, additionalCandidates);
+  if (!root) return [];
+
+  try {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => ({
+        key: `paperclipai/paperclip/${entry.name}`,
+        runtimeName: entry.name,
+        source: path.join(root, entry.name),
+        required: true,
+        requiredReason: "Bundled Paperclip skills are always available for local adapters.",
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export async function readInstalledSkillTargets(skillsHome: string): Promise<Map<string, InstalledSkillTarget>> {
+  const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+  const out = new Map<string, InstalledSkillTarget>();
+  for (const entry of entries) {
+    const fullPath = path.join(skillsHome, entry.name);
+    const linkedPath = entry.isSymbolicLink() ? await fs.readlink(fullPath).catch(() => null) : null;
+    out.set(entry.name, resolveInstalledEntryTarget(skillsHome, entry.name, entry, linkedPath));
+  }
+  return out;
+}
+
+export function buildPersistentSkillSnapshot(
+  options: PersistentSkillSnapshotOptions,
+): AdapterSkillSnapshot {
+  const {
+    adapterType,
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel,
+    installedDetail,
+    missingDetail,
+    externalConflictDetail,
+    externalDetail,
+  } = options;
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = [];
+  const warnings = [...(options.warnings ?? [])];
+
+  for (const available of availableEntries) {
+    const installedEntry = installed.get(available.runtimeName) ?? null;
+    const desired = desiredSet.has(available.key);
+    let state: AdapterSkillEntry["state"] = "available";
+    let managed = false;
+    let detail: string | null = null;
+
+    if (installedEntry?.targetPath === available.source) {
+      managed = true;
+      state = desired ? "installed" : "stale";
+      detail = installedDetail ?? null;
+    } else if (installedEntry) {
+      state = "external";
+      detail = desired ? externalConflictDetail : externalDetail;
+    } else if (desired) {
+      state = "missing";
+      detail = missingDetail;
+    }
+
+    entries.push({
+      key: available.key,
+      runtimeName: available.runtimeName,
+      desired,
+      managed,
+      state,
+      sourcePath: available.source,
+      targetPath: path.join(skillsHome, available.runtimeName),
+      detail,
+      required: Boolean(available.required),
+      requiredReason: available.requiredReason ?? null,
+      ...buildManagedSkillOrigin(available),
+    });
+  }
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: null,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+    });
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
+    entries.push({
+      key: name,
+      runtimeName: name,
+      desired: false,
+      managed: false,
+      state: "external",
+      origin: "user_installed",
+      originLabel: "User-installed",
+      locationLabel: skillLocationLabel(locationLabel),
+      readOnly: true,
+      sourcePath: null,
+      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+      detail: externalDetail,
+    });
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
+    adapterType,
+    supported: true,
+    mode: "persistent",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSkillEntry[] {
+  if (!Array.isArray(value)) return [];
+  const out: PaperclipSkillEntry[] = [];
+  for (const rawEntry of value) {
+    const entry = parseObject(rawEntry);
+    const key = asString(entry.key, asString(entry.name, "")).trim();
+    const runtimeName = asString(entry.runtimeName, asString(entry.name, "")).trim();
+    const source = asString(entry.source, "").trim();
+    if (!key || !runtimeName || !source) continue;
+    out.push({
+      key,
+      runtimeName,
+      source,
+      required: asBoolean(entry.required, false),
+      requiredReason:
+        typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
+          ? entry.requiredReason.trim()
+          : null,
+    });
+  }
+  return out;
+}
+
+export async function readPaperclipRuntimeSkillEntries(
+  config: Record<string, unknown>,
+  moduleDir: string,
+  additionalCandidates: string[] = [],
+): Promise<PaperclipSkillEntry[]> {
+  const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.paperclipRuntimeSkills);
+  if (configuredEntries.length > 0) return configuredEntries;
+  return listPaperclipSkillEntries(moduleDir, additionalCandidates);
+}
+
+export async function readPaperclipSkillMarkdown(
+  moduleDir: string,
+  skillKey: string,
+): Promise<string | null> {
+  const normalized = skillKey.trim().toLowerCase();
+  if (!normalized) return null;
+
+  const entries = await listPaperclipSkillEntries(moduleDir);
+  const match = entries.find((entry) => entry.key === normalized);
+  if (!match) return null;
+
+  try {
+    return await fs.readFile(path.join(match.source, "SKILL.md"), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function readPaperclipSkillSyncPreference(config: Record<string, unknown>): {
+  explicit: boolean;
+  desiredSkills: string[];
+} {
+  const raw = config.paperclipSkillSync;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { explicit: false, desiredSkills: [] };
+  }
+  const syncConfig = raw as Record<string, unknown>;
+  const desiredValues = syncConfig.desiredSkills;
+  const desired = Array.isArray(desiredValues)
+    ? desiredValues
+        .filter((value): value is string => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : [];
+  return {
+    explicit: Object.prototype.hasOwnProperty.call(raw, "desiredSkills"),
+    desiredSkills: Array.from(new Set(desired)),
+  };
+}
+
+function canonicalizeDesiredPaperclipSkillReference(
+  reference: string,
+  availableEntries: Array<{ key: string; runtimeName?: string | null }>,
+): string {
+  const normalizedReference = reference.trim().toLowerCase();
+  if (!normalizedReference) return "";
+
+  const exactKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === normalizedReference);
+  if (exactKey) return exactKey.key;
+
+  const byRuntimeName = availableEntries.filter((entry) =>
+    typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === normalizedReference,
+  );
+  if (byRuntimeName.length === 1) return byRuntimeName[0]!.key;
+
+  const slugMatches = availableEntries.filter((entry) =>
+    entry.key.trim().toLowerCase().split("/").pop() === normalizedReference,
+  );
+  if (slugMatches.length === 1) return slugMatches[0]!.key;
+
+  return normalizedReference;
+}
+
+export function resolvePaperclipDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; runtimeName?: string | null; required?: boolean }>,
+): string[] {
+  const preference = readPaperclipSkillSyncPreference(config);
+  const requiredSkills = availableEntries
+    .filter((entry) => entry.required)
+    .map((entry) => entry.key);
+  if (!preference.explicit) {
+    return Array.from(new Set(requiredSkills));
+  }
+  const desiredSkills = preference.desiredSkills
+    .map((reference) => canonicalizeDesiredPaperclipSkillReference(reference, availableEntries))
+    .filter(Boolean);
+  return Array.from(new Set([...requiredSkills, ...desiredSkills]));
+}
+
+export function writePaperclipSkillSyncPreference(
+  config: Record<string, unknown>,
+  desiredSkills: string[],
+): Record<string, unknown> {
+  const next = { ...config };
+  const raw = next.paperclipSkillSync;
+  const current =
+    typeof raw === "object" && raw !== null && !Array.isArray(raw)
+      ? { ...(raw as Record<string, unknown>) }
+      : {};
+  current.desiredSkills = Array.from(
+    new Set(
+      desiredSkills
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  );
+  next.paperclipSkillSync = current;
+  return next;
+}
+
+export async function ensurePaperclipSkillSymlink(
+  source: string,
+  target: string,
+  linkSkill: (source: string, target: string) => Promise<void> = (linkSource, linkTarget) =>
+    fs.symlink(linkSource, linkTarget),
+): Promise<"created" | "repaired" | "skipped"> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (!existing) {
+    await linkSkill(source, target);
+    return "created";
+  }
+
+  if (!existing.isSymbolicLink()) {
+    return "skipped";
+  }
+
+  const linkedPath = await fs.readlink(target).catch(() => null);
+  if (!linkedPath) return "skipped";
+
+  const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+  if (resolvedLinkedPath === source) {
+    return "skipped";
+  }
+
+  const linkedPathExists = await fs.stat(resolvedLinkedPath).then(() => true).catch(() => false);
+  if (linkedPathExists) {
+    return "skipped";
+  }
+
+  await fs.unlink(target);
+  await linkSkill(source, target);
+  return "repaired";
+}
+
+export async function removeMaintainerOnlySkillSymlinks(
+  skillsHome: string,
+  allowedSkillNames: Iterable<string>,
+): Promise<string[]> {
+  const allowed = new Set(Array.from(allowedSkillNames));
+  try {
+    const entries = await fs.readdir(skillsHome, { withFileTypes: true });
+    const removed: string[] = [];
+    for (const entry of entries) {
+      if (allowed.has(entry.name)) continue;
+
+      const target = path.join(skillsHome, entry.name);
+      const existing = await fs.lstat(target).catch(() => null);
+      if (!existing?.isSymbolicLink()) continue;
+
+      const linkedPath = await fs.readlink(target).catch(() => null);
+      if (!linkedPath) continue;
+
+      const resolvedLinkedPath = path.isAbsolute(linkedPath)
+        ? linkedPath
+        : path.resolve(path.dirname(target), linkedPath);
+      if (
+        !isMaintainerOnlySkillTarget(linkedPath) &&
+        !isMaintainerOnlySkillTarget(resolvedLinkedPath)
+      ) {
+        continue;
       }
-    }
-  }
 
+      await fs.unlink(target);
+      removed.push(entry.name);
+    }
+
+    return removed;
+  } catch {
+    return [];
+  }
+}
+
+export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
+  const resolved = await resolveCommandPath(command, cwd, env);
+  if (resolved) return;
+  if (command.includes("/") || command.includes("\\")) {
+    const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+    throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+  }
   throw new Error(`Command not found in PATH: "${command}"`);
 }
 
@@ -213,85 +757,116 @@ export async function runChildProcess(
     graceSec: number;
     onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
     onLogError?: (err: unknown, runId: string, message: string) => void;
+    onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
     stdin?: string;
   },
 ): 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: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
-    }) as ChildProcessWithEvents;
+    const rawMerged: NodeJS.ProcessEnv = { ...process.env, ...opts.env };
 
-    if (opts.stdin != null && child.stdin) {
-      child.stdin.write(opts.stdin);
-      child.stdin.end();
+    // Strip Claude Code nesting-guard env vars so spawned `claude` processes
+    // don't refuse to start with "cannot be launched inside another session".
+    // These vars leak in when the Paperclip server itself is started from
+    // within a Claude Code session (e.g. `npx paperclipai run` in a terminal
+    // owned by Claude Code) or when cron inherits a contaminated shell env.
+    const CLAUDE_CODE_NESTING_VARS = [
+      "CLAUDECODE",
+      "CLAUDE_CODE_ENTRYPOINT",
+      "CLAUDE_CODE_SESSION",
+      "CLAUDE_CODE_PARENT_SESSION",
+    ] as const;
+    for (const key of CLAUDE_CODE_NESTING_VARS) {
+      delete rawMerged[key];
     }
 
-    runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+    const mergedEnv = ensurePathInEnv(rawMerged);
+    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
+      .then((target) => {
+        const child = spawn(target.command, target.args, {
+          cwd: opts.cwd,
+          env: mergedEnv,
+          shell: false,
+          stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+        }) as ChildProcessWithEvents;
+        const startedAt = new Date().toISOString();
 
-    let timedOut = false;
-    let stdout = "";
-    let stderr = "";
-    let logChain: Promise<void> = Promise.resolve();
+        if (opts.stdin != null && child.stdin) {
+          child.stdin.write(opts.stdin);
+          child.stdin.end();
+        }
 
-    const timeout =
-      opts.timeoutSec > 0
-        ? setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGTERM");
-            setTimeout(() => {
-              if (!child.killed) {
-                child.kill("SIGKILL");
-              }
-            }, Math.max(1, opts.graceSec) * 1000);
-          }, opts.timeoutSec * 1000)
-        : null;
+        if (typeof child.pid === "number" && child.pid > 0 && opts.onSpawn) {
+          void opts.onSpawn({ pid: child.pid, startedAt }).catch((err) => {
+            onLogError(err, runId, "failed to record child process metadata");
+          });
+        }
 
-    child.stdout?.on("data", (chunk: unknown) => {
-      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"));
-    });
+        runningProcesses.set(runId, { child, graceSec: opts.graceSec });
 
-    child.stderr?.on("data", (chunk: unknown) => {
-      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"));
-    });
+        let timedOut = false;
+        let stdout = "";
+        let stderr = "";
+        let logChain: Promise<void> = Promise.resolve();
 
-    child.on("error", (err: Error) => {
-      if (timeout) 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));
-    });
+        const timeout =
+          opts.timeoutSec > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                setTimeout(() => {
+                  if (!child.killed) {
+                    child.kill("SIGKILL");
+                  }
+                }, Math.max(1, opts.graceSec) * 1000);
+              }, opts.timeoutSec * 1000)
+            : null;
 
-    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
-      if (timeout) clearTimeout(timeout);
-      runningProcesses.delete(runId);
-      void logChain.finally(() => {
-        resolve({
-          exitCode: code,
-          signal,
-          timedOut,
-          stdout,
-          stderr,
+        child.stdout?.on("data", (chunk: unknown) => {
+          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: unknown) => {
+          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: Error) => {
+          if (timeout) 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: number | null, signal: NodeJS.Signals | null) => {
+          if (timeout) clearTimeout(timeout);
+          runningProcesses.delete(runId);
+          void logChain.finally(() => {
+            resolve({
+              exitCode: code,
+              signal,
+              timedOut,
+              stdout,
+              stderr,
+              pid: child.pid ?? null,
+              startedAt,
+            });
+          });
+        });
+      })
+      .catch(reject);
   });
 }

packages/adapter-utils/src/session-compaction.ts

@@ -0,0 +1,175 @@
+export interface SessionCompactionPolicy {
+  enabled: boolean;
+  maxSessionRuns: number;
+  maxRawInputTokens: number;
+  maxSessionAgeHours: number;
+}
+
+export type NativeContextManagement = "confirmed" | "likely" | "unknown" | "none";
+
+export interface AdapterSessionManagement {
+  supportsSessionResume: boolean;
+  nativeContextManagement: NativeContextManagement;
+  defaultSessionCompaction: SessionCompactionPolicy;
+}
+
+export interface ResolvedSessionCompactionPolicy {
+  policy: SessionCompactionPolicy;
+  adapterSessionManagement: AdapterSessionManagement | null;
+  explicitOverride: Partial<SessionCompactionPolicy>;
+  source: "adapter_default" | "agent_override" | "legacy_fallback";
+}
+
+const DEFAULT_SESSION_COMPACTION_POLICY: SessionCompactionPolicy = {
+  enabled: true,
+  maxSessionRuns: 200,
+  maxRawInputTokens: 2_000_000,
+  maxSessionAgeHours: 72,
+};
+
+// Adapters with native context management still participate in session resume,
+// but Paperclip should not rotate them using threshold-based compaction.
+const ADAPTER_MANAGED_SESSION_POLICY: SessionCompactionPolicy = {
+  enabled: true,
+  maxSessionRuns: 0,
+  maxRawInputTokens: 0,
+  maxSessionAgeHours: 0,
+};
+
+export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
+  "claude_local",
+  "codex_local",
+  "cursor",
+  "gemini_local",
+  "opencode_local",
+  "pi_local",
+]);
+
+export const ADAPTER_SESSION_MANAGEMENT: Record<string, AdapterSessionManagement> = {
+  claude_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "confirmed",
+    defaultSessionCompaction: ADAPTER_MANAGED_SESSION_POLICY,
+  },
+  codex_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "confirmed",
+    defaultSessionCompaction: ADAPTER_MANAGED_SESSION_POLICY,
+  },
+  cursor: {
+    supportsSessionResume: true,
+    nativeContextManagement: "unknown",
+    defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+  },
+  gemini_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "unknown",
+    defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+  },
+  opencode_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "unknown",
+    defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+  },
+  pi_local: {
+    supportsSessionResume: true,
+    nativeContextManagement: "unknown",
+    defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+    return undefined;
+  }
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.max(0, Math.floor(value));
+  }
+  if (typeof value !== "string") return undefined;
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed)) : undefined;
+}
+
+export function getAdapterSessionManagement(adapterType: string | null | undefined): AdapterSessionManagement | null {
+  if (!adapterType) return null;
+  return ADAPTER_SESSION_MANAGEMENT[adapterType] ?? null;
+}
+
+export function readSessionCompactionOverride(runtimeConfig: unknown): Partial<SessionCompactionPolicy> {
+  const runtime = isRecord(runtimeConfig) ? runtimeConfig : {};
+  const heartbeat = isRecord(runtime.heartbeat) ? runtime.heartbeat : {};
+  const compaction = isRecord(
+    heartbeat.sessionCompaction ?? heartbeat.sessionRotation ?? runtime.sessionCompaction,
+  )
+    ? (heartbeat.sessionCompaction ?? heartbeat.sessionRotation ?? runtime.sessionCompaction) as Record<string, unknown>
+    : {};
+
+  const explicit: Partial<SessionCompactionPolicy> = {};
+  const enabled = readBoolean(compaction.enabled);
+  const maxSessionRuns = readNumber(compaction.maxSessionRuns);
+  const maxRawInputTokens = readNumber(compaction.maxRawInputTokens);
+  const maxSessionAgeHours = readNumber(compaction.maxSessionAgeHours);
+
+  if (enabled !== undefined) explicit.enabled = enabled;
+  if (maxSessionRuns !== undefined) explicit.maxSessionRuns = maxSessionRuns;
+  if (maxRawInputTokens !== undefined) explicit.maxRawInputTokens = maxRawInputTokens;
+  if (maxSessionAgeHours !== undefined) explicit.maxSessionAgeHours = maxSessionAgeHours;
+
+  return explicit;
+}
+
+export function resolveSessionCompactionPolicy(
+  adapterType: string | null | undefined,
+  runtimeConfig: unknown,
+): ResolvedSessionCompactionPolicy {
+  const adapterSessionManagement = getAdapterSessionManagement(adapterType);
+  const explicitOverride = readSessionCompactionOverride(runtimeConfig);
+  const hasExplicitOverride = Object.keys(explicitOverride).length > 0;
+  const fallbackEnabled = Boolean(adapterType && LEGACY_SESSIONED_ADAPTER_TYPES.has(adapterType));
+  const basePolicy = adapterSessionManagement?.defaultSessionCompaction ?? {
+    ...DEFAULT_SESSION_COMPACTION_POLICY,
+    enabled: fallbackEnabled,
+  };
+
+  return {
+    policy: {
+      enabled: explicitOverride.enabled ?? basePolicy.enabled,
+      maxSessionRuns: explicitOverride.maxSessionRuns ?? basePolicy.maxSessionRuns,
+      maxRawInputTokens: explicitOverride.maxRawInputTokens ?? basePolicy.maxRawInputTokens,
+      maxSessionAgeHours: explicitOverride.maxSessionAgeHours ?? basePolicy.maxSessionAgeHours,
+    },
+    adapterSessionManagement,
+    explicitOverride,
+    source: hasExplicitOverride
+      ? "agent_override"
+      : adapterSessionManagement
+        ? "adapter_default"
+        : "legacy_fallback",
+  };
+}
+
+export function hasSessionCompactionThresholds(policy: Pick<
+  SessionCompactionPolicy,
+  "maxSessionRuns" | "maxRawInputTokens" | "maxSessionAgeHours"
+>) {
+  return policy.maxSessionRuns > 0 || policy.maxRawInputTokens > 0 || policy.maxSessionAgeHours > 0;
+}

packages/adapter-utils/src/types.ts

@@ -30,7 +30,36 @@ export interface UsageSummary {
   cachedInputTokens?: number;
 }
 
-export type AdapterBillingType = "api" | "subscription" | "unknown";
+export type AdapterBillingType =
+  | "api"
+  | "subscription"
+  | "metered_api"
+  | "subscription_included"
+  | "subscription_overage"
+  | "credits"
+  | "fixed"
+  | "unknown";
+
+export interface AdapterRuntimeServiceReport {
+  id?: string | null;
+  projectId?: string | null;
+  projectWorkspaceId?: string | null;
+  issueId?: string | null;
+  scopeType?: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId?: string | null;
+  serviceName: string;
+  status?: "starting" | "running" | "stopped" | "failed";
+  lifecycle?: "shared" | "ephemeral";
+  reuseKey?: string | null;
+  command?: string | null;
+  cwd?: string | null;
+  port?: number | null;
+  url?: string | null;
+  providerRef?: string | null;
+  ownerAgentId?: string | null;
+  stopPolicy?: Record<string, unknown> | null;
+  healthStatus?: "unknown" | "healthy" | "unhealthy";
+}
 
 export interface AdapterExecutionResult {
   exitCode: number | null;
@@ -47,12 +76,22 @@ export interface AdapterExecutionResult {
   sessionParams?: Record<string, unknown> | null;
   sessionDisplayId?: string | null;
   provider?: string | null;
+  biller?: string | null;
   model?: string | null;
   billingType?: AdapterBillingType | null;
   costUsd?: number | null;
   resultJson?: Record<string, unknown> | null;
+  runtimeServices?: AdapterRuntimeServiceReport[];
   summary?: string | null;
   clearSession?: boolean;
+  question?: {
+    prompt: string;
+    choices: Array<{
+      key: string;
+      label: string;
+      description?: string;
+    }>;
+  } | null;
 }
 
 export interface AdapterSessionCodec {
@@ -69,6 +108,7 @@ export interface AdapterInvocationMeta {
   commandNotes?: string[];
   env?: Record<string, string>;
   prompt?: string;
+  promptMetrics?: Record<string, number>;
   context?: Record<string, unknown>;
 }
 
@@ -80,6 +120,7 @@ export interface AdapterExecutionContext {
   context: Record<string, unknown>;
   onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
   onMeta?: (meta: AdapterInvocationMeta) => Promise<void>;
+  onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
   authToken?: string;
 }
 
@@ -107,6 +148,55 @@ export interface AdapterEnvironmentTestResult {
   testedAt: string;
 }
 
+export type AdapterSkillSyncMode = "unsupported" | "persistent" | "ephemeral";
+
+export type AdapterSkillState =
+  | "available"
+  | "configured"
+  | "installed"
+  | "missing"
+  | "stale"
+  | "external";
+
+export type AdapterSkillOrigin =
+  | "company_managed"
+  | "paperclip_required"
+  | "user_installed"
+  | "external_unknown";
+
+export interface AdapterSkillEntry {
+  key: string;
+  runtimeName: string | null;
+  desired: boolean;
+  managed: boolean;
+  required?: boolean;
+  requiredReason?: string | null;
+  state: AdapterSkillState;
+  origin?: AdapterSkillOrigin;
+  originLabel?: string | null;
+  locationLabel?: string | null;
+  readOnly?: boolean;
+  sourcePath?: string | null;
+  targetPath?: string | null;
+  detail?: string | null;
+}
+
+export interface AdapterSkillSnapshot {
+  adapterType: string;
+  supported: boolean;
+  mode: AdapterSkillSyncMode;
+  desiredSkills: string[];
+  entries: AdapterSkillEntry[];
+  warnings: string[];
+}
+
+export interface AdapterSkillContext {
+  agentId: string;
+  companyId: string;
+  adapterType: string;
+  config: Record<string, unknown>;
+}
+
 export interface AdapterEnvironmentTestContext {
   companyId: string;
   adapterType: string;
@@ -140,11 +230,45 @@ export interface HireApprovedHookResult {
   detail?: Record<string, unknown>;
 }
 
+// ---------------------------------------------------------------------------
+// Quota window types — used by adapters that can report provider quota/rate-limit state
+// ---------------------------------------------------------------------------
+
+/** a single rate-limit or usage window returned by a provider quota API */
+export interface QuotaWindow {
+  /** human label, e.g. "5h", "7d", "Sonnet 7d", "Credits" */
+  label: string;
+  /** percent of the window already consumed (0-100), null when not reported */
+  usedPercent: number | null;
+  /** iso timestamp when this window resets, null when not reported */
+  resetsAt: string | null;
+  /** free-form value label for credit-style windows, e.g. "$4.20 remaining" */
+  valueLabel: string | null;
+  /** optional supporting text, e.g. reset details or provider-specific notes */
+  detail?: string | null;
+}
+
+/** result for one provider from getQuotaWindows() */
+export interface ProviderQuotaResult {
+  /** provider slug, e.g. "anthropic", "openai" */
+  provider: string;
+  /** source label when the provider reports where the quota data came from */
+  source?: string | null;
+  /** true when the fetch succeeded and windows is populated */
+  ok: boolean;
+  /** error message when ok is false */
+  error?: string;
+  windows: QuotaWindow[];
+}
+
 export interface ServerAdapterModule {
   type: string;
   execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
   testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+  listSkills?: (ctx: AdapterSkillContext) => Promise<AdapterSkillSnapshot>;
+  syncSkills?: (ctx: AdapterSkillContext, desiredSkills: string[]) => Promise<AdapterSkillSnapshot>;
   sessionCodec?: AdapterSessionCodec;
+  sessionManagement?: import("./session-compaction.js").AdapterSessionManagement;
   supportsLocalAgentJwt?: boolean;
   models?: AdapterModel[];
   listModels?: () => Promise<AdapterModel[]>;
@@ -157,6 +281,18 @@ export interface ServerAdapterModule {
     payload: HireApprovedPayload,
     adapterConfig: Record<string, unknown>,
   ) => Promise<HireApprovedHookResult>;
+  /**
+   * Optional: fetch live provider quota/rate-limit windows for this adapter.
+   * Returns a ProviderQuotaResult so the server can aggregate across adapters
+   * without knowing provider-specific credential paths or API shapes.
+   */
+  getQuotaWindows?: () => Promise<ProviderQuotaResult>;
+  /**
+   * Optional: detect the currently configured model from local config files.
+   * Returns the detected model/provider and the config source, or null if
+   * the adapter does not support detection or no config is found.
+   */
+  detectModel?: () => Promise<{ model: string; provider: string; source: string } | null>;
 }
 
 // ---------------------------------------------------------------------------
@@ -167,8 +303,8 @@ export type TranscriptEntry =
   | { kind: "assistant"; ts: string; text: string; delta?: boolean }
   | { kind: "thinking"; ts: string; text: string; delta?: boolean }
   | { kind: "user"; ts: string; text: string }
-  | { kind: "tool_call"; ts: string; name: string; input: unknown }
-  | { kind: "tool_result"; ts: string; toolUseId: string; content: string; isError: boolean }
+  | { kind: "tool_call"; ts: string; name: string; input: unknown; toolUseId?: string }
+  | { kind: "tool_result"; ts: string; toolUseId: string; toolName?: string; content: string; isError: boolean }
   | { 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 }
@@ -208,6 +344,12 @@ export interface CreateConfigValues {
   envBindings: Record<string, unknown>;
   url: string;
   bootstrapPrompt: string;
+  payloadTemplateJson?: string;
+  workspaceStrategyType?: string;
+  workspaceBaseRef?: string;
+  workspaceBranchTemplate?: string;
+  worktreeParentDir?: string;
+  runtimeServicesJson?: string;
   maxTurnsPerRun: number;
   heartbeatEnabled: boolean;
   intervalSec: number;

packages/adapter-utils/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/claude-local/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @paperclipai/adapter-claude-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/claude-local/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-claude-local",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/claude-local"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -38,7 +48,9 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "probe:quota": "pnpm exec tsx src/cli/quota-probe.ts --json",
+    "probe:quota:raw": "pnpm exec tsx src/cli/quota-probe.ts --json --raw-cli"
   },
   "dependencies": {
     "@paperclipai/adapter-utils": "workspace:*",

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

@@ -17,6 +17,27 @@ function asErrorText(value: unknown): string {
   }
 }
 
+function printToolResult(block: Record<string, unknown>): void {
+  const isError = block.is_error === true;
+  let text = "";
+  if (typeof block.content === "string") {
+    text = block.content;
+  } else if (Array.isArray(block.content)) {
+    const parts: string[] = [];
+    for (const part of block.content) {
+      if (typeof part !== "object" || part === null || Array.isArray(part)) continue;
+      const record = part as Record<string, unknown>;
+      if (typeof record.text === "string") parts.push(record.text);
+    }
+    text = parts.join("\n");
+  }
+
+  console.log((isError ? pc.red : pc.cyan)(`tool_result${isError ? " (error)" : ""}`));
+  if (text) {
+    console.log((isError ? pc.red : pc.gray)(text));
+  }
+}
+
 export function printClaudeStreamEvent(raw: string, debug: boolean): void {
   const line = raw.trim();
   if (!line) return;
@@ -51,6 +72,9 @@ export function printClaudeStreamEvent(raw: string, debug: boolean): void {
       if (blockType === "text") {
         const text = typeof block.text === "string" ? block.text : "";
         if (text) console.log(pc.green(`assistant: ${text}`));
+      } else if (blockType === "thinking") {
+        const text = typeof block.thinking === "string" ? block.thinking : "";
+        if (text) console.log(pc.gray(`thinking: ${text}`));
       } else if (blockType === "tool_use") {
         const name = typeof block.name === "string" ? block.name : "unknown";
         console.log(pc.yellow(`tool_call: ${name}`));
@@ -62,6 +86,22 @@ export function printClaudeStreamEvent(raw: string, debug: boolean): void {
     return;
   }
 
+  if (type === "user") {
+    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>;
+      if (typeof block.type === "string" && block.type === "tool_result") {
+        printToolResult(block);
+      }
+    }
+    return;
+  }
+
   if (type === "result") {
     const usage =
       typeof parsed.usage === "object" && parsed.usage !== null && !Array.isArray(parsed.usage)

packages/adapters/claude-local/src/cli/quota-probe.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import {
+  captureClaudeCliUsageText,
+  fetchClaudeCliQuota,
+  fetchClaudeQuota,
+  getQuotaWindows,
+  parseClaudeCliUsageText,
+  readClaudeAuthStatus,
+  readClaudeToken,
+} from "../server/quota.js";
+
+interface ProbeArgs {
+  json: boolean;
+  includeRawCli: boolean;
+  oauthOnly: boolean;
+  cliOnly: boolean;
+}
+
+function parseArgs(argv: string[]): ProbeArgs {
+  return {
+    json: argv.includes("--json"),
+    includeRawCli: argv.includes("--raw-cli"),
+    oauthOnly: argv.includes("--oauth-only"),
+    cliOnly: argv.includes("--cli-only"),
+  };
+}
+
+function stringifyError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.oauthOnly && args.cliOnly) {
+    throw new Error("Choose either --oauth-only or --cli-only, not both.");
+  }
+
+  const authStatus = await readClaudeAuthStatus();
+  const token = await readClaudeToken();
+
+  const result: Record<string, unknown> = {
+    timestamp: new Date().toISOString(),
+    authStatus,
+    tokenAvailable: token != null,
+  };
+
+  if (!args.cliOnly) {
+    if (!token) {
+      result.oauth = {
+        ok: false,
+        error: "No Claude OAuth access token found in local credentials files.",
+        windows: [],
+      };
+    } else {
+      try {
+        result.oauth = {
+          ok: true,
+          windows: await fetchClaudeQuota(token),
+        };
+      } catch (error) {
+        result.oauth = {
+          ok: false,
+          error: stringifyError(error),
+          windows: [],
+        };
+      }
+    }
+  }
+
+  if (!args.oauthOnly) {
+    try {
+      const rawCliText = args.includeRawCli ? await captureClaudeCliUsageText() : null;
+      const windows = rawCliText ? parseClaudeCliUsageText(rawCliText) : await fetchClaudeCliQuota();
+      result.cli = rawCliText
+        ? {
+            ok: true,
+            windows,
+            rawText: rawCliText,
+          }
+        : {
+            ok: true,
+            windows,
+          };
+    } catch (error) {
+      result.cli = {
+        ok: false,
+        error: stringifyError(error),
+        windows: [],
+      };
+    }
+  }
+
+  if (!args.oauthOnly && !args.cliOnly) {
+    try {
+      result.aggregated = await getQuotaWindows();
+    } catch (error) {
+      result.aggregated = {
+        ok: false,
+        error: stringifyError(error),
+      };
+    }
+  }
+
+  const oauthOk = (result.oauth as { ok?: boolean } | undefined)?.ok === true;
+  const cliOk = (result.cli as { ok?: boolean } | undefined)?.ok === true;
+  const aggregatedOk = (result.aggregated as { ok?: boolean } | undefined)?.ok === true;
+  const ok = oauthOk || cliOk || aggregatedOk;
+
+  if (args.json || process.stdout.isTTY === false) {
+    console.log(JSON.stringify({ ok, ...result }, null, 2));
+  } else {
+    console.log(`timestamp: ${result.timestamp}`);
+    console.log(`auth: ${JSON.stringify(authStatus)}`);
+    console.log(`tokenAvailable: ${token != null}`);
+    if (result.oauth) console.log(`oauth: ${JSON.stringify(result.oauth, null, 2)}`);
+    if (result.cli) console.log(`cli: ${JSON.stringify(result.cli, null, 2)}`);
+    if (result.aggregated) console.log(`aggregated: ${JSON.stringify(result.aggregated, null, 2)}`);
+  }
+
+  if (!ok) process.exitCode = 1;
+}
+
+await main();

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

@@ -25,8 +25,13 @@ Core fields:
 - command (string, optional): defaults to "claude"
 - extraArgs (string[], optional): additional CLI args
 - env (object, optional): KEY=VALUE environment variables
+- workspaceStrategy (object, optional): execution workspace strategy; currently supports { type: "git_worktree", baseRef?, branchTemplate?, worktreeParentDir? }
+- workspaceRuntime (object, optional): reserved for workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats
 
 Operational fields:
 - timeoutSec (number, optional): run timeout in seconds
 - graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

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

@@ -12,10 +12,13 @@ import {
   parseObject,
   parseJson,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  readPaperclipRuntimeSkillEntries,
+  joinPromptSections,
+  buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
   ensurePathInEnv,
+  resolveCommandForLogs,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -26,40 +29,32 @@ import {
   isClaudeMaxTurnsResult,
   isClaudeUnknownSessionError,
 } from "./parse.js";
+import { resolveClaudeDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),         // published: <pkg>/dist/server/ -> <pkg>/skills/
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: src/server/ -> repo root/skills/
-];
-
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
 
 /**
  * Create a tmpdir with `.claude/skills/` containing symlinks to skills from
  * the repo's `skills/` directory, so `--add-dir` makes Claude Code discover
  * them as proper registered skills.
  */
-async function buildSkillsDir(): Promise<string> {
+async function buildSkillsDir(config: Record<string, unknown>): Promise<string> {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skills-"));
   const target = path.join(tmp, ".claude", "skills");
   await fs.mkdir(target, { recursive: true });
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return tmp;
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      await fs.symlink(
-        path.join(skillsDir, entry.name),
-        path.join(target, entry.name),
-      );
-    }
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredNames = new Set(
+    resolveClaudeDesiredSkillNames(
+      config,
+      availableEntries,
+    ),
+  );
+  for (const entry of availableEntries) {
+    if (!desiredNames.has(entry.key)) continue;
+    await fs.symlink(
+      entry.source,
+      path.join(target, entry.runtimeName),
+    );
   }
   return tmp;
 }
@@ -74,11 +69,13 @@ interface ClaudeExecutionInput {
 
 interface ClaudeRuntimeConfig {
   command: string;
+  resolvedCommand: string;
   cwd: string;
   workspaceId: string | null;
   workspaceRepoUrl: string | null;
   workspaceRepoRef: string | null;
   env: Record<string, string>;
+  loggedEnv: Record<string, string>;
   timeoutSec: number;
   graceSec: number;
   extraArgs: string[];
@@ -115,14 +112,29 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
   const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceStrategy = asString(workspaceContext.strategy, "");
   const workspaceId = asString(workspaceContext.workspaceId, "") || null;
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "") || null;
   const workspaceRepoRef = asString(workspaceContext.repoRef, "") || null;
+  const workspaceBranch = asString(workspaceContext.branchName, "") || null;
+  const workspaceWorktreePath = asString(workspaceContext.worktreePath, "") || null;
+  const agentHome = asString(workspaceContext.agentHome, "") || null;
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
       )
     : [];
+  const runtimeServiceIntents = Array.isArray(context.paperclipRuntimeServiceIntents)
+    ? context.paperclipRuntimeServiceIntents.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimeServices = Array.isArray(context.paperclipRuntimeServices)
+    ? context.paperclipRuntimeServices.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
   const configuredCwd = asString(config.cwd, "");
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
@@ -183,6 +195,9 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (workspaceSource) {
     env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
   }
+  if (workspaceStrategy) {
+    env.PAPERCLIP_WORKSPACE_STRATEGY = workspaceStrategy;
+  }
   if (workspaceId) {
     env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   }
@@ -192,9 +207,27 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (workspaceBranch) {
+    env.PAPERCLIP_WORKSPACE_BRANCH = workspaceBranch;
+  }
+  if (workspaceWorktreePath) {
+    env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
+  }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }
+  if (runtimeServiceIntents.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
+  }
+  if (runtimeServices.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICES_JSON = JSON.stringify(runtimeServices);
+  }
+  if (runtimePrimaryUrl) {
+    env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
+  }
 
   for (const [key, value] of Object.entries(envConfig)) {
     if (typeof value === "string") env[key] = value;
@@ -206,6 +239,12 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
 
   const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
   await ensureCommandResolvable(command, cwd, runtimeEnv);
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME", "CLAUDE_CONFIG_DIR"],
+    resolvedCommand,
+  });
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 20);
@@ -217,11 +256,13 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
 
   return {
     command,
+    resolvedCommand,
     cwd,
     workspaceId,
     workspaceRepoUrl,
     workspaceRepoRef,
     env,
+    loggedEnv,
     timeoutSec,
     graceSec,
     extraArgs,
@@ -266,7 +307,7 @@ export async function runClaudeLogin(input: {
 }
 
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -294,28 +335,44 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   });
   const {
     command,
+    resolvedCommand,
     cwd,
     workspaceId,
     workspaceRepoUrl,
     workspaceRepoRef,
     env,
+    loggedEnv,
     timeoutSec,
     graceSec,
     extraArgs,
   } = runtimeConfig;
-  const billingType = resolveClaudeBillingType(env);
-  const skillsDir = await buildSkillsDir();
+  const effectiveEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env }).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  const billingType = resolveClaudeBillingType(effectiveEnv);
+  const skillsDir = await buildSkillsDir(config);
 
   // When instructionsFilePath is configured, create a combined temp file that
   // includes both the file content and the path directive, so we only need
   // --append-system-prompt-file (Claude CLI forbids using both flags together).
-  let effectiveInstructionsFilePath = instructionsFilePath;
+  let effectiveInstructionsFilePath: string | undefined = instructionsFilePath;
   if (instructionsFilePath) {
-    const instructionsContent = await fs.readFile(instructionsFilePath, "utf-8");
-    const pathDirective = `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}.`;
-    const combinedPath = path.join(skillsDir, "agent-instructions.md");
-    await fs.writeFile(combinedPath, instructionsContent + pathDirective, "utf-8");
-    effectiveInstructionsFilePath = combinedPath;
+    try {
+      const instructionsContent = await fs.readFile(instructionsFilePath, "utf-8");
+      const pathDirective = `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}.`;
+      const combinedPath = path.join(skillsDir, "agent-instructions.md");
+      await fs.writeFile(combinedPath, instructionsContent + pathDirective, "utf-8");
+      effectiveInstructionsFilePath = combinedPath;
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      await onLog(
+        "stderr",
+        `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
+      );
+      effectiveInstructionsFilePath = undefined;
+    }
   }
 
   const runtimeSessionParams = parseObject(runtime.sessionParams);
@@ -327,11 +384,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (runtimeSessionId && !canResumeSession) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
     );
   }
-  const prompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -339,7 +397,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const prompt = joinPromptSections([
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildClaudeArgs = (resumeSessionId: string | null) => {
     const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
@@ -378,12 +453,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (onMeta) {
       await onMeta({
         adapterType: "claude_local",
-        command,
+        command: resolvedCommand,
         cwd,
         commandArgs: args,
         commandNotes,
-        env: redactEnvForLogs(env),
+        env: loggedEnv,
         prompt,
+        promptMetrics,
         context,
       });
     }
@@ -394,6 +470,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       stdin: prompt,
       timeoutSec,
       graceSec,
+      onSpawn,
       onLog,
     });
 
@@ -491,6 +568,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       sessionParams: resolvedSessionParams,
       sessionDisplayId: resolvedSessionId,
       provider: "anthropic",
+      biller: "anthropic",
       model: parsedStream.model || asString(parsed.model, model),
       billingType,
       costUsd: parsedStream.costUsd ?? asNumber(parsed.total_cost_usd, 0),
@@ -510,7 +588,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       isClaudeUnknownSessionError(initial.parsed)
     ) {
       await onLog(
-        "stderr",
+        "stdout",
         `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
       );
       const retry = await runAttempt(null);

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

@@ -1,4 +1,5 @@
 export { execute, runClaudeLogin } from "./execute.js";
+export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   parseClaudeStreamJson,
@@ -6,6 +7,18 @@ export {
   isClaudeMaxTurnsResult,
   isClaudeUnknownSessionError,
 } from "./parse.js";
+export {
+  getQuotaWindows,
+  readClaudeAuthStatus,
+  readClaudeToken,
+  fetchClaudeQuota,
+  fetchClaudeCliQuota,
+  captureClaudeCliUsageText,
+  parseClaudeCliUsageText,
+  toPercent,
+  fetchWithTimeout,
+  claudeConfigDir,
+} from "./quota.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
 
 function readNonEmptyString(value: unknown): string | null {

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

@@ -0,0 +1,531 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import type { ProviderQuotaResult, QuotaWindow } from "@paperclipai/adapter-utils";
+
+const execFileAsync = promisify(execFile);
+
+const CLAUDE_USAGE_SOURCE_OAUTH = "anthropic-oauth";
+const CLAUDE_USAGE_SOURCE_CLI = "claude-cli";
+
+export function claudeConfigDir(): string {
+  const fromEnv = process.env.CLAUDE_CONFIG_DIR;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
+  return path.join(os.homedir(), ".claude");
+}
+
+function hasNonEmptyProcessEnv(key: string): boolean {
+  const value = process.env[key];
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function createClaudeQuotaEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (typeof value !== "string") continue;
+    if (key.startsWith("ANTHROPIC_")) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function stripBackspaces(text: string): string {
+  let out = "";
+  for (const char of text) {
+    if (char === "\b") {
+      out = out.slice(0, -1);
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+
+function stripAnsi(text: string): string {
+  return text
+    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/g, "")
+    .replace(/\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
+}
+
+function cleanTerminalText(text: string): string {
+  return stripAnsi(stripBackspaces(text))
+    .replace(/\u0000/g, "")
+    .replace(/\r/g, "\n");
+}
+
+function normalizeForLabelSearch(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function trimToLatestUsagePanel(text: string): string | null {
+  const lower = text.toLowerCase();
+  const settingsIndex = lower.lastIndexOf("settings:");
+  if (settingsIndex < 0) return null;
+  let tail = text.slice(settingsIndex);
+  const tailLower = tail.toLowerCase();
+  if (!tailLower.includes("usage")) return null;
+  if (!tailLower.includes("current session") && !tailLower.includes("loading usage")) return null;
+  const stopMarkers = [
+    "status dialog dismissed",
+    "checking for updates",
+    "press ctrl-c again to exit",
+  ];
+  let stopIndex = -1;
+  for (const marker of stopMarkers) {
+    const markerIndex = tailLower.indexOf(marker);
+    if (markerIndex >= 0 && (stopIndex === -1 || markerIndex < stopIndex)) {
+      stopIndex = markerIndex;
+    }
+  }
+  if (stopIndex >= 0) {
+    tail = tail.slice(0, stopIndex);
+  }
+  return tail;
+}
+
+async function readClaudeTokenFromFile(credPath: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(credPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const obj = parsed as Record<string, unknown>;
+  const oauth = obj["claudeAiOauth"];
+  if (typeof oauth !== "object" || oauth === null) return null;
+  const token = (oauth as Record<string, unknown>)["accessToken"];
+  return typeof token === "string" && token.length > 0 ? token : null;
+}
+
+interface ClaudeAuthStatus {
+  loggedIn: boolean;
+  authMethod: string | null;
+  subscriptionType: string | null;
+}
+
+export async function readClaudeAuthStatus(): Promise<ClaudeAuthStatus | null> {
+  try {
+    const { stdout } = await execFileAsync("claude", ["auth", "status"], {
+      env: process.env,
+      timeout: 5_000,
+      maxBuffer: 1024 * 1024,
+    });
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+    return {
+      loggedIn: parsed.loggedIn === true,
+      authMethod: typeof parsed.authMethod === "string" ? parsed.authMethod : null,
+      subscriptionType: typeof parsed.subscriptionType === "string" ? parsed.subscriptionType : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function describeClaudeSubscriptionAuth(status: ClaudeAuthStatus | null): string | null {
+  if (!status?.loggedIn || status.authMethod !== "claude.ai") return null;
+  return status.subscriptionType
+    ? `Claude is logged in via claude.ai (${status.subscriptionType})`
+    : "Claude is logged in via claude.ai";
+}
+
+export async function readClaudeToken(): Promise<string | null> {
+  const configDir = claudeConfigDir();
+  for (const filename of [".credentials.json", "credentials.json"]) {
+    const token = await readClaudeTokenFromFile(path.join(configDir, filename));
+    if (token) return token;
+  }
+  return null;
+}
+
+interface AnthropicUsageWindow {
+  utilization?: number | null;
+  resets_at?: string | null;
+}
+
+interface AnthropicExtraUsage {
+  is_enabled?: boolean | null;
+  monthly_limit?: number | null;
+  used_credits?: number | null;
+  utilization?: number | null;
+  currency?: string | null;
+}
+
+interface AnthropicUsageResponse {
+  five_hour?: AnthropicUsageWindow | null;
+  seven_day?: AnthropicUsageWindow | null;
+  seven_day_sonnet?: AnthropicUsageWindow | null;
+  seven_day_opus?: AnthropicUsageWindow | null;
+  extra_usage?: AnthropicExtraUsage | null;
+}
+
+function formatCurrencyAmount(value: number, currency: string | null | undefined): string {
+  const code = typeof currency === "string" && currency.trim().length > 0 ? currency.trim().toUpperCase() : "USD";
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: code,
+    maximumFractionDigits: 2,
+  }).format(value);
+}
+
+function formatExtraUsageLabel(extraUsage: AnthropicExtraUsage): string | null {
+  const monthlyLimit = extraUsage.monthly_limit;
+  const usedCredits = extraUsage.used_credits;
+  if (
+    typeof monthlyLimit !== "number" ||
+    !Number.isFinite(monthlyLimit) ||
+    typeof usedCredits !== "number" ||
+    !Number.isFinite(usedCredits)
+  ) {
+    return null;
+  }
+  return `${formatCurrencyAmount(usedCredits, extraUsage.currency)} / ${formatCurrencyAmount(monthlyLimit, extraUsage.currency)}`;
+}
+
+/** Convert a 0-1 utilization fraction to a 0-100 integer percent. Returns null for null/undefined input. */
+export function toPercent(utilization: number | null | undefined): number | null {
+  if (utilization == null) return null;
+  return Math.min(100, Math.round(utilization * 100));
+}
+
+/** fetch with an abort-based timeout so a hanging provider api doesn't block the response indefinitely */
+export async function fetchWithTimeout(url: string, init: RequestInit, ms = 8000): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchClaudeQuota(token: string): Promise<QuotaWindow[]> {
+  const resp = await fetchWithTimeout("https://api.anthropic.com/api/oauth/usage", {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "anthropic-beta": "oauth-2025-04-20",
+    },
+  });
+  if (!resp.ok) throw new Error(`anthropic usage api returned ${resp.status}`);
+  const body = (await resp.json()) as AnthropicUsageResponse;
+  const windows: QuotaWindow[] = [];
+
+  if (body.five_hour != null) {
+    windows.push({
+      label: "Current session",
+      usedPercent: toPercent(body.five_hour.utilization),
+      resetsAt: body.five_hour.resets_at ?? null,
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (body.seven_day != null) {
+    windows.push({
+      label: "Current week (all models)",
+      usedPercent: toPercent(body.seven_day.utilization),
+      resetsAt: body.seven_day.resets_at ?? null,
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (body.seven_day_sonnet != null) {
+    windows.push({
+      label: "Current week (Sonnet only)",
+      usedPercent: toPercent(body.seven_day_sonnet.utilization),
+      resetsAt: body.seven_day_sonnet.resets_at ?? null,
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (body.seven_day_opus != null) {
+    windows.push({
+      label: "Current week (Opus only)",
+      usedPercent: toPercent(body.seven_day_opus.utilization),
+      resetsAt: body.seven_day_opus.resets_at ?? null,
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (body.extra_usage != null) {
+    windows.push({
+      label: "Extra usage",
+      usedPercent: body.extra_usage.is_enabled === false ? null : toPercent(body.extra_usage.utilization),
+      resetsAt: null,
+      valueLabel:
+        body.extra_usage.is_enabled === false
+          ? "Not enabled"
+          : formatExtraUsageLabel(body.extra_usage),
+      detail:
+        body.extra_usage.is_enabled === false
+          ? "Extra usage not enabled"
+          : "Monthly extra usage pool",
+    });
+  }
+  return windows;
+}
+
+function usageOutputLooksRelevant(text: string): boolean {
+  const normalized = normalizeForLabelSearch(text);
+  return normalized.includes("currentsession")
+    || normalized.includes("currentweek")
+    || normalized.includes("loadingusage")
+    || normalized.includes("failedtoloadusagedata")
+    || normalized.includes("tokenexpired")
+    || normalized.includes("authenticationerror")
+    || normalized.includes("ratelimited");
+}
+
+function usageOutputLooksComplete(text: string): boolean {
+  const normalized = normalizeForLabelSearch(text);
+  if (
+    normalized.includes("failedtoloadusagedata")
+    || normalized.includes("tokenexpired")
+    || normalized.includes("authenticationerror")
+    || normalized.includes("ratelimited")
+  ) {
+    return true;
+  }
+  return normalized.includes("currentsession")
+    && (normalized.includes("currentweek") || normalized.includes("extrausage"))
+    && /[0-9]{1,3}(?:\.[0-9]+)?%/i.test(text);
+}
+
+function extractUsageError(text: string): string | null {
+  const lower = text.toLowerCase();
+  const compact = lower.replace(/\s+/g, "");
+  if (lower.includes("token_expired") || lower.includes("token has expired")) {
+    return "Claude CLI token expired. Run `claude login` to refresh.";
+  }
+  if (lower.includes("authentication_error")) {
+    return "Claude CLI authentication error. Run `claude login`.";
+  }
+  if (lower.includes("rate_limit_error") || lower.includes("rate limited") || compact.includes("ratelimited")) {
+    return "Claude CLI usage endpoint is rate limited right now. Please try again later.";
+  }
+  if (lower.includes("failed to load usage data") || compact.includes("failedtoloadusagedata")) {
+    return "Claude CLI could not load usage data. Open the CLI and retry `/usage`.";
+  }
+  return null;
+}
+
+function percentFromLine(line: string): number | null {
+  const match = line.match(/([0-9]{1,3}(?:\.[0-9]+)?)\s*%/i);
+  if (!match) return null;
+  const rawValue = Number(match[1]);
+  if (!Number.isFinite(rawValue)) return null;
+  const clamped = Math.min(100, Math.max(0, rawValue));
+  const lower = line.toLowerCase();
+  if (lower.includes("remaining") || lower.includes("left") || lower.includes("available")) {
+    return Math.max(0, Math.min(100, Math.round(100 - clamped)));
+  }
+  return Math.round(clamped);
+}
+
+function isQuotaLabel(line: string): boolean {
+  const normalized = normalizeForLabelSearch(line);
+  return normalized === "currentsession"
+    || normalized === "currentweekallmodels"
+    || normalized === "currentweeksonnetonly"
+    || normalized === "currentweeksonnet"
+    || normalized === "currentweekopusonly"
+    || normalized === "currentweekopus"
+    || normalized === "extrausage";
+}
+
+function canonicalQuotaLabel(line: string): string {
+  switch (normalizeForLabelSearch(line)) {
+    case "currentsession":
+      return "Current session";
+    case "currentweekallmodels":
+      return "Current week (all models)";
+    case "currentweeksonnetonly":
+    case "currentweeksonnet":
+      return "Current week (Sonnet only)";
+    case "currentweekopusonly":
+    case "currentweekopus":
+      return "Current week (Opus only)";
+    case "extrausage":
+      return "Extra usage";
+    default:
+      return line;
+  }
+}
+
+function formatClaudeCliDetail(label: string, lines: string[]): string | null {
+  const normalizedLabel = normalizeForLabelSearch(label);
+  if (normalizedLabel === "extrausage") {
+    const compact = lines.join(" ").replace(/\s+/g, "").toLowerCase();
+    if (compact.includes("extrausagenotenabled")) {
+      return "Extra usage not enabled • /extra-usage to enable";
+    }
+    const firstLine = lines.find((line) => line.trim().length > 0) ?? null;
+    return firstLine;
+  }
+
+  const resetLine = lines.find((line) => /^resets/i.test(line) || normalizeForLabelSearch(line).startsWith("resets"));
+  if (!resetLine) return null;
+  return resetLine
+    .replace(/^Resets/i, "Resets ")
+    .replace(/([A-Z][a-z]{2})(\d)/g, "$1 $2")
+    .replace(/(\d)at(\d)/g, "$1 at $2")
+    .replace(/(am|pm)\(/gi, "$1 (")
+    .replace(/([A-Za-z])\(/g, "$1 (")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function parseClaudeCliUsageText(text: string): QuotaWindow[] {
+  const cleaned = trimToLatestUsagePanel(cleanTerminalText(text)) ?? cleanTerminalText(text);
+  const usageError = extractUsageError(cleaned);
+  if (usageError) throw new Error(usageError);
+
+  const lines = cleaned
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  const sections: Array<{ label: string; lines: string[] }> = [];
+  let current: { label: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    if (isQuotaLabel(line)) {
+      if (current) sections.push(current);
+      current = { label: canonicalQuotaLabel(line), lines: [] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  if (current) sections.push(current);
+
+  const windows = sections.map<QuotaWindow>((section) => {
+    const usedPercent = section.lines.map(percentFromLine).find((value) => value != null) ?? null;
+    return {
+      label: section.label,
+      usedPercent,
+      resetsAt: null,
+      valueLabel: null,
+      detail: formatClaudeCliDetail(section.label, section.lines),
+    };
+  });
+
+  if (!windows.some((window) => normalizeForLabelSearch(window.label) === "currentsession")) {
+    throw new Error("Could not parse Claude CLI usage output.");
+  }
+  return windows;
+}
+
+function quoteForShell(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function buildClaudeCliShellProbeCommand(): string {
+  const feed = "(sleep 2; printf '/usage\\r'; sleep 6; printf '\\033'; sleep 1; printf '\\003')";
+  const claudeCommand = "claude --tools \"\"";
+  if (process.platform === "darwin") {
+    return `${feed} | script -q /dev/null ${claudeCommand}`;
+  }
+  return `${feed} | script -q -e -f -c ${quoteForShell(claudeCommand)} /dev/null`;
+}
+
+export async function captureClaudeCliUsageText(timeoutMs = 12_000): Promise<string> {
+  const command = buildClaudeCliShellProbeCommand();
+  try {
+    const { stdout, stderr } = await execFileAsync("sh", ["-c", command], {
+      env: createClaudeQuotaEnv(),
+      timeout: timeoutMs,
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    const output = `${stdout}${stderr}`;
+    const cleaned = cleanTerminalText(output);
+    if (usageOutputLooksComplete(cleaned)) return output;
+    throw new Error("Claude CLI usage probe ended before rendering usage.");
+  } catch (error) {
+    const stdout =
+      typeof error === "object" && error !== null && "stdout" in error && typeof error.stdout === "string"
+        ? error.stdout
+        : "";
+    const stderr =
+      typeof error === "object" && error !== null && "stderr" in error && typeof error.stderr === "string"
+        ? error.stderr
+        : "";
+    const output = `${stdout}${stderr}`;
+    const cleaned = cleanTerminalText(output);
+    if (usageOutputLooksComplete(cleaned)) return output;
+    if (usageOutputLooksRelevant(cleaned)) {
+      throw new Error("Claude CLI usage probe ended before rendering usage.");
+    }
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+}
+
+export async function fetchClaudeCliQuota(): Promise<QuotaWindow[]> {
+  const rawText = await captureClaudeCliUsageText();
+  return parseClaudeCliUsageText(rawText);
+}
+
+function formatProviderError(source: string, error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `${source}: ${message}`;
+}
+
+export async function getQuotaWindows(): Promise<ProviderQuotaResult> {
+  const authStatus = await readClaudeAuthStatus();
+  const authDescription = describeClaudeSubscriptionAuth(authStatus);
+  const token = await readClaudeToken();
+
+  const errors: string[] = [];
+
+  if (token) {
+    try {
+      const windows = await fetchClaudeQuota(token);
+      return { provider: "anthropic", source: CLAUDE_USAGE_SOURCE_OAUTH, ok: true, windows };
+    } catch (error) {
+      errors.push(formatProviderError("Anthropic OAuth usage", error));
+    }
+  }
+
+  try {
+    const windows = await fetchClaudeCliQuota();
+    return { provider: "anthropic", source: CLAUDE_USAGE_SOURCE_CLI, ok: true, windows };
+  } catch (error) {
+    errors.push(formatProviderError("Claude CLI /usage", error));
+  }
+
+  if (hasNonEmptyProcessEnv("ANTHROPIC_API_KEY") && !authDescription) {
+    return {
+      provider: "anthropic",
+      ok: false,
+      error:
+        errors[0]
+        ?? "ANTHROPIC_API_KEY is set and no local Claude subscription session is available for quota polling",
+      windows: [],
+    };
+  }
+
+  if (authDescription) {
+    return {
+      provider: "anthropic",
+      ok: false,
+      error:
+        errors.length > 0
+          ? `${authDescription}, but quota polling failed (${errors.join("; ")})`
+          : `${authDescription}, but Paperclip could not load subscription quota data`,
+      windows: [],
+    };
+  }
+
+  return {
+    provider: "anthropic",
+    ok: false,
+    error: errors[0] ?? "no local claude auth token",
+    windows: [],
+  };
+}

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

@@ -0,0 +1,121 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  readPaperclipRuntimeSkillEntries,
+  readInstalledSkillTargets,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveClaudeSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredHome = asString(env.HOME);
+  const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+  return path.join(home, ".claude", "skills");
+}
+
+async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const desiredSet = new Set(desiredSkills);
+  const skillsHome = resolveClaudeSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
+    key: entry.key,
+    runtimeName: entry.runtimeName,
+    desired: desiredSet.has(entry.key),
+    managed: true,
+    state: desiredSet.has(entry.key) ? "configured" : "available",
+    origin: entry.required ? "paperclip_required" : "company_managed",
+    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
+    readOnly: false,
+    sourcePath: entry.source,
+    targetPath: null,
+    detail: desiredSet.has(entry.key)
+      ? "Will be mounted into the ephemeral Claude skill directory on the next run."
+      : null,
+    required: Boolean(entry.required),
+    requiredReason: entry.requiredReason ?? null,
+  }));
+  const warnings: string[] = [];
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+      sourcePath: undefined,
+      targetPath: undefined,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
+    entries.push({
+      key: name,
+      runtimeName: name,
+      desired: false,
+      managed: false,
+      state: "external",
+      origin: "user_installed",
+      originLabel: "User-installed",
+      locationLabel: "~/.claude/skills",
+      readOnly: true,
+      sourcePath: null,
+      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+      detail: "Installed outside Paperclip management in the Claude skills home.",
+    });
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
+    adapterType: "claude_local",
+    supported: true,
+    mode: "ephemeral",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export async function syncClaudeSkills(
+  ctx: AdapterSkillContext,
+  _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export function resolveClaudeDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

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

@@ -50,11 +50,24 @@ function parseEnvBindings(bindings: unknown): Record<string, unknown> {
   return env;
 }
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.effort = v.thinkingEffort;
   if (v.chrome) ac.chrome = true;
@@ -70,6 +83,18 @@ export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, un
   if (Object.keys(env).length > 0) ac.env = env;
   ac.maxTurnsPerRun = v.maxTurnsPerRun;
   ac.dangerouslySkipPermissions = v.dangerouslySkipPermissions;
+  if (v.workspaceStrategyType === "git_worktree") {
+    ac.workspaceStrategy = {
+      type: "git_worktree",
+      ...(v.workspaceBaseRef ? { baseRef: v.workspaceBaseRef } : {}),
+      ...(v.workspaceBranchTemplate ? { branchTemplate: v.workspaceBranchTemplate } : {}),
+      ...(v.worktreeParentDir ? { worktreeParentDir: v.worktreeParentDir } : {}),
+    };
+  }
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   if (v.command) ac.command = v.command;
   if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
   return ac;

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

@@ -71,6 +71,12 @@ export function parseClaudeStdoutLine(line: string, ts: string): TranscriptEntry
           kind: "tool_call",
           ts,
           name: typeof block.name === "string" ? block.name : "unknown",
+          toolUseId:
+            typeof block.id === "string"
+              ? block.id
+              : typeof block.tool_use_id === "string"
+                ? block.tool_use_id
+                : undefined,
           input: block.input ?? {},
         });
       }

packages/adapters/claude-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/codex-local/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @paperclipai/adapter-codex-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/codex-local/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-codex-local",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/codex-local"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -38,7 +48,8 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "probe:quota": "pnpm exec tsx src/cli/quota-probe.ts --json"
   },
   "dependencies": {
     "@paperclipai/adapter-utils": "workspace:*",

packages/adapters/codex-local/src/cli/quota-probe.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import {
+  fetchCodexQuota,
+  fetchCodexRpcQuota,
+  getQuotaWindows,
+  readCodexAuthInfo,
+  readCodexToken,
+} from "../server/quota.js";
+
+interface ProbeArgs {
+  json: boolean;
+  rpcOnly: boolean;
+  whamOnly: boolean;
+}
+
+function parseArgs(argv: string[]): ProbeArgs {
+  return {
+    json: argv.includes("--json"),
+    rpcOnly: argv.includes("--rpc-only"),
+    whamOnly: argv.includes("--wham-only"),
+  };
+}
+
+function stringifyError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.rpcOnly && args.whamOnly) {
+    throw new Error("Choose either --rpc-only or --wham-only, not both.");
+  }
+
+  const auth = await readCodexAuthInfo();
+  const token = await readCodexToken();
+
+  const result: Record<string, unknown> = {
+    timestamp: new Date().toISOString(),
+    auth,
+    tokenAvailable: token != null,
+  };
+
+  if (!args.whamOnly) {
+    try {
+      result.rpc = {
+        ok: true,
+        ...(await fetchCodexRpcQuota()),
+      };
+    } catch (error) {
+      result.rpc = {
+        ok: false,
+        error: stringifyError(error),
+        windows: [],
+      };
+    }
+  }
+
+  if (!args.rpcOnly) {
+    if (!token) {
+      result.wham = {
+        ok: false,
+        error: "No local Codex auth token found in ~/.codex/auth.json.",
+        windows: [],
+      };
+    } else {
+      try {
+        result.wham = {
+          ok: true,
+          windows: await fetchCodexQuota(token.token, token.accountId),
+        };
+      } catch (error) {
+        result.wham = {
+          ok: false,
+          error: stringifyError(error),
+          windows: [],
+        };
+      }
+    }
+  }
+
+  if (!args.rpcOnly && !args.whamOnly) {
+    try {
+      result.aggregated = await getQuotaWindows();
+    } catch (error) {
+      result.aggregated = {
+        ok: false,
+        error: stringifyError(error),
+      };
+    }
+  }
+
+  const rpcOk = (result.rpc as { ok?: boolean } | undefined)?.ok === true;
+  const whamOk = (result.wham as { ok?: boolean } | undefined)?.ok === true;
+  const aggregatedOk = (result.aggregated as { ok?: boolean } | undefined)?.ok === true;
+  const ok = rpcOk || whamOk || aggregatedOk;
+
+  if (args.json || process.stdout.isTTY === false) {
+    console.log(JSON.stringify({ ok, ...result }, null, 2));
+  } else {
+    console.log(`timestamp: ${result.timestamp}`);
+    console.log(`auth: ${JSON.stringify(auth)}`);
+    console.log(`tokenAvailable: ${token != null}`);
+    if (result.rpc) console.log(`rpc: ${JSON.stringify(result.rpc, null, 2)}`);
+    if (result.wham) console.log(`wham: ${JSON.stringify(result.wham, null, 2)}`);
+    if (result.aggregated) console.log(`aggregated: ${JSON.stringify(result.aggregated, null, 2)}`);
+  }
+
+  if (!ok) process.exitCode = 1;
+}
+
+await main();

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

@@ -31,6 +31,8 @@ Core fields:
 - command (string, optional): defaults to "codex"
 - extraArgs (string[], optional): additional CLI args
 - env (object, optional): KEY=VALUE environment variables
+- workspaceStrategy (object, optional): execution workspace strategy; currently supports { type: "git_worktree", baseRef?, branchTemplate?, worktreeParentDir? }
+- workspaceRuntime (object, optional): reserved for workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats
 
 Operational fields:
 - timeoutSec (number, optional): run timeout in seconds
@@ -38,6 +40,10 @@ Operational fields:
 
 Notes:
 - Prompts are piped via stdin (Codex receives "-" prompt argument).
-- Paperclip auto-injects local skills into Codex personal skills dir ("$CODEX_HOME/skills" or "~/.codex/skills") when missing, so Codex can discover "$paperclip" and related skills.
+- If instructionsFilePath is configured, Paperclip prepends that file's contents to the stdin prompt on every run.
+- Codex exec automatically applies repo-scoped AGENTS.md instructions from the active workspace. Paperclip cannot suppress that discovery in exec mode, so repo AGENTS.md files may still apply even when you only configured an explicit instructionsFilePath.
+- Paperclip injects desired local skills into the effective CODEX_HOME/skills/ directory at execution time so Codex can discover "$paperclip" and related skills without polluting the project working directory. In managed-home mode (the default) this is ~/.paperclip/instances/<id>/companies/<companyId>/codex-home/skills/; when CODEX_HOME is explicitly overridden in adapter config, that override is used instead.
+- Unless explicitly overridden in adapter config, Paperclip runs Codex with a per-company managed CODEX_HOME under the active Paperclip instance and seeds auth/config from the shared Codex home (the CODEX_HOME env var, when set, or ~/.codex).
 - Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
+- When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

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

@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+
+const TRUTHY_ENV_RE = /^(1|true|yes|on)$/i;
+const COPIED_SHARED_FILES = ["config.json", "config.toml", "instructions.md"] as const;
+const SYMLINKED_SHARED_FILES = ["auth.json"] as const;
+const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+
+function nonEmpty(value: string | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export async function pathExists(candidate: string): Promise<boolean> {
+  return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+export function resolveSharedCodexHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const fromEnv = nonEmpty(env.CODEX_HOME);
+  return fromEnv ? path.resolve(fromEnv) : path.join(os.homedir(), ".codex");
+}
+
+function isWorktreeMode(env: NodeJS.ProcessEnv): boolean {
+  return TRUTHY_ENV_RE.test(env.PAPERCLIP_IN_WORKTREE ?? "");
+}
+
+export function resolveManagedCodexHomeDir(
+  env: NodeJS.ProcessEnv,
+  companyId?: string,
+): string {
+  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  return companyId
+    ? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "codex-home")
+    : path.resolve(paperclipHome, "instances", instanceId, "codex-home");
+}
+
+async function ensureParentDir(target: string): Promise<void> {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+}
+
+async function ensureSymlink(target: string, source: string): Promise<void> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (!existing) {
+    await ensureParentDir(target);
+    await fs.symlink(source, target);
+    return;
+  }
+
+  if (!existing.isSymbolicLink()) {
+    return;
+  }
+
+  const linkedPath = await fs.readlink(target).catch(() => null);
+  if (!linkedPath) return;
+
+  const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+  if (resolvedLinkedPath === source) return;
+
+  await fs.unlink(target);
+  await fs.symlink(source, target);
+}
+
+async function ensureCopiedFile(target: string, source: string): Promise<void> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (existing) return;
+  await ensureParentDir(target);
+  await fs.copyFile(source, target);
+}
+
+export async function prepareManagedCodexHome(
+  env: NodeJS.ProcessEnv,
+  onLog: AdapterExecutionContext["onLog"],
+  companyId?: string,
+): Promise<string> {
+  const targetHome = resolveManagedCodexHomeDir(env, companyId);
+
+  const sourceHome = resolveSharedCodexHomeDir(env);
+  if (path.resolve(sourceHome) === path.resolve(targetHome)) return targetHome;
+
+  await fs.mkdir(targetHome, { recursive: true });
+
+  for (const name of SYMLINKED_SHARED_FILES) {
+    const source = path.join(sourceHome, name);
+    if (!(await pathExists(source))) continue;
+    await ensureSymlink(path.join(targetHome, name), source);
+  }
+
+  for (const name of COPIED_SHARED_FILES) {
+    const source = path.join(sourceHome, name);
+    if (!(await pathExists(source))) continue;
+    await ensureCopiedFile(path.join(targetHome, name), source);
+  }
+
+  await onLog(
+    "stdout",
+    `[paperclip] Using ${isWorktreeMode(env) ? "worktree-isolated" : "Paperclip-managed"} Codex home "${targetHome}" (seeded from "${sourceHome}").\n`,
+  );
+  return targetHome;
+}

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

@@ -1,8 +1,7 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
 import {
   asString,
   asNumber,
@@ -10,20 +9,23 @@ import {
   asStringArray,
   parseObject,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  readPaperclipRuntimeSkillEntries,
+  resolveCommandForLogs,
+  resolvePaperclipDesiredSkillNames,
   renderTemplate,
+  joinPromptSections,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
+import { pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir, resolveSharedCodexHomeDir } from "./codex-home.js";
+import { resolveCodexDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),         // published: <pkg>/dist/server/ -> <pkg>/skills/
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: src/server/ -> repo root/skills/
-];
 const CODEX_ROLLOUT_NOISE_RE =
   /^\d{4}-\d{2}-\d{2}T[^\s]+\s+ERROR\s+codex_core::rollout::list:\s+state db missing rollout path for thread\s+[a-z0-9-]+$/i;
 
@@ -61,51 +63,157 @@ function resolveCodexBillingType(env: Record<string, string>): "api" | "subscrip
   return hasNonEmptyEnvValue(env, "OPENAI_API_KEY") ? "api" : "subscription";
 }
 
-function codexHomeDir(): string {
-  const fromEnv = process.env.CODEX_HOME;
-  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
-  return path.join(os.homedir(), ".codex");
+function resolveCodexBiller(env: Record<string, string>, billingType: "api" | "subscription"): string {
+  const openAiCompatibleBiller = inferOpenAiCompatibleBiller(env, "openai");
+  if (openAiCompatibleBiller === "openrouter") return "openrouter";
+  return billingType === "subscription" ? "chatgpt" : openAiCompatibleBiller ?? "openai";
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
+async function isLikelyPaperclipRepoRoot(candidate: string): Promise<boolean> {
+  const [hasWorkspace, hasPackageJson, hasServerDir, hasAdapterUtilsDir] = await Promise.all([
+    pathExists(path.join(candidate, "pnpm-workspace.yaml")),
+    pathExists(path.join(candidate, "package.json")),
+    pathExists(path.join(candidate, "server")),
+    pathExists(path.join(candidate, "packages", "adapter-utils")),
+  ]);
+
+  return hasWorkspace && hasPackageJson && hasServerDir && hasAdapterUtilsDir;
+}
+
+async function isLikelyPaperclipRuntimeSkillPath(
+  candidate: string,
+  skillName: string,
+  options: { requireSkillMarkdown?: boolean } = {},
+): Promise<boolean> {
+  if (path.basename(candidate) !== skillName) return false;
+  const skillsRoot = path.dirname(candidate);
+  if (path.basename(skillsRoot) !== "skills") return false;
+  if (options.requireSkillMarkdown !== false && !(await pathExists(path.join(candidate, "SKILL.md")))) {
+    return false;
   }
-  return null;
+
+  let cursor = path.dirname(skillsRoot);
+  for (let depth = 0; depth < 6; depth += 1) {
+    if (await isLikelyPaperclipRepoRoot(cursor)) return true;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+
+  return false;
 }
 
-async function ensureCodexSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+async function pruneBrokenUnavailablePaperclipSkillSymlinks(
+  skillsHome: string,
+  allowedSkillNames: Iterable<string>,
+  onLog: AdapterExecutionContext["onLog"],
+) {
+  const allowed = new Set(Array.from(allowedSkillNames));
+  const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
 
-  const skillsHome = path.join(codexHomeDir(), "skills");
-  await fs.mkdir(skillsHome, { recursive: true });
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
+    if (allowed.has(entry.name) || !entry.isSymbolicLink()) continue;
+
     const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
+    const linkedPath = await fs.readlink(target).catch(() => null);
+    if (!linkedPath) continue;
+
+    const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+    if (await pathExists(resolvedLinkedPath)) continue;
+    if (
+      !(await isLikelyPaperclipRuntimeSkillPath(resolvedLinkedPath, entry.name, {
+        requireSkillMarkdown: false,
+      }))
+    ) {
+      continue;
+    }
+
+    await fs.unlink(target).catch(() => {});
+    await onLog(
+      "stdout",
+      `[paperclip] Removed stale Codex skill "${entry.name}" from ${skillsHome}\n`,
+    );
+  }
+}
+
+function resolveCodexSkillsDir(codexHome: string): string {
+  return path.join(codexHome, "skills");
+}
+
+type EnsureCodexSkillsInjectedOptions = {
+  skillsHome?: string;
+  skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;
+  desiredSkillNames?: string[];
+  linkSkill?: (source: string, target: string) => Promise<void>;
+};
+
+export async function ensureCodexSkillsInjected(
+  onLog: AdapterExecutionContext["onLog"],
+  options: EnsureCodexSkillsInjectedOptions = {},
+) {
+  const allSkillsEntries = options.skillsEntries ?? await readPaperclipRuntimeSkillEntries({}, __moduleDir);
+  const desiredSkillNames =
+    options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.key);
+  const desiredSet = new Set(desiredSkillNames);
+  const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.key));
+  if (skillsEntries.length === 0) return;
+
+  const skillsHome = options.skillsHome ?? resolveCodexSkillsDir(resolveSharedCodexHomeDir());
+  await fs.mkdir(skillsHome, { recursive: true });
+  const linkSkill = options.linkSkill;
+  for (const entry of skillsEntries) {
+    const target = path.join(skillsHome, entry.runtimeName);
 
     try {
-      await fs.symlink(source, target);
+      const existing = await fs.lstat(target).catch(() => null);
+      if (existing?.isSymbolicLink()) {
+        const linkedPath = await fs.readlink(target).catch(() => null);
+        const resolvedLinkedPath = linkedPath
+          ? path.resolve(path.dirname(target), linkedPath)
+          : null;
+        if (
+          resolvedLinkedPath &&
+          resolvedLinkedPath !== entry.source &&
+          (await isLikelyPaperclipRuntimeSkillPath(resolvedLinkedPath, entry.runtimeName))
+        ) {
+          await fs.unlink(target);
+          if (linkSkill) {
+            await linkSkill(entry.source, target);
+          } else {
+            await fs.symlink(entry.source, target);
+          }
+          await onLog(
+            "stdout",
+            `[paperclip] Repaired Codex skill "${entry.runtimeName}" into ${skillsHome}\n`,
+          );
+          continue;
+        }
+      }
+
+      const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
+      if (result === "skipped") continue;
+
       await onLog(
-        "stderr",
-        `[paperclip] Injected Codex skill "${entry.name}" into ${skillsHome}\n`,
+        "stdout",
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Codex skill "${entry.runtimeName}" into ${skillsHome}\n`,
       );
     } catch (err) {
       await onLog(
         "stderr",
-        `[paperclip] Failed to inject Codex skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+        `[paperclip] Failed to inject Codex skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     }
   }
+
+  await pruneBrokenUnavailablePaperclipSkillSymlinks(
+    skillsHome,
+    skillsEntries.map((entry) => entry.runtimeName),
+    onLog,
+  );
 }
 
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -126,24 +234,61 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
   const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceStrategy = asString(workspaceContext.strategy, "");
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const workspaceBranch = asString(workspaceContext.branchName, "");
+  const workspaceWorktreePath = asString(workspaceContext.worktreePath, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
       )
     : [];
+  const runtimeServiceIntents = Array.isArray(context.paperclipRuntimeServiceIntents)
+    ? context.paperclipRuntimeServiceIntents.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimeServices = Array.isArray(context.paperclipRuntimeServices)
+    ? context.paperclipRuntimeServices.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
   const configuredCwd = asString(config.cwd, "");
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
-  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-  await ensureCodexSkillsInjected(onLog);
   const envConfig = parseObject(config.env);
+  const configuredCodexHome =
+    typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
+      ? path.resolve(envConfig.CODEX_HOME.trim())
+      : null;
+  const codexSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
+  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+  const preparedManagedCodexHome =
+    configuredCodexHome ? null : await prepareManagedCodexHome(process.env, onLog, agent.companyId);
+  const defaultCodexHome = resolveManagedCodexHomeDir(process.env, agent.companyId);
+  const effectiveCodexHome = configuredCodexHome ?? preparedManagedCodexHome ?? defaultCodexHome;
+  await fs.mkdir(effectiveCodexHome, { recursive: true });
+  // Inject skills into the same CODEX_HOME that Codex will actually run with
+  // (managed home in the default case, or an explicit override from adapter config).
+  const codexSkillsDir = resolveCodexSkillsDir(effectiveCodexHome);
+  await ensureCodexSkillsInjected(
+    onLog,
+    {
+      skillsHome: codexSkillsDir,
+      skillsEntries: codexSkillEntries,
+      desiredSkillNames,
+    },
+  );
   const hasExplicitApiKey =
     typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
   const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+  env.CODEX_HOME = effectiveCodexHome;
   env.PAPERCLIP_RUN_ID = runId;
   const wakeTaskId =
     (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
@@ -192,6 +337,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceSource) {
     env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
   }
+  if (workspaceStrategy) {
+    env.PAPERCLIP_WORKSPACE_STRATEGY = workspaceStrategy;
+  }
   if (workspaceId) {
     env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   }
@@ -201,18 +349,47 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (workspaceBranch) {
+    env.PAPERCLIP_WORKSPACE_BRANCH = workspaceBranch;
+  }
+  if (workspaceWorktreePath) {
+    env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
+  }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }
+  if (runtimeServiceIntents.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
+  }
+  if (runtimeServices.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICES_JSON = JSON.stringify(runtimeServices);
+  }
+  if (runtimePrimaryUrl) {
+    env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
+  }
   for (const [k, v] of Object.entries(envConfig)) {
     if (typeof v === "string") env[k] = v;
   }
   if (!hasExplicitApiKey && authToken) {
     env.PAPERCLIP_API_KEY = authToken;
   }
-  const billingType = resolveCodexBillingType(env);
-  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  const effectiveEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env }).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  const billingType = resolveCodexBillingType(effectiveEnv);
+  const runtimeEnv = ensurePathInEnv(effectiveEnv);
   await ensureCommandResolvable(command, cwd, runtimeEnv);
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME"],
+    resolvedCommand,
+  });
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 20);
@@ -231,13 +408,14 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (runtimeSessionId && !canResumeSession) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Codex session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
     );
   }
   const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
   const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
   let instructionsPrefix = "";
+  let instructionsChars = 0;
   if (instructionsFilePath) {
     try {
       const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
@@ -245,31 +423,35 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         `${instructionsContents}\n\n` +
         `The above agent instructions were loaded from ${instructionsFilePath}. ` +
         `Resolve any relative file references from ${instructionsDir}.\n\n`;
-      await onLog(
-        "stderr",
-        `[paperclip] Loaded agent instructions file: ${instructionsFilePath}\n`,
-      );
+      instructionsChars = instructionsPrefix.length;
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
       await onLog(
-        "stderr",
+        "stdout",
         `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
       );
     }
   }
+  const repoAgentsNote =
+    "Codex exec automatically applies repo-scoped AGENTS.md instructions from the current workspace; Paperclip does not currently suppress that discovery.";
   const commandNotes = (() => {
-    if (!instructionsFilePath) return [] as string[];
+    if (!instructionsFilePath) {
+      return [repoAgentsNote];
+    }
     if (instructionsPrefix.length > 0) {
       return [
         `Loaded agent instructions from ${instructionsFilePath}`,
         `Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
+        repoAgentsNote,
       ];
     }
     return [
       `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+      repoAgentsNote,
     ];
   })();
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -277,8 +459,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
-  const prompt = `${instructionsPrefix}${renderedPrompt}`;
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["exec", "--json"];
@@ -297,15 +497,16 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (onMeta) {
       await onMeta({
         adapterType: "codex_local",
-        command,
+        command: resolvedCommand,
         cwd,
         commandNotes,
         commandArgs: args.map((value, idx) => {
           if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;
           return value;
         }),
-        env: redactEnvForLogs(env),
+        env: loggedEnv,
         prompt,
+        promptMetrics,
         context,
       });
     }
@@ -316,6 +517,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       stdin: prompt,
       timeoutSec,
       graceSec,
+      onSpawn,
       onLog: async (stream, chunk) => {
         if (stream !== "stderr") {
           await onLog(stream, chunk);
@@ -381,6 +583,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       sessionParams: resolvedSessionParams,
       sessionDisplayId: resolvedSessionId,
       provider: "openai",
+      biller: resolveCodexBiller(effectiveEnv, billingType),
       model,
       billingType,
       costUsd: null,
@@ -401,7 +604,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     isCodexUnknownSessionError(initial.proc.stdout, initial.rawStderr)
   ) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Codex resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
     );
     const retry = await runAttempt(null);

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

@@ -1,6 +1,18 @@
-export { execute } from "./execute.js";
+export { execute, ensureCodexSkillsInjected } from "./execute.js";
+export { listCodexSkills, syncCodexSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
+export {
+  getQuotaWindows,
+  readCodexAuthInfo,
+  readCodexToken,
+  fetchCodexQuota,
+  fetchCodexRpcQuota,
+  mapCodexRpcQuota,
+  secondsToWindowLabel,
+  fetchWithTimeout,
+  codexHomeDir,
+} from "./quota.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
 
 function readNonEmptyString(value: unknown): string | null {

packages/adapters/codex-local/src/server/quota-spawn-error.test.ts

@@ -0,0 +1,85 @@
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { ChildProcess } from "node:child_process";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+const { mockSpawn } = vi.hoisted(() => ({
+  mockSpawn: vi.fn(),
+}));
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const cp = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...cp,
+    spawn: (...args: Parameters<typeof cp.spawn>) => mockSpawn(...args) as ReturnType<typeof cp.spawn>,
+  };
+});
+
+import { getQuotaWindows } from "./quota.js";
+
+function createChildThatErrorsOnMicrotask(err: Error): ChildProcess {
+  const child = new EventEmitter() as ChildProcess;
+  const stream = Object.assign(new EventEmitter(), {
+    setEncoding: () => {},
+  });
+  Object.assign(child, {
+    stdout: stream,
+    stderr: Object.assign(new EventEmitter(), { setEncoding: () => {} }),
+    stdin: { write: vi.fn(), end: vi.fn() },
+    kill: vi.fn(),
+  });
+  queueMicrotask(() => {
+    child.emit("error", err);
+  });
+  return child;
+}
+
+describe("CodexRpcClient spawn failures", () => {
+  let previousCodexHome: string | undefined;
+  let isolatedCodexHome: string | undefined;
+
+  beforeEach(() => {
+    mockSpawn.mockReset();
+    // After the RPC path fails, getQuotaWindows() calls readCodexToken() which
+    // reads $CODEX_HOME/auth.json (default ~/.codex). Point CODEX_HOME at an
+    // empty temp directory so we never hit real host auth or the WHAM network.
+    previousCodexHome = process.env.CODEX_HOME;
+    isolatedCodexHome = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-codex-spawn-test-"));
+    process.env.CODEX_HOME = isolatedCodexHome;
+  });
+
+  afterEach(() => {
+    if (isolatedCodexHome) {
+      try {
+        fs.rmSync(isolatedCodexHome, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+      isolatedCodexHome = undefined;
+    }
+    if (previousCodexHome === undefined) {
+      delete process.env.CODEX_HOME;
+    } else {
+      process.env.CODEX_HOME = previousCodexHome;
+    }
+  });
+
+  it("does not crash the process when codex is missing; getQuotaWindows returns ok: false", async () => {
+    const enoent = Object.assign(new Error("spawn codex ENOENT"), {
+      code: "ENOENT",
+      errno: -2,
+      syscall: "spawn codex",
+      path: "codex",
+    });
+    mockSpawn.mockImplementation(() => createChildThatErrorsOnMicrotask(enoent));
+
+    const result = await getQuotaWindows();
+
+    expect(result.ok).toBe(false);
+    expect(result.windows).toEqual([]);
+    expect(result.error).toContain("Codex app-server");
+    expect(result.error).toContain("spawn codex ENOENT");
+  });
+});

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

@@ -0,0 +1,563 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ProviderQuotaResult, QuotaWindow } from "@paperclipai/adapter-utils";
+
+const CODEX_USAGE_SOURCE_RPC = "codex-rpc";
+const CODEX_USAGE_SOURCE_WHAM = "codex-wham";
+
+export function codexHomeDir(): string {
+  const fromEnv = process.env.CODEX_HOME;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
+  return path.join(os.homedir(), ".codex");
+}
+
+interface CodexLegacyAuthFile {
+  accessToken?: string | null;
+  accountId?: string | null;
+}
+
+interface CodexTokenBlock {
+  id_token?: string | null;
+  access_token?: string | null;
+  refresh_token?: string | null;
+  account_id?: string | null;
+}
+
+interface CodexModernAuthFile {
+  OPENAI_API_KEY?: string | null;
+  tokens?: CodexTokenBlock | null;
+  last_refresh?: string | null;
+}
+
+export interface CodexAuthInfo {
+  accessToken: string;
+  accountId: string | null;
+  refreshToken: string | null;
+  idToken: string | null;
+  email: string | null;
+  planType: string | null;
+  lastRefresh: string | null;
+}
+
+function base64UrlDecode(input: string): string | null {
+  try {
+    let normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+    const remainder = normalized.length % 4;
+    if (remainder > 0) normalized += "=".repeat(4 - remainder);
+    return Buffer.from(normalized, "base64").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function decodeJwtPayload(token: string | null | undefined): Record<string, unknown> | null {
+  if (typeof token !== "string" || token.trim().length === 0) return null;
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  const decoded = base64UrlDecode(parts[1] ?? "");
+  if (!decoded) return null;
+  try {
+    const parsed = JSON.parse(decoded) as unknown;
+    return typeof parsed === "object" && parsed !== null ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function readNestedString(record: Record<string, unknown>, pathSegments: string[]): string | null {
+  let current: unknown = record;
+  for (const segment of pathSegments) {
+    if (typeof current !== "object" || current === null || Array.isArray(current)) return null;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return typeof current === "string" && current.trim().length > 0 ? current.trim() : null;
+}
+
+function parsePlanAndEmailFromToken(idToken: string | null, accessToken: string | null): {
+  email: string | null;
+  planType: string | null;
+} {
+  const payloads = [decodeJwtPayload(idToken), decodeJwtPayload(accessToken)].filter(
+    (value): value is Record<string, unknown> => value != null,
+  );
+  for (const payload of payloads) {
+    const directEmail = typeof payload.email === "string" ? payload.email : null;
+    const authBlock =
+      typeof payload["https://api.openai.com/auth"] === "object" &&
+      payload["https://api.openai.com/auth"] !== null &&
+      !Array.isArray(payload["https://api.openai.com/auth"])
+        ? payload["https://api.openai.com/auth"] as Record<string, unknown>
+        : null;
+    const profileBlock =
+      typeof payload["https://api.openai.com/profile"] === "object" &&
+      payload["https://api.openai.com/profile"] !== null &&
+      !Array.isArray(payload["https://api.openai.com/profile"])
+        ? payload["https://api.openai.com/profile"] as Record<string, unknown>
+        : null;
+    const email =
+      directEmail
+      ?? (typeof profileBlock?.email === "string" ? profileBlock.email : null)
+      ?? (typeof authBlock?.chatgpt_user_email === "string" ? authBlock.chatgpt_user_email : null);
+    const planType =
+      typeof authBlock?.chatgpt_plan_type === "string" ? authBlock.chatgpt_plan_type : null;
+    if (email || planType) return { email: email ?? null, planType };
+  }
+  return { email: null, planType: null };
+}
+
+export async function readCodexAuthInfo(codexHome?: string): Promise<CodexAuthInfo | null> {
+  const authPath = path.join(codexHome ?? codexHomeDir(), "auth.json");
+  let raw: string;
+  try {
+    raw = await fs.readFile(authPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const obj = parsed as Record<string, unknown>;
+  const modern = obj as CodexModernAuthFile;
+  const legacy = obj as CodexLegacyAuthFile;
+
+  const accessToken =
+    legacy.accessToken
+    ?? modern.tokens?.access_token
+    ?? readNestedString(obj, ["tokens", "access_token"]);
+  if (typeof accessToken !== "string" || accessToken.length === 0) return null;
+
+  const accountId =
+    legacy.accountId
+    ?? modern.tokens?.account_id
+    ?? readNestedString(obj, ["tokens", "account_id"]);
+  const refreshToken =
+    modern.tokens?.refresh_token
+    ?? readNestedString(obj, ["tokens", "refresh_token"]);
+  const idToken =
+    modern.tokens?.id_token
+    ?? readNestedString(obj, ["tokens", "id_token"]);
+  const { email, planType } = parsePlanAndEmailFromToken(idToken, accessToken);
+
+  return {
+    accessToken,
+    accountId:
+      typeof accountId === "string" && accountId.trim().length > 0 ? accountId.trim() : null,
+    refreshToken:
+      typeof refreshToken === "string" && refreshToken.trim().length > 0 ? refreshToken.trim() : null,
+    idToken:
+      typeof idToken === "string" && idToken.trim().length > 0 ? idToken.trim() : null,
+    email,
+    planType,
+    lastRefresh:
+      typeof modern.last_refresh === "string" && modern.last_refresh.trim().length > 0
+        ? modern.last_refresh.trim()
+        : null,
+  };
+}
+
+export async function readCodexToken(): Promise<{ token: string; accountId: string | null } | null> {
+  const auth = await readCodexAuthInfo();
+  if (!auth) return null;
+  return { token: auth.accessToken, accountId: auth.accountId };
+}
+
+interface WhamWindow {
+  used_percent?: number | null;
+  limit_window_seconds?: number | null;
+  reset_at?: string | number | null;
+}
+
+interface WhamCredits {
+  balance?: number | null;
+  unlimited?: boolean | null;
+}
+
+interface WhamUsageResponse {
+  plan_type?: string | null;
+  rate_limit?: {
+    primary_window?: WhamWindow | null;
+    secondary_window?: WhamWindow | null;
+  } | null;
+  credits?: WhamCredits | null;
+}
+
+/**
+ * Map a window duration in seconds to a human-readable label.
+ * Falls back to the provided fallback string when seconds is null/undefined.
+ */
+export function secondsToWindowLabel(
+  seconds: number | null | undefined,
+  fallback: string,
+): string {
+  if (seconds == null) return fallback;
+  const hours = seconds / 3600;
+  if (hours < 6) return "5h";
+  if (hours <= 24) return "24h";
+  if (hours <= 168) return "7d";
+  return `${Math.round(hours / 24)}d`;
+}
+
+/** fetch with an abort-based timeout so a hanging provider api doesn't block the response indefinitely */
+export async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  ms = 8000,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function normalizeCodexUsedPercent(rawPct: number | null | undefined): number | null {
+  if (rawPct == null) return null;
+  return Math.min(100, Math.round(rawPct < 1 ? rawPct * 100 : rawPct));
+}
+
+export async function fetchCodexQuota(
+  token: string,
+  accountId: string | null,
+): Promise<QuotaWindow[]> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  };
+  if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+
+  const resp = await fetchWithTimeout("https://chatgpt.com/backend-api/wham/usage", { headers });
+  if (!resp.ok) throw new Error(`chatgpt wham api returned ${resp.status}`);
+  const body = (await resp.json()) as WhamUsageResponse;
+  const windows: QuotaWindow[] = [];
+
+  const rateLimit = body.rate_limit;
+  if (rateLimit?.primary_window != null) {
+    const w = rateLimit.primary_window;
+    windows.push({
+      label: "5h limit",
+      usedPercent: normalizeCodexUsedPercent(w.used_percent),
+      resetsAt:
+        typeof w.reset_at === "number"
+          ? unixSecondsToIso(w.reset_at)
+          : (w.reset_at ?? null),
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (rateLimit?.secondary_window != null) {
+    const w = rateLimit.secondary_window;
+    windows.push({
+      label: "Weekly limit",
+      usedPercent: normalizeCodexUsedPercent(w.used_percent),
+      resetsAt:
+        typeof w.reset_at === "number"
+          ? unixSecondsToIso(w.reset_at)
+          : (w.reset_at ?? null),
+      valueLabel: null,
+      detail: null,
+    });
+  }
+  if (body.credits != null && body.credits.unlimited !== true) {
+    const balance = body.credits.balance;
+    const valueLabel = balance != null ? `$${(balance / 100).toFixed(2)} remaining` : "N/A";
+    windows.push({
+      label: "Credits",
+      usedPercent: null,
+      resetsAt: null,
+      valueLabel,
+      detail: null,
+    });
+  }
+  return windows;
+}
+
+interface CodexRpcWindow {
+  usedPercent?: number | null;
+  windowDurationMins?: number | null;
+  resetsAt?: number | null;
+}
+
+interface CodexRpcCredits {
+  hasCredits?: boolean | null;
+  unlimited?: boolean | null;
+  balance?: string | number | null;
+}
+
+interface CodexRpcLimit {
+  limitId?: string | null;
+  limitName?: string | null;
+  primary?: CodexRpcWindow | null;
+  secondary?: CodexRpcWindow | null;
+  credits?: CodexRpcCredits | null;
+  planType?: string | null;
+}
+
+interface CodexRpcRateLimitsResult {
+  rateLimits?: CodexRpcLimit | null;
+  rateLimitsByLimitId?: Record<string, CodexRpcLimit> | null;
+}
+
+interface CodexRpcAccountResult {
+  account?: {
+    type?: string | null;
+    email?: string | null;
+    planType?: string | null;
+  } | null;
+  requiresOpenaiAuth?: boolean | null;
+}
+
+export interface CodexRpcQuotaSnapshot {
+  windows: QuotaWindow[];
+  email: string | null;
+  planType: string | null;
+}
+
+function unixSecondsToIso(value: number | null | undefined): string | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return new Date(value * 1000).toISOString();
+}
+
+function buildCodexRpcWindow(label: string, window: CodexRpcWindow | null | undefined): QuotaWindow | null {
+  if (!window) return null;
+  return {
+    label,
+    usedPercent: normalizeCodexUsedPercent(window.usedPercent),
+    resetsAt: unixSecondsToIso(window.resetsAt),
+    valueLabel: null,
+    detail: null,
+  };
+}
+
+function parseCreditBalance(value: string | number | null | undefined): string | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `$${value.toFixed(2)} remaining`;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return `$${parsed.toFixed(2)} remaining`;
+    }
+    return value.trim();
+  }
+  return null;
+}
+
+export function mapCodexRpcQuota(result: CodexRpcRateLimitsResult, account?: CodexRpcAccountResult | null): CodexRpcQuotaSnapshot {
+  const windows: QuotaWindow[] = [];
+  const limitOrder = ["codex"];
+  const limitsById = result.rateLimitsByLimitId ?? {};
+  for (const key of Object.keys(limitsById)) {
+    if (!limitOrder.includes(key)) limitOrder.push(key);
+  }
+
+  const rootLimit = result.rateLimits ?? null;
+  const allLimits = new Map<string, CodexRpcLimit>();
+  if (rootLimit?.limitId) allLimits.set(rootLimit.limitId, rootLimit);
+  for (const [key, value] of Object.entries(limitsById)) {
+    allLimits.set(key, value);
+  }
+  if (!allLimits.has("codex") && rootLimit) allLimits.set("codex", rootLimit);
+
+  for (const limitId of limitOrder) {
+    const limit = allLimits.get(limitId);
+    if (!limit) continue;
+    const prefix =
+      limitId === "codex"
+        ? ""
+        : `${limit.limitName ?? limitId} · `;
+    const primary = buildCodexRpcWindow(`${prefix}5h limit`, limit.primary);
+    if (primary) windows.push(primary);
+    const secondary = buildCodexRpcWindow(`${prefix}Weekly limit`, limit.secondary);
+    if (secondary) windows.push(secondary);
+    if (limitId === "codex" && limit.credits && limit.credits.unlimited !== true) {
+      windows.push({
+        label: "Credits",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: parseCreditBalance(limit.credits.balance) ?? "N/A",
+        detail: null,
+      });
+    }
+  }
+
+  return {
+    windows,
+    email:
+      typeof account?.account?.email === "string" && account.account.email.trim().length > 0
+        ? account.account.email.trim()
+        : null,
+    planType:
+      typeof account?.account?.planType === "string" && account.account.planType.trim().length > 0
+        ? account.account.planType.trim()
+        : (typeof rootLimit?.planType === "string" && rootLimit.planType.trim().length > 0 ? rootLimit.planType.trim() : null),
+  };
+}
+
+type PendingRequest = {
+  resolve: (value: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+  timer: NodeJS.Timeout;
+};
+
+class CodexRpcClient {
+  private proc = spawn(
+    "codex",
+    ["-s", "read-only", "-a", "untrusted", "app-server"],
+    { stdio: ["pipe", "pipe", "pipe"], env: process.env },
+  );
+
+  private nextId = 1;
+  private buffer = "";
+  private pending = new Map<number, PendingRequest>();
+  private stderr = "";
+
+  constructor() {
+    this.proc.stdout.setEncoding("utf8");
+    this.proc.stderr.setEncoding("utf8");
+    this.proc.stdout.on("data", (chunk: string) => this.onStdout(chunk));
+    this.proc.stderr.on("data", (chunk: string) => {
+      this.stderr += chunk;
+    });
+    this.proc.on("exit", () => {
+      for (const request of this.pending.values()) {
+        clearTimeout(request.timer);
+        request.reject(new Error(this.stderr.trim() || "codex app-server closed unexpectedly"));
+      }
+      this.pending.clear();
+    });
+    this.proc.on("error", (err: Error) => {
+      for (const request of this.pending.values()) {
+        clearTimeout(request.timer);
+        request.reject(err);
+      }
+      this.pending.clear();
+    });
+  }
+
+  private onStdout(chunk: string) {
+    this.buffer += chunk;
+    while (true) {
+      const newlineIndex = this.buffer.indexOf("\n");
+      if (newlineIndex < 0) break;
+      const line = this.buffer.slice(0, newlineIndex).trim();
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      if (!line) continue;
+      let parsed: Record<string, unknown>;
+      try {
+        parsed = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const id = typeof parsed.id === "number" ? parsed.id : null;
+      if (id == null) continue;
+      const pending = this.pending.get(id);
+      if (!pending) continue;
+      this.pending.delete(id);
+      clearTimeout(pending.timer);
+      pending.resolve(parsed);
+    }
+  }
+
+  private request(method: string, params: Record<string, unknown> = {}, timeoutMs = 6_000): Promise<Record<string, unknown>> {
+    const id = this.nextId++;
+    const payload = JSON.stringify({ id, method, params }) + "\n";
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`codex app-server timed out on ${method}`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.proc.stdin.write(payload);
+    });
+  }
+
+  private notify(method: string, params: Record<string, unknown> = {}) {
+    this.proc.stdin.write(JSON.stringify({ method, params }) + "\n");
+  }
+
+  async initialize() {
+    await this.request("initialize", {
+      clientInfo: {
+        name: "paperclip",
+        version: "0.0.0",
+      },
+    });
+    this.notify("initialized", {});
+  }
+
+  async fetchRateLimits(): Promise<CodexRpcRateLimitsResult> {
+    const message = await this.request("account/rateLimits/read");
+    return (message.result as CodexRpcRateLimitsResult | undefined) ?? {};
+  }
+
+  async fetchAccount(): Promise<CodexRpcAccountResult | null> {
+    try {
+      const message = await this.request("account/read");
+      return (message.result as CodexRpcAccountResult | undefined) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async shutdown() {
+    this.proc.kill("SIGTERM");
+  }
+}
+
+export async function fetchCodexRpcQuota(): Promise<CodexRpcQuotaSnapshot> {
+  const client = new CodexRpcClient();
+  try {
+    await client.initialize();
+    const [limits, account] = await Promise.all([
+      client.fetchRateLimits(),
+      client.fetchAccount(),
+    ]);
+    return mapCodexRpcQuota(limits, account);
+  } finally {
+    await client.shutdown();
+  }
+}
+
+function formatProviderError(source: string, error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `${source}: ${message}`;
+}
+
+export async function getQuotaWindows(): Promise<ProviderQuotaResult> {
+  const errors: string[] = [];
+
+  try {
+    const rpc = await fetchCodexRpcQuota();
+    if (rpc.windows.length > 0) {
+      return { provider: "openai", source: CODEX_USAGE_SOURCE_RPC, ok: true, windows: rpc.windows };
+    }
+  } catch (error) {
+    errors.push(formatProviderError("Codex app-server", error));
+  }
+
+  const auth = await readCodexToken();
+  if (auth) {
+    try {
+      const windows = await fetchCodexQuota(auth.token, auth.accountId);
+      return { provider: "openai", source: CODEX_USAGE_SOURCE_WHAM, ok: true, windows };
+    } catch (error) {
+      errors.push(formatProviderError("ChatGPT WHAM usage", error));
+    }
+  } else {
+    errors.push("no local codex auth token");
+  }
+
+  return {
+    provider: "openai",
+    ok: false,
+    error: errors.join("; "),
+    windows: [],
+  };
+}

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

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  readPaperclipRuntimeSkillEntries,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+async function buildCodexSkillSnapshot(
+  config: Record<string, unknown>,
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
+    key: entry.key,
+    runtimeName: entry.runtimeName,
+    desired: desiredSet.has(entry.key),
+    managed: true,
+    state: desiredSet.has(entry.key) ? "configured" : "available",
+    origin: entry.required ? "paperclip_required" : "company_managed",
+    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
+    readOnly: false,
+    sourcePath: entry.source,
+    targetPath: null,
+    detail: desiredSet.has(entry.key)
+      ? "Will be linked into the effective CODEX_HOME/skills/ directory on the next run."
+      : null,
+    required: Boolean(entry.required),
+    requiredReason: entry.requiredReason ?? null,
+  }));
+  const warnings: string[] = [];
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+      sourcePath: null,
+      targetPath: null,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
+    adapterType: "codex_local",
+    supported: true,
+    mode: "ephemeral",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export async function syncCodexSkills(
+  ctx: AdapterSkillContext,
+  _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export function resolveCodexDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

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

@@ -15,6 +15,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import path from "node:path";
 import { parseCodexJsonl } from "./parse.js";
+import { codexHomeDir, readCodexAuthInfo } from "./quota.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -108,12 +109,23 @@ export async function testEnvironment(
       detail: `Detected in ${source}.`,
     });
   } else {
-    checks.push({
-      code: "codex_openai_api_key_missing",
-      level: "warn",
-      message: "OPENAI_API_KEY is not set. Codex runs may fail until authentication is configured.",
-      hint: "Set OPENAI_API_KEY in adapter env, shell environment, or Codex auth configuration.",
-    });
+    const codexHome = isNonEmpty(env.CODEX_HOME) ? env.CODEX_HOME : undefined;
+    const codexAuth = await readCodexAuthInfo(codexHome).catch(() => null);
+    if (codexAuth) {
+      checks.push({
+        code: "codex_native_auth_present",
+        level: "info",
+        message: "Codex is authenticated via its own auth configuration.",
+        detail: codexAuth.email ? `Logged in as ${codexAuth.email}.` : `Credentials found in ${path.join(codexHome ?? codexHomeDir(), "auth.json")}.`,
+      });
+    } else {
+      checks.push({
+        code: "codex_openai_api_key_missing",
+        level: "warn",
+        message: "OPENAI_API_KEY is not set. Codex runs may fail until authentication is configured.",
+        hint: "Set OPENAI_API_KEY in adapter env, shell environment, or run `codex auth` to log in.",
+      });
+    }
   }
 
   const canRunProbe =

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

@@ -54,11 +54,24 @@ function parseEnvBindings(bindings: unknown): Record<string, unknown> {
   return env;
 }
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   ac.model = v.model || DEFAULT_CODEX_LOCAL_MODEL;
   if (v.thinkingEffort) ac.modelReasoningEffort = v.thinkingEffort;
   ac.timeoutSec = 0;
@@ -76,6 +89,18 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
     typeof v.dangerouslyBypassSandbox === "boolean"
       ? v.dangerouslyBypassSandbox
       : DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX;
+  if (v.workspaceStrategyType === "git_worktree") {
+    ac.workspaceStrategy = {
+      type: "git_worktree",
+      ...(v.workspaceBaseRef ? { baseRef: v.workspaceBaseRef } : {}),
+      ...(v.workspaceBranchTemplate ? { branchTemplate: v.workspaceBranchTemplate } : {}),
+      ...(v.worktreeParentDir ? { worktreeParentDir: v.worktreeParentDir } : {}),
+    };
+  }
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   if (v.command) ac.command = v.command;
   if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
   return ac;

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

@@ -1,4 +1,4 @@
-import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import { type TranscriptEntry } from "@paperclipai/adapter-utils";
 
 function safeJsonParse(text: string): unknown {
   try {
@@ -57,6 +57,7 @@ function parseCommandExecutionItem(
   const command = asString(item.command);
   const status = asString(item.status);
   const exitCode = typeof item.exit_code === "number" && Number.isFinite(item.exit_code) ? item.exit_code : null;
+  const safeCommand = command;
   const output = asString(item.aggregated_output).replace(/\s+$/, "");
 
   if (phase === "started") {
@@ -64,15 +65,16 @@ function parseCommandExecutionItem(
       kind: "tool_call",
       ts,
       name: "command_execution",
+      toolUseId: id || command || "command_execution",
       input: {
         id,
-        command,
+        command: safeCommand,
       },
     }];
   }
 
   const lines: string[] = [];
-  if (command) lines.push(`command: ${command}`);
+  if (safeCommand) lines.push(`command: ${safeCommand}`);
   if (status) lines.push(`status: ${status}`);
   if (exitCode !== null) lines.push(`exit_code: ${exitCode}`);
   if (output) {
@@ -148,6 +150,7 @@ function parseCodexItem(
       kind: "tool_call",
       ts,
       name: asString(item.name, "unknown"),
+      toolUseId: asString(item.id),
       input: item.input ?? {},
     }];
   }
@@ -171,7 +174,11 @@ function parseCodexItem(
   const id = asString(item.id);
   const status = asString(item.status);
   const meta = [id ? `id=${id}` : "", status ? `status=${status}` : ""].filter(Boolean).join(" ");
-  return [{ kind: "system", ts, text: `item ${phase}: ${itemType || "unknown"}${meta ? ` (${meta})` : ""}` }];
+  return [{
+    kind: "system",
+    ts,
+    text: `item ${phase}: ${itemType || "unknown"}${meta ? ` (${meta})` : ""}`,
+  }];
 }
 
 export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[] {

packages/adapters/codex-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/codex-local/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+});

packages/adapters/cursor-local/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @paperclipai/adapter-cursor-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/cursor-local/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-cursor-local",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/cursor-local"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -1,20 +1,25 @@
 import fs from "node:fs/promises";
-import type { Dirent } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
 import {
   asString,
   asNumber,
   asStringArray,
   parseObject,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  readPaperclipRuntimeSkillEntries,
+  resolveCommandForLogs,
+  resolvePaperclipDesiredSkillNames,
+  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
+  joinPromptSections,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { DEFAULT_CURSOR_LOCAL_MODEL } from "../index.js";
@@ -23,10 +28,6 @@ import { normalizeCursorStreamLine } from "../shared/stream.js";
 import { hasCursorTrustBypassArg } from "../shared/trust.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 function firstNonEmptyLine(text: string): string {
   return (
@@ -48,6 +49,17 @@ function resolveCursorBillingType(env: Record<string, string>): "api" | "subscri
     : "subscription";
 }
 
+function resolveCursorBiller(
+  env: Record<string, string>,
+  billingType: "api" | "subscription",
+  provider: string | null,
+): string {
+  const openAiCompatibleBiller = inferOpenAiCompatibleBiller(env, null);
+  if (openAiCompatibleBiller === "openrouter") return "openrouter";
+  if (billingType === "subscription") return "cursor";
+  return provider ?? "cursor";
+}
+
 function resolveProviderFromModel(model: string): string | null {
   const trimmed = model.trim().toLowerCase();
   if (!trimmed) return null;
@@ -82,16 +94,9 @@ function cursorSkillsHome(): string {
   return path.join(os.homedir(), ".cursor", "skills");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
 type EnsureCursorSkillsInjectedOptions = {
   skillsDir?: string | null;
+  skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;
   skillsHome?: string;
   linkSkill?: (source: string, target: string) => Promise<void>;
 };
@@ -100,8 +105,17 @@ export async function ensureCursorSkillsInjected(
   onLog: AdapterExecutionContext["onLog"],
   options: EnsureCursorSkillsInjectedOptions = {},
 ) {
-  const skillsDir = options.skillsDir ?? await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+  const skillsEntries = options.skillsEntries
+    ?? (options.skillsDir
+      ? (await fs.readdir(options.skillsDir, { withFileTypes: true }))
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => ({
+            key: entry.name,
+            runtimeName: entry.name,
+            source: path.join(options.skillsDir!, entry.name),
+          }))
+      : await readPaperclipRuntimeSkillEntries({}, __moduleDir));
+  if (skillsEntries.length === 0) return;
 
   const skillsHome = options.skillsHome ?? cursorSkillsHome();
   try {
@@ -113,43 +127,38 @@ export async function ensureCursorSkillsInjected(
     );
     return;
   }
-
-  let entries: Dirent[];
-  try {
-    entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  } catch (err) {
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    skillsEntries.map((entry) => entry.runtimeName),
+  );
+  for (const skillName of removedSkills) {
     await onLog(
       "stderr",
-      `[paperclip] Failed to read Paperclip skills from ${skillsDir}: ${err instanceof Error ? err.message : String(err)}\n`,
+      `[paperclip] Removed maintainer-only Cursor skill "${skillName}" from ${skillsHome}\n`,
     );
-    return;
   }
-
   const linkSkill = options.linkSkill ?? ((source: string, target: string) => fs.symlink(source, target));
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
-    const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
-
+  for (const entry of skillsEntries) {
+    const target = path.join(skillsHome, entry.runtimeName);
     try {
-      await linkSkill(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
+      if (result === "skipped") continue;
+
       await onLog(
         "stderr",
-        `[paperclip] Injected Cursor skill "${entry.name}" into ${skillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Cursor skill "${entry.key}" into ${skillsHome}\n`,
       );
     } catch (err) {
       await onLog(
         "stderr",
-        `[paperclip] Failed to inject Cursor skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+        `[paperclip] Failed to inject Cursor skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     }
   }
 }
 
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -165,6 +174,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -175,7 +185,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-  await ensureCursorSkillsInjected(onLog);
+  const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);
+  await ensureCursorSkillsInjected(onLog, {
+    skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.key)),
+  });
 
   const envConfig = parseObject(config.env);
   const hasExplicitApiKey =
@@ -238,6 +252,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }
@@ -247,9 +264,20 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (!hasExplicitApiKey && authToken) {
     env.PAPERCLIP_API_KEY = authToken;
   }
-  const billingType = resolveCursorBillingType(env);
-  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  const effectiveEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env }).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  const billingType = resolveCursorBillingType(effectiveEnv);
+  const runtimeEnv = ensurePathInEnv(effectiveEnv);
   await ensureCommandResolvable(command, cwd, runtimeEnv);
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME"],
+    resolvedCommand,
+  });
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 20);
@@ -269,7 +297,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (runtimeSessionId && !canResumeSession) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Cursor session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
     );
   }
@@ -277,6 +305,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
   const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
   let instructionsPrefix = "";
+  let instructionsChars = 0;
   if (instructionsFilePath) {
     try {
       const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
@@ -284,14 +313,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         `${instructionsContents}\n\n` +
         `The above agent instructions were loaded from ${instructionsFilePath}. ` +
         `Resolve any relative file references from ${instructionsDir}.\n\n`;
-      await onLog(
-        "stderr",
-        `[paperclip] Loaded agent instructions file: ${instructionsFilePath}\n`,
-      );
+      instructionsChars = instructionsPrefix.length;
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
       await onLog(
-        "stderr",
+        "stdout",
         `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
       );
     }
@@ -316,7 +342,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     return notes;
   })();
 
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -324,9 +351,29 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
   const paperclipEnvNote = renderPaperclipEnvNote(env);
-  const prompt = `${instructionsPrefix}${paperclipEnvNote}${renderedPrompt}`;
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    paperclipEnvNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    runtimeNoteChars: paperclipEnvNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["-p", "--output-format", "stream-json", "--workspace", cwd];
@@ -343,12 +390,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (onMeta) {
       await onMeta({
         adapterType: "cursor",
-        command,
+        command: resolvedCommand,
         cwd,
         commandNotes,
         commandArgs: args,
-        env: redactEnvForLogs(env),
+        env: loggedEnv,
         prompt,
+        promptMetrics,
         context,
       });
     }
@@ -383,6 +431,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       timeoutSec,
       graceSec,
       stdin: prompt,
+      onSpawn,
       onLog: async (stream, chunk) => {
         if (stream !== "stdout") {
           await onLog(stream, chunk);
@@ -454,6 +503,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       sessionParams: resolvedSessionParams,
       sessionDisplayId: resolvedSessionId,
       provider: providerFromModel,
+      biller: resolveCursorBiller(effectiveEnv, billingType, providerFromModel),
       model,
       billingType,
       costUsd: attempt.parsed.costUsd,
@@ -474,7 +524,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     isCursorUnknownSessionError(initial.proc.stdout, initial.proc.stderr)
   ) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Cursor resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
     );
     const retry = await runAttempt(null);

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

@@ -1,4 +1,5 @@
 export { execute, ensureCursorSkillsInjected } from "./execute.js";
+export { listCursorSkills, syncCursorSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export { parseCursorJsonl, isCursorUnknownSessionError } from "./parse.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";

packages/adapters/cursor-local/src/server/skills.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  buildPersistentSkillSnapshot,
+  ensurePaperclipSkillSymlink,
+  readPaperclipRuntimeSkillEntries,
+  readInstalledSkillTargets,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveCursorSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredHome = asString(env.HOME);
+  const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+  return path.join(home, ".cursor", "skills");
+}
+
+async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const skillsHome = resolveCursorSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  return buildPersistentSkillSnapshot({
+    adapterType: "cursor",
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel: "~/.cursor/skills",
+    missingDetail: "Configured but not currently linked into the Cursor skills home.",
+    externalConflictDetail: "Skill name is occupied by an external installation.",
+    externalDetail: "Installed outside Paperclip management.",
+  });
+}
+
+export async function listCursorSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildCursorSkillSnapshot(ctx.config);
+}
+
+export async function syncCursorSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+  const desiredSet = new Set([
+    ...desiredSkills,
+    ...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
+  ]);
+  const skillsHome = resolveCursorSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.key)) continue;
+    const target = path.join(skillsHome, available.runtimeName);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByRuntimeName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(available.key)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildCursorSkillSnapshot(ctx.config);
+}
+
+export function resolveCursorDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

packages/adapters/cursor-local/src/server/test.ts

@@ -12,6 +12,8 @@ import {
   ensurePathInEnv,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
+import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { DEFAULT_CURSOR_LOCAL_MODEL } from "../index.js";
 import { parseCursorJsonl } from "./parse.js";
@@ -49,6 +51,41 @@ function summarizeProbeDetail(stdout: string, stderr: string, parsedError: strin
   return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
 }
 
+export interface CursorAuthInfo {
+  email: string | null;
+  displayName: string | null;
+  userId: number | null;
+}
+
+export function cursorConfigPath(cursorHome?: string): string {
+  return path.join(cursorHome ?? path.join(os.homedir(), ".cursor"), "cli-config.json");
+}
+
+export async function readCursorAuthInfo(cursorHome?: string): Promise<CursorAuthInfo | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(cursorConfigPath(cursorHome), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const obj = parsed as Record<string, unknown>;
+  const authInfo = obj.authInfo;
+  if (typeof authInfo !== "object" || authInfo === null) return null;
+  const info = authInfo as Record<string, unknown>;
+  const email = typeof info.email === "string" && info.email.trim().length > 0 ? info.email.trim() : null;
+  const displayName = typeof info.displayName === "string" && info.displayName.trim().length > 0 ? info.displayName.trim() : null;
+  const userId = typeof info.userId === "number" ? info.userId : null;
+  if (!email && !displayName && userId == null) return null;
+  return { email, displayName, userId };
+}
+
 const CURSOR_AUTH_REQUIRED_RE =
   /(?:authentication\s+required|not\s+authenticated|not\s+logged\s+in|unauthorized|invalid(?:\s+or\s+missing)?\s+api(?:[_\s-]?key)?|cursor[_\s-]?api[_\s-]?key|run\s+'?agent\s+login'?\s+first|api(?:[_\s-]?key)?(?:\s+is)?\s+required)/i;
 
@@ -109,12 +146,25 @@ export async function testEnvironment(
       detail: `Detected in ${source}.`,
     });
   } else {
-    checks.push({
-      code: "cursor_api_key_missing",
-      level: "warn",
-      message: "CURSOR_API_KEY is not set. Cursor runs may fail until authentication is configured.",
-      hint: "Set CURSOR_API_KEY in adapter env or run `agent login`.",
-    });
+    const cursorHome = isNonEmpty(env.CURSOR_HOME) ? env.CURSOR_HOME : undefined;
+    const cursorAuth = await readCursorAuthInfo(cursorHome).catch(() => null);
+    if (cursorAuth) {
+      checks.push({
+        code: "cursor_native_auth_present",
+        level: "info",
+        message: "Cursor is authenticated via `agent login`.",
+        detail: cursorAuth.email
+          ? `Logged in as ${cursorAuth.email}.`
+          : `Credentials found in ${cursorConfigPath(cursorHome)}.`,
+      });
+    } else {
+      checks.push({
+        code: "cursor_api_key_missing",
+        level: "warn",
+        message: "CURSOR_API_KEY is not set. Cursor runs may fail until authentication is configured.",
+        hint: "Set CURSOR_API_KEY in adapter env or run `agent login`.",
+      });
+    }
   }
 
   const canRunProbe =

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

@@ -62,6 +62,7 @@ export function buildCursorLocalConfig(v: CreateConfigValues): Record<string, un
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   ac.model = v.model || DEFAULT_CURSOR_LOCAL_MODEL;
   const mode = normalizeMode(v.thinkingEffort);
   if (mode) ac.mode = mode;

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

@@ -142,6 +142,12 @@ function parseAssistantMessage(messageRaw: unknown, ts: string): TranscriptEntry
         kind: "tool_call",
         ts,
         name,
+        toolUseId:
+          asString(part.tool_use_id) ||
+          asString(part.toolUseId) ||
+          asString(part.call_id) ||
+          asString(part.id) ||
+          undefined,
         input,
       });
       continue;
@@ -199,6 +205,7 @@ function parseCursorToolCallEvent(event: Record<string, unknown>, ts: string): T
       kind: "tool_call",
       ts,
       name: toolName,
+      toolUseId: callId,
       input,
     }];
   }

packages/adapters/cursor-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",

packages/adapters/gemini-local/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@paperclipai/adapter-gemini-local",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/gemini-local"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/server/index.d.ts",
+        "import": "./dist/server/index.js"
+      },
+      "./ui": {
+        "types": "./dist/ui/index.d.ts",
+        "import": "./dist/ui/index.js"
+      },
+      "./cli": {
+        "types": "./dist/cli/index.d.ts",
+        "import": "./dist/cli/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@paperclipai/adapter-utils": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.7.3"
+  }
+}

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

@@ -0,0 +1,208 @@
+import pc from "picocolors";
+
+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 asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringifyUnknown(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "";
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+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 printTextMessage(prefix: string, colorize: (text: string) => string, messageRaw: unknown): void {
+  if (typeof messageRaw === "string") {
+    const text = messageRaw.trim();
+    if (text) console.log(colorize(`${prefix}: ${text}`));
+    return;
+  }
+
+  const message = asRecord(messageRaw);
+  if (!message) return;
+
+  const directText = asString(message.text).trim();
+  if (directText) console.log(colorize(`${prefix}: ${directText}`));
+
+  const content = Array.isArray(message.content) ? message.content : [];
+  for (const partRaw of content) {
+    const part = asRecord(partRaw);
+    if (!part) continue;
+    const type = asString(part.type).trim();
+
+    if (type === "output_text" || type === "text" || type === "content") {
+      const text = asString(part.text).trim() || asString(part.content).trim();
+      if (text) console.log(colorize(`${prefix}: ${text}`));
+      continue;
+    }
+
+    if (type === "thinking") {
+      const text = asString(part.text).trim();
+      if (text) console.log(pc.gray(`thinking: ${text}`));
+      continue;
+    }
+
+    if (type === "tool_call") {
+      const name = asString(part.name, asString(part.tool, "tool"));
+      console.log(pc.yellow(`tool_call: ${name}`));
+      const input = part.input ?? part.arguments ?? part.args;
+      if (input !== undefined) console.log(pc.gray(stringifyUnknown(input)));
+      continue;
+    }
+
+    if (type === "tool_result" || type === "tool_response") {
+      const isError = part.is_error === true || asString(part.status).toLowerCase() === "error";
+      const contentText =
+        asString(part.output) ||
+        asString(part.text) ||
+        asString(part.result) ||
+        stringifyUnknown(part.output ?? part.result ?? part.text ?? part.response);
+      console.log((isError ? pc.red : pc.cyan)(`tool_result${isError ? " (error)" : ""}`));
+      if (contentText) console.log((isError ? pc.red : pc.gray)(contentText));
+    }
+  }
+}
+
+function printUsage(parsed: Record<string, unknown>) {
+  const usage = asRecord(parsed.usage) ?? asRecord(parsed.usageMetadata);
+  const usageMetadata = asRecord(usage?.usageMetadata);
+  const source = usageMetadata ?? usage ?? {};
+  const input = asNumber(source.input_tokens, asNumber(source.inputTokens, asNumber(source.promptTokenCount)));
+  const output = asNumber(source.output_tokens, asNumber(source.outputTokens, asNumber(source.candidatesTokenCount)));
+  const cached = asNumber(
+    source.cached_input_tokens,
+    asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount)),
+  );
+  const cost = asNumber(parsed.total_cost_usd, asNumber(parsed.cost_usd, asNumber(parsed.cost)));
+  console.log(pc.blue(`tokens: in=${input} out=${output} cached=${cached} cost=$${cost.toFixed(6)}`));
+}
+
+export function printGeminiStreamEvent(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 = asString(parsed.type);
+
+  if (type === "system") {
+    const subtype = asString(parsed.subtype);
+    if (subtype === "init") {
+      const sessionId =
+        asString(parsed.session_id) ||
+        asString(parsed.sessionId) ||
+        asString(parsed.sessionID) ||
+        asString(parsed.checkpoint_id);
+      const model = asString(parsed.model);
+      const details = [sessionId ? `session: ${sessionId}` : "", model ? `model: ${model}` : ""]
+        .filter(Boolean)
+        .join(", ");
+      console.log(pc.blue(`Gemini init${details ? ` (${details})` : ""}`));
+      return;
+    }
+    if (subtype === "error") {
+      const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
+      if (text) console.log(pc.red(`error: ${text}`));
+      return;
+    }
+    console.log(pc.blue(`system: ${subtype || "event"}`));
+    return;
+  }
+
+  if (type === "assistant") {
+    printTextMessage("assistant", pc.green, parsed.message);
+    return;
+  }
+
+  if (type === "user") {
+    printTextMessage("user", pc.gray, parsed.message);
+    return;
+  }
+
+  if (type === "thinking") {
+    const text = asString(parsed.text).trim() || asString(asRecord(parsed.delta)?.text).trim();
+    if (text) console.log(pc.gray(`thinking: ${text}`));
+    return;
+  }
+
+  if (type === "tool_call") {
+    const subtype = asString(parsed.subtype).trim().toLowerCase();
+    const toolCall = asRecord(parsed.tool_call ?? parsed.toolCall);
+    const [toolName] = toolCall ? Object.keys(toolCall) : [];
+    if (!toolCall || !toolName) {
+      console.log(pc.yellow(`tool_call${subtype ? `: ${subtype}` : ""}`));
+      return;
+    }
+    const payload = asRecord(toolCall[toolName]) ?? {};
+    if (subtype === "started" || subtype === "start") {
+      console.log(pc.yellow(`tool_call: ${toolName}`));
+      console.log(pc.gray(stringifyUnknown(payload.args ?? payload.input ?? payload.arguments ?? payload)));
+      return;
+    }
+    if (subtype === "completed" || subtype === "complete" || subtype === "finished") {
+      const isError =
+        parsed.is_error === true ||
+        payload.is_error === true ||
+        payload.error !== undefined ||
+        asString(payload.status).toLowerCase() === "error";
+      console.log((isError ? pc.red : pc.cyan)(`tool_result${isError ? " (error)" : ""}`));
+      console.log((isError ? pc.red : pc.gray)(stringifyUnknown(payload.result ?? payload.output ?? payload.error)));
+      return;
+    }
+    console.log(pc.yellow(`tool_call: ${toolName}${subtype ? ` (${subtype})` : ""}`));
+    return;
+  }
+
+  if (type === "result") {
+    printUsage(parsed);
+    const subtype = asString(parsed.subtype, "result");
+    const isError = parsed.is_error === true;
+    if (subtype || isError) {
+      console.log((isError ? pc.red : pc.blue)(`result: subtype=${subtype} is_error=${isError ? "true" : "false"}`));
+    }
+    return;
+  }
+
+  if (type === "error") {
+    const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
+    if (text) console.log(pc.red(`error: ${text}`));
+    return;
+  }
+
+  console.log(line);
+}

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

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

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

@@ -0,0 +1,47 @@
+export const type = "gemini_local";
+export const label = "Gemini CLI (local)";
+export const DEFAULT_GEMINI_LOCAL_MODEL = "auto";
+
+export const models = [
+  { id: DEFAULT_GEMINI_LOCAL_MODEL, label: "Auto" },
+  { id: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
+  { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
+  { id: "gemini-2.5-flash-lite", label: "Gemini 2.5 Flash Lite" },
+  { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
+  { id: "gemini-2.0-flash-lite", label: "Gemini 2.0 Flash Lite" },
+];
+
+export const agentConfigurationDoc = `# gemini_local agent configuration
+
+Adapter: gemini_local
+
+Use when:
+- You want Paperclip to run the Gemini CLI locally on the host machine
+- You want Gemini chat sessions resumed across heartbeats with --resume
+- You want Paperclip skills injected locally without polluting the global environment
+
+Don't use when:
+- You need webhook-style external invocation (use http or openclaw_gateway)
+- You only need a one-shot script without an AI coding agent loop (use process)
+- Gemini CLI is not installed on the machine that runs Paperclip
+
+Core fields:
+- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
+- instructionsFilePath (string, optional): absolute path to a markdown instructions file prepended to the run prompt
+- promptTemplate (string, optional): run prompt template
+- model (string, optional): Gemini model id. Defaults to auto.
+- sandbox (boolean, optional): run in sandbox mode (default: false, passes --sandbox=none)
+- command (string, optional): defaults to "gemini"
+- extraArgs (string[], optional): additional CLI args
+- env (object, optional): KEY=VALUE environment variables
+
+Operational fields:
+- timeoutSec (number, optional): run timeout in seconds
+- graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- Runs use positional prompt arguments, not stdin.
+- Sessions resume with --resume when stored session cwd matches the current cwd.
+- Paperclip auto-injects local skills into \`~/.gemini/skills/\` via symlinks, so the CLI can discover both credentials and skills in their natural location.
+- Authentication can use GEMINI_API_KEY / GOOGLE_API_KEY or local Gemini CLI login.
+`;

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

@@ -0,0 +1,468 @@
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import {
+  asBoolean,
+  asNumber,
+  asString,
+  asStringArray,
+  buildPaperclipEnv,
+  buildInvocationEnvForLogs,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
+  joinPromptSections,
+  ensurePathInEnv,
+  readPaperclipRuntimeSkillEntries,
+  resolveCommandForLogs,
+  resolvePaperclipDesiredSkillNames,
+  removeMaintainerOnlySkillSymlinks,
+  parseObject,
+  renderTemplate,
+  runChildProcess,
+} from "@paperclipai/adapter-utils/server-utils";
+import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
+import {
+  describeGeminiFailure,
+  detectGeminiAuthRequired,
+  isGeminiTurnLimitResult,
+  isGeminiUnknownSessionError,
+  parseGeminiJsonl,
+} from "./parse.js";
+import { firstNonEmptyLine } from "./utils.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
+  const raw = env[key];
+  return typeof raw === "string" && raw.trim().length > 0;
+}
+
+function resolveGeminiBillingType(env: Record<string, string>): "api" | "subscription" {
+  return hasNonEmptyEnvValue(env, "GEMINI_API_KEY") || hasNonEmptyEnvValue(env, "GOOGLE_API_KEY")
+    ? "api"
+    : "subscription";
+}
+
+function renderPaperclipEnvNote(env: Record<string, string>): string {
+  const paperclipKeys = Object.keys(env)
+    .filter((key) => key.startsWith("PAPERCLIP_"))
+    .sort();
+  if (paperclipKeys.length === 0) return "";
+  return [
+    "Paperclip runtime note:",
+    `The following PAPERCLIP_* environment variables are available in this run: ${paperclipKeys.join(", ")}`,
+    "Do not assume these variables are missing without checking your shell environment.",
+    "",
+    "",
+  ].join("\n");
+}
+
+function renderApiAccessNote(env: Record<string, string>): string {
+  if (!hasNonEmptyEnvValue(env, "PAPERCLIP_API_URL") || !hasNonEmptyEnvValue(env, "PAPERCLIP_API_KEY")) return "";
+  return [
+    "Paperclip API access note:",
+    "Use run_shell_command with curl to make Paperclip API requests.",
+    "GET example:",
+    `  run_shell_command({ command: "curl -s -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" \\"$PAPERCLIP_API_URL/api/agents/me\\"" })`,
+    "POST/PATCH example:",
+    `  run_shell_command({ command: "curl -s -X POST -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" -H 'Content-Type: application/json' -H \\"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\\" -d '{...}' \\"$PAPERCLIP_API_URL/api/issues/{id}/checkout\\"" })`,
+    "",
+    "",
+  ].join("\n");
+}
+
+function geminiSkillsHome(): string {
+  return path.join(os.homedir(), ".gemini", "skills");
+}
+
+/**
+ * Inject Paperclip skills directly into `~/.gemini/skills/` via symlinks.
+ * This avoids needing GEMINI_CLI_HOME overrides, so the CLI naturally finds
+ * both its auth credentials and the injected skills in the real home directory.
+ */
+async function ensureGeminiSkillsInjected(
+  onLog: AdapterExecutionContext["onLog"],
+  skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
+  desiredSkillNames?: string[],
+): Promise<void> {
+  const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
+  const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
+  if (selectedEntries.length === 0) return;
+
+  const skillsHome = geminiSkillsHome();
+  try {
+    await fs.mkdir(skillsHome, { recursive: true });
+  } catch (err) {
+    await onLog(
+      "stderr",
+      `[paperclip] Failed to prepare Gemini skills directory ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return;
+  }
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    selectedEntries.map((entry) => entry.runtimeName),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Gemini skill "${skillName}" from ${skillsHome}\n`,
+    );
+  }
+
+  for (const entry of selectedEntries) {
+    const target = path.join(skillsHome, entry.runtimeName);
+
+    try {
+      const result = await ensurePaperclipSkillSymlink(entry.source, target);
+      if (result === "skipped") continue;
+      await onLog(
+        "stderr",
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Linked"} Gemini skill: ${entry.key}\n`,
+      );
+    } catch (err) {
+      await onLog(
+        "stderr",
+        `[paperclip] Failed to link Gemini skill "${entry.key}": ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
+  }
+}
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
+
+  const promptTemplate = asString(
+    config.promptTemplate,
+    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  );
+  const command = asString(config.command, "gemini");
+  const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
+  const sandbox = asBoolean(config.sandbox, false);
+
+  const workspaceContext = parseObject(context.paperclipWorkspace);
+  const workspaceCwd = asString(workspaceContext.cwd, "");
+  const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceId = asString(workspaceContext.workspaceId, "");
+  const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+  const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
+  const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+    ? context.paperclipWorkspaces.filter(
+      (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+    )
+    : [];
+  const configuredCwd = asString(config.cwd, "");
+  const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+  const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+  const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+  const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredGeminiSkillNames = resolvePaperclipDesiredSkillNames(config, geminiSkillEntries);
+  await ensureGeminiSkillsInjected(onLog, geminiSkillEntries, desiredGeminiSkillNames);
+
+  const envConfig = parseObject(config.env);
+  const hasExplicitApiKey =
+    typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
+  const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+  env.PAPERCLIP_RUN_ID = runId;
+  const wakeTaskId =
+    (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
+    (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
+    null;
+  const wakeReason =
+    typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
+      ? context.wakeReason.trim()
+      : null;
+  const wakeCommentId =
+    (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
+    (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
+    null;
+  const approvalId =
+    typeof context.approvalId === "string" && context.approvalId.trim().length > 0
+      ? context.approvalId.trim()
+      : null;
+  const approvalStatus =
+    typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
+      ? context.approvalStatus.trim()
+      : null;
+  const linkedIssueIds = Array.isArray(context.issueIds)
+    ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+    : [];
+  if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+  if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
+  if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+  if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
+  if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+  if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+  if (effectiveWorkspaceCwd) env.PAPERCLIP_WORKSPACE_CWD = effectiveWorkspaceCwd;
+  if (workspaceSource) env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
+  if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
+  if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
+  if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
+  if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
+
+  for (const [key, value] of Object.entries(envConfig)) {
+    if (typeof value === "string") env[key] = value;
+  }
+  if (!hasExplicitApiKey && authToken) {
+    env.PAPERCLIP_API_KEY = authToken;
+  }
+  const effectiveEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env }).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  const billingType = resolveGeminiBillingType(effectiveEnv);
+  const runtimeEnv = ensurePathInEnv(effectiveEnv);
+  await ensureCommandResolvable(command, cwd, runtimeEnv);
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME"],
+    resolvedCommand,
+  });
+
+  const timeoutSec = asNumber(config.timeoutSec, 0);
+  const graceSec = asNumber(config.graceSec, 20);
+  const extraArgs = (() => {
+    const fromExtraArgs = asStringArray(config.extraArgs);
+    if (fromExtraArgs.length > 0) return fromExtraArgs;
+    return asStringArray(config.args);
+  })();
+
+  const runtimeSessionParams = parseObject(runtime.sessionParams);
+  const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+  const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+  const canResumeSession =
+    runtimeSessionId.length > 0 &&
+    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
+  const sessionId = canResumeSession ? runtimeSessionId : null;
+  if (runtimeSessionId && !canResumeSession) {
+    await onLog(
+      "stdout",
+      `[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
+    );
+  }
+
+  const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+  const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
+  let instructionsPrefix = "";
+  if (instructionsFilePath) {
+    try {
+      const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
+      instructionsPrefix =
+        `${instructionsContents}\n\n` +
+        `The above agent instructions were loaded from ${instructionsFilePath}. ` +
+        `Resolve any relative file references from ${instructionsDir}.\n\n`;
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      await onLog(
+        "stdout",
+        `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
+      );
+    }
+  }
+  const commandNotes = (() => {
+    const notes: string[] = ["Prompt is passed to Gemini via --prompt for non-interactive execution."];
+    notes.push("Added --approval-mode yolo for unattended execution.");
+    if (!instructionsFilePath) return notes;
+    if (instructionsPrefix.length > 0) {
+      notes.push(
+        `Loaded agent instructions from ${instructionsFilePath}`,
+        `Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
+      );
+      return notes;
+    }
+    notes.push(
+      `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+    );
+    return notes;
+  })();
+
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
+    agentId: agent.id,
+    companyId: agent.companyId,
+    runId,
+    company: { id: agent.companyId },
+    agent,
+    run: { id: runId, source: "on_demand" },
+    context,
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const paperclipEnvNote = renderPaperclipEnvNote(env);
+  const apiAccessNote = renderApiAccessNote(env);
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    paperclipEnvNote,
+    apiAccessNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars: instructionsPrefix.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
+
+  const buildArgs = (resumeSessionId: string | null) => {
+    const args = ["--output-format", "stream-json"];
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
+    if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
+    args.push("--approval-mode", "yolo");
+    if (sandbox) {
+      args.push("--sandbox");
+    } else {
+      args.push("--sandbox=none");
+    }
+    if (extraArgs.length > 0) args.push(...extraArgs);
+    args.push("--prompt", prompt);
+    return args;
+  };
+
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildArgs(resumeSessionId);
+    if (onMeta) {
+      await onMeta({
+        adapterType: "gemini_local",
+        command: resolvedCommand,
+        cwd,
+        commandNotes,
+        commandArgs: args.map((value, index) => (
+          index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
+        )),
+        env: loggedEnv,
+        prompt,
+        promptMetrics,
+        context,
+      });
+    }
+
+    const proc = await runChildProcess(runId, command, args, {
+      cwd,
+      env,
+      timeoutSec,
+      graceSec,
+      onSpawn,
+      onLog,
+    });
+    return {
+      proc,
+      parsed: parseGeminiJsonl(proc.stdout),
+    };
+  };
+
+  const toResult = (
+    attempt: {
+      proc: {
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        stdout: string;
+        stderr: string;
+      };
+      parsed: ReturnType<typeof parseGeminiJsonl>;
+    },
+    clearSessionOnMissingSession = false,
+    isRetry = false,
+  ): AdapterExecutionResult => {
+    const authMeta = detectGeminiAuthRequired({
+      parsed: attempt.parsed.resultEvent,
+      stdout: attempt.proc.stdout,
+      stderr: attempt.proc.stderr,
+    });
+
+    if (attempt.proc.timedOut) {
+      return {
+        exitCode: attempt.proc.exitCode,
+        signal: attempt.proc.signal,
+        timedOut: true,
+        errorMessage: `Timed out after ${timeoutSec}s`,
+        errorCode: authMeta.requiresAuth ? "gemini_auth_required" : null,
+        clearSession: clearSessionOnMissingSession,
+      };
+    }
+
+    const clearSessionForTurnLimit = isGeminiTurnLimitResult(attempt.parsed.resultEvent, attempt.proc.exitCode);
+
+    // On retry, don't fall back to old session ID — the old session was stale
+    const canFallbackToRuntimeSession = !isRetry;
+    const resolvedSessionId = attempt.parsed.sessionId
+      ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
+    const resolvedSessionParams = resolvedSessionId
+      ? ({
+        sessionId: resolvedSessionId,
+        cwd,
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
+        ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
+      } as Record<string, unknown>)
+      : null;
+    const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
+    const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+    const structuredFailure = attempt.parsed.resultEvent
+      ? describeGeminiFailure(attempt.parsed.resultEvent)
+      : null;
+    const fallbackErrorMessage =
+      parsedError ||
+      structuredFailure ||
+      stderrLine ||
+      `Gemini exited with code ${attempt.proc.exitCode ?? -1}`;
+
+    return {
+      exitCode: attempt.proc.exitCode,
+      signal: attempt.proc.signal,
+      timedOut: false,
+      errorMessage: (attempt.proc.exitCode ?? 0) === 0 ? null : fallbackErrorMessage,
+      errorCode: (attempt.proc.exitCode ?? 0) !== 0 && authMeta.requiresAuth ? "gemini_auth_required" : null,
+      usage: attempt.parsed.usage,
+      sessionId: resolvedSessionId,
+      sessionParams: resolvedSessionParams,
+      sessionDisplayId: resolvedSessionId,
+      provider: "google",
+      biller: "google",
+      model,
+      billingType,
+      costUsd: attempt.parsed.costUsd,
+      resultJson: attempt.parsed.resultEvent ?? {
+        stdout: attempt.proc.stdout,
+        stderr: attempt.proc.stderr,
+      },
+      summary: attempt.parsed.summary,
+      question: attempt.parsed.question,
+      clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
+    };
+  };
+
+  const initial = await runAttempt(sessionId);
+  if (
+    sessionId &&
+    !initial.proc.timedOut &&
+    (initial.proc.exitCode ?? 0) !== 0 &&
+    isGeminiUnknownSessionError(initial.proc.stdout, initial.proc.stderr)
+  ) {
+    await onLog(
+      "stdout",
+      `[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+    );
+    const retry = await runAttempt(null);
+    return toResult(retry, true, true);
+  }
+
+  return toResult(initial);
+}

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

@@ -0,0 +1,71 @@
+export { execute } from "./execute.js";
+export { listGeminiSkills, syncGeminiSkills } from "./skills.js";
+export { testEnvironment } from "./test.js";
+export {
+  parseGeminiJsonl,
+  isGeminiUnknownSessionError,
+  describeGeminiFailure,
+  detectGeminiAuthRequired,
+  isGeminiTurnLimitResult,
+} from "./parse.js";
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+  deserialize(raw: unknown) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+    const record = raw as Record<string, unknown>;
+    const sessionId =
+      readNonEmptyString(record.sessionId) ??
+      readNonEmptyString(record.session_id) ??
+      readNonEmptyString(record.sessionID);
+    if (!sessionId) return null;
+    const cwd =
+      readNonEmptyString(record.cwd) ??
+      readNonEmptyString(record.workdir) ??
+      readNonEmptyString(record.folder);
+    const workspaceId = readNonEmptyString(record.workspaceId) ?? readNonEmptyString(record.workspace_id);
+    const repoUrl = readNonEmptyString(record.repoUrl) ?? readNonEmptyString(record.repo_url);
+    const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(repoUrl ? { repoUrl } : {}),
+      ...(repoRef ? { repoRef } : {}),
+    };
+  },
+  serialize(params: Record<string, unknown> | null) {
+    if (!params) return null;
+    const sessionId =
+      readNonEmptyString(params.sessionId) ??
+      readNonEmptyString(params.session_id) ??
+      readNonEmptyString(params.sessionID);
+    if (!sessionId) return null;
+    const cwd =
+      readNonEmptyString(params.cwd) ??
+      readNonEmptyString(params.workdir) ??
+      readNonEmptyString(params.folder);
+    const workspaceId = readNonEmptyString(params.workspaceId) ?? readNonEmptyString(params.workspace_id);
+    const repoUrl = readNonEmptyString(params.repoUrl) ?? readNonEmptyString(params.repo_url);
+    const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(repoUrl ? { repoUrl } : {}),
+      ...(repoRef ? { repoRef } : {}),
+    };
+  },
+  getDisplayId(params: Record<string, unknown> | null) {
+    if (!params) return null;
+    return (
+      readNonEmptyString(params.sessionId) ??
+      readNonEmptyString(params.session_id) ??
+      readNonEmptyString(params.sessionID)
+    );
+  },
+};

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

@@ -0,0 +1,281 @@
+import { asNumber, asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";
+
+function collectMessageText(message: unknown): string[] {
+  if (typeof message === "string") {
+    const trimmed = message.trim();
+    return trimmed ? [trimmed] : [];
+  }
+
+  const record = parseObject(message);
+  const direct = asString(record.text, "").trim();
+  const lines: string[] = direct ? [direct] : [];
+  const content = Array.isArray(record.content) ? record.content : [];
+
+  for (const partRaw of content) {
+    const part = parseObject(partRaw);
+    const type = asString(part.type, "").trim();
+    if (type === "output_text" || type === "text" || type === "content") {
+      const text = asString(part.text, "").trim() || asString(part.content, "").trim();
+      if (text) lines.push(text);
+    }
+  }
+
+  return lines;
+}
+
+function readSessionId(event: Record<string, unknown>): string | null {
+  return (
+    asString(event.session_id, "").trim() ||
+    asString(event.sessionId, "").trim() ||
+    asString(event.sessionID, "").trim() ||
+    asString(event.checkpoint_id, "").trim() ||
+    asString(event.thread_id, "").trim() ||
+    null
+  );
+}
+
+function asErrorText(value: unknown): string {
+  if (typeof value === "string") return value;
+  const rec = parseObject(value);
+  const message =
+    asString(rec.message, "") ||
+    asString(rec.error, "") ||
+    asString(rec.code, "") ||
+    asString(rec.detail, "");
+  if (message) return message;
+  try {
+    return JSON.stringify(rec);
+  } catch {
+    return "";
+  }
+}
+
+function accumulateUsage(
+  target: { inputTokens: number; cachedInputTokens: number; outputTokens: number },
+  usageRaw: unknown,
+) {
+  const usage = parseObject(usageRaw);
+  const usageMetadata = parseObject(usage.usageMetadata);
+  const source = Object.keys(usageMetadata).length > 0 ? usageMetadata : usage;
+
+  target.inputTokens += asNumber(
+    source.input_tokens,
+    asNumber(source.inputTokens, asNumber(source.promptTokenCount, 0)),
+  );
+  target.cachedInputTokens += asNumber(
+    source.cached_input_tokens,
+    asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount, 0)),
+  );
+  target.outputTokens += asNumber(
+    source.output_tokens,
+    asNumber(source.outputTokens, asNumber(source.candidatesTokenCount, 0)),
+  );
+}
+
+export function parseGeminiJsonl(stdout: string) {
+  let sessionId: string | null = null;
+  const messages: string[] = [];
+  let errorMessage: string | null = null;
+  let costUsd: number | null = null;
+  let resultEvent: Record<string, unknown> | null = null;
+  let question: { prompt: string; choices: Array<{ key: string; label: string; description?: string }> } | null = null;
+  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 foundSessionId = readSessionId(event);
+    if (foundSessionId) sessionId = foundSessionId;
+
+    const type = asString(event.type, "").trim();
+
+    if (type === "assistant") {
+      messages.push(...collectMessageText(event.message));
+      const messageObj = parseObject(event.message);
+      const content = Array.isArray(messageObj.content) ? messageObj.content : [];
+      for (const partRaw of content) {
+        const part = parseObject(partRaw);
+        if (asString(part.type, "").trim() === "question") {
+          question = {
+            prompt: asString(part.prompt, "").trim(),
+            choices: (Array.isArray(part.choices) ? part.choices : []).map((choiceRaw) => {
+              const choice = parseObject(choiceRaw);
+              return {
+                key: asString(choice.key, "").trim(),
+                label: asString(choice.label, "").trim(),
+                description: asString(choice.description, "").trim() || undefined,
+              };
+            }),
+          };
+          break; // only one question per message
+        }
+      }
+      continue;
+    }
+
+    if (type === "result") {
+      resultEvent = event;
+      accumulateUsage(usage, event.usage ?? event.usageMetadata);
+      const resultText =
+        asString(event.result, "").trim() ||
+        asString(event.text, "").trim() ||
+        asString(event.response, "").trim();
+      if (resultText && messages.length === 0) messages.push(resultText);
+      costUsd = asNumber(event.total_cost_usd, asNumber(event.cost_usd, asNumber(event.cost, costUsd ?? 0))) || costUsd;
+      const isError = event.is_error === true || asString(event.subtype, "").toLowerCase() === "error";
+      if (isError) {
+        const text = asErrorText(event.error ?? event.message ?? event.result).trim();
+        if (text) errorMessage = text;
+      }
+      continue;
+    }
+
+    if (type === "error") {
+      const text = asErrorText(event.error ?? event.message ?? event.detail).trim();
+      if (text) errorMessage = text;
+      continue;
+    }
+
+    if (type === "system") {
+      const subtype = asString(event.subtype, "").trim().toLowerCase();
+      if (subtype === "error") {
+        const text = asErrorText(event.error ?? event.message ?? event.detail).trim();
+        if (text) errorMessage = text;
+      }
+      continue;
+    }
+
+    if (type === "text") {
+      const part = parseObject(event.part);
+      const text = asString(part.text, "").trim();
+      if (text) messages.push(text);
+      continue;
+    }
+
+    if (type === "step_finish" || event.usage || event.usageMetadata) {
+      accumulateUsage(usage, event.usage ?? event.usageMetadata);
+      costUsd = asNumber(event.total_cost_usd, asNumber(event.cost_usd, asNumber(event.cost, costUsd ?? 0))) || costUsd;
+      continue;
+    }
+  }
+
+  return {
+    sessionId,
+    summary: messages.join("\n\n").trim(),
+    usage,
+    costUsd,
+    errorMessage,
+    resultEvent,
+    question,
+  };
+}
+
+export function isGeminiUnknownSessionError(stdout: string, stderr: string): boolean {
+  const haystack = `${stdout}\n${stderr}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+
+  return /unknown\s+session|session\s+.*\s+not\s+found|resume\s+.*\s+not\s+found|checkpoint\s+.*\s+not\s+found|cannot\s+resume|failed\s+to\s+resume/i.test(
+    haystack,
+  );
+}
+
+function extractGeminiErrorMessages(parsed: Record<string, unknown>): string[] {
+  const messages: string[] = [];
+  const errorMsg = asString(parsed.error, "").trim();
+  if (errorMsg) messages.push(errorMsg);
+
+  const raw = Array.isArray(parsed.errors) ? parsed.errors : [];
+  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 describeGeminiFailure(parsed: Record<string, unknown>): string | null {
+  const status = asString(parsed.status, "");
+  const errors = extractGeminiErrorMessages(parsed);
+
+  const detail = errors[0] ?? "";
+  const parts = ["Gemini run failed"];
+  if (status) parts.push(`status=${status}`);
+  if (detail) parts.push(detail);
+  return parts.length > 1 ? parts.join(": ") : null;
+}
+
+const GEMINI_AUTH_REQUIRED_RE = /(?:not\s+authenticated|please\s+authenticate|api[_ ]?key\s+(?:required|missing|invalid)|authentication\s+required|unauthorized|invalid\s+credentials|not\s+logged\s+in|login\s+required|run\s+`?gemini\s+auth(?:\s+login)?`?\s+first)/i;
+const GEMINI_QUOTA_EXHAUSTED_RE =
+  /(?:resource_exhausted|quota|rate[-\s]?limit|too many requests|\b429\b|billing details)/i;
+
+export function detectGeminiAuthRequired(input: {
+  parsed: Record<string, unknown> | null;
+  stdout: string;
+  stderr: string;
+}): { requiresAuth: boolean } {
+  const errors = extractGeminiErrorMessages(input.parsed ?? {});
+  const messages = [...errors, input.stdout, input.stderr]
+    .join("\n")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const requiresAuth = messages.some((line) => GEMINI_AUTH_REQUIRED_RE.test(line));
+  return { requiresAuth };
+}
+
+export function detectGeminiQuotaExhausted(input: {
+  parsed: Record<string, unknown> | null;
+  stdout: string;
+  stderr: string;
+}): { exhausted: boolean } {
+  const errors = extractGeminiErrorMessages(input.parsed ?? {});
+  const messages = [...errors, input.stdout, input.stderr]
+    .join("\n")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const exhausted = messages.some((line) => GEMINI_QUOTA_EXHAUSTED_RE.test(line));
+  return { exhausted };
+}
+
+export function isGeminiTurnLimitResult(
+  parsed: Record<string, unknown> | null | undefined,
+  exitCode?: number | null,
+): boolean {
+  if (exitCode === 53) return true;
+  if (!parsed) return false;
+
+  const status = asString(parsed.status, "").trim().toLowerCase();
+  if (status === "turn_limit" || status === "max_turns") return true;
+
+  const error = asString(parsed.error, "").trim();
+  return /turn\s*limit|max(?:imum)?\s+turns?/i.test(error);
+}

packages/adapters/gemini-local/src/server/skills.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  buildPersistentSkillSnapshot,
+  ensurePaperclipSkillSymlink,
+  readPaperclipRuntimeSkillEntries,
+  readInstalledSkillTargets,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveGeminiSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredHome = asString(env.HOME);
+  const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+  return path.join(home, ".gemini", "skills");
+}
+
+async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const skillsHome = resolveGeminiSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  return buildPersistentSkillSnapshot({
+    adapterType: "gemini_local",
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel: "~/.gemini/skills",
+    missingDetail: "Configured but not currently linked into the Gemini skills home.",
+    externalConflictDetail: "Skill name is occupied by an external installation.",
+    externalDetail: "Installed outside Paperclip management.",
+  });
+}
+
+export async function listGeminiSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildGeminiSkillSnapshot(ctx.config);
+}
+
+export async function syncGeminiSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+  const desiredSet = new Set([
+    ...desiredSkills,
+    ...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
+  ]);
+  const skillsHome = resolveGeminiSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.key)) continue;
+    const target = path.join(skillsHome, available.runtimeName);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByRuntimeName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(available.key)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildGeminiSkillSnapshot(ctx.config);
+}
+
+export function resolveGeminiDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

packages/adapters/gemini-local/src/server/test.ts

@@ -0,0 +1,239 @@
+import path from "node:path";
+import type {
+  AdapterEnvironmentCheck,
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+  asBoolean,
+  asNumber,
+  asString,
+  asStringArray,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePathInEnv,
+  parseObject,
+  runChildProcess,
+} from "@paperclipai/adapter-utils/server-utils";
+import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
+import { detectGeminiAuthRequired, detectGeminiQuotaExhausted, parseGeminiJsonl } from "./parse.js";
+import { firstNonEmptyLine } from "./utils.js";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+  if (checks.some((check) => check.level === "error")) return "fail";
+  if (checks.some((check) => check.level === "warn")) return "warn";
+  return "pass";
+}
+
+function isNonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function commandLooksLike(command: string, expected: string): boolean {
+  const base = path.basename(command).toLowerCase();
+  return base === expected || base === `${expected}.cmd` || base === `${expected}.exe`;
+}
+
+function summarizeProbeDetail(stdout: string, stderr: string, parsedError: string | null): string | null {
+  const raw = parsedError?.trim() || firstNonEmptyLine(stderr) || firstNonEmptyLine(stdout);
+  if (!raw) return null;
+  const clean = raw.replace(/\s+/g, " ").trim();
+  const max = 240;
+  return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+
+export async function testEnvironment(
+  ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+  const checks: AdapterEnvironmentCheck[] = [];
+  const config = parseObject(ctx.config);
+  const command = asString(config.command, "gemini");
+  const cwd = asString(config.cwd, process.cwd());
+
+  try {
+    await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+    checks.push({
+      code: "gemini_cwd_valid",
+      level: "info",
+      message: `Working directory is valid: ${cwd}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "gemini_cwd_invalid",
+      level: "error",
+      message: err instanceof Error ? err.message : "Invalid working directory",
+      detail: cwd,
+    });
+  }
+
+  const envConfig = parseObject(config.env);
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(envConfig)) {
+    if (typeof value === "string") env[key] = value;
+  }
+  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  try {
+    await ensureCommandResolvable(command, cwd, runtimeEnv);
+    checks.push({
+      code: "gemini_command_resolvable",
+      level: "info",
+      message: `Command is executable: ${command}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "gemini_command_unresolvable",
+      level: "error",
+      message: err instanceof Error ? err.message : "Command is not executable",
+      detail: command,
+    });
+  }
+
+  const configGeminiApiKey = env.GEMINI_API_KEY;
+  const hostGeminiApiKey = process.env.GEMINI_API_KEY;
+  const configGoogleApiKey = env.GOOGLE_API_KEY;
+  const hostGoogleApiKey = process.env.GOOGLE_API_KEY;
+  const hasGca = env.GOOGLE_GENAI_USE_GCA === "true" || process.env.GOOGLE_GENAI_USE_GCA === "true";
+  if (
+    isNonEmpty(configGeminiApiKey) ||
+    isNonEmpty(hostGeminiApiKey) ||
+    isNonEmpty(configGoogleApiKey) ||
+    isNonEmpty(hostGoogleApiKey) ||
+    hasGca
+  ) {
+    const source = hasGca
+      ? "Google account login (GCA)"
+      : isNonEmpty(configGeminiApiKey) || isNonEmpty(configGoogleApiKey)
+        ? "adapter config env"
+        : "server environment";
+    checks.push({
+      code: "gemini_api_key_present",
+      level: "info",
+      message: "Gemini API credentials are set for CLI authentication.",
+      detail: `Detected in ${source}.`,
+    });
+  } else {
+    checks.push({
+      code: "gemini_api_key_missing",
+      level: "info",
+      message: "No explicit API key detected. Gemini CLI may still authenticate via `gemini auth login` (OAuth).",
+      hint: "If the hello probe fails with an auth error, set GEMINI_API_KEY or GOOGLE_API_KEY in adapter env, or run `gemini auth login`.",
+    });
+  }
+
+  const canRunProbe =
+    checks.every((check) => check.code !== "gemini_cwd_invalid" && check.code !== "gemini_command_unresolvable");
+  if (canRunProbe) {
+    if (!commandLooksLike(command, "gemini")) {
+      checks.push({
+        code: "gemini_hello_probe_skipped_custom_command",
+        level: "info",
+        message: "Skipped hello probe because command is not `gemini`.",
+        detail: command,
+        hint: "Use the `gemini` CLI command to run the automatic installation and auth probe.",
+      });
+    } else {
+      const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
+      const approvalMode = asString(config.approvalMode, asBoolean(config.yolo, false) ? "yolo" : "default");
+      const sandbox = asBoolean(config.sandbox, false);
+      const helloProbeTimeoutSec = Math.max(1, asNumber(config.helloProbeTimeoutSec, 10));
+      const extraArgs = (() => {
+        const fromExtraArgs = asStringArray(config.extraArgs);
+        if (fromExtraArgs.length > 0) return fromExtraArgs;
+        return asStringArray(config.args);
+      })();
+
+      const args = ["--output-format", "stream-json", "--prompt", "Respond with hello."];
+      if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
+      if (approvalMode !== "default") args.push("--approval-mode", approvalMode);
+      if (sandbox) {
+        args.push("--sandbox");
+      } else {
+        args.push("--sandbox=none");
+      }
+      if (extraArgs.length > 0) args.push(...extraArgs);
+
+      const probe = await runChildProcess(
+        `gemini-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+        command,
+        args,
+        {
+          cwd,
+          env,
+          timeoutSec: helloProbeTimeoutSec,
+          graceSec: 5,
+          onLog: async () => { },
+        },
+      );
+      const parsed = parseGeminiJsonl(probe.stdout);
+      const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
+      const authMeta = detectGeminiAuthRequired({
+        parsed: parsed.resultEvent,
+        stdout: probe.stdout,
+        stderr: probe.stderr,
+      });
+      const quotaMeta = detectGeminiQuotaExhausted({
+        parsed: parsed.resultEvent,
+        stdout: probe.stdout,
+        stderr: probe.stderr,
+      });
+
+      if (quotaMeta.exhausted) {
+        checks.push({
+          code: "gemini_hello_probe_quota_exhausted",
+          level: "warn",
+          message: probe.timedOut
+            ? "Gemini CLI is retrying after quota exhaustion."
+            : "Gemini CLI authentication is configured, but the current account or API key is over quota.",
+          ...(detail ? { detail } : {}),
+          hint: "The configured Gemini account or API key is over quota. Check ai.google.dev usage/billing, then retry the probe.",
+        });
+      } else if (probe.timedOut) {
+        checks.push({
+          code: "gemini_hello_probe_timed_out",
+          level: "warn",
+          message: "Gemini hello probe timed out.",
+          hint: "Retry the probe. If this persists, verify Gemini can run `Respond with hello.` from this directory manually.",
+        });
+      } else if ((probe.exitCode ?? 1) === 0) {
+        const summary = parsed.summary.trim();
+        const hasHello = /\bhello\b/i.test(summary);
+        checks.push({
+          code: hasHello ? "gemini_hello_probe_passed" : "gemini_hello_probe_unexpected_output",
+          level: hasHello ? "info" : "warn",
+          message: hasHello
+            ? "Gemini hello probe succeeded."
+            : "Gemini probe ran but did not return `hello` as expected.",
+          ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+          ...(hasHello
+            ? {}
+            : {
+              hint: "Try `gemini --output-format json \"Respond with hello.\"` manually to inspect full output.",
+            }),
+        });
+      } else if (authMeta.requiresAuth) {
+        checks.push({
+          code: "gemini_hello_probe_auth_required",
+          level: "warn",
+          message: "Gemini CLI is installed, but authentication is not ready.",
+          ...(detail ? { detail } : {}),
+          hint: "Run `gemini auth` or configure GEMINI_API_KEY / GOOGLE_API_KEY in adapter env/shell, then retry the probe.",
+        });
+      } else {
+        checks.push({
+          code: "gemini_hello_probe_failed",
+          level: "error",
+          message: "Gemini hello probe failed.",
+          ...(detail ? { detail } : {}),
+          hint: "Run `gemini --output-format json \"Respond with hello.\"` manually in this working directory to debug.",
+        });
+      }
+    }
+  }
+
+  return {
+    adapterType: ctx.adapterType,
+    status: summarizeStatus(checks),
+    checks,
+    testedAt: new Date().toISOString(),
+  };
+}

packages/adapters/gemini-local/src/server/utils.ts

@@ -0,0 +1,8 @@
+export function firstNonEmptyLine(text: string): string {
+    return (
+        text
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find(Boolean) ?? ""
+    );
+}

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

@@ -0,0 +1,76 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
+
+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;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+  if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+  const env: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(bindings)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (typeof raw === "string") {
+      env[key] = { type: "plain", value: raw };
+      continue;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+    const rec = raw as Record<string, unknown>;
+    if (rec.type === "plain" && typeof rec.value === "string") {
+      env[key] = { type: "plain", value: rec.value };
+      continue;
+    }
+    if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+      env[key] = {
+        type: "secret_ref",
+        secretId: rec.secretId,
+        ...(typeof rec.version === "number" || rec.version === "latest"
+          ? { version: rec.version }
+          : {}),
+      };
+    }
+  }
+  return env;
+}
+
+export function buildGeminiLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.cwd) ac.cwd = v.cwd;
+  if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
+  if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
+  ac.model = v.model || DEFAULT_GEMINI_LOCAL_MODEL;
+  ac.timeoutSec = 0;
+  ac.graceSec = 15;
+  const env = parseEnvBindings(v.envBindings);
+  const legacy = parseEnvVars(v.envVars);
+  for (const [key, value] of Object.entries(legacy)) {
+    if (!Object.prototype.hasOwnProperty.call(env, key)) {
+      env[key] = { type: "plain", value };
+    }
+  }
+  if (Object.keys(env).length > 0) ac.env = env;
+  ac.sandbox = !v.dangerouslyBypassSandbox;
+
+  if (v.command) ac.command = v.command;
+  if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+  return ac;
+}

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

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

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

@@ -0,0 +1,274 @@
+import type { TranscriptEntry } from "@paperclipai/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>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringifyUnknown(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "";
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+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 collectTextEntries(messageRaw: unknown, ts: string, kind: "assistant" | "user"): TranscriptEntry[] {
+  if (typeof messageRaw === "string") {
+    const text = messageRaw.trim();
+    return text ? [{ kind, ts, text }] : [];
+  }
+
+  const message = asRecord(messageRaw);
+  if (!message) return [];
+
+  const entries: TranscriptEntry[] = [];
+  const directText = asString(message.text).trim();
+  if (directText) entries.push({ kind, ts, text: directText });
+
+  const content = Array.isArray(message.content) ? message.content : [];
+  for (const partRaw of content) {
+    const part = asRecord(partRaw);
+    if (!part) continue;
+    const type = asString(part.type).trim();
+    if (type !== "output_text" && type !== "text" && type !== "content") continue;
+    const text = asString(part.text).trim() || asString(part.content).trim();
+    if (text) entries.push({ kind, ts, text });
+  }
+
+  return entries;
+}
+
+function parseAssistantMessage(messageRaw: unknown, ts: string): TranscriptEntry[] {
+  if (typeof messageRaw === "string") {
+    const text = messageRaw.trim();
+    return text ? [{ kind: "assistant", ts, text }] : [];
+  }
+
+  const message = asRecord(messageRaw);
+  if (!message) return [];
+
+  const entries: TranscriptEntry[] = [];
+  const directText = asString(message.text).trim();
+  if (directText) entries.push({ kind: "assistant", ts, text: directText });
+
+  const content = Array.isArray(message.content) ? message.content : [];
+  for (const partRaw of content) {
+    const part = asRecord(partRaw);
+    if (!part) continue;
+    const type = asString(part.type).trim();
+
+    if (type === "output_text" || type === "text" || type === "content") {
+      const text = asString(part.text).trim() || asString(part.content).trim();
+      if (text) entries.push({ kind: "assistant", ts, text });
+      continue;
+    }
+
+    if (type === "thinking") {
+      const text = asString(part.text).trim();
+      if (text) entries.push({ kind: "thinking", ts, text });
+      continue;
+    }
+
+    if (type === "tool_call") {
+      const name = asString(part.name, asString(part.tool, "tool"));
+      entries.push({
+        kind: "tool_call",
+        ts,
+        name,
+        input: part.input ?? part.arguments ?? part.args ?? {},
+      });
+      continue;
+    }
+
+    if (type === "tool_result" || type === "tool_response") {
+      const toolUseId =
+        asString(part.tool_use_id) ||
+        asString(part.toolUseId) ||
+        asString(part.call_id) ||
+        asString(part.id) ||
+        "tool_result";
+      const contentText =
+        asString(part.output) ||
+        asString(part.text) ||
+        asString(part.result) ||
+        stringifyUnknown(part.output ?? part.result ?? part.text ?? part.response);
+      const isError = part.is_error === true || asString(part.status).toLowerCase() === "error";
+      entries.push({
+        kind: "tool_result",
+        ts,
+        toolUseId,
+        content: contentText,
+        isError,
+      });
+    }
+  }
+
+  return entries;
+}
+
+function parseTopLevelToolEvent(parsed: Record<string, unknown>, ts: string): TranscriptEntry[] {
+  const subtype = asString(parsed.subtype).trim().toLowerCase();
+  const callId = asString(parsed.call_id, asString(parsed.callId, asString(parsed.id, "tool_call")));
+  const toolCall = asRecord(parsed.tool_call ?? parsed.toolCall);
+  if (!toolCall) {
+    return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}` }];
+  }
+
+  const [toolName] = Object.keys(toolCall);
+  if (!toolName) {
+    return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}` }];
+  }
+  const payload = asRecord(toolCall[toolName]) ?? {};
+
+  if (subtype === "started" || subtype === "start") {
+    return [{
+      kind: "tool_call",
+      ts,
+      name: toolName,
+      input: payload.args ?? payload.input ?? payload.arguments ?? payload,
+    }];
+  }
+
+  if (subtype === "completed" || subtype === "complete" || subtype === "finished") {
+    const result = payload.result ?? payload.output ?? payload.error;
+    const isError =
+      parsed.is_error === true ||
+      payload.is_error === true ||
+      payload.error !== undefined ||
+      asString(payload.status).toLowerCase() === "error";
+    return [{
+      kind: "tool_result",
+      ts,
+      toolUseId: callId,
+      content: result !== undefined ? stringifyUnknown(result) : `${toolName} completed`,
+      isError,
+    }];
+  }
+
+  return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}: ${toolName}` }];
+}
+
+function readSessionId(parsed: Record<string, unknown>): string {
+  return (
+    asString(parsed.session_id) ||
+    asString(parsed.sessionId) ||
+    asString(parsed.sessionID) ||
+    asString(parsed.checkpoint_id) ||
+    asString(parsed.thread_id)
+  );
+}
+
+function readUsage(parsed: Record<string, unknown>) {
+  const usage = asRecord(parsed.usage) ?? asRecord(parsed.usageMetadata);
+  const usageMetadata = asRecord(usage?.usageMetadata);
+  const source = usageMetadata ?? usage ?? {};
+  return {
+    inputTokens: asNumber(source.input_tokens, asNumber(source.inputTokens, asNumber(source.promptTokenCount))),
+    outputTokens: asNumber(source.output_tokens, asNumber(source.outputTokens, asNumber(source.candidatesTokenCount))),
+    cachedTokens: asNumber(
+      source.cached_input_tokens,
+      asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount)),
+    ),
+  };
+}
+
+export function parseGeminiStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const parsed = asRecord(safeJsonParse(line));
+  if (!parsed) {
+    return [{ kind: "stdout", ts, text: line }];
+  }
+
+  const type = asString(parsed.type);
+
+  if (type === "system") {
+    const subtype = asString(parsed.subtype);
+    if (subtype === "init") {
+      const sessionId = readSessionId(parsed);
+      return [{ kind: "init", ts, model: asString(parsed.model, "gemini"), sessionId }];
+    }
+    if (subtype === "error") {
+      const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
+      return [{ kind: "stderr", ts, text: text || "error" }];
+    }
+    return [{ kind: "system", ts, text: `system: ${subtype || "event"}` }];
+  }
+
+  if (type === "assistant") {
+    return parseAssistantMessage(parsed.message, ts);
+  }
+
+  if (type === "user") {
+    return collectTextEntries(parsed.message, ts, "user");
+  }
+
+  if (type === "thinking") {
+    const text = asString(parsed.text).trim() || asString(asRecord(parsed.delta)?.text).trim();
+    return text ? [{ kind: "thinking", ts, text }] : [];
+  }
+
+  if (type === "tool_call") {
+    return parseTopLevelToolEvent(parsed, ts);
+  }
+
+  if (type === "result") {
+    const usage = readUsage(parsed);
+    const errors = parsed.is_error === true
+      ? [errorText(parsed.error ?? parsed.message ?? parsed.result)].filter(Boolean)
+      : [];
+    return [{
+      kind: "result",
+      ts,
+      text: asString(parsed.result) || asString(parsed.text) || asString(parsed.response),
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cachedTokens: usage.cachedTokens,
+      costUsd: asNumber(parsed.total_cost_usd, asNumber(parsed.cost_usd, asNumber(parsed.cost))),
+      subtype: asString(parsed.subtype, "result"),
+      isError: parsed.is_error === true,
+      errors,
+    }];
+  }
+
+  if (type === "error") {
+    const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
+    return [{ kind: "stderr", ts, text: text || "error" }];
+  }
+
+  return [{ kind: "stdout", ts, text: line }];
+}

packages/adapters/gemini-local/tsconfig.json

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

packages/adapters/openclaw-gateway/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @paperclipai/adapter-openclaw-gateway
+
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0

packages/adapters/openclaw-gateway/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-openclaw-gateway",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/openclaw-gateway"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/openclaw-gateway/src/index.ts

@@ -31,6 +31,7 @@ Gateway connect identity fields:
 
 Request behavior fields:
 - payloadTemplate (object, optional): additional fields merged into gateway agent params
+- workspaceRuntime (object, optional): reserved workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats
 - timeoutSec (number, optional): adapter timeout in seconds (default 120)
 - waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
 - autoPairOnFirstConnect (boolean, optional): on first "pairing required", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)
@@ -39,4 +40,15 @@ Request behavior fields:
 Session routing fields:
 - sessionKeyStrategy (string, optional): issue (default), fixed, or run
 - sessionKey (string, optional): fixed session key when strategy=fixed (default paperclip)
+
+Standard outbound payload additions:
+- paperclip (object): standardized Paperclip context added to every gateway agent request
+- paperclip.workspace (object, optional): resolved execution workspace for this run
+- paperclip.workspaces (array, optional): additional workspace hints Paperclip exposed to the run
+- paperclip.workspaceRuntime (object, optional): reserved workspace runtime metadata when explicitly supplied outside normal heartbeat execution
+
+Standard result metadata supported:
+- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports
+- meta.previewUrl (string, optional): shorthand single preview URL
+- meta.previewUrls (string[], optional): shorthand multiple preview URLs
 `;

packages/adapters/openclaw-gateway/src/server/execute.ts

@@ -1,4 +1,8 @@
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import type {
+  AdapterExecutionContext,
+  AdapterExecutionResult,
+  AdapterRuntimeServiceReport,
+} from "@paperclipai/adapter-utils";
 import { asNumber, asString, buildPaperclipEnv, parseObject } from "@paperclipai/adapter-utils/server-utils";
 import crypto, { randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
@@ -411,6 +415,58 @@ function appendWakeText(baseText: string, wakeText: string): string {
   return trimmedBase.length > 0 ? `${trimmedBase}\n\n${wakeText}` : wakeText;
 }
 
+function buildStandardPaperclipPayload(
+  ctx: AdapterExecutionContext,
+  wakePayload: WakePayload,
+  paperclipEnv: Record<string, string>,
+  payloadTemplate: Record<string, unknown>,
+): Record<string, unknown> {
+  const templatePaperclip = parseObject(payloadTemplate.paperclip);
+  const workspace = asRecord(ctx.context.paperclipWorkspace);
+  const workspaces = Array.isArray(ctx.context.paperclipWorkspaces)
+    ? ctx.context.paperclipWorkspaces.filter((entry): entry is Record<string, unknown> => Boolean(asRecord(entry)))
+    : [];
+  const configuredWorkspaceRuntime = parseObject(ctx.config.workspaceRuntime);
+  const runtimeServiceIntents = Array.isArray(ctx.context.paperclipRuntimeServiceIntents)
+    ? ctx.context.paperclipRuntimeServiceIntents.filter(
+        (entry): entry is Record<string, unknown> => Boolean(asRecord(entry)),
+      )
+    : [];
+
+  const standardPaperclip: Record<string, unknown> = {
+    runId: ctx.runId,
+    companyId: ctx.agent.companyId,
+    agentId: ctx.agent.id,
+    agentName: ctx.agent.name,
+    taskId: wakePayload.taskId,
+    issueId: wakePayload.issueId,
+    issueIds: wakePayload.issueIds,
+    wakeReason: wakePayload.wakeReason,
+    wakeCommentId: wakePayload.wakeCommentId,
+    approvalId: wakePayload.approvalId,
+    approvalStatus: wakePayload.approvalStatus,
+    apiUrl: paperclipEnv.PAPERCLIP_API_URL ?? null,
+  };
+
+  if (workspace) {
+    standardPaperclip.workspace = workspace;
+  }
+  if (workspaces.length > 0) {
+    standardPaperclip.workspaces = workspaces;
+  }
+  if (runtimeServiceIntents.length > 0 || Object.keys(configuredWorkspaceRuntime).length > 0) {
+    standardPaperclip.workspaceRuntime = {
+      ...configuredWorkspaceRuntime,
+      ...(runtimeServiceIntents.length > 0 ? { services: runtimeServiceIntents } : {}),
+    };
+  }
+
+  return {
+    ...templatePaperclip,
+    ...standardPaperclip,
+  };
+}
+
 function normalizeUrl(input: string): URL | null {
   try {
     return new URL(input);
@@ -549,6 +605,7 @@ class GatewayWsClient {
       this.resolveChallenge = resolve;
       this.rejectChallenge = reject;
     });
+    this.challengePromise.catch(() => {});
   }
 
   async connect(
@@ -835,6 +892,91 @@ function parseUsage(value: unknown): AdapterExecutionResult["usage"] | undefined
   };
 }
 
+function extractRuntimeServicesFromMeta(meta: Record<string, unknown> | null): AdapterRuntimeServiceReport[] {
+  if (!meta) return [];
+  const reports: AdapterRuntimeServiceReport[] = [];
+
+  const runtimeServices = Array.isArray(meta.runtimeServices)
+    ? meta.runtimeServices.filter((entry): entry is Record<string, unknown> => Boolean(asRecord(entry)))
+    : [];
+  for (const entry of runtimeServices) {
+    const serviceName = nonEmpty(entry.serviceName) ?? nonEmpty(entry.name);
+    if (!serviceName) continue;
+    const rawStatus = nonEmpty(entry.status)?.toLowerCase();
+    const status =
+      rawStatus === "starting" || rawStatus === "running" || rawStatus === "stopped" || rawStatus === "failed"
+        ? rawStatus
+        : "running";
+    const rawLifecycle = nonEmpty(entry.lifecycle)?.toLowerCase();
+    const lifecycle = rawLifecycle === "shared" ? "shared" : "ephemeral";
+    const rawScopeType = nonEmpty(entry.scopeType)?.toLowerCase();
+    const scopeType =
+      rawScopeType === "project_workspace" ||
+      rawScopeType === "execution_workspace" ||
+      rawScopeType === "agent"
+        ? rawScopeType
+        : "run";
+    const rawHealth = nonEmpty(entry.healthStatus)?.toLowerCase();
+    const healthStatus =
+      rawHealth === "healthy" || rawHealth === "unhealthy" || rawHealth === "unknown"
+        ? rawHealth
+        : status === "running"
+          ? "healthy"
+          : "unknown";
+
+    reports.push({
+      id: nonEmpty(entry.id),
+      projectId: nonEmpty(entry.projectId),
+      projectWorkspaceId: nonEmpty(entry.projectWorkspaceId),
+      issueId: nonEmpty(entry.issueId),
+      scopeType,
+      scopeId: nonEmpty(entry.scopeId),
+      serviceName,
+      status,
+      lifecycle,
+      reuseKey: nonEmpty(entry.reuseKey),
+      command: nonEmpty(entry.command),
+      cwd: nonEmpty(entry.cwd),
+      port: parseOptionalPositiveInteger(entry.port),
+      url: nonEmpty(entry.url),
+      providerRef: nonEmpty(entry.providerRef) ?? nonEmpty(entry.previewId),
+      ownerAgentId: nonEmpty(entry.ownerAgentId),
+      stopPolicy: asRecord(entry.stopPolicy),
+      healthStatus,
+    });
+  }
+
+  const previewUrl = nonEmpty(meta.previewUrl);
+  if (previewUrl) {
+    reports.push({
+      serviceName: "preview",
+      status: "running",
+      lifecycle: "ephemeral",
+      scopeType: "run",
+      url: previewUrl,
+      providerRef: nonEmpty(meta.previewId) ?? previewUrl,
+      healthStatus: "healthy",
+    });
+  }
+
+  const previewUrls = Array.isArray(meta.previewUrls)
+    ? meta.previewUrls.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+  previewUrls.forEach((url, index) => {
+    reports.push({
+      serviceName: index === 0 ? "preview" : `preview-${index + 1}`,
+      status: "running",
+      lifecycle: "ephemeral",
+      scopeType: "run",
+      url,
+      providerRef: `${url}#${index}`,
+      healthStatus: "healthy",
+    });
+  });
+
+  return reports;
+}
+
 function extractResultText(value: unknown): string | null {
   const record = asRecord(value);
   if (!record) return null;
@@ -924,6 +1066,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const templateMessage = nonEmpty(payloadTemplate.message) ?? nonEmpty(payloadTemplate.text);
   const message = templateMessage ? appendWakeText(templateMessage, wakeText) : wakeText;
+  const paperclipPayload = buildStandardPaperclipPayload(ctx, wakePayload, paperclipEnv, payloadTemplate);
 
   const agentParams: Record<string, unknown> = {
     ...payloadTemplate,
@@ -1188,12 +1331,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         null;
       const summary = summaryFromEvents || summaryFromPayload || null;
 
-      const meta = asRecord(asRecord(acceptedPayload?.result)?.meta) ?? asRecord(acceptedPayload?.meta);
-      const agentMeta = asRecord(meta?.agentMeta);
-      const usage = parseUsage(agentMeta?.usage ?? meta?.usage);
-      const provider = nonEmpty(agentMeta?.provider) ?? nonEmpty(meta?.provider) ?? "openclaw";
-      const model = nonEmpty(agentMeta?.model) ?? nonEmpty(meta?.model) ?? null;
-      const costUsd = asNumber(agentMeta?.costUsd ?? meta?.costUsd, 0);
+      const acceptedResult = asRecord(acceptedPayload?.result);
+      const latestPayload = asRecord(latestResultPayload);
+      const latestResult = asRecord(latestPayload?.result);
+      const acceptedMeta = asRecord(acceptedResult?.meta) ?? asRecord(acceptedPayload?.meta);
+      const latestMeta = asRecord(latestResult?.meta) ?? asRecord(latestPayload?.meta);
+      const mergedMeta = {
+        ...(acceptedMeta ?? {}),
+        ...(latestMeta ?? {}),
+      };
+      const agentMeta =
+        asRecord(mergedMeta.agentMeta) ??
+        asRecord(acceptedMeta?.agentMeta) ??
+        asRecord(latestMeta?.agentMeta);
+      const usage = parseUsage(agentMeta?.usage ?? mergedMeta.usage);
+      const runtimeServices = extractRuntimeServicesFromMeta(agentMeta ?? mergedMeta);
+      const provider = nonEmpty(agentMeta?.provider) ?? nonEmpty(mergedMeta.provider) ?? "openclaw";
+      const model = nonEmpty(agentMeta?.model) ?? nonEmpty(mergedMeta.model) ?? null;
+      const costUsd = asNumber(agentMeta?.costUsd ?? mergedMeta.costUsd, 0);
 
       await ctx.onLog(
         "stdout",
@@ -1209,6 +1364,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         ...(usage ? { usage } : {}),
         ...(costUsd > 0 ? { costUsd } : {}),
         resultJson: asRecord(latestResultPayload),
+        ...(runtimeServices.length > 0 ? { runtimeServices } : {}),
         ...(summary ? { summary } : {}),
       };
     } catch (err) {

packages/adapters/openclaw-gateway/src/ui/build-config.ts

@@ -1,5 +1,17 @@
 import type { CreateConfigValues } from "@paperclipai/adapter-utils";
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.url) ac.url = v.url;
@@ -8,5 +20,11 @@ export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string
   ac.sessionKeyStrategy = "issue";
   ac.role = "operator";
   ac.scopes = ["operator.admin"];
+  const payloadTemplate = parseJsonObject(v.payloadTemplateJson ?? "");
+  if (payloadTemplate) ac.payloadTemplate = payloadTemplate;
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   return ac;
 }

packages/adapters/openclaw-gateway/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/opencode-local/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @paperclipai/adapter-opencode-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/opencode-local/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-opencode-local",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/opencode-local"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -30,6 +30,7 @@ Core fields:
 - instructionsFilePath (string, optional): absolute path to a markdown instructions file prepended to the run prompt
 - model (string, required): OpenCode model id in provider/model format (for example anthropic/claude-sonnet-4-5)
 - variant (string, optional): provider-specific reasoning/profile variant passed as --variant (for example minimal|low|medium|high|xhigh|max)
+- dangerouslySkipPermissions (boolean, optional): inject a runtime OpenCode config that allows \`external_directory\` access without interactive prompts; defaults to true for unattended Paperclip runs
 - promptTemplate (string, optional): run prompt template
 - command (string, optional): defaults to "opencode"
 - extraArgs (string[], optional): additional CLI args
@@ -45,4 +46,10 @@ Notes:
 - Paperclip requires an explicit \`model\` value for \`opencode_local\` agents.
 - Runs are executed with: opencode run --format json ...
 - Sessions are resumed with --session when stored session cwd matches current cwd.
+- The adapter sets OPENCODE_DISABLE_PROJECT_CONFIG=true to prevent OpenCode from \
+  writing an opencode.json config file into the project working directory. Model \
+  selection is passed via the --model CLI flag instead.
+- When \`dangerouslySkipPermissions\` is enabled, Paperclip injects a temporary \
+  runtime config with \`permission.external_directory=allow\` so headless runs do \
+  not stall on approval prompts.
 `;

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

@@ -2,28 +2,31 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
 import {
   asString,
   asNumber,
   asStringArray,
   parseObject,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  joinPromptSections,
+  buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  resolveCommandForLogs,
   renderTemplate,
   runChildProcess,
+  readPaperclipRuntimeSkillEntries,
+  resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
 import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";
 import { ensureOpenCodeModelConfiguredAndAvailable } from "./models.js";
+import { removeMaintainerOnlySkillSymlinks } from "@paperclipai/adapter-utils/server-utils";
+import { prepareOpenCodeRuntimeConfig } from "./runtime-config.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 function firstNonEmptyLine(text: string): string {
   return (
@@ -41,49 +44,54 @@ function parseModelProvider(model: string | null): string | null {
   return trimmed.slice(0, trimmed.indexOf("/")).trim() || null;
 }
 
+function resolveOpenCodeBiller(env: Record<string, string>, provider: string | null): string {
+  return inferOpenAiCompatibleBiller(env, null) ?? provider ?? "unknown";
+}
+
 function claudeSkillsHome(): string {
   return path.join(os.homedir(), ".claude", "skills");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
-async function ensureOpenCodeSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
-
+async function ensureOpenCodeSkillsInjected(
+  onLog: AdapterExecutionContext["onLog"],
+  skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
+  desiredSkillNames?: string[],
+) {
   const skillsHome = claudeSkillsHome();
   await fs.mkdir(skillsHome, { recursive: true });
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
-    const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
+  const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
+  const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    selectedEntries.map((entry) => entry.runtimeName),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only OpenCode skill "${skillName}" from ${skillsHome}\n`,
+    );
+  }
+  for (const entry of selectedEntries) {
+    const target = path.join(skillsHome, entry.runtimeName);
 
     try {
-      await fs.symlink(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target);
+      if (result === "skipped") continue;
       await onLog(
         "stderr",
-        `[paperclip] Injected OpenCode skill "${entry.name}" into ${skillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} OpenCode skill "${entry.key}" into ${skillsHome}\n`,
       );
     } catch (err) {
       await onLog(
         "stderr",
-        `[paperclip] Failed to inject OpenCode skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+        `[paperclip] Failed to inject OpenCode skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     }
   }
 }
 
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -99,6 +107,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -109,7 +118,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-  await ensureOpenCodeSkillsInjected(onLog);
+  const openCodeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredOpenCodeSkillNames = resolvePaperclipDesiredSkillNames(config, openCodeSkillEntries);
+  await ensureOpenCodeSkillsInjected(
+    onLog,
+    openCodeSkillEntries,
+    desiredOpenCodeSkillNames,
+  );
 
   const envConfig = parseObject(config.env);
   const hasExplicitApiKey =
@@ -150,221 +165,259 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
   if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
   if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
 
   for (const [key, value] of Object.entries(envConfig)) {
     if (typeof value === "string") env[key] = value;
   }
+  // Prevent OpenCode from writing an opencode.json config file into the
+  // project working directory (which would pollute the git repo).  Model
+  // selection is already handled via the --model CLI flag.  Set after the
+  // envConfig loop so user overrides cannot disable this guard.
+  env.OPENCODE_DISABLE_PROJECT_CONFIG = "true";
   if (!hasExplicitApiKey && authToken) {
     env.PAPERCLIP_API_KEY = authToken;
   }
-  const runtimeEnv = Object.fromEntries(
-    Object.entries(ensurePathInEnv({ ...process.env, ...env })).filter(
-      (entry): entry is [string, string] => typeof entry[1] === "string",
-    ),
-  );
-  await ensureCommandResolvable(command, cwd, runtimeEnv);
-
-  await ensureOpenCodeModelConfiguredAndAvailable({
-    model,
-    command,
-    cwd,
-    env: runtimeEnv,
-  });
-
-  const timeoutSec = asNumber(config.timeoutSec, 0);
-  const graceSec = asNumber(config.graceSec, 20);
-  const extraArgs = (() => {
-    const fromExtraArgs = asStringArray(config.extraArgs);
-    if (fromExtraArgs.length > 0) return fromExtraArgs;
-    return asStringArray(config.args);
-  })();
-
-  const runtimeSessionParams = parseObject(runtime.sessionParams);
-  const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
-  const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
-  const canResumeSession =
-    runtimeSessionId.length > 0 &&
-    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
-  const sessionId = canResumeSession ? runtimeSessionId : null;
-  if (runtimeSessionId && !canResumeSession) {
-    await onLog(
-      "stderr",
-      `[paperclip] OpenCode session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
+  const preparedRuntimeConfig = await prepareOpenCodeRuntimeConfig({ env, config });
+  try {
+    const runtimeEnv = Object.fromEntries(
+      Object.entries(ensurePathInEnv({ ...process.env, ...preparedRuntimeConfig.env })).filter(
+        (entry): entry is [string, string] => typeof entry[1] === "string",
+      ),
     );
-  }
+    await ensureCommandResolvable(command, cwd, runtimeEnv);
+    const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+    const loggedEnv = buildInvocationEnvForLogs(preparedRuntimeConfig.env, {
+      runtimeEnv,
+      includeRuntimeKeys: ["HOME"],
+      resolvedCommand,
+    });
 
-  const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
-  const resolvedInstructionsFilePath = instructionsFilePath
-    ? path.resolve(cwd, instructionsFilePath)
-    : "";
-  const instructionsDir = resolvedInstructionsFilePath ? `${path.dirname(resolvedInstructionsFilePath)}/` : "";
-  let instructionsPrefix = "";
-  if (resolvedInstructionsFilePath) {
-    try {
-      const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
-      instructionsPrefix =
-        `${instructionsContents}\n\n` +
-        `The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
-        `Resolve any relative file references from ${instructionsDir}.\n\n`;
-      await onLog(
-        "stderr",
-        `[paperclip] Loaded agent instructions file: ${resolvedInstructionsFilePath}\n`,
-      );
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      await onLog(
-        "stderr",
-        `[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
-      );
-    }
-  }
-
-  const commandNotes = (() => {
-    if (!resolvedInstructionsFilePath) return [] as string[];
-    if (instructionsPrefix.length > 0) {
-      return [
-        `Loaded agent instructions from ${resolvedInstructionsFilePath}`,
-        `Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
-      ];
-    }
-    return [
-      `Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
-    ];
-  })();
-
-  const renderedPrompt = renderTemplate(promptTemplate, {
-    agentId: agent.id,
-    companyId: agent.companyId,
-    runId,
-    company: { id: agent.companyId },
-    agent,
-    run: { id: runId, source: "on_demand" },
-    context,
-  });
-  const prompt = `${instructionsPrefix}${renderedPrompt}`;
-
-  const buildArgs = (resumeSessionId: string | null) => {
-    const args = ["run", "--format", "json"];
-    if (resumeSessionId) args.push("--session", resumeSessionId);
-    if (model) args.push("--model", model);
-    if (variant) args.push("--variant", variant);
-    if (extraArgs.length > 0) args.push(...extraArgs);
-    return args;
-  };
-
-  const runAttempt = async (resumeSessionId: string | null) => {
-    const args = buildArgs(resumeSessionId);
-    if (onMeta) {
-      await onMeta({
-        adapterType: "opencode_local",
-        command,
-        cwd,
-        commandNotes,
-        commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],
-        env: redactEnvForLogs(env),
-        prompt,
-        context,
-      });
-    }
-
-    const proc = await runChildProcess(runId, command, args, {
+    await ensureOpenCodeModelConfiguredAndAvailable({
+      model,
+      command,
       cwd,
       env: runtimeEnv,
-      stdin: prompt,
-      timeoutSec,
-      graceSec,
-      onLog,
     });
-    return {
-      proc,
-      rawStderr: proc.stderr,
-      parsed: parseOpenCodeJsonl(proc.stdout),
-    };
-  };
 
-  const toResult = (
-    attempt: {
-      proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string };
-      rawStderr: string;
-      parsed: ReturnType<typeof parseOpenCodeJsonl>;
-    },
-    clearSessionOnMissingSession = false,
-  ): AdapterExecutionResult => {
-    if (attempt.proc.timedOut) {
-      return {
-        exitCode: attempt.proc.exitCode,
-        signal: attempt.proc.signal,
-        timedOut: true,
-        errorMessage: `Timed out after ${timeoutSec}s`,
-        clearSession: clearSessionOnMissingSession,
-      };
+    const timeoutSec = asNumber(config.timeoutSec, 0);
+    const graceSec = asNumber(config.graceSec, 20);
+    const extraArgs = (() => {
+      const fromExtraArgs = asStringArray(config.extraArgs);
+      if (fromExtraArgs.length > 0) return fromExtraArgs;
+      return asStringArray(config.args);
+    })();
+
+    const runtimeSessionParams = parseObject(runtime.sessionParams);
+    const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+    const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+    const canResumeSession =
+      runtimeSessionId.length > 0 &&
+      (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
+    const sessionId = canResumeSession ? runtimeSessionId : null;
+    if (runtimeSessionId && !canResumeSession) {
+      await onLog(
+        "stdout",
+        `[paperclip] OpenCode session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
+      );
     }
 
-    const resolvedSessionId =
-      attempt.parsed.sessionId ??
-      (clearSessionOnMissingSession ? null : runtimeSessionId ?? runtime.sessionId ?? null);
-    const resolvedSessionParams = resolvedSessionId
-      ? ({
-          sessionId: resolvedSessionId,
-          cwd,
-          ...(workspaceId ? { workspaceId } : {}),
-          ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
-          ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
-        } as Record<string, unknown>)
-      : null;
+    const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+    const resolvedInstructionsFilePath = instructionsFilePath
+      ? path.resolve(cwd, instructionsFilePath)
+      : "";
+    const instructionsDir = resolvedInstructionsFilePath ? `${path.dirname(resolvedInstructionsFilePath)}/` : "";
+    let instructionsPrefix = "";
+    if (resolvedInstructionsFilePath) {
+      try {
+        const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
+        instructionsPrefix =
+          `${instructionsContents}\n\n` +
+          `The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
+          `Resolve any relative file references from ${instructionsDir}.\n\n`;
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        await onLog(
+          "stdout",
+          `[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
+        );
+      }
+    }
 
-    const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
-    const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
-    const rawExitCode = attempt.proc.exitCode;
-    const synthesizedExitCode = parsedError && (rawExitCode ?? 0) === 0 ? 1 : rawExitCode;
-    const fallbackErrorMessage =
-      parsedError ||
-      stderrLine ||
-      `OpenCode exited with code ${synthesizedExitCode ?? -1}`;
-    const modelId = model || null;
+    const commandNotes = (() => {
+      const notes = [...preparedRuntimeConfig.notes];
+      if (!resolvedInstructionsFilePath) return notes;
+      if (instructionsPrefix.length > 0) {
+        notes.push(`Loaded agent instructions from ${resolvedInstructionsFilePath}`);
+        notes.push(
+          `Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
+        );
+        return notes;
+      }
+      notes.push(
+        `Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+      );
+      return notes;
+    })();
 
-    return {
-      exitCode: synthesizedExitCode,
-      signal: attempt.proc.signal,
-      timedOut: false,
-      errorMessage: (synthesizedExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
-      usage: {
-        inputTokens: attempt.parsed.usage.inputTokens,
-        outputTokens: attempt.parsed.usage.outputTokens,
-        cachedInputTokens: attempt.parsed.usage.cachedInputTokens,
-      },
-      sessionId: resolvedSessionId,
-      sessionParams: resolvedSessionParams,
-      sessionDisplayId: resolvedSessionId,
-      provider: parseModelProvider(modelId),
-      model: modelId,
-      billingType: "unknown",
-      costUsd: attempt.parsed.costUsd,
-      resultJson: {
-        stdout: attempt.proc.stdout,
-        stderr: attempt.proc.stderr,
-      },
-      summary: attempt.parsed.summary,
-      clearSession: Boolean(clearSessionOnMissingSession && !attempt.parsed.sessionId),
+    const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+    const templateData = {
+      agentId: agent.id,
+      companyId: agent.companyId,
+      runId,
+      company: { id: agent.companyId },
+      agent,
+      run: { id: runId, source: "on_demand" },
+      context,
+    };
+    const renderedPrompt = renderTemplate(promptTemplate, templateData);
+    const renderedBootstrapPrompt =
+      !sessionId && bootstrapPromptTemplate.trim().length > 0
+        ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+        : "";
+    const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+    const prompt = joinPromptSections([
+      instructionsPrefix,
+      renderedBootstrapPrompt,
+      sessionHandoffNote,
+      renderedPrompt,
+    ]);
+    const promptMetrics = {
+      promptChars: prompt.length,
+      instructionsChars: instructionsPrefix.length,
+      bootstrapPromptChars: renderedBootstrapPrompt.length,
+      sessionHandoffChars: sessionHandoffNote.length,
+      heartbeatPromptChars: renderedPrompt.length,
     };
-  };
 
-  const initial = await runAttempt(sessionId);
-  const initialFailed =
-    !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || Boolean(initial.parsed.errorMessage));
-  if (
-    sessionId &&
-    initialFailed &&
-    isOpenCodeUnknownSessionError(initial.proc.stdout, initial.rawStderr)
-  ) {
-    await onLog(
-      "stderr",
-      `[paperclip] OpenCode session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
-    );
-    const retry = await runAttempt(null);
-    return toResult(retry, true);
+    const buildArgs = (resumeSessionId: string | null) => {
+      const args = ["run", "--format", "json"];
+      if (resumeSessionId) args.push("--session", resumeSessionId);
+      if (model) args.push("--model", model);
+      if (variant) args.push("--variant", variant);
+      if (extraArgs.length > 0) args.push(...extraArgs);
+      return args;
+    };
+
+    const runAttempt = async (resumeSessionId: string | null) => {
+      const args = buildArgs(resumeSessionId);
+      if (onMeta) {
+        await onMeta({
+          adapterType: "opencode_local",
+          command: resolvedCommand,
+          cwd,
+          commandNotes,
+          commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],
+          env: loggedEnv,
+          prompt,
+          promptMetrics,
+          context,
+        });
+      }
+
+      const proc = await runChildProcess(runId, command, args, {
+        cwd,
+        env: runtimeEnv,
+        stdin: prompt,
+        timeoutSec,
+        graceSec,
+        onSpawn,
+        onLog,
+      });
+      return {
+        proc,
+        rawStderr: proc.stderr,
+        parsed: parseOpenCodeJsonl(proc.stdout),
+      };
+    };
+
+    const toResult = (
+      attempt: {
+        proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string };
+        rawStderr: string;
+        parsed: ReturnType<typeof parseOpenCodeJsonl>;
+      },
+      clearSessionOnMissingSession = false,
+    ): AdapterExecutionResult => {
+      if (attempt.proc.timedOut) {
+        return {
+          exitCode: attempt.proc.exitCode,
+          signal: attempt.proc.signal,
+          timedOut: true,
+          errorMessage: `Timed out after ${timeoutSec}s`,
+          clearSession: clearSessionOnMissingSession,
+        };
+      }
+
+      const resolvedSessionId =
+        attempt.parsed.sessionId ??
+        (clearSessionOnMissingSession ? null : runtimeSessionId ?? runtime.sessionId ?? null);
+      const resolvedSessionParams = resolvedSessionId
+        ? ({
+            sessionId: resolvedSessionId,
+            cwd,
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
+            ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
+          } as Record<string, unknown>)
+        : null;
+
+      const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
+      const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+      const rawExitCode = attempt.proc.exitCode;
+      const synthesizedExitCode = parsedError && (rawExitCode ?? 0) === 0 ? 1 : rawExitCode;
+      const fallbackErrorMessage =
+        parsedError ||
+        stderrLine ||
+        `OpenCode exited with code ${synthesizedExitCode ?? -1}`;
+      const modelId = model || null;
+
+      return {
+        exitCode: synthesizedExitCode,
+        signal: attempt.proc.signal,
+        timedOut: false,
+        errorMessage: (synthesizedExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
+        usage: {
+          inputTokens: attempt.parsed.usage.inputTokens,
+          outputTokens: attempt.parsed.usage.outputTokens,
+          cachedInputTokens: attempt.parsed.usage.cachedInputTokens,
+        },
+        sessionId: resolvedSessionId,
+        sessionParams: resolvedSessionParams,
+        sessionDisplayId: resolvedSessionId,
+        provider: parseModelProvider(modelId),
+        biller: resolveOpenCodeBiller(runtimeEnv, parseModelProvider(modelId)),
+        model: modelId,
+        billingType: "unknown",
+        costUsd: attempt.parsed.costUsd,
+        resultJson: {
+          stdout: attempt.proc.stdout,
+          stderr: attempt.proc.stderr,
+        },
+        summary: attempt.parsed.summary,
+        clearSession: Boolean(clearSessionOnMissingSession && !attempt.parsed.sessionId),
+      };
+    };
+
+    const initial = await runAttempt(sessionId);
+    const initialFailed =
+      !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || Boolean(initial.parsed.errorMessage));
+    if (
+      sessionId &&
+      initialFailed &&
+      isOpenCodeUnknownSessionError(initial.proc.stdout, initial.rawStderr)
+    ) {
+      await onLog(
+        "stdout",
+        `[paperclip] OpenCode session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+      );
+      const retry = await runAttempt(null);
+      return toResult(retry, true);
+    }
+
+    return toResult(initial);
+  } finally {
+    await preparedRuntimeConfig.cleanup();
   }
-
-  return toResult(initial);
 }

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

@@ -61,6 +61,7 @@ export const sessionCodec: AdapterSessionCodec = {
 };
 
 export { execute } from "./execute.js";
+export { listOpenCodeSkills, syncOpenCodeSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   listOpenCodeModels,

packages/adapters/opencode-local/src/server/models.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import os from "node:os";
 import type { AdapterModel } from "@paperclipai/adapter-utils";
 import {
   asString,
@@ -7,6 +8,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 
 const MODELS_CACHE_TTL_MS = 60_000;
+const MODELS_DISCOVERY_TIMEOUT_MS = 20_000;
 
 function resolveOpenCodeCommand(input: unknown): string {
   const envOverride =
@@ -19,7 +21,7 @@ function resolveOpenCodeCommand(input: unknown): string {
 
 const discoveryCache = new Map<string, { expiresAt: number; models: AdapterModel[] }>();
 const VOLATILE_ENV_KEY_PREFIXES = ["PAPERCLIP_", "npm_", "NPM_"] as const;
-const VOLATILE_ENV_KEY_EXACT = new Set(["PWD", "OLDPWD", "SHLVL", "_", "TERM_SESSION_ID"]);
+const VOLATILE_ENV_KEY_EXACT = new Set(["PWD", "OLDPWD", "SHLVL", "_", "TERM_SESSION_ID", "HOME"]);
 
 function dedupeModels(models: AdapterModel[]): AdapterModel[] {
   const seen = new Set<string>();
@@ -106,7 +108,20 @@ export async function discoverOpenCodeModels(input: {
   const command = resolveOpenCodeCommand(input.command);
   const cwd = asString(input.cwd, process.cwd());
   const env = normalizeEnv(input.env);
-  const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...env }));
+  // Ensure HOME points to the actual running user's home directory.
+  // When the server is started via `runuser -u <user>`, HOME may still
+  // reflect the parent process (e.g. /root), causing OpenCode to miss
+  // provider auth credentials stored under the target user's home.
+  let resolvedHome: string | undefined;
+  try {
+    resolvedHome = os.userInfo().homedir || undefined;
+  } catch {
+    // os.userInfo() throws a SystemError when the current UID has no
+    // /etc/passwd entry (e.g. `docker run --user 1234` with a minimal
+    // image). Fall back to process.env.HOME.
+  }
+  // Prevent OpenCode from writing an opencode.json into the working directory.
+  const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...env, ...(resolvedHome ? { HOME: resolvedHome } : {}), OPENCODE_DISABLE_PROJECT_CONFIG: "true" }));
 
   const result = await runChildProcess(
     `opencode-models-${Date.now()}-${Math.random().toString(16).slice(2)}`,
@@ -115,14 +130,14 @@ export async function discoverOpenCodeModels(input: {
     {
       cwd,
       env: runtimeEnv,
-      timeoutSec: 20,
+      timeoutSec: MODELS_DISCOVERY_TIMEOUT_MS / 1000,
       graceSec: 3,
       onLog: async () => {},
     },
   );
 
   if (result.timedOut) {
-    throw new Error("`opencode models` timed out.");
+    throw new Error(`\`opencode models\` timed out after ${MODELS_DISCOVERY_TIMEOUT_MS / 1000}s.`);
   }
   if ((result.exitCode ?? 1) !== 0) {
     const detail = firstNonEmptyLine(result.stderr) || firstNonEmptyLine(result.stdout);

packages/adapters/opencode-local/src/server/runtime-config.test.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { prepareOpenCodeRuntimeConfig } from "./runtime-config.js";
+
+const cleanupPaths = new Set<string>();
+
+afterEach(async () => {
+  await Promise.all(
+    [...cleanupPaths].map(async (filepath) => {
+      await fs.rm(filepath, { recursive: true, force: true });
+      cleanupPaths.delete(filepath);
+    }),
+  );
+});
+
+async function makeConfigHome(initialConfig?: Record<string, unknown>) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-test-"));
+  cleanupPaths.add(root);
+  const configDir = path.join(root, "opencode");
+  await fs.mkdir(configDir, { recursive: true });
+  if (initialConfig) {
+    await fs.writeFile(
+      path.join(configDir, "opencode.json"),
+      `${JSON.stringify(initialConfig, null, 2)}\n`,
+      "utf8",
+    );
+  }
+  return root;
+}
+
+describe("prepareOpenCodeRuntimeConfig", () => {
+  it("injects an external_directory allow rule by default", async () => {
+    const configHome = await makeConfigHome({
+      permission: {
+        read: "allow",
+      },
+      theme: "system",
+    });
+
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome },
+      config: {},
+    });
+    cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
+
+    expect(prepared.env.XDG_CONFIG_HOME).not.toBe(configHome);
+    const runtimeConfig = JSON.parse(
+      await fs.readFile(
+        path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"),
+        "utf8",
+      ),
+    ) as Record<string, unknown>;
+    expect(runtimeConfig).toMatchObject({
+      theme: "system",
+      permission: {
+        read: "allow",
+        external_directory: "allow",
+      },
+    });
+
+    await prepared.cleanup();
+    cleanupPaths.delete(prepared.env.XDG_CONFIG_HOME);
+    await expect(fs.access(prepared.env.XDG_CONFIG_HOME)).rejects.toThrow();
+  });
+
+  it("respects explicit opt-out", async () => {
+    const configHome = await makeConfigHome();
+    const prepared = await prepareOpenCodeRuntimeConfig({
+      env: { XDG_CONFIG_HOME: configHome },
+      config: { dangerouslySkipPermissions: false },
+    });
+
+    expect(prepared.env).toEqual({ XDG_CONFIG_HOME: configHome });
+    expect(prepared.notes).toEqual([]);
+    await prepared.cleanup();
+  });
+});

packages/adapters/opencode-local/src/server/runtime-config.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { asBoolean } from "@paperclipai/adapter-utils/server-utils";
+
+type PreparedOpenCodeRuntimeConfig = {
+  env: Record<string, string>;
+  notes: string[];
+  cleanup: () => Promise<void>;
+};
+
+function resolveXdgConfigHome(env: Record<string, string>): string {
+  return (
+    (typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()) ||
+    (typeof process.env.XDG_CONFIG_HOME === "string" && process.env.XDG_CONFIG_HOME.trim()) ||
+    path.join(os.homedir(), ".config")
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readJsonObject(filepath: string): Promise<Record<string, unknown>> {
+  try {
+    const raw = await fs.readFile(filepath, "utf8");
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function prepareOpenCodeRuntimeConfig(input: {
+  env: Record<string, string>;
+  config: Record<string, unknown>;
+}): Promise<PreparedOpenCodeRuntimeConfig> {
+  const skipPermissions = asBoolean(input.config.dangerouslySkipPermissions, true);
+  if (!skipPermissions) {
+    return {
+      env: input.env,
+      notes: [],
+      cleanup: async () => {},
+    };
+  }
+
+  const sourceConfigDir = path.join(resolveXdgConfigHome(input.env), "opencode");
+  const runtimeConfigHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-config-"));
+  const runtimeConfigDir = path.join(runtimeConfigHome, "opencode");
+  const runtimeConfigPath = path.join(runtimeConfigDir, "opencode.json");
+
+  await fs.mkdir(runtimeConfigDir, { recursive: true });
+  try {
+    await fs.cp(sourceConfigDir, runtimeConfigDir, {
+      recursive: true,
+      force: true,
+      errorOnExist: false,
+      dereference: false,
+    });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException | null)?.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  const existingConfig = await readJsonObject(runtimeConfigPath);
+  const existingPermission = isPlainObject(existingConfig.permission)
+    ? existingConfig.permission
+    : {};
+  const nextConfig = {
+    ...existingConfig,
+    permission: {
+      ...existingPermission,
+      external_directory: "allow",
+    },
+  };
+  await fs.writeFile(runtimeConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+
+  return {
+    env: {
+      ...input.env,
+      XDG_CONFIG_HOME: runtimeConfigHome,
+    },
+    notes: [
+      "Injected runtime OpenCode config with permission.external_directory=allow to avoid headless approval prompts.",
+    ],
+    cleanup: async () => {
+      await fs.rm(runtimeConfigHome, { recursive: true, force: true });
+    },
+  };
+}

packages/adapters/opencode-local/src/server/skills.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  buildPersistentSkillSnapshot,
+  ensurePaperclipSkillSymlink,
+  readPaperclipRuntimeSkillEntries,
+  readInstalledSkillTargets,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredHome = asString(env.HOME);
+  const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+  return path.join(home, ".claude", "skills");
+}
+
+async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const skillsHome = resolveOpenCodeSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  return buildPersistentSkillSnapshot({
+    adapterType: "opencode_local",
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel: "~/.claude/skills",
+    installedDetail: "Installed in the shared Claude/OpenCode skills home.",
+    missingDetail: "Configured but not currently linked into the shared Claude/OpenCode skills home.",
+    externalConflictDetail: "Skill name is occupied by an external installation in the shared skills home.",
+    externalDetail: "Installed outside Paperclip management in the shared skills home.",
+    warnings: [
+      "OpenCode currently uses the shared Claude skills home (~/.claude/skills).",
+    ],
+  });
+}
+
+export async function listOpenCodeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildOpenCodeSkillSnapshot(ctx.config);
+}
+
+export async function syncOpenCodeSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+  const desiredSet = new Set([
+    ...desiredSkills,
+    ...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
+  ]);
+  const skillsHome = resolveOpenCodeSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.key)) continue;
+    const target = path.join(skillsHome, available.runtimeName);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByRuntimeName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(available.key)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildOpenCodeSkillSnapshot(ctx.config);
+}
+
+export function resolveOpenCodeDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

packages/adapters/opencode-local/src/server/test.ts

@@ -4,6 +4,7 @@ import type {
   AdapterEnvironmentTestResult,
 } from "@paperclipai/adapter-utils";
 import {
+  asBoolean,
   asString,
   asStringArray,
   parseObject,
@@ -14,6 +15,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import { discoverOpenCodeModels, ensureOpenCodeModelConfiguredAndAvailable } from "./models.js";
 import { parseOpenCodeJsonl } from "./parse.js";
+import { prepareOpenCodeRuntimeConfig } from "./runtime-config.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -90,224 +92,238 @@ export async function testEnvironment(
     });
   }
 
-  const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...env }));
-
-  const cwdInvalid = checks.some((check) => check.code === "opencode_cwd_invalid");
-  if (cwdInvalid) {
+  // Prevent OpenCode from writing an opencode.json into the working directory.
+  env.OPENCODE_DISABLE_PROJECT_CONFIG = "true";
+  const preparedRuntimeConfig = await prepareOpenCodeRuntimeConfig({ env, config });
+  if (asBoolean(config.dangerouslySkipPermissions, true)) {
     checks.push({
-      code: "opencode_command_skipped",
-      level: "warn",
-      message: "Skipped command check because working directory validation failed.",
-      detail: command,
+      code: "opencode_headless_permissions_enabled",
+      level: "info",
+      message: "Headless OpenCode external-directory permissions are auto-approved for unattended runs.",
     });
-  } else {
-    try {
-      await ensureCommandResolvable(command, cwd, runtimeEnv);
+  }
+  try {
+    const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...preparedRuntimeConfig.env }));
+
+    const cwdInvalid = checks.some((check) => check.code === "opencode_cwd_invalid");
+    if (cwdInvalid) {
       checks.push({
-        code: "opencode_command_resolvable",
-        level: "info",
-        message: `Command is executable: ${command}`,
-      });
-    } catch (err) {
-      checks.push({
-        code: "opencode_command_unresolvable",
-        level: "error",
-        message: err instanceof Error ? err.message : "Command is not executable",
+        code: "opencode_command_skipped",
+        level: "warn",
+        message: "Skipped command check because working directory validation failed.",
         detail: command,
       });
-    }
-  }
-
-  const canRunProbe =
-    checks.every((check) => check.code !== "opencode_cwd_invalid" && check.code !== "opencode_command_unresolvable");
-
-  let modelValidationPassed = false;
-  const configuredModel = asString(config.model, "").trim();
-
-  if (canRunProbe && configuredModel) {
-    try {
-      const discovered = await discoverOpenCodeModels({ command, cwd, env: runtimeEnv });
-      if (discovered.length > 0) {
+    } else {
+      try {
+        await ensureCommandResolvable(command, cwd, runtimeEnv);
         checks.push({
-          code: "opencode_models_discovered",
+          code: "opencode_command_resolvable",
           level: "info",
-          message: `Discovered ${discovered.length} model(s) from OpenCode providers.`,
+          message: `Command is executable: ${command}`,
         });
-      } else {
+      } catch (err) {
         checks.push({
-          code: "opencode_models_empty",
+          code: "opencode_command_unresolvable",
           level: "error",
-          message: "OpenCode returned no models.",
-          hint: "Run `opencode models` and verify provider authentication.",
-        });
-      }
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      if (/ProviderModelNotFoundError/i.test(errMsg)) {
-        checks.push({
-          code: "opencode_hello_probe_model_unavailable",
-          level: "warn",
-          message: "The configured model was not found by the provider.",
-          detail: errMsg,
-          hint: "Run `opencode models` and choose an available provider/model ID.",
-        });
-      } else {
-        checks.push({
-          code: "opencode_models_discovery_failed",
-          level: "error",
-          message: errMsg || "OpenCode model discovery failed.",
-          hint: "Run `opencode models` manually to verify provider auth and config.",
+          message: err instanceof Error ? err.message : "Command is not executable",
+          detail: command,
         });
       }
     }
-  } else if (canRunProbe && !configuredModel) {
-    try {
-      const discovered = await discoverOpenCodeModels({ command, cwd, env: runtimeEnv });
-      if (discovered.length > 0) {
-        checks.push({
-          code: "opencode_models_discovered",
-          level: "info",
-          message: `Discovered ${discovered.length} model(s) from OpenCode providers.`,
-        });
+
+    const canRunProbe =
+      checks.every((check) => check.code !== "opencode_cwd_invalid" && check.code !== "opencode_command_unresolvable");
+
+    let modelValidationPassed = false;
+    const configuredModel = asString(config.model, "").trim();
+
+    if (canRunProbe && configuredModel) {
+      try {
+        const discovered = await discoverOpenCodeModels({ command, cwd, env: runtimeEnv });
+        if (discovered.length > 0) {
+          checks.push({
+            code: "opencode_models_discovered",
+            level: "info",
+            message: `Discovered ${discovered.length} model(s) from OpenCode providers.`,
+          });
+        } else {
+          checks.push({
+            code: "opencode_models_empty",
+            level: "error",
+            message: "OpenCode returned no models.",
+            hint: "Run `opencode models` and verify provider authentication.",
+          });
+        }
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        if (/ProviderModelNotFoundError/i.test(errMsg)) {
+          checks.push({
+            code: "opencode_hello_probe_model_unavailable",
+            level: "warn",
+            message: "The configured model was not found by the provider.",
+            detail: errMsg,
+            hint: "Run `opencode models` and choose an available provider/model ID.",
+          });
+        } else {
+          checks.push({
+            code: "opencode_models_discovery_failed",
+            level: "error",
+            message: errMsg || "OpenCode model discovery failed.",
+            hint: "Run `opencode models` manually to verify provider auth and config.",
+          });
+        }
       }
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      if (/ProviderModelNotFoundError/i.test(errMsg)) {
-        checks.push({
-          code: "opencode_hello_probe_model_unavailable",
-          level: "warn",
-          message: "The configured model was not found by the provider.",
-          detail: errMsg,
-          hint: "Run `opencode models` and choose an available provider/model ID.",
-        });
-      } else {
-        checks.push({
-          code: "opencode_models_discovery_failed",
-          level: "warn",
-          message: errMsg || "OpenCode model discovery failed (best-effort, no model configured).",
-          hint: "Run `opencode models` manually to verify provider auth and config.",
-        });
+    } else if (canRunProbe && !configuredModel) {
+      try {
+        const discovered = await discoverOpenCodeModels({ command, cwd, env: runtimeEnv });
+        if (discovered.length > 0) {
+          checks.push({
+            code: "opencode_models_discovered",
+            level: "info",
+            message: `Discovered ${discovered.length} model(s) from OpenCode providers.`,
+          });
+        }
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        if (/ProviderModelNotFoundError/i.test(errMsg)) {
+          checks.push({
+            code: "opencode_hello_probe_model_unavailable",
+            level: "warn",
+            message: "The configured model was not found by the provider.",
+            detail: errMsg,
+            hint: "Run `opencode models` and choose an available provider/model ID.",
+          });
+        } else {
+          checks.push({
+            code: "opencode_models_discovery_failed",
+            level: "warn",
+            message: errMsg || "OpenCode model discovery failed (best-effort, no model configured).",
+            hint: "Run `opencode models` manually to verify provider auth and config.",
+          });
+        }
       }
     }
-  }
 
-  const modelUnavailable = checks.some((check) => check.code === "opencode_hello_probe_model_unavailable");
-  if (!configuredModel && !modelUnavailable) {
-    // No model configured – skip model requirement if no model-related checks exist
-  } else if (configuredModel && canRunProbe) {
-    try {
-      await ensureOpenCodeModelConfiguredAndAvailable({
-        model: configuredModel,
-        command,
-        cwd,
-        env: runtimeEnv,
-      });
-      checks.push({
-        code: "opencode_model_configured",
-        level: "info",
-        message: `Configured model: ${configuredModel}`,
-      });
-      modelValidationPassed = true;
-    } catch (err) {
-      checks.push({
-        code: "opencode_model_invalid",
-        level: "error",
-        message: err instanceof Error ? err.message : "Configured model is unavailable.",
-        hint: "Run `opencode models` and choose a currently available provider/model ID.",
-      });
-    }
-  }
-
-  if (canRunProbe && modelValidationPassed) {
-    const extraArgs = (() => {
-      const fromExtraArgs = asStringArray(config.extraArgs);
-      if (fromExtraArgs.length > 0) return fromExtraArgs;
-      return asStringArray(config.args);
-    })();
-    const variant = asString(config.variant, "").trim();
-    const probeModel = configuredModel;
-
-    const args = ["run", "--format", "json"];
-    args.push("--model", probeModel);
-    if (variant) args.push("--variant", variant);
-    if (extraArgs.length > 0) args.push(...extraArgs);
-
-    try {
-      const probe = await runChildProcess(
-        `opencode-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
-        command,
-        args,
-        {
+    const modelUnavailable = checks.some((check) => check.code === "opencode_hello_probe_model_unavailable");
+    if (!configuredModel && !modelUnavailable) {
+      // No model configured – skip model requirement if no model-related checks exist
+    } else if (configuredModel && canRunProbe) {
+      try {
+        await ensureOpenCodeModelConfiguredAndAvailable({
+          model: configuredModel,
+          command,
           cwd,
           env: runtimeEnv,
-          timeoutSec: 60,
-          graceSec: 5,
-          stdin: "Respond with hello.",
-          onLog: async () => {},
-        },
-      );
+        });
+        checks.push({
+          code: "opencode_model_configured",
+          level: "info",
+          message: `Configured model: ${configuredModel}`,
+        });
+        modelValidationPassed = true;
+      } catch (err) {
+        checks.push({
+          code: "opencode_model_invalid",
+          level: "error",
+          message: err instanceof Error ? err.message : "Configured model is unavailable.",
+          hint: "Run `opencode models` and choose a currently available provider/model ID.",
+        });
+      }
+    }
 
-      const parsed = parseOpenCodeJsonl(probe.stdout);
-      const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
-      const authEvidence = `${parsed.errorMessage ?? ""}\n${probe.stdout}\n${probe.stderr}`.trim();
+    if (canRunProbe && modelValidationPassed) {
+      const extraArgs = (() => {
+        const fromExtraArgs = asStringArray(config.extraArgs);
+        if (fromExtraArgs.length > 0) return fromExtraArgs;
+        return asStringArray(config.args);
+      })();
+      const variant = asString(config.variant, "").trim();
+      const probeModel = configuredModel;
 
-      if (probe.timedOut) {
-        checks.push({
-          code: "opencode_hello_probe_timed_out",
-          level: "warn",
-          message: "OpenCode hello probe timed out.",
-          hint: "Retry the probe. If this persists, run OpenCode manually in this working directory.",
-        });
-      } else if ((probe.exitCode ?? 1) === 0 && !parsed.errorMessage) {
-        const summary = parsed.summary.trim();
-        const hasHello = /\bhello\b/i.test(summary);
-        checks.push({
-          code: hasHello ? "opencode_hello_probe_passed" : "opencode_hello_probe_unexpected_output",
-          level: hasHello ? "info" : "warn",
-          message: hasHello
-            ? "OpenCode hello probe succeeded."
-            : "OpenCode probe ran but did not return `hello` as expected.",
-          ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
-          ...(hasHello
-            ? {}
-            : {
-                hint: "Run `opencode run --format json` manually and prompt `Respond with hello` to inspect output.",
-              }),
-        });
-      } else if (/ProviderModelNotFoundError/i.test(authEvidence)) {
-        checks.push({
-          code: "opencode_hello_probe_model_unavailable",
-          level: "warn",
-          message: "The configured model was not found by the provider.",
-          ...(detail ? { detail } : {}),
-          hint: "Run `opencode models` and choose an available provider/model ID.",
-        });
-      } else if (OPENCODE_AUTH_REQUIRED_RE.test(authEvidence)) {
-        checks.push({
-          code: "opencode_hello_probe_auth_required",
-          level: "warn",
-          message: "OpenCode is installed, but provider authentication is not ready.",
-          ...(detail ? { detail } : {}),
-          hint: "Run `opencode auth login` or set provider credentials, then retry the probe.",
-        });
-      } else {
+      const args = ["run", "--format", "json"];
+      args.push("--model", probeModel);
+      if (variant) args.push("--variant", variant);
+      if (extraArgs.length > 0) args.push(...extraArgs);
+
+      try {
+        const probe = await runChildProcess(
+          `opencode-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+          command,
+          args,
+          {
+            cwd,
+            env: runtimeEnv,
+            timeoutSec: 60,
+            graceSec: 5,
+            stdin: "Respond with hello.",
+            onLog: async () => {},
+          },
+        );
+
+        const parsed = parseOpenCodeJsonl(probe.stdout);
+        const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
+        const authEvidence = `${parsed.errorMessage ?? ""}\n${probe.stdout}\n${probe.stderr}`.trim();
+
+        if (probe.timedOut) {
+          checks.push({
+            code: "opencode_hello_probe_timed_out",
+            level: "warn",
+            message: "OpenCode hello probe timed out.",
+            hint: "Retry the probe. If this persists, run OpenCode manually in this working directory.",
+          });
+        } else if ((probe.exitCode ?? 1) === 0 && !parsed.errorMessage) {
+          const summary = parsed.summary.trim();
+          const hasHello = /\bhello\b/i.test(summary);
+          checks.push({
+            code: hasHello ? "opencode_hello_probe_passed" : "opencode_hello_probe_unexpected_output",
+            level: hasHello ? "info" : "warn",
+            message: hasHello
+              ? "OpenCode hello probe succeeded."
+              : "OpenCode probe ran but did not return `hello` as expected.",
+            ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+            ...(hasHello
+              ? {}
+              : {
+                  hint: "Run `opencode run --format json` manually and prompt `Respond with hello` to inspect output.",
+                }),
+          });
+        } else if (/ProviderModelNotFoundError/i.test(authEvidence)) {
+          checks.push({
+            code: "opencode_hello_probe_model_unavailable",
+            level: "warn",
+            message: "The configured model was not found by the provider.",
+            ...(detail ? { detail } : {}),
+            hint: "Run `opencode models` and choose an available provider/model ID.",
+          });
+        } else if (OPENCODE_AUTH_REQUIRED_RE.test(authEvidence)) {
+          checks.push({
+            code: "opencode_hello_probe_auth_required",
+            level: "warn",
+            message: "OpenCode is installed, but provider authentication is not ready.",
+            ...(detail ? { detail } : {}),
+            hint: "Run `opencode auth login` or set provider credentials, then retry the probe.",
+          });
+        } else {
+          checks.push({
+            code: "opencode_hello_probe_failed",
+            level: "error",
+            message: "OpenCode hello probe failed.",
+            ...(detail ? { detail } : {}),
+            hint: "Run `opencode run --format json` manually in this working directory to debug.",
+          });
+        }
+      } catch (err) {
         checks.push({
           code: "opencode_hello_probe_failed",
           level: "error",
           message: "OpenCode hello probe failed.",
-          ...(detail ? { detail } : {}),
+          detail: err instanceof Error ? err.message : String(err),
           hint: "Run `opencode run --format json` manually in this working directory to debug.",
         });
       }
-    } catch (err) {
-      checks.push({
-        code: "opencode_hello_probe_failed",
-        level: "error",
-        message: "OpenCode hello probe failed.",
-        detail: err instanceof Error ? err.message : String(err),
-        hint: "Run `opencode run --format json` manually in this working directory to debug.",
-      });
     }
+  } finally {
+    await preparedRuntimeConfig.cleanup();
   }
 
   return {

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

@@ -55,8 +55,10 @@ export function buildOpenCodeLocalConfig(v: CreateConfigValues): Record<string,
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.variant = v.thinkingEffort;
+  ac.dangerouslySkipPermissions = v.dangerouslySkipPermissions;
   // OpenCode sessions can run until the CLI exits naturally; keep timeout disabled (0)
   // and rely on graceSec for termination handling when a timeout is configured elsewhere.
   ac.timeoutSec = 0;

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

@@ -50,6 +50,7 @@ function parseToolUse(parsed: Record<string, unknown>, ts: string): TranscriptEn
     kind: "tool_call",
     ts,
     name: toolName,
+    toolUseId: asString(part.callID) || asString(part.id) || undefined,
     input,
   };
 

packages/adapters/opencode-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/pi-local/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @paperclipai/adapter-pi-local
+
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.0

packages/adapters/pi-local/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/adapter-pi-local",
-  "version": "0.1.0",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/pi-local"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -2,17 +2,23 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
 import {
   asString,
   asNumber,
   asStringArray,
   parseObject,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  joinPromptSections,
+  buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  readPaperclipRuntimeSkillEntries,
+  resolveCommandForLogs,
+  resolvePaperclipDesiredSkillNames,
+  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -20,12 +26,9 @@ import { isPiUnknownSessionError, parsePiJsonl } from "./parse.js";
 import { ensurePiModelConfiguredAndAvailable } from "./models.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 const PAPERCLIP_SESSIONS_DIR = path.join(os.homedir(), ".pi", "paperclips");
+const PI_AGENT_SKILLS_DIR = path.join(os.homedir(), ".pi", "agent", "skills");
 
 function firstNonEmptyLine(text: string): string {
   return (
@@ -50,44 +53,49 @@ function parseModelId(model: string | null): string | null {
   return trimmed.slice(trimmed.indexOf("/") + 1).trim() || null;
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
+async function ensurePiSkillsInjected(
+  onLog: AdapterExecutionContext["onLog"],
+  skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
+  desiredSkillNames?: string[],
+) {
+  const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
+  const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
+  if (selectedEntries.length === 0) return;
+  await fs.mkdir(PI_AGENT_SKILLS_DIR, { recursive: true });
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    PI_AGENT_SKILLS_DIR,
+    selectedEntries.map((entry) => entry.runtimeName),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Pi skill "${skillName}" from ${PI_AGENT_SKILLS_DIR}\n`,
+    );
   }
-  return null;
-}
 
-async function ensurePiSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
-
-  const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
-  await fs.mkdir(piSkillsHome, { recursive: true });
-  
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
-    const target = path.join(piSkillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
+  for (const entry of selectedEntries) {
+    const target = path.join(PI_AGENT_SKILLS_DIR, entry.runtimeName);
 
     try {
-      await fs.symlink(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target);
+      if (result === "skipped") continue;
       await onLog(
         "stderr",
-        `[paperclip] Injected Pi skill "${entry.name}" into ${piSkillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Pi skill "${entry.runtimeName}" into ${PI_AGENT_SKILLS_DIR}\n`,
       );
     } catch (err) {
       await onLog(
         "stderr",
-        `[paperclip] Failed to inject Pi skill "${entry.name}" into ${piSkillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+        `[paperclip] Failed to inject Pi skill "${entry.runtimeName}" into ${PI_AGENT_SKILLS_DIR}: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     }
   }
 }
 
+function resolvePiBiller(env: Record<string, string>, provider: string | null): string {
+  return inferOpenAiCompatibleBiller(env, null) ?? provider ?? "unknown";
+}
+
 async function ensureSessionsDir(): Promise<string> {
   await fs.mkdir(PAPERCLIP_SESSIONS_DIR, { recursive: true });
   return PAPERCLIP_SESSIONS_DIR;
@@ -99,7 +107,7 @@ function buildSessionPath(agentId: string, timestamp: string): string {
 }
 
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -119,6 +127,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -134,7 +143,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   await ensureSessionsDir();
   
   // Inject skills
-  await ensurePiSkillsInjected(onLog);
+  const piSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredPiSkillNames = resolvePaperclipDesiredSkillNames(config, piSkillEntries);
+  await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);
 
   // Build environment
   const envConfig = parseObject(config.env);
@@ -178,6 +189,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
   if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
   if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
 
   for (const [key, value] of Object.entries(envConfig)) {
@@ -193,6 +205,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     ),
   );
   await ensureCommandResolvable(command, cwd, runtimeEnv);
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME"],
+    resolvedCommand,
+  });
 
   // Validate model is available before execution
   await ensurePiModelConfiguredAndAvailable({
@@ -221,7 +239,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   
   if (runtimeSessionId && !canResumeSession) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
     );
   }
@@ -255,15 +273,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         `The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
         `Resolve any relative file references from ${instructionsFileDir}.\n\n` +
         `You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.`;
-      await onLog(
-        "stderr",
-        `[paperclip] Loaded agent instructions file: ${resolvedInstructionsFilePath}\n`,
-      );
     } catch (err) {
       instructionsReadFailed = true;
       const reason = err instanceof Error ? err.message : String(err);
       await onLog(
-        "stderr",
+        "stdout",
         `[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
       );
       // Fall back to base prompt template
@@ -273,7 +287,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     systemPromptExtension = promptTemplate;
   }
 
-  const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -281,18 +296,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
-
-  // User prompt is simple - just the rendered prompt template without instructions
-  const userPrompt = renderTemplate(promptTemplate, {
-    agentId: agent.id,
-    companyId: agent.companyId,
-    runId,
-    company: { id: agent.companyId },
-    agent,
-    run: { id: runId, source: "on_demand" },
-    context,
-  });
+  };
+  const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, templateData);
+  const renderedHeartbeatPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !canResumeSession && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const userPrompt = joinPromptSections([
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedHeartbeatPrompt,
+  ]);
+  const promptMetrics = {
+    systemPromptChars: renderedSystemPromptExtension.length,
+    promptChars: userPrompt.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedHeartbeatPrompt.length,
+  };
 
   const commandNotes = (() => {
     if (!resolvedInstructionsFilePath) return [] as string[];
@@ -310,8 +333,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const buildArgs = (sessionFile: string): string[] => {
     const args: string[] = [];
     
-    // Use RPC mode for proper lifecycle management (waits for agent completion)
-    args.push("--mode", "rpc");
+    // Use JSON mode for structured output with print mode (non-interactive)
+    args.push("--mode", "json");
+    args.push("-p"); // Non-interactive mode: process prompt and exit
     
     // Use --append-system-prompt to extend Pi's default system prompt
     args.push("--append-system-prompt", renderedSystemPromptExtension);
@@ -319,22 +343,19 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (provider) args.push("--provider", provider);
     if (modelId) args.push("--model", modelId);
     if (thinking) args.push("--thinking", thinking);
-    
+
     args.push("--tools", "read,bash,edit,write,grep,find,ls");
     args.push("--session", sessionFile);
-    
+
+    // Add Paperclip skills directory so Pi can load the paperclip skill
+    args.push("--skill", PI_AGENT_SKILLS_DIR);
+
     if (extraArgs.length > 0) args.push(...extraArgs);
     
-    return args;
-  };
+    // Add the user prompt as the last argument
+    args.push(userPrompt);
 
-  const buildRpcStdin = (): string => {
-    // Send the prompt as an RPC command
-    const promptCommand = {
-      type: "prompt",
-      message: userPrompt,
-    };
-    return JSON.stringify(promptCommand) + "\n";
+    return args;
   };
 
   const runAttempt = async (sessionFile: string) => {
@@ -342,12 +363,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (onMeta) {
       await onMeta({
         adapterType: "pi_local",
-        command,
+        command: resolvedCommand,
         cwd,
         commandNotes,
         commandArgs: args,
-        env: redactEnvForLogs(env),
+        env: loggedEnv,
         prompt: userPrompt,
+        promptMetrics,
         context,
       });
     }
@@ -380,8 +402,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       env: runtimeEnv,
       timeoutSec,
       graceSec,
+      onSpawn,
       onLog: bufferedOnLog,
-      stdin: buildRpcStdin(),
     });
     
     // Flush any remaining buffer content
@@ -437,6 +459,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       sessionParams: resolvedSessionParams,
       sessionDisplayId: resolvedSessionId,
       provider: provider,
+      biller: resolvePiBiller(runtimeEnv, provider),
       model: model,
       billingType: "unknown",
       costUsd: attempt.parsed.usage.costUsd,
@@ -459,7 +482,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     isPiUnknownSessionError(initial.proc.stdout, initial.rawStderr)
   ) {
     await onLog(
-      "stderr",
+      "stdout",
       `[paperclip] Pi session "${runtimeSessionId}" is unavailable; retrying with a fresh session.\n`,
     );
     const newSessionPath = buildSessionPath(agent.id, new Date().toISOString());

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

@@ -49,6 +49,7 @@ export const sessionCodec: AdapterSessionCodec = {
 };
 
 export { execute } from "./execute.js";
+export { listPiSkills, syncPiSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   listPiModels,

packages/adapters/pi-local/src/server/models.ts

@@ -131,7 +131,9 @@ export async function discoverPiModels(input: {
     throw new Error(detail ? `\`pi --list-models\` failed: ${detail}` : "`pi --list-models` failed.");
   }
 
-  return sortModels(dedupeModels(parseModelsOutput(result.stdout)));
+  // Pi outputs model list to stderr, but fall back to stdout for older versions
+  const output = result.stderr || result.stdout;
+  return sortModels(dedupeModels(parseModelsOutput(output)));
 }
 
 function normalizeEnv(input: unknown): Record<string, string> {

packages/adapters/pi-local/src/server/skills.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  buildPersistentSkillSnapshot,
+  ensurePaperclipSkillSymlink,
+  readPaperclipRuntimeSkillEntries,
+  readInstalledSkillTargets,
+  resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolvePiSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredHome = asString(env.HOME);
+  const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+  return path.join(home, ".pi", "agent", "skills");
+}
+
+async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+  const skillsHome = resolvePiSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  return buildPersistentSkillSnapshot({
+    adapterType: "pi_local",
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel: "~/.pi/agent/skills",
+    missingDetail: "Configured but not currently linked into the Pi skills home.",
+    externalConflictDetail: "Skill name is occupied by an external installation.",
+    externalDetail: "Installed outside Paperclip management.",
+  });
+}
+
+export async function listPiSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildPiSkillSnapshot(ctx.config);
+}
+
+export async function syncPiSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+  const desiredSet = new Set([
+    ...desiredSkills,
+    ...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
+  ]);
+  const skillsHome = resolvePiSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.key)) continue;
+    const target = path.join(skillsHome, available.runtimeName);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByRuntimeName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(available.key)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildPiSkillSnapshot(ctx.config);
+}
+
+export function resolvePiDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableEntries: Array<{ key: string; required?: boolean }>,
+) {
+  return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}

packages/adapters/pi-local/src/server/test.ts

@@ -51,6 +51,26 @@ function normalizeEnv(input: unknown): Record<string, string> {
 
 const PI_AUTH_REQUIRED_RE =
   /(?:auth(?:entication)?\s+required|api\s*key|invalid\s*api\s*key|not\s+logged\s+in|free\s+usage\s+exceeded)/i;
+const PI_STALE_PACKAGE_RE = /pi-driver|npm:\s*pi-driver/i;
+
+function buildPiModelDiscoveryFailureCheck(message: string): AdapterEnvironmentCheck {
+  if (PI_STALE_PACKAGE_RE.test(message)) {
+    return {
+      code: "pi_package_install_failed",
+      level: "warn",
+      message: "Pi startup failed while installing configured package `npm:pi-driver`.",
+      detail: message,
+      hint: "Remove `npm:pi-driver` from ~/.pi/agent/settings.json or set adapter env HOME to a clean Pi profile, then retry `pi --list-models`.",
+    };
+  }
+
+  return {
+    code: "pi_models_discovery_failed",
+    level: "warn",
+    message,
+    hint: "Run `pi --list-models` manually to verify provider auth and config.",
+  };
+}
 
 export async function testEnvironment(
   ctx: AdapterEnvironmentTestContext,
@@ -130,12 +150,11 @@ export async function testEnvironment(
         });
       }
     } catch (err) {
-      checks.push({
-        code: "pi_models_discovery_failed",
-        level: "warn",
-        message: err instanceof Error ? err.message : "Pi model discovery failed.",
-        hint: "Run `pi --list-models` manually to verify provider auth and config.",
-      });
+      checks.push(
+        buildPiModelDiscoveryFailureCheck(
+          err instanceof Error ? err.message : "Pi model discovery failed.",
+        ),
+      );
     }
   }
 

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

@@ -48,6 +48,7 @@ export function buildPiLocalConfig(v: CreateConfigValues): Record<string, unknow
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.thinking = v.thinkingEffort;
   

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

@@ -17,19 +17,39 @@ function asString(value: unknown, fallback = ""): string {
   return typeof value === "string" ? value : fallback;
 }
 
-function extractTextContent(content: string | Array<{ type: string; text?: string }>): string {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .filter((c) => c.type === "text" && c.text)
-    .map((c) => c.text!)
-    .join("");
+function extractTextContent(content: string | Array<{ type: string; text?: string; thinking?: string }>): { text: string; thinking: string } {
+  if (typeof content === "string") return { text: content, thinking: "" };
+  if (!Array.isArray(content)) return { text: "", thinking: "" };
+  
+  let text = "";
+  let thinking = "";
+  
+  for (const c of content) {
+    if (c.type === "text" && c.text) {
+      text += c.text;
+    }
+    if (c.type === "thinking" && c.thinking) {
+      thinking += c.thinking;
+    }
+  }
+  
+  return { text, thinking };
+}
+
+// Track pending tool calls for proper toolUseId matching
+let pendingToolCalls = new Map<string, { toolName: string; args: unknown }>();
+
+export function resetParserState(): void {
+  pendingToolCalls.clear();
 }
 
 export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
   const parsed = asRecord(safeJsonParse(line));
   if (!parsed) {
-    return [{ kind: "stdout", ts, text: line }];
+    // Non-JSON line, treat as raw stdout
+    const trimmed = line.trim();
+    if (!trimmed) return [];
+    return [{ kind: "stdout", ts, text: trimmed }];
   }
 
   const type = asString(parsed.type);
@@ -41,16 +61,64 @@ export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
 
   // Agent lifecycle
   if (type === "agent_start") {
-    return [{ kind: "system", ts, text: "Pi agent started" }];
+    return [{ kind: "system", ts, text: "🚀 Pi agent started" }];
   }
 
   if (type === "agent_end") {
-    return [{ kind: "system", ts, text: "Pi agent finished" }];
+    const entries: TranscriptEntry[] = [];
+    
+    // Extract final message from messages array if available
+    const messages = parsed.messages as Array<Record<string, unknown>> | undefined;
+    if (messages && messages.length > 0) {
+      const lastMessage = messages[messages.length - 1];
+      if (lastMessage?.role === "assistant") {
+        const content = lastMessage.content as string | Array<{ type: string; text?: string; thinking?: string }>;
+        const { text, thinking } = extractTextContent(content);
+        
+        if (thinking) {
+          entries.push({ kind: "thinking", ts, text: thinking });
+        }
+        if (text) {
+          entries.push({ kind: "assistant", ts, text });
+        }
+        
+        // Extract usage
+        const usage = asRecord(lastMessage.usage);
+        if (usage) {
+          const inputTokens = (usage.inputTokens ?? usage.input ?? 0) as number;
+          const outputTokens = (usage.outputTokens ?? usage.output ?? 0) as number;
+          const cachedTokens = (usage.cacheRead ?? usage.cachedInputTokens ?? 0) as number;
+          const costRecord = asRecord(usage.cost);
+          const costUsd = (costRecord?.total ?? usage.costUsd ?? 0) as number;
+          
+          if (inputTokens > 0 || outputTokens > 0) {
+            entries.push({
+              kind: "result",
+              ts,
+              text: "Run completed",
+              inputTokens,
+              outputTokens,
+              cachedTokens,
+              costUsd,
+              subtype: "end",
+              isError: false,
+              errors: [],
+            });
+          }
+        }
+      }
+    }
+    
+    if (entries.length === 0) {
+      entries.push({ kind: "system", ts, text: "✅ Pi agent finished" });
+    }
+    
+    return entries;
   }
 
   // Turn lifecycle
   if (type === "turn_start") {
-    return [{ kind: "system", ts, text: "Turn started" }];
+    return []; // Skip noisy lifecycle events
   }
 
   if (type === "turn_end") {
@@ -60,30 +128,54 @@ export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
     const entries: TranscriptEntry[] = [];
     
     if (message) {
-      const content = message.content as string | Array<{ type: string; text?: string }>;
-      const text = extractTextContent(content);
+      const content = message.content as string | Array<{ type: string; text?: string; thinking?: string }>;
+      const { text, thinking } = extractTextContent(content);
+      
+      if (thinking) {
+        entries.push({ kind: "thinking", ts, text: thinking });
+      }
       if (text) {
         entries.push({ kind: "assistant", ts, text });
       }
     }
     
-    // Process tool results
+    // Process tool results - match with pending tool calls
     if (toolResults) {
       for (const tr of toolResults) {
+        const toolCallId = asString(tr.toolCallId, `tool-${Date.now()}`);
         const content = tr.content;
         const isError = tr.isError === true;
-        const contentStr = typeof content === "string" ? content : JSON.stringify(content);
+        
+        // Extract text from Pi's content array format
+        let contentStr: string;
+        if (typeof content === "string") {
+          contentStr = content;
+        } else if (Array.isArray(content)) {
+          const extracted = extractTextContent(content as Array<{ type: string; text?: string }>);
+          contentStr = extracted.text || JSON.stringify(content);
+        } else {
+          contentStr = JSON.stringify(content);
+        }
+        
+        // Get tool name from pending calls if available
+        const pendingCall = pendingToolCalls.get(toolCallId);
+        const toolName = asString(tr.toolName, pendingCall?.toolName || "tool");
+        
         entries.push({
           kind: "tool_result",
           ts,
-          toolUseId: asString(tr.toolCallId, "unknown"),
+          toolUseId: toolCallId,
+          toolName,
           content: contentStr,
           isError,
         });
+        
+        // Clean up pending call
+        pendingToolCalls.delete(toolCallId);
       }
     }
     
-    return entries.length > 0 ? entries : [{ kind: "system", ts, text: "Turn ended" }];
+    return entries;
   }
 
   // Message streaming
@@ -95,33 +187,81 @@ export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
     const assistantEvent = asRecord(parsed.assistantMessageEvent);
     if (assistantEvent) {
       const msgType = asString(assistantEvent.type);
+      
+      // Handle thinking deltas
+      if (msgType === "thinking_delta") {
+        const delta = asString(assistantEvent.delta);
+        if (delta) {
+          return [{ kind: "thinking", ts, text: delta, delta: true }];
+        }
+      }
+      
+      // Handle text deltas
       if (msgType === "text_delta") {
         const delta = asString(assistantEvent.delta);
         if (delta) {
           return [{ kind: "assistant", ts, text: delta, delta: true }];
         }
       }
+      
+      // Handle thinking end - emit full thinking block
+      if (msgType === "thinking_end") {
+        const content = asString(assistantEvent.content);
+        if (content) {
+          return [{ kind: "thinking", ts, text: content }];
+        }
+      }
+      
+      // Handle text end - emit full text block
+      if (msgType === "text_end") {
+        const content = asString(assistantEvent.content);
+        if (content) {
+          return [{ kind: "assistant", ts, text: content }];
+        }
+      }
     }
     return [];
   }
 
   if (type === "message_end") {
+    const message = asRecord(parsed.message);
+    if (message) {
+      const content = message.content as string | Array<{ type: string; text?: string; thinking?: string }>;
+      const { text, thinking } = extractTextContent(content);
+      
+      const entries: TranscriptEntry[] = [];
+      
+      // Emit final thinking block if present
+      if (thinking) {
+        entries.push({ kind: "thinking", ts, text: thinking });
+      }
+      
+      // Emit final text block if present
+      if (text) {
+        entries.push({ kind: "assistant", ts, text });
+      }
+      
+      return entries;
+    }
     return [];
   }
 
   // Tool execution
   if (type === "tool_execution_start") {
-    const toolName = asString(parsed.toolName);
+    const toolCallId = asString(parsed.toolCallId, `tool-${Date.now()}`);
+    const toolName = asString(parsed.toolName, "tool");
     const args = parsed.args;
-    if (toolName) {
-      return [{
-        kind: "tool_call",
-        ts,
-        name: toolName,
-        input: args,
-      }];
-    }
-    return [{ kind: "system", ts, text: `Tool started` }];
+    
+    // Track this tool call for later matching
+    pendingToolCalls.set(toolCallId, { toolName, args });
+    
+    return [{
+      kind: "tool_call",
+      ts,
+      name: toolName,
+      input: args,
+      toolUseId: toolCallId,
+    }];
   }
 
   if (type === "tool_execution_update") {
@@ -129,19 +269,43 @@ export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
   }
 
   if (type === "tool_execution_end") {
-    const toolCallId = asString(parsed.toolCallId);
+    const toolCallId = asString(parsed.toolCallId, `tool-${Date.now()}`);
+    const toolName = asString(parsed.toolName, "tool");
     const result = parsed.result;
     const isError = parsed.isError === true;
-    const contentStr = typeof result === "string" ? result : JSON.stringify(result);
+    
+    // Extract text from Pi's content array format
+    let contentStr: string;
+    if (typeof result === "string") {
+      contentStr = result;
+    } else if (Array.isArray(result)) {
+      const extracted = extractTextContent(result as Array<{ type: string; text?: string }>);
+      contentStr = extracted.text || JSON.stringify(result);
+    } else if (result && typeof result === "object") {
+      const resultObj = result as Record<string, unknown>;
+      if (Array.isArray(resultObj.content)) {
+        const extracted = extractTextContent(resultObj.content as Array<{ type: string; text?: string }>);
+        contentStr = extracted.text || JSON.stringify(result);
+      } else {
+        contentStr = JSON.stringify(result);
+      }
+    } else {
+      contentStr = String(result);
+    }
+    
+    // Clean up pending call
+    pendingToolCalls.delete(toolCallId);
     
     return [{
       kind: "tool_result",
       ts,
-      toolUseId: toolCallId || "unknown",
+      toolUseId: toolCallId,
+      toolName,
       content: contentStr,
       isError,
     }];
   }
 
+  // Fallback for unknown event types
   return [{ kind: "stdout", ts, text: line }];
 }

packages/adapters/pi-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/db/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @paperclipai/db
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/shared@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies [6077ae6]
+- Updated dependencies
+  - @paperclipai/shared@0.3.0
+
 ## 0.2.7
 
 ### Patch Changes

packages/db/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@paperclipai/db",
-  "version": "0.2.7",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/db"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -35,6 +45,7 @@
   "dependencies": {
     "@paperclipai/shared": "workspace:*",
     "drizzle-orm": "^0.38.4",
+    "embedded-postgres": "^18.1.0-beta.16",
     "postgres": "^3.4.5"
   },
   "devDependencies": {

packages/db/src/backup-lib.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
 import postgres from "postgres";
 
 export type RunDatabaseBackupOptions = {
@@ -9,6 +9,9 @@ export type RunDatabaseBackupOptions = {
   retentionDays: number;
   filenamePrefix?: string;
   connectTimeoutSeconds?: number;
+  includeMigrationJournal?: boolean;
+  excludeTables?: string[];
+  nullifyColumns?: Record<string, string[]>;
 };
 
 export type RunDatabaseBackupResult = {
@@ -17,6 +20,50 @@ export type RunDatabaseBackupResult = {
   prunedCount: number;
 };
 
+export type RunDatabaseRestoreOptions = {
+  connectionString: string;
+  backupFile: string;
+  connectTimeoutSeconds?: number;
+};
+
+type SequenceDefinition = {
+  sequence_schema: string;
+  sequence_name: string;
+  data_type: string;
+  start_value: string;
+  minimum_value: string;
+  maximum_value: string;
+  increment: string;
+  cycle_option: "YES" | "NO";
+  owner_schema: string | null;
+  owner_table: string | null;
+  owner_column: string | null;
+};
+
+type TableDefinition = {
+  schema_name: string;
+  tablename: string;
+};
+
+const DRIZZLE_SCHEMA = "drizzle";
+const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
+
+const STATEMENT_BREAKPOINT = "-- paperclip statement breakpoint 69f6f3f1-42fd-46a6-bf17-d1d85f8f3900";
+
+function sanitizeRestoreErrorMessage(error: unknown): string {
+  if (error && typeof error === "object") {
+    const record = error as Record<string, unknown>;
+    const firstLine = typeof record.message === "string"
+      ? record.message.split(/\r?\n/, 1)[0]?.trim()
+      : "";
+    const detail = typeof record.detail === "string" ? record.detail.trim() : "";
+    const severity = typeof record.severity === "string" ? record.severity.trim() : "";
+    const message = firstLine || detail || (error instanceof Error ? error.message : String(error));
+    return severity ? `${severity}: ${message}` : message;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
 function timestamp(date: Date = new Date()): string {
   const pad = (n: number) => String(n).padStart(2, "0");
   return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
@@ -47,10 +94,60 @@ function formatBackupSize(sizeBytes: number): string {
   return `${(sizeBytes / (1024 * 1024)).toFixed(1)}M`;
 }
 
+function formatSqlLiteral(value: string): string {
+  const sanitized = value.replace(/\u0000/g, "");
+  let tag = "$paperclip$";
+  while (sanitized.includes(tag)) {
+    tag = `$paperclip_${Math.random().toString(36).slice(2, 8)}$`;
+  }
+  return `${tag}${sanitized}${tag}`;
+}
+
+function normalizeTableNameSet(values: string[] | undefined): Set<string> {
+  return new Set(
+    (values ?? [])
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0),
+  );
+}
+
+function normalizeNullifyColumnMap(values: Record<string, string[]> | undefined): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  if (!values) return out;
+  for (const [tableName, columns] of Object.entries(values)) {
+    const normalizedTable = tableName.trim();
+    if (normalizedTable.length === 0) continue;
+    const normalizedColumns = new Set(
+      columns
+        .map((column) => column.trim())
+        .filter((column) => column.length > 0),
+    );
+    if (normalizedColumns.size > 0) {
+      out.set(normalizedTable, normalizedColumns);
+    }
+  }
+  return out;
+}
+
+function quoteIdentifier(value: string): string {
+  return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+
+function quoteQualifiedName(schemaName: string, objectName: string): string {
+  return `${quoteIdentifier(schemaName)}.${quoteIdentifier(objectName)}`;
+}
+
+function tableKey(schemaName: string, tableName: string): string {
+  return `${schemaName}.${tableName}`;
+}
+
 export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise<RunDatabaseBackupResult> {
   const filenamePrefix = opts.filenamePrefix ?? "paperclip";
   const retentionDays = Math.max(1, Math.trunc(opts.retentionDays));
   const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  const includeMigrationJournal = opts.includeMigrationJournal === true;
+  const excludedTableNames = normalizeTableNameSet(opts.excludeTables);
+  const nullifiedColumnsByTable = normalizeNullifyColumnMap(opts.nullifyColumns);
   const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
 
   try {
@@ -58,13 +155,35 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
 
     const lines: string[] = [];
     const emit = (line: string) => lines.push(line);
+    const emitStatement = (statement: string) => {
+      emit(statement);
+      emit(STATEMENT_BREAKPOINT);
+    };
+    const emitStatementBoundary = () => {
+      emit(STATEMENT_BREAKPOINT);
+    };
 
     emit("-- Paperclip database backup");
     emit(`-- Created: ${new Date().toISOString()}`);
     emit("");
-    emit("BEGIN;");
+    emitStatement("BEGIN;");
+    emitStatement("SET LOCAL session_replication_role = replica;");
+    emitStatement("SET LOCAL client_min_messages = warning;");
     emit("");
 
+    const allTables = await sql<TableDefinition[]>`
+      SELECT table_schema AS schema_name, table_name AS tablename
+      FROM information_schema.tables
+      WHERE table_type = 'BASE TABLE'
+        AND (
+          table_schema = 'public'
+          OR (${includeMigrationJournal}::boolean AND table_schema = ${DRIZZLE_SCHEMA} AND table_name = ${DRIZZLE_MIGRATIONS_TABLE})
+        )
+      ORDER BY table_schema, table_name
+    `;
+    const tables = allTables;
+    const includedTableNames = new Set(tables.map(({ schema_name, tablename }) => tableKey(schema_name, tablename)));
+
     // Get all enums
     const enums = await sql<{ typname: string; labels: string[] }[]>`
       SELECT t.typname, array_agg(e.enumlabel ORDER BY e.enumsortorder) AS labels
@@ -78,23 +197,65 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
 
     for (const e of enums) {
       const labels = e.labels.map((l) => `'${l.replace(/'/g, "''")}'`).join(", ");
-      emit(`CREATE TYPE "public"."${e.typname}" AS ENUM (${labels});`);
+      emitStatement(`CREATE TYPE "public"."${e.typname}" AS ENUM (${labels});`);
     }
     if (enums.length > 0) emit("");
 
-    // Get tables in dependency order (referenced tables first)
-    const tables = await sql<{ tablename: string }[]>`
-      SELECT c.relname AS tablename
-      FROM pg_class c
-      JOIN pg_namespace n ON n.oid = c.relnamespace
-      WHERE n.nspname = 'public'
-        AND c.relkind = 'r'
-        AND c.relname != '__drizzle_migrations'
-      ORDER BY c.relname
+    const allSequences = await sql<SequenceDefinition[]>`
+      SELECT
+        s.sequence_schema,
+        s.sequence_name,
+        s.data_type,
+        s.start_value,
+        s.minimum_value,
+        s.maximum_value,
+        s.increment,
+        s.cycle_option,
+        tblns.nspname AS owner_schema,
+        tbl.relname AS owner_table,
+        attr.attname AS owner_column
+      FROM information_schema.sequences s
+      JOIN pg_class seq ON seq.relname = s.sequence_name
+      JOIN pg_namespace n ON n.oid = seq.relnamespace AND n.nspname = s.sequence_schema
+      LEFT JOIN pg_depend dep ON dep.objid = seq.oid AND dep.deptype = 'a'
+      LEFT JOIN pg_class tbl ON tbl.oid = dep.refobjid
+      LEFT JOIN pg_namespace tblns ON tblns.oid = tbl.relnamespace
+      LEFT JOIN pg_attribute attr ON attr.attrelid = tbl.oid AND attr.attnum = dep.refobjsubid
+      WHERE s.sequence_schema = 'public'
+         OR (${includeMigrationJournal}::boolean AND s.sequence_schema = ${DRIZZLE_SCHEMA})
+      ORDER BY s.sequence_schema, s.sequence_name
     `;
+    const sequences = allSequences.filter(
+      (seq) => !seq.owner_table || includedTableNames.has(tableKey(seq.owner_schema ?? "public", seq.owner_table)),
+    );
+
+    const schemas = new Set<string>();
+    for (const table of tables) schemas.add(table.schema_name);
+    for (const seq of sequences) schemas.add(seq.sequence_schema);
+    const extraSchemas = [...schemas].filter((schemaName) => schemaName !== "public");
+    if (extraSchemas.length > 0) {
+      emit("-- Schemas");
+      for (const schemaName of extraSchemas) {
+        emitStatement(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schemaName)};`);
+      }
+      emit("");
+    }
+
+    if (sequences.length > 0) {
+      emit("-- Sequences");
+      for (const seq of sequences) {
+        const qualifiedSequenceName = quoteQualifiedName(seq.sequence_schema, seq.sequence_name);
+        emitStatement(`DROP SEQUENCE IF EXISTS ${qualifiedSequenceName} CASCADE;`);
+        emitStatement(
+          `CREATE SEQUENCE ${qualifiedSequenceName} AS ${seq.data_type} INCREMENT BY ${seq.increment} MINVALUE ${seq.minimum_value} MAXVALUE ${seq.maximum_value} START WITH ${seq.start_value}${seq.cycle_option === "YES" ? " CYCLE" : " NO CYCLE"};`,
+        );
+      }
+      emit("");
+    }
 
     // Get full CREATE TABLE DDL via column info
-    for (const { tablename } of tables) {
+    for (const { schema_name, tablename } of tables) {
+      const qualifiedTableName = quoteQualifiedName(schema_name, tablename);
       const columns = await sql<{
         column_name: string;
         data_type: string;
@@ -108,12 +269,12 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
         SELECT column_name, data_type, udt_name, is_nullable, column_default,
                character_maximum_length, numeric_precision, numeric_scale
         FROM information_schema.columns
-        WHERE table_schema = 'public' AND table_name = ${tablename}
+        WHERE table_schema = ${schema_name} AND table_name = ${tablename}
         ORDER BY ordinal_position
       `;
 
-      emit(`-- Table: ${tablename}`);
-      emit(`DROP TABLE IF EXISTS "${tablename}" CASCADE;`);
+      emit(`-- Table: ${schema_name}.${tablename}`);
+      emitStatement(`DROP TABLE IF EXISTS ${qualifiedTableName} CASCADE;`);
 
       const colDefs: string[] = [];
       for (const col of columns) {
@@ -149,7 +310,7 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
         JOIN pg_class t ON t.oid = c.conrelid
         JOIN pg_namespace n ON n.oid = t.relnamespace
         JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(c.conkey)
-        WHERE n.nspname = 'public' AND t.relname = ${tablename} AND c.contype = 'p'
+        WHERE n.nspname = ${schema_name} AND t.relname = ${tablename} AND c.contype = 'p'
         GROUP BY c.conname
       `;
       for (const p of pk) {
@@ -157,17 +318,31 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
         colDefs.push(`  CONSTRAINT "${p.constraint_name}" PRIMARY KEY (${cols})`);
       }
 
-      emit(`CREATE TABLE "${tablename}" (`);
+      emit(`CREATE TABLE ${qualifiedTableName} (`);
       emit(colDefs.join(",\n"));
       emit(");");
+      emitStatementBoundary();
+      emit("");
+    }
+
+    const ownedSequences = sequences.filter((seq) => seq.owner_table && seq.owner_column);
+    if (ownedSequences.length > 0) {
+      emit("-- Sequence ownership");
+      for (const seq of ownedSequences) {
+        emitStatement(
+          `ALTER SEQUENCE ${quoteQualifiedName(seq.sequence_schema, seq.sequence_name)} OWNED BY ${quoteQualifiedName(seq.owner_schema ?? "public", seq.owner_table!)}.${quoteIdentifier(seq.owner_column!)};`,
+        );
+      }
       emit("");
     }
 
     // Foreign keys (after all tables created)
-    const fks = await sql<{
+    const allForeignKeys = await sql<{
       constraint_name: string;
+      source_schema: string;
       source_table: string;
       source_columns: string[];
+      target_schema: string;
       target_table: string;
       target_columns: string[];
       update_rule: string;
@@ -175,137 +350,157 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
     }[]>`
       SELECT
         c.conname AS constraint_name,
+        srcn.nspname AS source_schema,
         src.relname AS source_table,
         array_agg(sa.attname ORDER BY array_position(c.conkey, sa.attnum)) AS source_columns,
+        tgtn.nspname AS target_schema,
         tgt.relname AS target_table,
         array_agg(ta.attname ORDER BY array_position(c.confkey, ta.attnum)) AS target_columns,
         CASE c.confupdtype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS update_rule,
         CASE c.confdeltype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS delete_rule
       FROM pg_constraint c
       JOIN pg_class src ON src.oid = c.conrelid
+      JOIN pg_namespace srcn ON srcn.oid = src.relnamespace
       JOIN pg_class tgt ON tgt.oid = c.confrelid
-      JOIN pg_namespace n ON n.oid = src.relnamespace
+      JOIN pg_namespace tgtn ON tgtn.oid = tgt.relnamespace
       JOIN pg_attribute sa ON sa.attrelid = src.oid AND sa.attnum = ANY(c.conkey)
       JOIN pg_attribute ta ON ta.attrelid = tgt.oid AND ta.attnum = ANY(c.confkey)
-      WHERE c.contype = 'f' AND n.nspname = 'public'
-      GROUP BY c.conname, src.relname, tgt.relname, c.confupdtype, c.confdeltype
-      ORDER BY src.relname, c.conname
+      WHERE c.contype = 'f' AND (
+        srcn.nspname = 'public'
+        OR (${includeMigrationJournal}::boolean AND srcn.nspname = ${DRIZZLE_SCHEMA})
+      )
+      GROUP BY c.conname, srcn.nspname, src.relname, tgtn.nspname, tgt.relname, c.confupdtype, c.confdeltype
+      ORDER BY srcn.nspname, src.relname, c.conname
     `;
+    const fks = allForeignKeys.filter(
+      (fk) => includedTableNames.has(tableKey(fk.source_schema, fk.source_table))
+        && includedTableNames.has(tableKey(fk.target_schema, fk.target_table)),
+    );
 
     if (fks.length > 0) {
       emit("-- Foreign keys");
       for (const fk of fks) {
         const srcCols = fk.source_columns.map((c) => `"${c}"`).join(", ");
         const tgtCols = fk.target_columns.map((c) => `"${c}"`).join(", ");
-        emit(
-          `ALTER TABLE "${fk.source_table}" ADD CONSTRAINT "${fk.constraint_name}" FOREIGN KEY (${srcCols}) REFERENCES "${fk.target_table}" (${tgtCols}) ON UPDATE ${fk.update_rule} ON DELETE ${fk.delete_rule};`,
+        emitStatement(
+          `ALTER TABLE ${quoteQualifiedName(fk.source_schema, fk.source_table)} ADD CONSTRAINT "${fk.constraint_name}" FOREIGN KEY (${srcCols}) REFERENCES ${quoteQualifiedName(fk.target_schema, fk.target_table)} (${tgtCols}) ON UPDATE ${fk.update_rule} ON DELETE ${fk.delete_rule};`,
         );
       }
       emit("");
     }
 
     // Unique constraints
-    const uniques = await sql<{
+    const allUniqueConstraints = await sql<{
       constraint_name: string;
+      schema_name: string;
       tablename: string;
       column_names: string[];
     }[]>`
       SELECT c.conname AS constraint_name,
+             n.nspname AS schema_name,
              t.relname AS tablename,
              array_agg(a.attname ORDER BY array_position(c.conkey, a.attnum)) AS column_names
       FROM pg_constraint c
       JOIN pg_class t ON t.oid = c.conrelid
       JOIN pg_namespace n ON n.oid = t.relnamespace
       JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(c.conkey)
-      WHERE n.nspname = 'public' AND c.contype = 'u'
-      GROUP BY c.conname, t.relname
-      ORDER BY t.relname, c.conname
+      WHERE c.contype = 'u' AND (
+        n.nspname = 'public'
+        OR (${includeMigrationJournal}::boolean AND n.nspname = ${DRIZZLE_SCHEMA})
+      )
+      GROUP BY c.conname, n.nspname, t.relname
+      ORDER BY n.nspname, t.relname, c.conname
     `;
+    const uniques = allUniqueConstraints.filter((entry) => includedTableNames.has(tableKey(entry.schema_name, entry.tablename)));
 
     if (uniques.length > 0) {
       emit("-- Unique constraints");
       for (const u of uniques) {
         const cols = u.column_names.map((c) => `"${c}"`).join(", ");
-        emit(`ALTER TABLE "${u.tablename}" ADD CONSTRAINT "${u.constraint_name}" UNIQUE (${cols});`);
+        emitStatement(`ALTER TABLE ${quoteQualifiedName(u.schema_name, u.tablename)} ADD CONSTRAINT "${u.constraint_name}" UNIQUE (${cols});`);
       }
       emit("");
     }
 
     // Indexes (non-primary, non-unique-constraint)
-    const indexes = await sql<{ indexdef: string }[]>`
-      SELECT indexdef
+    const allIndexes = await sql<{ schema_name: string; tablename: string; indexdef: string }[]>`
+      SELECT schemaname AS schema_name, tablename, indexdef
       FROM pg_indexes
-      WHERE schemaname = 'public'
-        AND indexname NOT IN (
-          SELECT conname FROM pg_constraint
-          WHERE connamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'public')
+      WHERE (
+          schemaname = 'public'
+          OR (${includeMigrationJournal}::boolean AND schemaname = ${DRIZZLE_SCHEMA})
         )
-      ORDER BY tablename, indexname
+        AND indexname NOT IN (
+          SELECT conname FROM pg_constraint c
+          JOIN pg_namespace n ON n.oid = c.connamespace
+          WHERE n.nspname = pg_indexes.schemaname
+        )
+      ORDER BY schemaname, tablename, indexname
     `;
+    const indexes = allIndexes.filter((entry) => includedTableNames.has(tableKey(entry.schema_name, entry.tablename)));
 
     if (indexes.length > 0) {
       emit("-- Indexes");
       for (const idx of indexes) {
-        emit(`${idx.indexdef};`);
+        emitStatement(`${idx.indexdef};`);
       }
       emit("");
     }
 
     // Dump data for each table
-    for (const { tablename } of tables) {
-      const count = await sql<{ n: number }[]>`
-        SELECT count(*)::int AS n FROM ${sql(tablename)}
-      `;
-      if ((count[0]?.n ?? 0) === 0) continue;
+    for (const { schema_name, tablename } of tables) {
+      const qualifiedTableName = quoteQualifiedName(schema_name, tablename);
+      const count = await sql.unsafe<{ n: number }[]>(`SELECT count(*)::int AS n FROM ${qualifiedTableName}`);
+      if (excludedTableNames.has(tablename) || (count[0]?.n ?? 0) === 0) continue;
 
       // Get column info for this table
       const cols = await sql<{ column_name: string; data_type: string }[]>`
         SELECT column_name, data_type
         FROM information_schema.columns
-        WHERE table_schema = 'public' AND table_name = ${tablename}
+        WHERE table_schema = ${schema_name} AND table_name = ${tablename}
         ORDER BY ordinal_position
       `;
       const colNames = cols.map((c) => `"${c.column_name}"`).join(", ");
 
-      emit(`-- Data for: ${tablename} (${count[0]!.n} rows)`);
+      emit(`-- Data for: ${schema_name}.${tablename} (${count[0]!.n} rows)`);
 
-      const rows = await sql`SELECT * FROM ${sql(tablename)}`.values();
+      const rows = await sql.unsafe(`SELECT * FROM ${qualifiedTableName}`).values();
+      const nullifiedColumns = nullifiedColumnsByTable.get(tablename) ?? new Set<string>();
       for (const row of rows) {
-        const values = row.map((val: unknown) => {
+        const values = row.map((rawValue: unknown, index) => {
+          const columnName = cols[index]?.column_name;
+          const val = columnName && nullifiedColumns.has(columnName) ? null : rawValue;
           if (val === null || val === undefined) return "NULL";
           if (typeof val === "boolean") return val ? "true" : "false";
           if (typeof val === "number") return String(val);
-          if (val instanceof Date) return `'${val.toISOString()}'`;
-          if (typeof val === "object") return `'${JSON.stringify(val).replace(/'/g, "''")}'`;
-          return `'${String(val).replace(/'/g, "''")}'`;
+          if (val instanceof Date) return formatSqlLiteral(val.toISOString());
+          if (typeof val === "object") return formatSqlLiteral(JSON.stringify(val));
+          return formatSqlLiteral(String(val));
         });
-        emit(`INSERT INTO "${tablename}" (${colNames}) VALUES (${values.join(", ")});`);
+        emitStatement(`INSERT INTO ${qualifiedTableName} (${colNames}) VALUES (${values.join(", ")});`);
       }
       emit("");
     }
 
     // Sequence values
-    const sequences = await sql<{ sequence_name: string }[]>`
-      SELECT sequence_name
-      FROM information_schema.sequences
-      WHERE sequence_schema = 'public'
-      ORDER BY sequence_name
-    `;
-
     if (sequences.length > 0) {
       emit("-- Sequence values");
       for (const seq of sequences) {
-        const val = await sql<{ last_value: string }[]>`
-          SELECT last_value::text FROM ${sql(seq.sequence_name)}
-        `;
-        if (val[0]) {
-          emit(`SELECT setval('"${seq.sequence_name}"', ${val[0].last_value});`);
+        const qualifiedSequenceName = quoteQualifiedName(seq.sequence_schema, seq.sequence_name);
+        const val = await sql.unsafe<{ last_value: string; is_called: boolean }[]>(
+          `SELECT last_value::text, is_called FROM ${qualifiedSequenceName}`,
+        );
+        const skipSequenceValue =
+          seq.owner_table !== null
+            && excludedTableNames.has(seq.owner_table);
+        if (val[0] && !skipSequenceValue) {
+          emitStatement(`SELECT setval('${qualifiedSequenceName.replaceAll("'", "''")}', ${val[0].last_value}, ${val[0].is_called ? "true" : "false"});`);
         }
       }
       emit("");
     }
 
-    emit("COMMIT;");
+    emitStatement("COMMIT;");
     emit("");
 
     // Write the backup file
@@ -326,6 +521,36 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
   }
 }
 
+export async function runDatabaseRestore(opts: RunDatabaseRestoreOptions): Promise<void> {
+  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+
+  try {
+    await sql`SELECT 1`;
+    const contents = await readFile(opts.backupFile, "utf8");
+    const statements = contents
+      .split(STATEMENT_BREAKPOINT)
+      .map((statement) => statement.trim())
+      .filter((statement) => statement.length > 0);
+
+    for (const statement of statements) {
+      await sql.unsafe(statement).execute();
+    }
+  } catch (error) {
+    const statementPreview = typeof error === "object" && error !== null && typeof (error as Record<string, unknown>).query === "string"
+      ? String((error as Record<string, unknown>).query)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0 && !line.startsWith("--"))
+      : null;
+    throw new Error(
+      `Failed to restore ${basename(opts.backupFile)}: ${sanitizeRestoreErrorMessage(error)}${statementPreview ? ` [statement: ${statementPreview.slice(0, 120)}]` : ""}`,
+    );
+  } finally {
+    await sql.end();
+  }
+}
+
 export function formatDatabaseBackupResult(result: RunDatabaseBackupResult): string {
   const size = formatBackupSize(result.sizeBytes);
   const pruned = result.prunedCount > 0 ? `; pruned ${result.prunedCount} old backup(s)` : "";

packages/db/src/client.test.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { afterEach, describe, expect, it } from "vitest";
+import postgres from "postgres";
+import {
+  applyPendingMigrations,
+  inspectMigrations,
+} from "./client.js";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./test-embedded-postgres.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+async function createTempDatabase(): Promise<string> {
+  const db = await startEmbeddedPostgresTestDatabase("paperclip-db-client-");
+  cleanups.push(db.cleanup);
+  return db.connectionString;
+}
+
+async function migrationHash(migrationFile: string): Promise<string> {
+  const content = await fs.promises.readFile(
+    new URL(`./migrations/${migrationFile}`, import.meta.url),
+    "utf8",
+  );
+  return createHash("sha256").update(content).digest("hex");
+}
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    const cleanup = cleanups.pop();
+    await cleanup?.();
+  }
+});
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres migration tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("applyPendingMigrations", () => {
+  it(
+    "applies an inserted earlier migration without replaying later legacy migrations",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const richMagnetoHash = await migrationHash("0030_rich_magneto.sql");
+
+        await sql.unsafe(
+          `DELETE FROM "drizzle"."__drizzle_migrations" WHERE hash = '${richMagnetoHash}'`,
+        );
+        await sql.unsafe(`DROP TABLE "company_logos"`);
+      } finally {
+        await sql.end();
+      }
+
+      const pendingState = await inspectMigrations(connectionString);
+      expect(pendingState).toMatchObject({
+        status: "needsMigrations",
+        pendingMigrations: ["0030_rich_magneto.sql"],
+        reason: "pending-migrations",
+      });
+
+      await applyPendingMigrations(connectionString);
+
+      const finalState = await inspectMigrations(connectionString);
+      expect(finalState.status).toBe("upToDate");
+
+      const verifySql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const rows = await verifySql.unsafe<{ table_name: string }[]>(
+          `
+            SELECT table_name
+            FROM information_schema.tables
+            WHERE table_schema = 'public'
+              AND table_name IN ('company_logos', 'execution_workspaces')
+            ORDER BY table_name
+          `,
+        );
+        expect(rows.map((row) => row.table_name)).toEqual([
+          "company_logos",
+          "execution_workspaces",
+        ]);
+      } finally {
+        await verifySql.end();
+      }
+    },
+    20_000,
+  );
+
+  it(
+    "replays migration 0044 safely when its schema changes already exist",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const illegalToadHash = await migrationHash("0044_illegal_toad.sql");
+
+        await sql.unsafe(
+          `DELETE FROM "drizzle"."__drizzle_migrations" WHERE hash = '${illegalToadHash}'`,
+        );
+
+        const columns = await sql.unsafe<{ column_name: string }[]>(
+          `
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_schema = 'public'
+              AND table_name = 'instance_settings'
+              AND column_name = 'general'
+          `,
+        );
+        expect(columns).toHaveLength(1);
+      } finally {
+        await sql.end();
+      }
+
+      const pendingState = await inspectMigrations(connectionString);
+      expect(pendingState).toMatchObject({
+        status: "needsMigrations",
+        pendingMigrations: ["0044_illegal_toad.sql"],
+        reason: "pending-migrations",
+      });
+
+      await applyPendingMigrations(connectionString);
+
+      const finalState = await inspectMigrations(connectionString);
+      expect(finalState.status).toBe("upToDate");
+    },
+    20_000,
+  );
+
+  it(
+    "enforces a unique board_api_keys.key_hash after migration 0044",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        await sql.unsafe(`
+          INSERT INTO "user" ("id", "name", "email", "email_verified", "created_at", "updated_at")
+          VALUES ('user-1', 'User One', 'user@example.com', true, now(), now())
+        `);
+        await sql.unsafe(`
+          INSERT INTO "board_api_keys" ("id", "user_id", "name", "key_hash", "created_at")
+          VALUES ('00000000-0000-0000-0000-000000000001', 'user-1', 'Key One', 'dup-hash', now())
+        `);
+        await expect(
+          sql.unsafe(`
+            INSERT INTO "board_api_keys" ("id", "user_id", "name", "key_hash", "created_at")
+            VALUES ('00000000-0000-0000-0000-000000000002', 'user-1', 'Key Two', 'dup-hash', now())
+          `),
+        ).rejects.toThrow();
+      } finally {
+        await sql.end();
+      }
+    },
+    20_000,
+  );
+});

packages/db/src/client.ts

@@ -10,6 +10,10 @@ const MIGRATIONS_FOLDER = fileURLToPath(new URL("./migrations", import.meta.url)
 const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
 const MIGRATIONS_JOURNAL_JSON = fileURLToPath(new URL("./migrations/meta/_journal.json", import.meta.url));
 
+function createUtilitySql(url: string) {
+  return postgres(url, { max: 1, onnotice: () => {} });
+}
+
 function isSafeIdentifier(value: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
 }
@@ -46,6 +50,21 @@ export function createDb(url: string) {
   return drizzlePg(sql, { schema });
 }
 
+export async function getPostgresDataDirectory(url: string): Promise<string | null> {
+  const sql = createUtilitySql(url);
+  try {
+    const rows = await sql<{ data_directory: string | null }[]>`
+      SELECT current_setting('data_directory', true) AS data_directory
+    `;
+    const actual = rows[0]?.data_directory;
+    return typeof actual === "string" && actual.length > 0 ? actual : null;
+  } catch {
+    return null;
+  } finally {
+    await sql.end();
+  }
+}
+
 async function listMigrationFiles(): Promise<string[]> {
   const entries = await readdir(MIGRATIONS_FOLDER, { withFileTypes: true });
   return entries
@@ -223,7 +242,7 @@ async function applyPendingMigrationsManually(
     journalEntries.map((entry) => [entry.fileName, normalizeFolderMillis(entry.folderMillis)]),
   );
 
-  const sql = postgres(url, { max: 1 });
+  const sql = createUtilitySql(url);
   try {
     const { migrationTableSchema, columnNames } = await ensureMigrationJournalTable(sql);
     const qualifiedTable = `${quoteIdentifier(migrationTableSchema)}.${quoteIdentifier(DRIZZLE_MIGRATIONS_TABLE)}`;
@@ -472,7 +491,7 @@ export async function reconcilePendingMigrationHistory(
     return { repairedMigrations: [], remainingMigrations: [] };
   }
 
-  const sql = postgres(url, { max: 1 });
+  const sql = createUtilitySql(url);
   const repairedMigrations: string[] = [];
 
   try {
@@ -579,7 +598,7 @@ async function discoverMigrationTableSchema(sql: ReturnType<typeof postgres>): P
 }
 
 export async function inspectMigrations(url: string): Promise<MigrationState> {
-  const sql = postgres(url, { max: 1 });
+  const sql = createUtilitySql(url);
 
   try {
     const availableMigrations = await listMigrationFiles();
@@ -642,13 +661,37 @@ export async function applyPendingMigrations(url: string): Promise<void> {
   const initialState = await inspectMigrations(url);
   if (initialState.status === "upToDate") return;
 
-  const sql = postgres(url, { max: 1 });
+  if (initialState.reason === "no-migration-journal-empty-db") {
+    const sql = createUtilitySql(url);
+    try {
+      const db = drizzlePg(sql);
+      await migratePg(db, { migrationsFolder: MIGRATIONS_FOLDER });
+    } finally {
+      await sql.end();
+    }
 
-  try {
-    const db = drizzlePg(sql);
-    await migratePg(db, { migrationsFolder: MIGRATIONS_FOLDER });
-  } finally {
-    await sql.end();
+    let bootstrappedState = await inspectMigrations(url);
+    if (bootstrappedState.status === "upToDate") return;
+    if (bootstrappedState.reason === "pending-migrations") {
+      const repair = await reconcilePendingMigrationHistory(url);
+      if (repair.repairedMigrations.length > 0) {
+        bootstrappedState = await inspectMigrations(url);
+      }
+      if (bootstrappedState.status === "needsMigrations" && bootstrappedState.reason === "pending-migrations") {
+        await applyPendingMigrationsManually(url, bootstrappedState.pendingMigrations);
+        bootstrappedState = await inspectMigrations(url);
+      }
+    }
+    if (bootstrappedState.status === "upToDate") return;
+    throw new Error(
+      `Failed to bootstrap migrations: ${bootstrappedState.pendingMigrations.join(", ")}`,
+    );
+  }
+
+  if (initialState.reason === "no-migration-journal-non-empty-db") {
+    throw new Error(
+      "Database has tables but no migration journal; automatic migration is unsafe. Initialize migration history manually.",
+    );
   }
 
   let state = await inspectMigrations(url);
@@ -661,7 +704,7 @@ export async function applyPendingMigrations(url: string): Promise<void> {
   }
 
   if (state.status !== "needsMigrations" || state.reason !== "pending-migrations") {
-    throw new Error("Migrations are still pending after attempted apply; run inspectMigrations for details.");
+    throw new Error("Migrations are still pending after migration-history reconciliation; run inspectMigrations for details.");
   }
 
   await applyPendingMigrationsManually(url, state.pendingMigrations);
@@ -680,7 +723,7 @@ export type MigrationBootstrapResult =
   | { migrated: false; reason: "not-empty-no-migration-journal"; tableCount: number };
 
 export async function migratePostgresIfEmpty(url: string): Promise<MigrationBootstrapResult> {
-  const sql = postgres(url, { max: 1 });
+  const sql = createUtilitySql(url);
 
   try {
     const migrationTableSchema = await discoverMigrationTableSchema(sql);
@@ -719,14 +762,14 @@ export async function ensurePostgresDatabase(
     throw new Error(`Unsafe database name: ${databaseName}`);
   }
 
-  const sql = postgres(url, { max: 1 });
+  const sql = createUtilitySql(url);
   try {
     const existing = await sql<{ one: number }[]>`
       select 1 as one from pg_database where datname = ${databaseName} limit 1
     `;
     if (existing.length > 0) return "exists";
 
-    await sql.unsafe(`create database "${databaseName}"`);
+    await sql.unsafe(`create database "${databaseName}" encoding 'UTF8' lc_collate 'C' lc_ctype 'C' template template0`);
     return "created";
   } finally {
     await sql.end();

packages/db/src/embedded-postgres-error.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createEmbeddedPostgresLogBuffer, formatEmbeddedPostgresError } from "./embedded-postgres-error.js";
+
+describe("formatEmbeddedPostgresError", () => {
+  it("adds a shared-memory hint when initdb logs expose the real cause", () => {
+    const error = formatEmbeddedPostgresError("Postgres init script exited with code 1.", {
+      fallbackMessage: "Failed to initialize embedded PostgreSQL cluster",
+      recentLogs: [
+        "running bootstrap script ...",
+        "FATAL:  could not create shared memory segment: Cannot allocate memory",
+        "DETAIL:  Failed system call was shmget(key=123, size=56, 03600).",
+      ],
+    });
+
+    expect(error.message).toContain("could not allocate shared memory");
+    expect(error.message).toContain("kern.sysv.shm");
+    expect(error.message).toContain("could not create shared memory segment");
+  });
+
+  it("keeps only recent non-empty log lines in the collector", () => {
+    const buffer = createEmbeddedPostgresLogBuffer(2);
+    buffer.append("line one\n\n");
+    buffer.append("line two");
+    buffer.append("line three");
+
+    expect(buffer.getRecentLogs()).toEqual(["line two", "line three"]);
+  });
+});

packages/db/src/embedded-postgres-error.ts

@@ -0,0 +1,89 @@
+const DEFAULT_RECENT_LOG_LIMIT = 40;
+const RECENT_LOG_SUMMARY_LINES = 8;
+
+function toError(error: unknown, fallbackMessage: string): Error {
+  if (error instanceof Error) return error;
+  if (error === undefined) return new Error(fallbackMessage);
+  if (typeof error === "string") return new Error(`${fallbackMessage}: ${error}`);
+
+  try {
+    return new Error(`${fallbackMessage}: ${JSON.stringify(error)}`);
+  } catch {
+    return new Error(`${fallbackMessage}: ${String(error)}`);
+  }
+}
+
+function summarizeRecentLogs(recentLogs: string[]): string | null {
+  if (recentLogs.length === 0) return null;
+  return recentLogs
+    .slice(-RECENT_LOG_SUMMARY_LINES)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .join(" | ");
+}
+
+function detectEmbeddedPostgresHint(recentLogs: string[]): string | null {
+  const haystack = recentLogs.join("\n").toLowerCase();
+  if (!haystack.includes("could not create shared memory segment")) {
+    return null;
+  }
+
+  return (
+    "Embedded PostgreSQL bootstrap could not allocate shared memory. " +
+    "On macOS, this usually means the host's kern.sysv.shm* limits are too low for another local PostgreSQL cluster. " +
+    "Stop other local PostgreSQL servers or raise the shared-memory sysctls, then retry."
+  );
+}
+
+export function createEmbeddedPostgresLogBuffer(limit = DEFAULT_RECENT_LOG_LIMIT): {
+  append(message: unknown): void;
+  getRecentLogs(): string[];
+} {
+  const recentLogs: string[] = [];
+
+  return {
+    append(message: unknown) {
+      const text =
+        typeof message === "string"
+          ? message
+          : message instanceof Error
+            ? message.message
+            : String(message ?? "");
+
+      for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line) continue;
+        recentLogs.push(line);
+        if (recentLogs.length > limit) {
+          recentLogs.splice(0, recentLogs.length - limit);
+        }
+      }
+    },
+    getRecentLogs() {
+      return [...recentLogs];
+    },
+  };
+}
+
+export function formatEmbeddedPostgresError(
+  error: unknown,
+  input: {
+    fallbackMessage: string;
+    recentLogs?: string[];
+  },
+): Error {
+  const baseError = toError(error, input.fallbackMessage);
+  const recentLogs = input.recentLogs ?? [];
+  const parts = [baseError.message];
+  const hint = detectEmbeddedPostgresHint(recentLogs);
+  const recentSummary = summarizeRecentLogs(recentLogs);
+
+  if (hint) {
+    parts.push(hint);
+  }
+  if (recentSummary) {
+    parts.push(`Recent embedded Postgres logs: ${recentSummary}`);
+  }
+
+  return new Error(parts.join(" "));
+}

packages/db/src/index.ts

@@ -1,5 +1,6 @@
 export {
   createDb,
+  getPostgresDataDirectory,
   ensurePostgresDatabase,
   inspectMigrations,
   applyPendingMigrations,
@@ -10,10 +11,22 @@ export {
   type MigrationBootstrapResult,
   type Db,
 } from "./client.js";
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "./test-embedded-postgres.js";
 export {
   runDatabaseBackup,
+  runDatabaseRestore,
   formatDatabaseBackupResult,
   type RunDatabaseBackupOptions,
   type RunDatabaseBackupResult,
+  type RunDatabaseRestoreOptions,
 } from "./backup-lib.js";
+export {
+  createEmbeddedPostgresLogBuffer,
+  formatEmbeddedPostgresError,
+} from "./embedded-postgres-error.js";
 export * from "./schema/index.js";

packages/db/src/migrate.ts

@@ -1,21 +1,29 @@
 import { applyPendingMigrations, inspectMigrations } from "./client.js";
+import { resolveMigrationConnection } from "./migration-runtime.js";
 
-const url = process.env.DATABASE_URL;
+async function main(): Promise<void> {
+  const resolved = await resolveMigrationConnection();
 
-if (!url) {
-  throw new Error("DATABASE_URL is required for db:migrate");
-}
+  console.log(`Migrating database via ${resolved.source}`);
 
-const before = await inspectMigrations(url);
-if (before.status === "upToDate") {
-  console.log("No pending migrations");
-} else {
-  console.log(`Applying ${before.pendingMigrations.length} pending migration(s)...`);
-  await applyPendingMigrations(url);
+  try {
+    const before = await inspectMigrations(resolved.connectionString);
+    if (before.status === "upToDate") {
+      console.log("No pending migrations");
+      return;
+    }
 
-  const after = await inspectMigrations(url);
-  if (after.status !== "upToDate") {
-    throw new Error(`Migrations incomplete: ${after.pendingMigrations.join(", ")}`);
+    console.log(`Applying ${before.pendingMigrations.length} pending migration(s)...`);
+    await applyPendingMigrations(resolved.connectionString);
+
+    const after = await inspectMigrations(resolved.connectionString);
+    if (after.status !== "upToDate") {
+      throw new Error(`Migrations incomplete: ${after.pendingMigrations.join(", ")}`);
+    }
+    console.log("Migrations complete");
+  } finally {
+    await resolved.stop();
   }
-  console.log("Migrations complete");
 }
+
+await main();

packages/db/src/migration-runtime.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import path from "node:path";
+import { ensurePostgresDatabase, getPostgresDataDirectory } from "./client.js";
+import { createEmbeddedPostgresLogBuffer, formatEmbeddedPostgresError } from "./embedded-postgres-error.js";
+import { resolveDatabaseTarget } from "./runtime-config.js";
+
+type EmbeddedPostgresInstance = {
+  initialise(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+};
+
+type EmbeddedPostgresCtor = new (opts: {
+  databaseDir: string;
+  user: string;
+  password: string;
+  port: number;
+  persistent: boolean;
+  initdbFlags?: string[];
+  onLog?: (message: unknown) => void;
+  onError?: (message: unknown) => void;
+}) => EmbeddedPostgresInstance;
+
+export type MigrationConnection = {
+  connectionString: string;
+  source: string;
+  stop: () => Promise<void>;
+};
+
+function readRunningPostmasterPid(postmasterPidFile: string): number | null {
+  if (!existsSync(postmasterPidFile)) return null;
+  try {
+    const pid = Number(readFileSync(postmasterPidFile, "utf8").split("\n")[0]?.trim());
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+function readPidFilePort(postmasterPidFile: string): number | null {
+  if (!existsSync(postmasterPidFile)) return null;
+  try {
+    const lines = readFileSync(postmasterPidFile, "utf8").split("\n");
+    const port = Number(lines[3]?.trim());
+    return Number.isInteger(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+async function isPortInUse(port: number): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (error: NodeJS.ErrnoException) => {
+      resolve(error.code === "EADDRINUSE");
+    });
+    server.listen(port, "127.0.0.1", () => {
+      server.close();
+      resolve(false);
+    });
+  });
+}
+
+async function findAvailablePort(startPort: number): Promise<number> {
+  const maxLookahead = 20;
+  let port = startPort;
+  for (let i = 0; i < maxLookahead; i += 1, port += 1) {
+    if (!(await isPortInUse(port))) return port;
+  }
+  throw new Error(
+    `Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}`,
+  );
+}
+
+async function loadEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
+  try {
+    const mod = await import("embedded-postgres");
+    return mod.default as EmbeddedPostgresCtor;
+  } catch {
+    throw new Error(
+      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
+    );
+  }
+}
+
+async function ensureEmbeddedPostgresConnection(
+  dataDir: string,
+  preferredPort: number,
+): Promise<MigrationConnection> {
+  const EmbeddedPostgres = await loadEmbeddedPostgresCtor();
+  const selectedPort = await findAvailablePort(preferredPort);
+  const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
+  const pgVersionFile = path.resolve(dataDir, "PG_VERSION");
+  const runningPid = readRunningPostmasterPid(postmasterPidFile);
+  const runningPort = readPidFilePort(postmasterPidFile);
+  const preferredAdminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/postgres`;
+  const logBuffer = createEmbeddedPostgresLogBuffer();
+
+  if (!runningPid && existsSync(pgVersionFile)) {
+    try {
+      const actualDataDir = await getPostgresDataDirectory(preferredAdminConnectionString);
+      const matchesDataDir =
+        typeof actualDataDir === "string" &&
+        path.resolve(actualDataDir) === path.resolve(dataDir);
+      if (!matchesDataDir) {
+        throw new Error("reachable postgres does not use the expected embedded data directory");
+      }
+      await ensurePostgresDatabase(preferredAdminConnectionString, "paperclip");
+      process.emitWarning(
+        `Adopting an existing PostgreSQL instance on port ${preferredPort} for embedded data dir ${dataDir} because postmaster.pid is missing.`,
+      );
+      return {
+        connectionString: `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/paperclip`,
+        source: `embedded-postgres@${preferredPort}`,
+        stop: async () => {},
+      };
+    } catch {
+      // Fall through and attempt to start the configured embedded cluster.
+    }
+  }
+
+  if (runningPid) {
+    const port = runningPort ?? preferredPort;
+    const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
+    await ensurePostgresDatabase(adminConnectionString, "paperclip");
+    return {
+      connectionString: `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`,
+      source: `embedded-postgres@${port}`,
+      stop: async () => {},
+    };
+  }
+
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port: selectedPort,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: logBuffer.append,
+    onError: logBuffer.append,
+  });
+
+  if (!existsSync(path.resolve(dataDir, "PG_VERSION"))) {
+    try {
+      await instance.initialise();
+    } catch (error) {
+      throw formatEmbeddedPostgresError(error, {
+        fallbackMessage:
+          `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${selectedPort}`,
+        recentLogs: logBuffer.getRecentLogs(),
+      });
+    }
+  }
+  if (existsSync(postmasterPidFile)) {
+    rmSync(postmasterPidFile, { force: true });
+  }
+  try {
+    await instance.start();
+  } catch (error) {
+    throw formatEmbeddedPostgresError(error, {
+      fallbackMessage: `Failed to start embedded PostgreSQL on port ${selectedPort}`,
+      recentLogs: logBuffer.getRecentLogs(),
+    });
+  }
+
+  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${selectedPort}/postgres`;
+  await ensurePostgresDatabase(adminConnectionString, "paperclip");
+
+  return {
+    connectionString: `postgres://paperclip:paperclip@127.0.0.1:${selectedPort}/paperclip`,
+    source: `embedded-postgres@${selectedPort}`,
+    stop: async () => {
+      await instance.stop();
+    },
+  };
+}
+
+export async function resolveMigrationConnection(): Promise<MigrationConnection> {
+  const target = resolveDatabaseTarget();
+  if (target.mode === "postgres") {
+    return {
+      connectionString: target.connectionString,
+      source: target.source,
+      stop: async () => {},
+    };
+  }
+
+  return ensureEmbeddedPostgresConnection(target.dataDir, target.port);
+}

packages/db/src/migration-status.ts

@@ -0,0 +1,61 @@
+import { inspectMigrations } from "./client.js";
+import { resolveMigrationConnection } from "./migration-runtime.js";
+
+const jsonMode = process.argv.includes("--json");
+
+function toError(error: unknown, context = "Migration status check failed"): Error {
+  if (error instanceof Error) return error;
+  if (error === undefined) return new Error(context);
+  if (typeof error === "string") return new Error(`${context}: ${error}`);
+
+  try {
+    return new Error(`${context}: ${JSON.stringify(error)}`);
+  } catch {
+    return new Error(`${context}: ${String(error)}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const connection = await resolveMigrationConnection();
+
+  try {
+    const state = await inspectMigrations(connection.connectionString);
+    const payload =
+      state.status === "upToDate"
+        ? {
+            source: connection.source,
+            status: "upToDate" as const,
+            tableCount: state.tableCount,
+            pendingMigrations: [] as string[],
+          }
+        : {
+            source: connection.source,
+            status: "needsMigrations" as const,
+            tableCount: state.tableCount,
+            pendingMigrations: state.pendingMigrations,
+            reason: state.reason,
+          };
+
+    if (jsonMode) {
+      console.log(JSON.stringify(payload));
+      return;
+    }
+
+    if (payload.status === "upToDate") {
+      console.log(`Database is up to date via ${payload.source}`);
+      return;
+    }
+
+    console.log(
+      `Pending migrations via ${payload.source}: ${payload.pendingMigrations.join(", ")}`,
+    );
+  } finally {
+    await connection.stop();
+  }
+}
+
+main().catch((error) => {
+  const err = toError(error, "Migration status check failed");
+  process.stderr.write(`${err.stack ?? err.message}\n`);
+  process.exit(1);
+});