@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/agents/lib/source-context-scan.js

@@ -0,0 +1,388 @@
+import { opendirSync, realpathSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+/**
+ * Cheap, contents-free Source scan for Build Plan authoring.
+ *
+ * The Build Plan authoring agent locks a plan skeleton before reading any
+ * Source file. Without an inventory it defaults to a generic 4-stage plan
+ * for every Source. This scan gives the draft agent a real, task-agnostic
+ * map of the Source up front so it can shape stages to what is actually
+ * there.
+ *
+ * Guarantees:
+ * - Never opens or reads file contents. It only lists directory entries and
+ *   parses names/extensions. Source files stay read-only and unread.
+ * - Generic: no intent keywords, no task taxonomy, no per-Project answers.
+ *   It works for a folder of calls, PDFs, a codebase, or anything else.
+ * - O(file-listing) with hard caps so a pathological tree (deep nesting,
+ *   huge fan-out) can never turn the scan into a recursion or time bomb.
+ */
+const MAX_ENTRIES = 20000;
+const MAX_DEPTH = 6;
+const MAX_FOLDER_ITEMS = 40;
+const MAX_SAMPLE_NAMES = 6;
+const MAX_OBSERVATIONS = 24;
+const IGNORED_ENTRY_NAMES = new Set([
+    ".git",
+    ".interf",
+    "node_modules",
+    ".DS_Store",
+    ".cache",
+    "__pycache__",
+    ".venv",
+    ".svn",
+    ".hg",
+]);
+// Canonical, task-agnostic file kinds. Mirrors the Source Manifest kind
+// vocabulary (pdf, document, spreadsheet, presentation, image, text, other)
+// plus coarse buckets that are useful for plan shaping (code, data, audio,
+// video, archive). No kind is intent-specific.
+function classifyKind(extension) {
+    const ext = extension.replace(/^\./, "").toLowerCase();
+    if (!ext)
+        return "no-extension";
+    if (ext === "pdf")
+        return "pdf";
+    if (["doc", "docx", "rtf", "odt", "pages"].includes(ext))
+        return "document";
+    if (["csv", "tsv", "xls", "xlsx", "ods", "numbers", "parquet"].includes(ext)) {
+        return "spreadsheet";
+    }
+    if (["ppt", "pptx", "odp", "key"].includes(ext))
+        return "presentation";
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg", "heic", "tiff", "bmp"].includes(ext)) {
+        return "image";
+    }
+    if (["mp3", "wav", "m4a", "aac", "flac", "ogg", "aiff"].includes(ext))
+        return "audio";
+    if (["mp4", "mov", "avi", "mkv", "webm", "m4v"].includes(ext))
+        return "video";
+    if (["zip", "tar", "gz", "tgz", "bz2", "7z", "rar"].includes(ext))
+        return "archive";
+    if (["md", "markdown", "txt", "text"].includes(ext))
+        return "text";
+    if (["json", "ndjson", "yaml", "yml", "xml", "toml", "ini"].includes(ext))
+        return "data";
+    if ([
+        "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java",
+        "kt", "c", "h", "cpp", "hpp", "cs", "php", "swift", "sh", "sql", "html",
+        "css", "scss", "vue", "svelte",
+    ].includes(ext)) {
+        return "code";
+    }
+    return "other";
+}
+// Bare year (2019), year-month (2024-03, 2024_03), or full date
+// (2024-03-15, 20240315) appearing in a filename. Filename-only; we never
+// read file contents to find dates.
+const DATE_TOKEN = /\b(19|20)\d{2}([-_./]?(0[1-9]|1[0-2]))?([-_./]?(0[1-9]|[12]\d|3[01]))?\b/g;
+function extractDateTokens(name) {
+    const matches = name.match(DATE_TOKEN);
+    if (!matches)
+        return [];
+    return matches.filter((token) => /^(19|20)\d{2}/.test(token));
+}
+function makeFolder() {
+    return { fileCount: 0, kinds: new Map(), sampleNames: [] };
+}
+function recordFile(folder, name) {
+    folder.fileCount += 1;
+    const kind = classifyKind(extname(name));
+    folder.kinds.set(kind, (folder.kinds.get(kind) ?? 0) + 1);
+    if (folder.sampleNames.length < MAX_SAMPLE_NAMES) {
+        folder.sampleNames.push(name);
+    }
+}
+function kindSummary(kinds) {
+    return [...kinds.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, count]) => `${count} ${kind}`)
+        .join(", ");
+}
+/**
+ * Resolve a directory entry to a coarse type, following symlinks.
+ *
+ * `Dirent` reports the type of the entry itself, so a symlink is neither a
+ * file nor a directory and would be dropped. The Source can legitimately be
+ * (or contain) symlinked files and dirs — mirroring the repo walker in
+ * contracts/utils/filesystem.ts, we stat the link target and classify the
+ * entry as the target's type. Broken or inaccessible links resolve to
+ * "other" and are skipped. We never read file contents here.
+ */
+function resolveEntryType(fullPath, isSymlink, isDir, isFile) {
+    if (isDir)
+        return { type: "dir", realDir: null };
+    if (isFile)
+        return { type: "file", realDir: null };
+    if (!isSymlink)
+        return { type: "other", realDir: null };
+    // Symlink: stat (follows the link) to learn the target's real type.
+    try {
+        const target = statSync(fullPath);
+        if (target.isDirectory()) {
+            // Need the canonical target path to guard against symlink cycles.
+            let realDir = null;
+            try {
+                realDir = realpathSync(fullPath);
+            }
+            catch {
+                realDir = null;
+            }
+            return { type: "dir", realDir };
+        }
+        if (target.isFile())
+            return { type: "file", realDir: null };
+        return { type: "other", realDir: null };
+    }
+    catch {
+        // Broken or inaccessible link.
+        return { type: "other", realDir: null };
+    }
+}
+/**
+ * Walk the Source tree shallowly and group counts by the top-level folder
+ * (files directly under the root group under "."). Bounded by MAX_ENTRIES
+ * and MAX_DEPTH so the cost is always O(file-listing) with a ceiling.
+ *
+ * Directories are streamed via `opendirSync` and read one entry at a time so
+ * a pathological directory with hundreds of thousands of entries can never be
+ * materialized into a single array — the MAX_ENTRIES ceiling is enforced
+ * while iterating, and iteration stops the moment it is hit. Symlinked files
+ * and directories are followed (with cycle protection) so a Source built from
+ * symlinks is counted instead of silently yielding an empty inventory.
+ */
+function scan(sourceFolderPath) {
+    const folders = new Map();
+    const totalKinds = new Map();
+    const dateTokens = [];
+    let totalFiles = 0;
+    let visited = 0;
+    let truncated = false;
+    // A read failure on the Source root itself (permission denied, path is a
+    // file, etc.) means a real Source may exist but Interf could not enumerate
+    // it. That is distinct from an empty-but-readable Source and must not be
+    // silently flattened into the same "no inventory" result. ENOENT (the root
+    // is simply not there) is treated as empty, not as a read failure.
+    let rootReadError = null;
+    // Canonical paths of directories already walked. Following symlinked dirs
+    // can introduce cycles; this set keeps the walk finite. Seeded lazily with
+    // each directory's realpath as it is opened.
+    const visitedDirs = new Set();
+    // Stack-based shallow walk. Each entry carries the absolute dir path, its
+    // depth, and the top-level group it rolls up into.
+    const stack = [
+        { dir: sourceFolderPath, depth: 0, group: "." },
+    ];
+    while (stack.length > 0) {
+        if (visited >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        const { dir, depth, group } = stack.pop();
+        // Cycle guard: skip a directory whose canonical path we have already
+        // walked (reached again through a symlink).
+        let canonicalDir;
+        try {
+            canonicalDir = realpathSync(dir);
+        }
+        catch {
+            canonicalDir = dir;
+        }
+        if (visitedDirs.has(canonicalDir))
+            continue;
+        visitedDirs.add(canonicalDir);
+        // Stream the directory: opendirSync yields one Dirent at a time so a
+        // directory with 100k+ entries is never materialized as an array. We
+        // stop reading as soon as the MAX_ENTRIES budget is exhausted.
+        let handle;
+        try {
+            handle = opendirSync(dir);
+        }
+        catch (error) {
+            // A failure to open the Source root is a read failure we must surface,
+            // not swallow — otherwise an unreadable Source produces the same empty
+            // inventory as a genuinely empty one and the draft silently goes
+            // generic. ENOENT (root absent) is left as the empty/null case so an
+            // unbound or missing Source still degrades quietly. Failures on nested
+            // directories during the walk stay tolerated: they yield a partial
+            // inventory, which the truncation note already covers.
+            if (depth === 0) {
+                const errno = error;
+                if (errno?.code !== "ENOENT")
+                    rootReadError = errno;
+            }
+            continue;
+        }
+        try {
+            let entry = handle.readSync();
+            while (entry !== null) {
+                if (visited >= MAX_ENTRIES) {
+                    truncated = true;
+                    break;
+                }
+                const name = entry.name;
+                if (IGNORED_ENTRY_NAMES.has(name) || name.startsWith(".")) {
+                    entry = handle.readSync();
+                    continue;
+                }
+                visited += 1;
+                const resolved = resolveEntryType(join(dir, name), entry.isSymbolicLink(), entry.isDirectory(), entry.isFile());
+                if (resolved.type === "dir") {
+                    // At the root, each subfolder becomes its own top-level group.
+                    const childGroup = depth === 0 ? name : group;
+                    if (!folders.has(childGroup))
+                        folders.set(childGroup, makeFolder());
+                    if (depth + 1 <= MAX_DEPTH) {
+                        if (!(resolved.realDir !== null && visitedDirs.has(resolved.realDir))) {
+                            stack.push({ dir: join(dir, name), depth: depth + 1, group: childGroup });
+                        }
+                    }
+                    else {
+                        truncated = true;
+                    }
+                }
+                else if (resolved.type === "file") {
+                    const folder = folders.get(group) ?? makeFolder();
+                    if (!folders.has(group))
+                        folders.set(group, folder);
+                    recordFile(folder, name);
+                    totalFiles += 1;
+                    const kind = classifyKind(extname(name));
+                    totalKinds.set(kind, (totalKinds.get(kind) ?? 0) + 1);
+                    for (const token of extractDateTokens(name))
+                        dateTokens.push(token);
+                }
+                entry = handle.readSync();
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+    }
+    return { folders, totalFiles, totalKinds, dateTokens, truncated, rootReadError };
+}
+function dateRange(tokens) {
+    if (tokens.length === 0)
+        return null;
+    // Compare on a normalized digits-only key so 2024-03 sorts against
+    // 20240315 consistently; report the original tokens for the bounds.
+    // Drop any token whose normalized key is not a YYYY[MMDD] digit key — a
+    // malformed or separator-only token must never become a reported date
+    // bound, which would feed the draft a misleading "Filenames span X to Y".
+    const keyed = tokens
+        .map((token) => ({
+        token,
+        key: token.replace(/[-_./]/g, "").padEnd(8, "0"),
+    }))
+        .filter(({ key }) => /^(19|20)\d{6}$/.test(key));
+    if (keyed.length === 0)
+        return null;
+    keyed.sort((a, b) => a.key.localeCompare(b.key));
+    return { min: keyed[0].token, max: keyed[keyed.length - 1].token };
+}
+/**
+ * Build the SourceContext returned when the Source root could not be read.
+ *
+ * A read failure is NOT the empty/null case: returning null here would let the
+ * draft go generic as if the Source had no files, hiding a real Source that
+ * Interf simply could not enumerate (permission denied, path is a file, etc.).
+ * Instead we surface a populated SourceContext whose limitations make the
+ * failure explicit, so the authoring agent sees it and does not lock a generic
+ * plan on a false "empty Source" reading. No file is ever opened or read.
+ */
+function readErrorContext(sourceFolderPath, error) {
+    const code = error?.code ? ` (${error.code})` : "";
+    return {
+        summary: "Contents-free Source scan could not read the Source root" +
+            `${code}; no inventory was produced.`,
+        items: [],
+        observations: [
+            `Interf could not enumerate the Source at ${sourceFolderPath}${code}.`,
+        ],
+        limitations: [
+            "Interf could not read the Source root, so this is NOT an empty Source. " +
+                "Do not lock a generic plan: inspect the Source through your own tools " +
+                "and confirm access before shaping stages.",
+        ],
+    };
+}
+/**
+ * Produce a populated SourceContext for the authoring agent from a cheap,
+ * contents-free scan. Returns null when the Source has no readable files so
+ * callers can fall back to the existing null (no fabricated inventory). A
+ * genuine read failure on the Source root returns an explicit read-error
+ * SourceContext instead, so an unreadable Source never silently degrades into
+ * a generic plan.
+ */
+export function scanSourceContext(sourceFolderPath) {
+    let result;
+    try {
+        result = scan(sourceFolderPath);
+    }
+    catch (error) {
+        // scan() handles its own root-open failure, so a throw here is unexpected.
+        // Classify it the same way: a non-ENOENT errno is a read failure that must
+        // be surfaced, not flattened into the empty/null result; ENOENT (or a
+        // non-errno) stays the quiet empty case.
+        const errno = error;
+        if (errno?.code && errno.code !== "ENOENT") {
+            return readErrorContext(sourceFolderPath, errno);
+        }
+        return null;
+    }
+    // A read failure on the Source root with nothing enumerated is distinct from
+    // a genuinely empty Source: surface it loudly so the draft never goes generic
+    // on a false "empty" reading.
+    if (result.totalFiles === 0 && result.rootReadError) {
+        return readErrorContext(sourceFolderPath, result.rootReadError);
+    }
+    if (result.totalFiles === 0)
+        return null;
+    const items = [];
+    const sortedFolders = [...result.folders.entries()]
+        .filter(([, folder]) => folder.fileCount > 0)
+        .sort((a, b) => b[1].fileCount - a[1].fileCount)
+        .slice(0, MAX_FOLDER_ITEMS);
+    for (const [folderName, folder] of sortedFolders) {
+        const sample = folder.sampleNames.join(", ");
+        const noteParts = [
+            `${folder.fileCount} file(s)`,
+            kindSummary(folder.kinds),
+        ].filter((part) => part.length > 0);
+        if (sample)
+            noteParts.push(`e.g. ${sample}`);
+        items.push({
+            name: folderName === "." ? "(root)" : folderName,
+            path: folderName === "." ? "." : folderName,
+            kind: "folder",
+            note: noteParts.join(" — "),
+        });
+    }
+    const observations = [];
+    observations.push(`${result.totalFiles} file(s) across ${result.folders.size} top-level group(s).`);
+    const totalKindSummary = kindSummary(result.totalKinds);
+    if (totalKindSummary) {
+        observations.push(`File kinds by extension: ${totalKindSummary}.`);
+    }
+    const range = dateRange(result.dateTokens);
+    if (range) {
+        observations.push(range.min === range.max
+            ? `Filenames reference the period ${range.min}.`
+            : `Filenames span ${range.min} to ${range.max} (parsed from names, not contents).`);
+    }
+    const limitations = [
+        "Inventory is filename- and extension-only; Interf did not open or read any Source file. Inspect the Source through your own tools before locking stages.",
+    ];
+    if (result.truncated) {
+        limitations.push("Scan was capped for cost; some files or deep folders were not enumerated. Treat counts as a lower bound.");
+    }
+    return {
+        summary: `Contents-free Source scan: ${result.totalFiles} file(s) in ` +
+            `${result.folders.size} top-level group(s)` +
+            (totalKindSummary ? ` (${totalKindSummary})` : "") +
+            ".",
+        items,
+        observations: observations.slice(0, MAX_OBSERVATIONS),
+        limitations,
+    };
+}

package/dist/packages/{engine → runtime}/agents/lib/status.js

@@ -1,3 +1,4 @@
+import { pickString } from "./string-utils.js";
 export function extractAgentFailureStatus(event) {
     const candidates = [];
     const directMessage = pickString(event.message) ??
@@ -42,17 +43,3 @@ export function classifyTerminalVisibleStatus(text) {
 export function hasAgentStalled(lastActivityAt, now, stallTimeoutMs) {
     return typeof stallTimeoutMs === "number" && stallTimeoutMs > 0 && now - lastActivityAt >= stallTimeoutMs;
 }
-function pickString(value) {
-    if (typeof value === "string")
-        return value;
-    if (!Array.isArray(value))
-        return null;
-    for (const entry of value) {
-        if (typeof entry === "string")
-            return entry;
-        if (entry && typeof entry === "object" && "text" in entry && typeof entry.text === "string") {
-            return entry.text;
-        }
-    }
-    return null;
-}

package/dist/packages/runtime/agents/lib/string-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pick the first usable string out of a value that may be a bare string or an
+ * array of strings / `{ text }` content blocks. Agent event payloads carry
+ * message/text/content/output/summary fields in either shape across executors,
+ * so status-determination and render paths both reach for this.
+ */
+export declare function pickString(value: unknown): string | null;
+/**
+ * Pull the primary path-like field out of a tool-use `input` record for display
+ * summaries. Tools name the same concept differently — `file_path` (Read/Write/
+ * Edit), `path`, `pattern` (Glob/Grep), `command` (Bash), `notebook_path`
+ * (notebook tools) — so every render site collapses them with the same
+ * precedence. Returns an empty string when no field is present, matching the
+ * `?? ""` default the call sites relied on.
+ */
+export declare function extractInputPath(input: Record<string, unknown>): string;

package/dist/packages/runtime/agents/lib/string-utils.js

@@ -0,0 +1,36 @@
+/**
+ * Pick the first usable string out of a value that may be a bare string or an
+ * array of strings / `{ text }` content blocks. Agent event payloads carry
+ * message/text/content/output/summary fields in either shape across executors,
+ * so status-determination and render paths both reach for this.
+ */
+export function pickString(value) {
+    if (typeof value === "string")
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    for (const entry of value) {
+        if (typeof entry === "string")
+            return entry;
+        if (entry && typeof entry === "object" && "text" in entry && typeof entry.text === "string") {
+            return entry.text;
+        }
+    }
+    return null;
+}
+/**
+ * Pull the primary path-like field out of a tool-use `input` record for display
+ * summaries. Tools name the same concept differently — `file_path` (Read/Write/
+ * Edit), `path`, `pattern` (Glob/Grep), `command` (Bash), `notebook_path`
+ * (notebook tools) — so every render site collapses them with the same
+ * precedence. Returns an empty string when no field is present, matching the
+ * `?? ""` default the call sites relied on.
+ */
+export function extractInputPath(input) {
+    return (input.file_path ??
+        input.path ??
+        input.pattern ??
+        input.command ??
+        input.notebook_path ??
+        "");
+}

package/dist/packages/{engine → runtime}/agents/lib/types.d.ts

@@ -25,6 +25,7 @@ export interface AgentAutomationReadiness {
 export interface SpawnAgentOptions {
     eventLogPath?: string | null;
     statusLogPath?: string | null;
+    reasoningLogPath?: string | null;
     executionProfile?: AgentExecutionProfile;
     completionCheck?: (() => boolean) | null;
     onStatus?: (line: string) => void;

package/dist/packages/{engine → runtime}/agents/lib/user-config.d.ts

@@ -1,5 +1,11 @@
-import { type InterfUserConfig } from "./schema.js";
-export type { InterfUserConfig } from "./schema.js";
+import { z } from "zod";
+export declare const InterfUserConfigSchema: z.ZodObject<{
+    agent: z.ZodString;
+    agentCommand: z.ZodString;
+    skillsInstalled: z.ZodBoolean;
+    initialized: z.ZodString;
+}, z.core.$strip>;
+export type InterfUserConfig = z.infer<typeof InterfUserConfigSchema>;
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export declare function interfHome(): string;
 /** `~/.interf/config.json` — local executor preferences. */

package/dist/packages/{engine → runtime}/agents/lib/user-config.js

@@ -1,8 +1,14 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { z } from "zod";
 import { readJsonFileWithSchema } from "../../../contracts/utils/parse.js";
-import { interfHomeRoot } from "../../../contracts/lib/preparation-paths.js";
-import { InterfUserConfigSchema } from "./schema.js";
+import { interfHomeRoot } from "../../../contracts/lib/project-paths.js";
+export const InterfUserConfigSchema = z.object({
+    agent: z.string(),
+    agentCommand: z.string(),
+    skillsInstalled: z.boolean(),
+    initialized: z.string(),
+});
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export function interfHome() {
     return interfHomeRoot();

package/dist/packages/runtime/agents/providers/claude-code.d.ts

@@ -0,0 +1,13 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Claude Code provider.
+ *
+ * Configuration follows Anthropic's third-party integration spec:
+ * https://code.claude.com/docs/en/third-party-integrations
+ *
+ * The user-facing model knob is the alias (`opus`, `sonnet`, `haiku`)
+ * which Anthropic resolves server-side to the current pinned version.
+ * Hosts that need to pin a specific version do it via the
+ * `ANTHROPIC_DEFAULT_*_MODEL` env vars supplied by the user.
+ */
+export declare const claudeCodeProvider: AgentProvider;

package/dist/packages/runtime/agents/providers/claude-code.js

@@ -0,0 +1,45 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Claude Code provider.
+ *
+ * Configuration follows Anthropic's third-party integration spec:
+ * https://code.claude.com/docs/en/third-party-integrations
+ *
+ * The user-facing model knob is the alias (`opus`, `sonnet`, `haiku`)
+ * which Anthropic resolves server-side to the current pinned version.
+ * Hosts that need to pin a specific version do it via the
+ * `ANTHROPIC_DEFAULT_*_MODEL` env vars supplied by the user.
+ */
+export const claudeCodeProvider = {
+    name: "claude-code",
+    displayName: "Claude Code",
+    command: "claude",
+    homeDir: join(homedir(), ".claude"),
+    skillsDir: join(homedir(), ".claude", "skills"),
+    supportsAutomatedRuns: true,
+    defaultModel: "claude-sonnet-4-6",
+    defaultEffort: "low",
+    noiseFilters: [],
+    buildArgs(prompt, profile) {
+        const args = [
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--allowedTools",
+            "Read,Write,Edit,Bash,Grep,Glob,Agent",
+        ];
+        if (profile.model) {
+            args.push("--model", profile.model);
+        }
+        if (profile.effort) {
+            args.push("--effort", profile.effort);
+        }
+        return args;
+    },
+    buildEnv(baseEnv) {
+        return { ...baseEnv };
+    },
+};

package/dist/packages/runtime/agents/providers/codex.d.ts

@@ -0,0 +1,17 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Codex provider.
+ *
+ * Reasoning effort is passed via the documented config override
+ * (`-c model_reasoning_effort=...`) rather than a flag.
+ *
+ * The `SHELL` env var is stripped from the spawn so Codex picks a
+ * sandbox-safe default shell instead of inheriting the host login shell.
+ *
+ * Two stderr noise lines are expected on every run and must not be
+ * treated as preflight failures.
+ *
+ * Codex preflight is retried when it reports transient session-record
+ * errors that resolve on a second attempt.
+ */
+export declare const codexProvider: AgentProvider;

package/dist/packages/runtime/agents/providers/codex.js

@@ -0,0 +1,66 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SANDBOX_MODE = `work${"space-write"}`;
+/**
+ * Codex provider.
+ *
+ * Reasoning effort is passed via the documented config override
+ * (`-c model_reasoning_effort=...`) rather than a flag.
+ *
+ * The `SHELL` env var is stripped from the spawn so Codex picks a
+ * sandbox-safe default shell instead of inheriting the host login shell.
+ *
+ * Two stderr noise lines are expected on every run and must not be
+ * treated as preflight failures.
+ *
+ * Codex preflight is retried when it reports transient session-record
+ * errors that resolve on a second attempt.
+ */
+export const codexProvider = {
+    name: "codex",
+    displayName: "Codex",
+    command: "codex",
+    homeDir: join(homedir(), ".codex"),
+    skillsDir: join(homedir(), ".codex", "skills"),
+    supportsAutomatedRuns: true,
+    defaultModel: "gpt-5.3-codex",
+    defaultEffort: "high",
+    noiseFilters: [
+        /codex_core_skills::loader: failed to stat skills entry .*\/interf-[^ ]+ \(symlink\): No such file or directory/,
+        /codex_core::codex: failed to load skill .*\/gstack\/SKILL\.md: invalid description: exceeds maximum length of 1024 characters/,
+    ],
+    buildArgs(prompt, profile) {
+        const args = [
+            "exec",
+            "--json",
+            "-s",
+            SANDBOX_MODE,
+            "--skip-git-repo-check",
+            "-c",
+            'service_tier="fast"',
+        ];
+        if (profile.model) {
+            args.push("--model", profile.model);
+        }
+        if (profile.profile) {
+            args.push("--profile", profile.profile);
+        }
+        if (profile.effort) {
+            args.push("-c", `model_reasoning_effort=${JSON.stringify(profile.effort)}`);
+        }
+        args.push(prompt);
+        return args;
+    },
+    buildEnv(baseEnv) {
+        const env = { ...baseEnv };
+        delete env.SHELL;
+        return env;
+    },
+    isTransientPreflightFailure(stderr, errorMessage) {
+        const text = `${errorMessage}\n${stderr}`;
+        if (/usage limit/i.test(text))
+            return false;
+        return /failed to record rollout items/i.test(text)
+            || /thread\s+[0-9a-f-]+\s+not found/i.test(text);
+    },
+};

package/dist/packages/runtime/agents/providers/cursor.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Cursor provider.
+ *
+ * Cursor is detected for `interf init` so the listing shows it, but
+ * Interf cannot drive automated Build runs through Cursor today.
+ * `buildArgs` therefore throws.
+ */
+export declare const cursorProvider: AgentProvider;