@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/codex-effective-config.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { codexConfigOverrides, isRecord, RETIRED_SHARED_MCP_SERVER_NAMES } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "../adapter";
+import { providerHomePathFor, providerSourceHome } from "../profile-home";
+import { hostProviderDefaultArgs } from "../host-asset-plan";
+
+/** Mirror native config precedence for launch policies that inspect inherited and caller settings. */
+export function readCodexConfig(configArgs: string[], codexHome?: string, cwd?: string, trusted = false): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+  const file = codexHome ? join(codexHome, "config.toml") : undefined;
+  try {
+    if (file && existsSync(file)) mergeConfig(config, Bun.TOML.parse(readFileSync(file, "utf8")) as Record<string, unknown>);
+  } catch { /* Codex refuses an unparseable config.toml itself. */ }
+  if (cwd) {
+    const dirs: string[] = [];
+    for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+      dirs.push(dir);
+      if (existsSync(join(dir, ".git")) || dirname(dir) === dir) break;
+    }
+    const projects = isRecord(config.projects) ? config.projects : {};
+    // #3476 — no repository means cwd-only settings; trust in a nested cwd never trusts its ancestors.
+    if (!existsSync(join(dirs.at(-1)!, ".git"))) dirs.splice(1);
+    let projectTrusted = false;
+    for (const dir of dirs.reverse()) {
+      const trust = projects[dir];
+      if (isRecord(trust) && typeof trust.trust_level === "string") projectTrusted = trust.trust_level === "trusted";
+      else if (dir === resolve(cwd) && trusted) projectTrusted = true;
+      if (!projectTrusted) continue;
+      try {
+        const file = join(dir, ".codex", "config.toml");
+        if (existsSync(file)) mergeConfig(config, Bun.TOML.parse(readFileSync(file, "utf8")) as Record<string, unknown>);
+      } catch { /* Codex handles invalid project configuration. */ }
+    }
+  }
+  for (const override of codexConfigOverrides(configArgs)) {
+    const eq = override.indexOf("=");
+    if (eq > 0) setDotted(config, override.slice(0, eq).trim().split("."), codexOverrideValue(override.slice(eq + 1)));
+  }
+  return config;
+}
+
+export function codexRetiredMcpConfigArgs(config: RunnerSpawnConfig): string[] {
+  const isolatedHome = providerHomePathFor("codex", config);
+  const inheritedHome = isolatedHome ?? config.env.CODEX_HOME ?? providerSourceHome("codex");
+  const args = [...hostProviderDefaultArgs(config), ...config.providerArgs];
+  const effective = readCodexConfig(args, inheritedHome, config.cwd, !!isolatedHome).mcp_servers;
+  if (!isRecord(effective)) return [];
+  return RETIRED_SHARED_MCP_SERVER_NAMES.flatMap(name => {
+    const server = effective[name];
+    return isRecord(server) && (typeof server.command === "string" || typeof server.url === "string")
+      ? ["-c", `mcp_servers.${name}.enabled=false`] : [];
+  });
+}
+
+function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    if (isRecord(value)) {
+      if (!Object.hasOwn(target, key) || !isRecord(target[key])) target[key] = {};
+      mergeConfig(target[key] as Record<string, unknown>, value);
+    } else target[key] = value;
+  }
+}
+
+/** Codex parses a `-c` value as TOML and falls back to the literal string. */
+function codexOverrideValue(raw: string): unknown {
+  try {
+    return (Bun.TOML.parse(`v = ${raw}`) as { v: unknown }).v;
+  } catch {
+    return raw;
+  }
+}
+
+function setDotted(target: Record<string, unknown>, keys: string[], value: unknown): void {
+  if (keys.some(key => key === "__proto__" || key === "constructor" || key === "prototype")) return;
+  let node = target;
+  for (const key of keys.slice(0, -1)) {
+    if (!Object.hasOwn(node, key) || !isRecord(node[key])) node[key] = {};
+    node = node[key] as Record<string, unknown>;
+  }
+  const key = keys[keys.length - 1]!;
+  if (isRecord(value)) {
+    node[key] = {};
+    mergeConfig(node[key] as Record<string, unknown>, value);
+  } else node[key] = value;
+}

package/src/adapters/codex-launch-config.ts

@@ -0,0 +1,153 @@
+// Codex launch/config-arg construction: the `-c` override builders, CLI command
+// resolution (shim detection), and the tool-output token limit. Extracted from
+// codex.ts (file-size ratchet, epic #291); codex.ts re-exports these so existing
+// consumers + tests keep their import path.
+import { accessSync, constants, realpathSync } from "node:fs";
+import { basename, join } from "node:path";
+import { harnessSubagentsEnabled, isRecord, parseCodexFlagArgs } from "@humwick/sdk";
+import { profileAllowsRelayFeature, type ProviderConfig, type RunnerSpawnConfig, type SpawnArgs } from "../adapter";
+import { hostProviderDefaultArgs } from "../host-asset-plan";
+import { bundledSkillConfigArgs } from "../launch-assembly";
+import { codexRetiredMcpConfigArgs } from "./codex-effective-config";
+import { codexWebToolsConfigArgs } from "../web-tools";
+import { tomlString } from "../relay-mcp";
+
+export const DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT = 12_000;
+
+// #1248 — default background-terminal poll window (300000ms/5min) is too short for
+// our long-running commands (tests/releases run 5+ min), forcing agents to poll
+// instead of just waiting. Verified against installed codex-cli's source (rust-v0.144.0):
+// `background_terminal_max_timeout` is a top-level Config field — it replaced the older
+// `background_terminal_timeout` key — and IS correctly threaded through: ConfigManager
+// replays these launch `-c` overrides for every thread (config/mod.rs,
+// app-server/src/config_manager.rs), so `UnifiedExecProcessManager` (unified_exec/mod.rs)
+// is built with this raised ceiling and the `write_stdin` handler clamps empty-poll
+// yield_time_ms against it (unified_exec/process_manager.rs). The config value alone does
+// NOT make agents wait longer, though: codex's `write_stdin` tool schema
+// (tools/handlers/shell_spec.rs::create_write_stdin_tool) ships a hardcoded description —
+// "empty polls wait 5000-300000 ms by default" — that never reflects this override, so a
+// model sees no signal it may request more and keeps polling at ~300000ms. That's why a
+// live probe still saw ~300.001s polls after this override landed. We deliberately do NOT
+// advertise longer polls to the model (#2776): agents are steered to end the turn and take the wake.
+const CODEX_BACKGROUND_TERMINAL_MAX_TIMEOUT_MS = 900000;
+
+export function codexModelConfigArgs(model?: string, effort?: string): string[] {
+  const args: string[] = [];
+  if (model) args.push("-c", `model=${tomlString(model)}`);
+  if (effort) args.push("-c", `model_reasoning_effort=${tomlString(effort)}`);
+  // The catalog alias `astra` resolves to this provider model before runner launch.
+  if (model === "gpt-6-astra") {
+    args.push("-c", "model_context_window=1000000", "-c", "model_auto_compact_token_limit=272000");
+  }
+  return args;
+}
+
+export function codexApprovalConfigArgs(approvalMode?: string): string[] {
+  const sandboxMode = approvalMode === "open"
+    ? "danger-full-access"
+    : approvalMode === "read-only"
+      ? "read-only"
+      : "workspace-write";
+  return [
+    "-c",
+    'approval_policy="never"',
+    "-c",
+    `sandbox_mode=${tomlString(sandboxMode)}`,
+  ];
+}
+
+// #1248 — see CODEX_BACKGROUND_TERMINAL_MAX_TIMEOUT_MS above.
+export function codexManagedConfigArgs(): string[] {
+  return [
+    "-c",
+    "check_for_update_on_startup=false",
+    "-c",
+    `background_terminal_max_timeout=${CODEX_BACKGROUND_TERMINAL_MAX_TIMEOUT_MS}`,
+  ];
+}
+
+/** Production-shared construction of the optional visible Codex TUI invocation. */
+export function buildCodexTuiSpawnArgs(
+  config: RunnerSpawnConfig,
+  providerConfig: ProviderConfig,
+  appServerUrl: string,
+  env: Record<string, string>,
+): SpawnArgs | undefined {
+  if (config.headless || !isCodexCliCommand(providerConfig.command)) return undefined;
+  const relaySkillArgs = profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : [];
+  const defaultArgs = hostProviderDefaultArgs(config, providerConfig);
+  return {
+    command: providerConfig.command,
+    args: ["--remote", appServerUrl, ...relaySkillArgs, ...defaultArgs, ...config.providerArgs, ...codexManagedConfigArgs(), ...codexHarnessConfigArgs(config), ...codexWebToolsConfigArgs(config), ...codexRetiredMcpConfigArgs(config)],
+    cwd: config.cwd,
+    env,
+  };
+}
+
+export function isCodexCliCommand(command: string): boolean {
+  return basename(command) === "codex";
+}
+
+export function resolveRealCodexCommand(command: string, pathValue = process.env.PATH || ""): string {
+  const candidates: string[] = [];
+  if (command.includes("/")) candidates.push(command);
+  for (const dir of pathValue.split(":").filter(Boolean)) candidates.push(join(dir, "codex"));
+
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (!isExecutableFile(candidate)) continue;
+    const real = realPath(candidate);
+    if (isHumwickCodexShim(candidate) || isHumwickCodexShim(real)) continue;
+    return candidate;
+  }
+  return command;
+}
+
+function isExecutableFile(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function isHumwickCodexShim(path: string): boolean {
+  return path.includes("/.agent-relay/codex/bin/codex");
+}
+
+export function codexAppServerConfigArgs(...argLists: string[][]): string[] {
+  return argLists.flatMap((args) => parseCodexFlagArgs(args).flatMap((a) => a.tokens));
+}
+
+export function codexToolOutputTokenLimitConfigArgs(config: Pick<RunnerSpawnConfig, "agentProfile">): string[] {
+  const configured = codexToolOutputTokenLimit(config.agentProfile?.providerOptions);
+  if (configured === null) return [];
+  const limit = configured ?? DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT;
+  return ["-c", `tool_output_token_limit=${limit}`];
+}
+
+function codexToolOutputTokenLimit(providerOptions: unknown): number | null | undefined {
+  if (!isRecord(providerOptions)) return undefined;
+  const codex = providerOptions.codex;
+  if (!isRecord(codex)) return undefined;
+  const limit = codex.toolOutputTokenLimit;
+  return typeof limit === "number" || limit === null ? limit : undefined;
+}
+
+// CLI overrides outrank host config and caller -c flags, including the newer agent harness.
+export function codexHarnessConfigArgs(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">): string[] {
+  const codex = config.agentProfile?.providerOptions?.codex;
+  return ["-c", `agents.enabled=${harnessSubagentsEnabled(config)}`, "-c", `features.multi_agent=${harnessSubagentsEnabled(config)}`, "-c", "features.multi_agent_v2=false",
+    ...(config.agentProfile ? ["-c", `features.image_generation=${isRecord(codex) && codex.imageGeneration === true}`] : [])];
+}

package/src/adapters/codex-rollout-context.ts

@@ -0,0 +1,272 @@
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ContextState } from "@humwick/sdk";
+import { isRecord, stringValue } from "@humwick/sdk";
+import type { ManagedProcess } from "../adapter";
+import { providerContextState } from "../transcript-context";
+import { incrementalFileNeedsReset, readIncrementalFileRangeSync, splitIncrementalFileLines, statIncrementalFileSync, type IncrementalFileInfo, type IncrementalFileLineBuffer, type IncrementalFileLinePolicy, type IncrementalFilePosition } from "./incremental-file";
+
+/** The `{usage, total, last}` triple both codexTokenUsageContext (this file) and
+ *  codexTokenUsageReport (codex-token-usage-capture.ts) read out of a token-usage
+ *  payload — the app-server's `thread/tokenUsage/updated` params or a rollout
+ *  `token_count` payload share the same field-name variants (camelCase live,
+ *  snake_case in the rollout). One resolver so the variant list can't drift (#2483). */
+export interface CodexUsageSections {
+  usage: Record<string, unknown>;
+  total?: Record<string, unknown>;
+  last?: Record<string, unknown>;
+}
+
+export function codexUsageSections(params: Record<string, unknown> | undefined): CodexUsageSections | undefined {
+  const usage = isRecord(params?.tokenUsage) ? params.tokenUsage
+    : isRecord(params?.token_usage) ? params.token_usage
+    : isRecord(params?.usage) ? params.usage
+    : isRecord(params?.info) ? params.info
+    : params;
+  if (!usage) return undefined;
+  const total = isRecord(usage.total) ? usage.total
+    : isRecord(usage.totalTokenUsage) ? usage.totalTokenUsage
+    : isRecord(usage.total_token_usage) ? usage.total_token_usage
+    : undefined;
+  const last = isRecord(usage.last) ? usage.last
+    : isRecord(usage.lastTokenUsage) ? usage.lastTokenUsage
+    : isRecord(usage.last_token_usage) ? usage.last_token_usage
+    : undefined;
+  return { usage, total, last };
+}
+
+export function codexTokenUsageContext(params: Record<string, unknown> | undefined, now = Date.now()): ContextState | undefined {
+  const sections = codexUsageSections(params);
+  if (!sections) return undefined;
+  const { usage, total, last } = sections;
+  const tokensUsed = numberValue(last?.totalTokens) ?? numberValue(last?.total_tokens) ??
+    numberValue(total?.totalTokens) ?? numberValue(total?.total_tokens) ??
+    numberValue(usage.totalTokens) ?? numberValue(usage.total_tokens);
+  const tokensMax = numberValue(usage.modelContextWindow) ?? numberValue(usage.model_context_window) ??
+    numberValue(params?.modelContextWindow) ?? numberValue(params?.model_context_window);
+  if (tokensUsed === undefined || tokensMax === undefined || tokensMax <= 0) return undefined;
+  return providerContextState(tokensUsed, tokensMax, now);
+}
+
+export function latestCodexContext(process: ManagedProcess): ContextState | undefined {
+  const meta = process.meta ?? {};
+  const current = isContextState(meta.context) ? meta.context : undefined;
+  const explicitPath = stringValue(meta.threadPath);
+  const threadId = stringValue(meta.threadId);
+  const rolloutPath = explicitPath ?? (threadId ? findCodexRolloutPath(threadId) : undefined);
+  if (!rolloutPath) return current;
+  const reader = meta[ROLLOUT_CONTEXT_READER_KEY] instanceof CodexRolloutContextReader
+    ? meta[ROLLOUT_CONTEXT_READER_KEY]
+    : new CodexRolloutContextReader();
+  const candidate = reader.read(rolloutPath);
+  const context = candidate && (!current || candidate.lastUpdatedAt >= current.lastUpdatedAt) ? candidate : undefined;
+  process.meta = context
+    ? { ...meta, context, threadPath: rolloutPath, [ROLLOUT_CONTEXT_READER_KEY]: reader }
+    : { ...meta, threadPath: rolloutPath, [ROLLOUT_CONTEXT_READER_KEY]: reader };
+  return context ?? current;
+}
+
+const ROLLOUT_CONTEXT_READER_KEY = "codexRolloutContextReader";
+/** Backward initialization reads a fixed chunk at a time, never the whole rollout. */
+export const CODEX_ROLLOUT_CONTEXT_SCAN_BYTES = 64 * 1024;
+/** Limit synchronous reset recovery to a bounded amount of a very large/no-token rollout. */
+export const CODEX_ROLLOUT_CONTEXT_INITIAL_SCAN_MAX_BYTES = 1024 * 1024;
+/** Codex token_count entries are tiny; cap a malformed non-token partial at one MiB. */
+export const CODEX_ROLLOUT_CONTEXT_PARTIAL_MAX_BYTES = 1024 * 1024;
+const CODEX_ROLLOUT_CONTEXT_LINE_POLICY: IncrementalFileLinePolicy = { maxPartialBytes: CODEX_ROLLOUT_CONTEXT_PARTIAL_MAX_BYTES };
+
+export interface CodexRolloutContextReaderDeps {
+  stat?: (path: string) => IncrementalFileInfo;
+  /** Read bytes in [start, end). Kept injectable so the no-history-reread contract is testable. */
+  readRange?: (path: string, start: number, end: number) => Uint8Array;
+}
+
+interface InitialScanResult {
+  context?: ContextState;
+  partial?: Buffer;
+}
+
+/**
+ * Incremental rollout reader for the synchronous heartbeat path. Once initialized,
+ * every appended byte is read exactly once; rotation/truncation re-initializes with a
+ * bounded backwards scan that stops as soon as it finds the latest token_count.
+ */
+export class CodexRolloutContextReader {
+  private position: IncrementalFilePosition | undefined;
+  private lineBuffer: IncrementalFileLineBuffer = {};
+
+  constructor(private readonly deps: CodexRolloutContextReaderDeps = {}) {}
+
+  read(path: string): ContextState | undefined {
+    let info: IncrementalFileInfo;
+    try {
+      info = (this.deps.stat ?? statIncrementalFileSync)(path);
+    } catch {
+      return undefined;
+    }
+
+    if (incrementalFileNeedsReset(this.position, path, info)) {
+      const initial = this.readLatestFromEnd(path, info.size);
+      if (initial === null) return undefined;
+      this.position = { path, ino: info.ino, offset: info.size };
+      this.lineBuffer = initial.partial ? { partial: initial.partial } : {};
+      return initial.context;
+    }
+    const position = this.position;
+    if (!position || info.size <= position.offset) return undefined;
+
+    let data: Buffer;
+    try {
+      // A delayed heartbeat can have a large append. Read all of it: each byte is
+      // consumed once from the committed watermark, so steady-state cost is O(new bytes).
+      data = Buffer.from((this.deps.readRange ?? readIncrementalFileRangeSync)(path, position.offset, info.size));
+    } catch {
+      return undefined;
+    }
+    const complete = splitIncrementalFileLines(this.lineBuffer, data, CODEX_ROLLOUT_CONTEXT_LINE_POLICY);
+    const context = codexRolloutContextFromLines(complete.lines);
+    position.offset += data.length;
+    this.lineBuffer = complete.buffer;
+    return context;
+  }
+
+  /** Returns null when a read fails; successful scans retain the trailing partial JSONL line. */
+  private readLatestFromEnd(path: string, size: number): InitialScanResult | null {
+    let end = size;
+    let scanned = 0;
+    let suffix: Buffer | undefined;
+    let trailing: Buffer | undefined;
+    while (end > 0 && scanned < CODEX_ROLLOUT_CONTEXT_INITIAL_SCAN_MAX_BYTES) {
+      const length = Math.min(CODEX_ROLLOUT_CONTEXT_SCAN_BYTES, CODEX_ROLLOUT_CONTEXT_INITIAL_SCAN_MAX_BYTES - scanned);
+      const start = Math.max(0, end - length);
+      let data: Buffer;
+      try {
+        const chunk = Buffer.from((this.deps.readRange ?? readIncrementalFileRangeSync)(path, start, end));
+        data = suffix?.length ? Buffer.concat([chunk, suffix]) : chunk;
+      } catch {
+        return null;
+      }
+      scanned += end - start;
+      if (!trailing) {
+        const lastNewline = data.lastIndexOf(0x0a);
+        if (lastNewline >= 0) trailing = data.subarray(lastNewline + 1);
+        else if (start === 0) trailing = data;
+      }
+      const context = codexRolloutContextFromText(data.toString("utf8"));
+      if (context) return { context, partial: trailing?.length ? trailing : undefined };
+      if (start === 0) return { partial: trailing?.length ? trailing : undefined };
+
+      // Preserve the leading partial line for the next chunk. This assembles a
+      // token_count record larger than one chunk without retaining rollout history.
+      const firstNewline = data.indexOf(0x0a);
+      suffix = firstNewline >= 0 ? data.subarray(0, firstNewline + 1) : data;
+      end = start;
+    }
+    return { partial: trailing?.length ? trailing : undefined };
+  }
+}
+
+export function codexRolloutContextFromText(input: string): ContextState | undefined {
+  return codexRolloutContextFromLines(input.split(/\r?\n/));
+}
+
+function codexRolloutContextFromLines(lines: readonly (string | Buffer)[]): ContextState | undefined {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const raw = lines[i];
+    const line = (typeof raw === "string" ? raw : raw?.toString("utf8"))?.trim();
+    if (!line) continue;
+    let event: unknown;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(event)) continue;
+    const payload = isRecord(event.payload) ? event.payload : undefined;
+    if (payload?.type !== "token_count") continue;
+    const timestamp = typeof event.timestamp === "string" ? Date.parse(event.timestamp) : Date.now();
+    return codexTokenUsageContext(payload, Number.isFinite(timestamp) ? timestamp : Date.now());
+  }
+  return undefined;
+}
+
+export function findCodexRolloutPath(threadId: string): string | undefined {
+  const root = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+  return findFileContaining(root, threadId);
+}
+
+/**
+ * Fallback model resolution (#2483 review F2) for when the spawn config carries no
+ * `model` — a managed-policy/restart Codex spawn resolves with no explicit model
+ * (`skipDefaultWhenEmpty:true`), so the token-usage capture would otherwise skip
+ * every report for that agent forever, silently. The rollout records the resolved
+ * model on every `turn_context` event; a single bounded tail-end read (reused
+ * scan-size constant, no incremental state needed — this is a rare fallback path,
+ * not the per-heartbeat hot path `CodexRolloutContextReader` serves) finds the most
+ * recent one.
+ */
+export function codexModelFromRolloutPath(path: string, deps: CodexRolloutContextReaderDeps = {}): string | undefined {
+  let info: IncrementalFileInfo;
+  try {
+    info = (deps.stat ?? statIncrementalFileSync)(path);
+  } catch {
+    return undefined;
+  }
+  const start = Math.max(0, info.size - CODEX_ROLLOUT_CONTEXT_INITIAL_SCAN_MAX_BYTES);
+  let data: Buffer;
+  try {
+    data = Buffer.from((deps.readRange ?? readIncrementalFileRangeSync)(path, start, info.size));
+  } catch {
+    return undefined;
+  }
+  const lines = data.toString("utf8").split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+    let event: unknown;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(event) || event.type !== "turn_context") continue;
+    const payload = isRecord(event.payload) ? event.payload : event;
+    const model = stringValue(payload.model);
+    if (model) return model;
+  }
+  return undefined;
+}
+
+function findFileContaining(dir: string, needle: string, depth = 0): string | undefined {
+  if (depth > 8) return undefined;
+  let entries: Array<{ name: string; isFile(): boolean; isDirectory(): boolean }>;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  entries.sort((a, b) => b.name.localeCompare(a.name));
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isFile() && entry.name.includes(needle) && entry.name.endsWith(".jsonl")) return path;
+    if (entry.isDirectory()) {
+      const found = findFileContaining(path, needle, depth + 1);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+export function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}

package/src/adapters/codex-skill-discovery.ts

@@ -0,0 +1,18 @@
+import { errMessage } from "@humwick/sdk";
+import type { CodexAppClient } from "./codex-client";
+
+/** Register once before any thread starts. Codex owns catalog rendering; updating these
+ * roots later can re-inject its full catalog (#3694), so Relay supplies the complete set here. */
+export async function registerCodexSkillRoots(
+  client: Pick<CodexAppClient, "skillsSetExtraRoots">,
+  roots: string[],
+  warn: (message: string) => void,
+): Promise<void> {
+  if (!roots.length) return;
+  try {
+    // skills.config controls enablement, but does not add native discovery roots.
+    await client.skillsSetExtraRoots(roots);
+  } catch (error) {
+    warn(`Codex skills/extraRoots/set unavailable; continuing without exposing Relay skills at ${roots.join(", ")}: ${errMessage(error)}`);
+  }
+}