merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/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;
+}

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

@@ -0,0 +1,606 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import {
+  asString,
+  asNumber,
+  asBoolean,
+  asStringArray,
+  parseObject,
+  buildPaperclipEnv,
+  redactEnvForLogs,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
+  ensurePathInEnv,
+  readPaperclipRuntimeSkillEntries,
+  resolvePaperclipDesiredSkillNames,
+  renderTemplate,
+  joinPromptSections,
+  runChildProcess,
+} from "@paperclipai/adapter-utils/server-utils";
+import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
+import { pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir } from "./codex-home.js";
+import { resolveCodexDesiredSkillNames } from "./skills.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+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;
+
+function stripCodexRolloutNoise(text: string): string {
+  const parts = text.split(/\r?\n/);
+  const kept: string[] = [];
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) {
+      kept.push(part);
+      continue;
+    }
+    if (CODEX_ROLLOUT_NOISE_RE.test(trimmed)) continue;
+    kept.push(part);
+  }
+  return kept.join("\n");
+}
+
+function firstNonEmptyLine(text: string): string {
+  return (
+    text
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean) ?? ""
+  );
+}
+
+function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
+  const raw = env[key];
+  return typeof raw === "string" && raw.trim().length > 0;
+}
+
+function resolveCodexBillingType(env: Record<string, string>): "api" | "subscription" {
+  // Codex uses API-key auth when OPENAI_API_KEY is present; otherwise rely on local login/session auth.
+  return hasNonEmptyEnvValue(env, "OPENAI_API_KEY") ? "api" : "subscription";
+}
+
+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 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;
+  }
+
+  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 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(() => []);
+
+  for (const entry of entries) {
+    if (allowed.has(entry.name) || !entry.isSymbolicLink()) continue;
+
+    const target = path.join(skillsHome, entry.name);
+    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 resolveCodexWorkspaceSkillsDir(cwd: string): string {
+  return path.join(cwd, ".agents", "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 ?? resolveCodexWorkspaceSkillsDir(process.cwd());
+  await fs.mkdir(skillsHome, { recursive: true });
+  const linkSkill = options.linkSkill;
+  for (const entry of skillsEntries) {
+    const target = path.join(skillsHome, entry.runtimeName);
+
+    try {
+      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(
+        "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.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, onSpawn, authToken } = ctx;
+
+  const promptTemplate = asString(
+    config.promptTemplate,
+    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  );
+  const command = asString(config.command, "codex");
+  const model = asString(config.model, "");
+  const modelReasoningEffort = asString(
+    config.modelReasoningEffort,
+    asString(config.reasoningEffort, ""),
+  );
+  const search = asBoolean(config.search, false);
+  const bypass = asBoolean(
+    config.dangerouslyBypassApprovalsAndSandbox,
+    asBoolean(config.dangerouslyBypassSandbox, false),
+  );
+
+  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();
+  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 });
+  const codexWorkspaceSkillsDir = resolveCodexWorkspaceSkillsDir(cwd);
+  await ensureCodexSkillsInjected(
+    onLog,
+    {
+      skillsHome: codexWorkspaceSkillsDir,
+      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()) ||
+    (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 (workspaceStrategy) {
+    env.PAPERCLIP_WORKSPACE_STRATEGY = workspaceStrategy;
+  }
+  if (workspaceId) {
+    env.PAPERCLIP_WORKSPACE_ID = workspaceId;
+  }
+  if (workspaceRepoUrl) {
+    env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
+  }
+  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 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 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] 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");
+      instructionsPrefix =
+        `${instructionsContents}\n\n` +
+        `The above agent instructions were loaded from ${instructionsFilePath}. ` +
+        `Resolve any relative file references from ${instructionsDir}.\n\n`;
+      instructionsChars = instructionsPrefix.length;
+    } 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 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 [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 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,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
+
+  const buildArgs = (resumeSessionId: string | null) => {
+    const args = ["exec", "--json"];
+    if (search) args.unshift("--search");
+    if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
+    if (model) args.push("--model", model);
+    if (modelReasoningEffort) args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+    if (extraArgs.length > 0) args.push(...extraArgs);
+    if (resumeSessionId) args.push("resume", resumeSessionId, "-");
+    else args.push("-");
+    return args;
+  };
+
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildArgs(resumeSessionId);
+    if (onMeta) {
+      await onMeta({
+        adapterType: "codex_local",
+        command,
+        cwd,
+        commandNotes,
+        commandArgs: args.map((value, idx) => {
+          if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;
+          return value;
+        }),
+        env: redactEnvForLogs(env),
+        prompt,
+        promptMetrics,
+        context,
+      });
+    }
+
+    const proc = await runChildProcess(runId, command, args, {
+      cwd,
+      env,
+      stdin: prompt,
+      timeoutSec,
+      graceSec,
+      onSpawn,
+      onLog: async (stream, chunk) => {
+        if (stream !== "stderr") {
+          await onLog(stream, chunk);
+          return;
+        }
+        const cleaned = stripCodexRolloutNoise(chunk);
+        if (!cleaned.trim()) return;
+        await onLog(stream, cleaned);
+      },
+    });
+    const cleanedStderr = stripCodexRolloutNoise(proc.stderr);
+    return {
+      proc: {
+        ...proc,
+        stderr: cleanedStderr,
+      },
+      rawStderr: proc.stderr,
+      parsed: parseCodexJsonl(proc.stdout),
+    };
+  };
+
+  const toResult = (
+    attempt: { proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string }; rawStderr: string; parsed: ReturnType<typeof parseCodexJsonl> },
+    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 ?? 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 fallbackErrorMessage =
+      parsedError ||
+      stderrLine ||
+      `Codex 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,
+      usage: attempt.parsed.usage,
+      sessionId: resolvedSessionId,
+      sessionParams: resolvedSessionParams,
+      sessionDisplayId: resolvedSessionId,
+      provider: "openai",
+      biller: resolveCodexBiller(effectiveEnv, billingType),
+      model,
+      billingType,
+      costUsd: null,
+      resultJson: {
+        stdout: attempt.proc.stdout,
+        stderr: attempt.proc.stderr,
+      },
+      summary: attempt.parsed.summary,
+      clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
+    };
+  };
+
+  const initial = await runAttempt(sessionId);
+  if (
+    sessionId &&
+    !initial.proc.timedOut &&
+    (initial.proc.exitCode ?? 0) !== 0 &&
+    isCodexUnknownSessionError(initial.proc.stdout, initial.rawStderr)
+  ) {
+    await onLog(
+      "stdout",
+      `[paperclip] Codex resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+    );
+    const retry = await runAttempt(null);
+    return toResult(retry, true);
+  }
+
+  return toResult(initial);
+}

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

@@ -0,0 +1,66 @@
+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 {
+  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);
+    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);
+    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);
+  },
+};

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

@@ -0,0 +1,73 @@
+import { asString, asNumber, parseObject, parseJson } from "@paperclipai/adapter-utils/server-utils";
+
+export function parseCodexJsonl(stdout: string) {
+  let sessionId: string | null = null;
+  const messages: string[] = [];
+  let errorMessage: 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 type = asString(event.type, "");
+    if (type === "thread.started") {
+      sessionId = asString(event.thread_id, sessionId ?? "") || sessionId;
+      continue;
+    }
+
+    if (type === "error") {
+      const msg = asString(event.message, "").trim();
+      if (msg) errorMessage = msg;
+      continue;
+    }
+
+    if (type === "item.completed") {
+      const item = parseObject(event.item);
+      if (asString(item.type, "") === "agent_message") {
+        const text = asString(item.text, "");
+        if (text) messages.push(text);
+      }
+      continue;
+    }
+
+    if (type === "turn.completed") {
+      const usageObj = parseObject(event.usage);
+      usage.inputTokens = asNumber(usageObj.input_tokens, usage.inputTokens);
+      usage.cachedInputTokens = asNumber(usageObj.cached_input_tokens, usage.cachedInputTokens);
+      usage.outputTokens = asNumber(usageObj.output_tokens, usage.outputTokens);
+      continue;
+    }
+
+    if (type === "turn.failed") {
+      const err = parseObject(event.error);
+      const msg = asString(err.message, "").trim();
+      if (msg) errorMessage = msg;
+    }
+  }
+
+  return {
+    sessionId,
+    summary: messages.join("\n\n").trim(),
+    usage,
+    errorMessage,
+  };
+}
+
+export function isCodexUnknownSessionError(stdout: string, stderr: string): boolean {
+  const haystack = `${stdout}\n${stderr}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+  return /unknown (session|thread)|session .* not found|thread .* not found|conversation .* not found|missing rollout path for thread|state db missing rollout path/i.test(
+    haystack,
+  );
+}

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

@@ -0,0 +1,556 @@
+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();
+    });
+  }
+
+  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: [],
+  };
+}

paperclip-reference/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 workspace .agents/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);
+}

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

@@ -0,0 +1,235 @@
+import type {
+  AdapterEnvironmentCheck,
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+  asString,
+  asBoolean,
+  asStringArray,
+  parseObject,
+  ensureAbsoluteDirectory,
+  ensureCommandResolvable,
+  ensurePathInEnv,
+  runChildProcess,
+} 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";
+  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 firstNonEmptyLine(text: string): string {
+  return (
+    text
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean) ?? ""
+  );
+}
+
+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;
+}
+
+const CODEX_AUTH_REQUIRED_RE =
+  /(?:not\s+logged\s+in|login\s+required|authentication\s+required|unauthorized|invalid(?:\s+or\s+missing)?\s+api(?:[_\s-]?key)?|openai[_\s-]?api[_\s-]?key|api[_\s-]?key.*required|please\s+run\s+`?codex\s+login`?)/i;
+
+export async function testEnvironment(
+  ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+  const checks: AdapterEnvironmentCheck[] = [];
+  const config = parseObject(ctx.config);
+  const command = asString(config.command, "codex");
+  const cwd = asString(config.cwd, process.cwd());
+
+  try {
+    await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+    checks.push({
+      code: "codex_cwd_valid",
+      level: "info",
+      message: `Working directory is valid: ${cwd}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "codex_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: "codex_command_resolvable",
+      level: "info",
+      message: `Command is executable: ${command}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "codex_command_unresolvable",
+      level: "error",
+      message: err instanceof Error ? err.message : "Command is not executable",
+      detail: command,
+    });
+  }
+
+  const configOpenAiKey = env.OPENAI_API_KEY;
+  const hostOpenAiKey = process.env.OPENAI_API_KEY;
+  if (isNonEmpty(configOpenAiKey) || isNonEmpty(hostOpenAiKey)) {
+    const source = isNonEmpty(configOpenAiKey) ? "adapter config env" : "server environment";
+    checks.push({
+      code: "codex_openai_api_key_present",
+      level: "info",
+      message: "OPENAI_API_KEY is set for Codex authentication.",
+      detail: `Detected in ${source}.`,
+    });
+  } else {
+    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 =
+    checks.every((check) => check.code !== "codex_cwd_invalid" && check.code !== "codex_command_unresolvable");
+  if (canRunProbe) {
+    if (!commandLooksLike(command, "codex")) {
+      checks.push({
+        code: "codex_hello_probe_skipped_custom_command",
+        level: "info",
+        message: "Skipped hello probe because command is not `codex`.",
+        detail: command,
+        hint: "Use the `codex` CLI command to run the automatic login and installation probe.",
+      });
+    } else {
+      const model = asString(config.model, "").trim();
+      const modelReasoningEffort = asString(
+        config.modelReasoningEffort,
+        asString(config.reasoningEffort, ""),
+      ).trim();
+      const search = asBoolean(config.search, false);
+      const bypass = asBoolean(
+        config.dangerouslyBypassApprovalsAndSandbox,
+        asBoolean(config.dangerouslyBypassSandbox, false),
+      );
+      const extraArgs = (() => {
+        const fromExtraArgs = asStringArray(config.extraArgs);
+        if (fromExtraArgs.length > 0) return fromExtraArgs;
+        return asStringArray(config.args);
+      })();
+
+      const args = ["exec", "--json"];
+      if (search) args.unshift("--search");
+      if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
+      if (model) args.push("--model", model);
+      if (modelReasoningEffort) {
+        args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+      }
+      if (extraArgs.length > 0) args.push(...extraArgs);
+      args.push("-");
+
+      const probe = await runChildProcess(
+        `codex-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+        command,
+        args,
+        {
+          cwd,
+          env,
+          timeoutSec: 45,
+          graceSec: 5,
+          stdin: "Respond with hello.",
+          onLog: async () => {},
+        },
+      );
+      const parsed = parseCodexJsonl(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: "codex_hello_probe_timed_out",
+          level: "warn",
+          message: "Codex hello probe timed out.",
+          hint: "Retry the probe. If this persists, verify Codex 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 ? "codex_hello_probe_passed" : "codex_hello_probe_unexpected_output",
+          level: hasHello ? "info" : "warn",
+          message: hasHello
+            ? "Codex hello probe succeeded."
+            : "Codex probe ran but did not return `hello` as expected.",
+          ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+          ...(hasHello
+            ? {}
+            : {
+                hint: "Try the probe manually (`codex exec --json -` then prompt: Respond with hello) to inspect full output.",
+              }),
+        });
+      } else if (CODEX_AUTH_REQUIRED_RE.test(authEvidence)) {
+        checks.push({
+          code: "codex_hello_probe_auth_required",
+          level: "warn",
+          message: "Codex CLI is installed, but authentication is not ready.",
+          ...(detail ? { detail } : {}),
+          hint: "Configure OPENAI_API_KEY in adapter env/shell or run `codex login`, then retry the probe.",
+        });
+      } else {
+        checks.push({
+          code: "codex_hello_probe_failed",
+          level: "error",
+          message: "Codex hello probe failed.",
+          ...(detail ? { detail } : {}),
+          hint: "Run `codex exec --json -` manually in this working directory and prompt `Respond with hello` to debug.",
+        });
+      }
+    }
+  }
+
+  return {
+    adapterType: ctx.adapterType,
+    status: summarizeStatus(checks),
+    checks,
+    testedAt: new Date().toISOString(),
+  };
+}