aiwcli 0.15.5 → 0.17.0

package/dist/lib/prompt-file-manager.js

@@ -0,0 +1,41 @@
+/**
+ * PromptFileManager — owns prompt file lifecycle (creation, cleanup).
+ * Replaces scattered writeFileSync calls for prompt temp files.
+ */
+import { writeFileSync } from 'node:fs';
+import * as fs from 'node:fs';
+import path from 'node:path';
+export class PromptFileManager {
+    files = [];
+    tempDir;
+    now;
+    pid;
+    constructor(options) {
+        this.tempDir = options.tempDir;
+        this.now = options.now;
+        this.pid = options.pid;
+    }
+    /**
+     * Write prompt text to a temp file and return the path.
+     */
+    materialize(promptText) {
+        const filePath = path.join(this.tempDir, `aiwcli-prompt-${this.now()}-${this.pid}.txt`);
+        writeFileSync(filePath, promptText, { encoding: 'utf8', mode: 0o600 });
+        this.files.push(filePath);
+        return filePath;
+    }
+    /**
+     * Clean up all created prompt files. Call in finally block.
+     */
+    cleanup() {
+        for (const filePath of this.files) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+        this.files.length = 0;
+    }
+}

package/dist/lib/runtime/agent-launcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared agent-launcher utilities used by Codex, Devin, and future agent skills.
+ * Extracted from codex skill to avoid duplication across agent launch scripts.
+ */
+import type { ContextState } from "../types.js";
+export declare const POLL_INTERVAL_MS = 2000;
+export declare const POLL_TIMEOUT_MS = 3000;
+export declare const WAIT_TIMEOUT_MS_DEFAULT = 14400000;
+type PaneBackend = "tmux" | "window" | "exec";
+export interface PaneWatchTarget {
+    backend?: PaneBackend;
+    paneId?: string;
+    sentinelPath?: string;
+}
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Print to stderr (shared by agent launch scripts).
+ */
+export declare function eprint(...args: unknown[]): void;
+/**
+ * Best-effort cleanup of a sentinel directory.
+ */
+export declare function cleanupSentinel(sentinelPath: string | null | undefined): void;
+/**
+ * Case-sensitive (or case-insensitive on Windows) path comparison.
+ */
+export declare function samePath(a: string, b: string): boolean;
+/**
+ * Heuristic check for LLM output that isn't a real summary.
+ */
+export declare function looksLikeBadSummary(output: string): boolean;
+/**
+ * Return a deterministic summary file path for a given agent prefix + task ID.
+ * Callers can advertise this path before the session finishes so consumers
+ * know where to look for the summary once it's written.
+ */
+export declare function getWellKnownSummaryPath(prefix: string, taskId: string, projectRoot?: string): string;
+export declare function persistSummary(summary: string, prefix: string, sessionId?: string, taskId?: string, projectRoot?: string): string | null;
+/** Fallback plan discovery: scan all context plan dirs by mtime. */
+export declare function findLatestPlanByMtime(projectRoot: string): string | null;
+export declare function buildFileModeBootstrapPrompt(targetPath: string, sourceLabel: "plan" | "file", extraPrompt?: string, orientation?: string): string;
+export declare function resolveContextForLaunch(contextFlag: string | undefined, projectRoot: string): ContextState | null;
+export interface WritePromptFileOpts {
+    ctx?: ContextState | null;
+    extraPrompt?: string;
+    projectRoot: string;
+    tempFilePrefix: string;
+}
+export interface WriteFileRefPromptFileOpts extends WritePromptFileOpts {
+    fileReferencePath: string;
+    label: "plan" | "file";
+}
+export interface WriteInlinePromptFileOpts extends WritePromptFileOpts {
+    text: string;
+}
+/**
+ * Build a file-reference bootstrap prompt and write it to a temp file.
+ * Returns the temp file path.
+ */
+export declare function writeFileRefPromptFile(opts: WriteFileRefPromptFileOpts): string;
+/**
+ * Write inline text to a temp file, prepend context orientation, append extra prompt.
+ * Returns the temp file path.
+ */
+export declare function writeInlinePromptFile(opts: WriteInlinePromptFileOpts): string;
+export declare function waitForPaneClose(target: string | PaneWatchTarget, timeoutMs?: number): Promise<void>;
+export {};

package/dist/lib/runtime/agent-launcher.js

@@ -0,0 +1,262 @@
+/**
+ * Shared agent-launcher utilities used by Codex, Devin, and future agent skills.
+ * Extracted from codex skill to avoid duplication across agent launch scripts.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import path from "node:path";
+import { logDebug, logWarn } from "./logger.js";
+import { execFileAsync, findExecutable } from "./subprocess-utils.js";
+import { buildExternalAgentContext } from "../context/context-formatter.js";
+import { getContextBySessionId, getContext } from "../context/context-store.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const POLL_INTERVAL_MS = 2000;
+export const POLL_TIMEOUT_MS = 3000;
+export const WAIT_TIMEOUT_MS_DEFAULT = 14_400_000;
+// ---------------------------------------------------------------------------
+// Generic Helpers
+// ---------------------------------------------------------------------------
+export function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Print to stderr (shared by agent launch scripts).
+ */
+export function eprint(...args) {
+    process.stderr.write(args.map(String).join(" ") + "\n");
+}
+/**
+ * Best-effort cleanup of a sentinel directory.
+ */
+export function cleanupSentinel(sentinelPath) {
+    if (!sentinelPath)
+        return;
+    try {
+        const dir = path.dirname(sentinelPath);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Case-sensitive (or case-insensitive on Windows) path comparison.
+ */
+export function samePath(a, b) {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    if (process.platform === "win32") {
+        return left.toLowerCase() === right.toLowerCase();
+    }
+    return left === right;
+}
+/**
+ * Heuristic check for LLM output that isn't a real summary.
+ */
+export function looksLikeBadSummary(output) {
+    const normalized = output.toLowerCase();
+    return (normalized.includes("don't see") ||
+        normalized.includes("no output") ||
+        normalized.includes("could you provide") ||
+        normalized.includes("paste"));
+}
+/**
+ * Return a deterministic summary file path for a given agent prefix + task ID.
+ * Callers can advertise this path before the session finishes so consumers
+ * know where to look for the summary once it's written.
+ */
+export function getWellKnownSummaryPath(prefix, taskId, projectRoot) {
+    const sessionKey = projectRoot
+        ? path.basename(projectRoot)
+        : "unknown";
+    const dir = path.join(os.tmpdir(), "aiw-agent-output", sessionKey);
+    return path.join(dir, `${prefix}-${taskId}.md`).replaceAll("\\", "/");
+}
+export function persistSummary(summary, prefix, sessionId, taskId, projectRoot) {
+    try {
+        const suffix = sessionId
+            ? sessionId.replaceAll(/[^a-zA-Z0-9_-]/g, "").slice(0, 8)
+            : String(process.pid);
+        const filePath = path.join(os.tmpdir(), `${prefix}-summary-${Date.now()}-${suffix}.md`);
+        fs.writeFileSync(filePath, summary, "utf8");
+        // Also write to the well-known path for deterministic discovery.
+        if (taskId) {
+            try {
+                const wkPath = getWellKnownSummaryPath(prefix, taskId, projectRoot);
+                fs.mkdirSync(path.dirname(wkPath), { recursive: true });
+                fs.writeFileSync(wkPath, summary, "utf8");
+            }
+            catch {
+                logWarn("agent-launcher", "Failed to write well-known summary path");
+            }
+        }
+        return filePath.replaceAll("\\", "/");
+    }
+    catch (error) {
+        logWarn("agent-launcher", `Failed to persist summary: ${String(error)}`);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plan Discovery
+// ---------------------------------------------------------------------------
+/** Fallback plan discovery: scan all context plan dirs by mtime. */
+export function findLatestPlanByMtime(projectRoot) {
+    const contextsDir = path.join(projectRoot, "_output", "contexts");
+    if (!fs.existsSync(contextsDir))
+        return null;
+    let best = null;
+    for (const ctxEntry of fs.readdirSync(contextsDir)) {
+        if (ctxEntry.startsWith("_"))
+            continue;
+        const plansDir = path.join(contextsDir, ctxEntry, "plans");
+        if (!fs.existsSync(plansDir))
+            continue;
+        for (const file of fs.readdirSync(plansDir)) {
+            if (!file.endsWith(".md"))
+                continue;
+            const fullPath = path.join(plansDir, file);
+            try {
+                const mtime = fs.statSync(fullPath).mtimeMs;
+                if (!best || mtime > best.mtime) {
+                    best = { path: fullPath, mtime };
+                }
+            }
+            catch { /* skip unreadable */ }
+        }
+    }
+    return best?.path ?? null;
+}
+// ---------------------------------------------------------------------------
+// Bootstrap Prompt Construction
+// ---------------------------------------------------------------------------
+export function buildFileModeBootstrapPrompt(targetPath, sourceLabel, extraPrompt, orientation) {
+    const absolutePath = path.resolve(targetPath);
+    const sourceTitle = sourceLabel === "plan" ? "Plan Source" : "File Source";
+    const sections = ["## Startup Brief", ""];
+    if (orientation?.trim()) {
+        sections.push(orientation.trim(), "", "---", "");
+    }
+    sections.push(`## ${sourceTitle}`, "", `Primary input path: ${absolutePath}`, "", "Read this file directly from disk before taking action.", "Treat its contents as the source of truth.", "Do not ask for the file contents to be pasted inline.");
+    if (extraPrompt?.trim()) {
+        sections.push("", "## Additional Instructions", "", extraPrompt.trim());
+    }
+    return sections.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Context Resolution
+// ---------------------------------------------------------------------------
+export function resolveContextForLaunch(contextFlag, projectRoot) {
+    if (contextFlag) {
+        return getContext(contextFlag, projectRoot) ?? null;
+    }
+    const sessionId = process.env.CLAUDE_SESSION_ID;
+    if (sessionId) {
+        return getContextBySessionId(sessionId, projectRoot) ?? null;
+    }
+    return null;
+}
+/**
+ * Build a file-reference bootstrap prompt and write it to a temp file.
+ * Returns the temp file path.
+ */
+export function writeFileRefPromptFile(opts) {
+    let orientation = "";
+    if (opts.ctx) {
+        try {
+            orientation = buildExternalAgentContext(opts.ctx, opts.projectRoot);
+        }
+        catch {
+            logWarn("agent-launcher", `Context orientation build failed for ${opts.ctx.id}`);
+        }
+    }
+    const bootstrap = buildFileModeBootstrapPrompt(opts.fileReferencePath, opts.label, opts.extraPrompt, orientation);
+    const tempFile = path.join(os.tmpdir(), `${opts.tempFilePrefix}-file-ref-${Date.now()}.md`);
+    fs.writeFileSync(tempFile, bootstrap, "utf8");
+    return tempFile;
+}
+/**
+ * Write inline text to a temp file, prepend context orientation, append extra prompt.
+ * Returns the temp file path.
+ */
+export function writeInlinePromptFile(opts) {
+    let content = opts.text;
+    if (opts.ctx) {
+        try {
+            const orientation = buildExternalAgentContext(opts.ctx, opts.projectRoot);
+            content = `${orientation}\n\n---\n\n${content}`;
+        }
+        catch {
+            logWarn("agent-launcher", `Context orientation prepend failed for ${opts.ctx.id}`);
+        }
+    }
+    if (opts.extraPrompt?.trim()) {
+        content = `${content}\n\n---\n\n## Additional Instructions\n\n${opts.extraPrompt}`;
+    }
+    const tempFile = path.join(os.tmpdir(), `${opts.tempFilePrefix}-prompt-${Date.now()}.md`);
+    fs.writeFileSync(tempFile, content, "utf8");
+    return tempFile;
+}
+// ---------------------------------------------------------------------------
+// Pane Watching
+// ---------------------------------------------------------------------------
+async function waitForSentinelClose(sentinelPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (fs.existsSync(sentinelPath))
+            return;
+        if (Date.now() >= deadline) {
+            logDebug("agent-launcher", `watch timeout reached waiting for sentinel ${sentinelPath}`);
+            return;
+        }
+        const remainingMs = deadline - Date.now();
+        await sleep(Math.max(0, Math.min(POLL_INTERVAL_MS, remainingMs)));
+    }
+}
+function normalizeWatchTarget(target) {
+    if (typeof target === "string") {
+        return { backend: "tmux", paneId: target };
+    }
+    return target;
+}
+export async function waitForPaneClose(target, timeoutMs = WAIT_TIMEOUT_MS_DEFAULT) {
+    const watch = normalizeWatchTarget(target);
+    if (watch.sentinelPath) {
+        await waitForSentinelClose(watch.sentinelPath, timeoutMs);
+        return;
+    }
+    const backend = watch.backend ?? "tmux";
+    const paneId = watch.paneId ?? "";
+    if (backend !== "tmux") {
+        logDebug("agent-launcher", `No pane watcher for backend=${backend}; continuing without wait`);
+        return;
+    }
+    if (!paneId)
+        return;
+    const tmuxPath = findExecutable("tmux");
+    if (!tmuxPath) {
+        logWarn("agent-launcher", `tmux unavailable while watching pane ${paneId}`);
+        return;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (Date.now() >= deadline) {
+            logDebug("agent-launcher", `watch timeout reached for pane ${paneId} after ${timeoutMs}ms`);
+            return;
+        }
+        const result = await execFileAsync(tmuxPath, ["list-panes", "-a", "-F", "#{pane_id}"], {
+            timeout: POLL_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0) {
+            logDebug("agent-launcher", `list-panes failed; assuming pane closed (${result.stderr.trim() || "no stderr"})`);
+            return;
+        }
+        const activePaneIds = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (!activePaneIds.includes(paneId))
+            return;
+        const remainingMs = deadline - Date.now();
+        await sleep(Math.max(0, Math.min(POLL_INTERVAL_MS, remainingMs)));
+    }
+}

package/dist/lib/runtime/aiw-cli.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Helper to discover and invoke the `aiw` CLI binary from template scripts.
+ *
+ * Reads the resolved binary path from `.aiwcli/.aiw-bin-path` (written by `aiw init`).
+ * Falls back to `aiw` on PATH if the file is missing.
+ */
+export interface AiwLaunchOptions {
+    /** Launch codex instead of claude. */
+    codex?: boolean;
+    /** Launch devin instead of claude. */
+    devin?: boolean;
+    /** Working directory. */
+    cwd?: string;
+    /** Extra env vars to inject. */
+    env?: Record<string, string>;
+    /** Return JSON output. */
+    json?: boolean;
+    /** Path to prompt file. */
+    promptPath?: string;
+    /** Split direction: auto, h, or v. */
+    split?: "auto" | "h" | "v";
+    /** Timeout in ms (only relevant with --wait). */
+    timeoutMs?: number;
+    /** Block until pane exits. */
+    wait?: boolean;
+}
+export interface AiwLaunchResult {
+    backend: string;
+    exitCode: null | number;
+    launched: boolean;
+    paneId: null | string;
+    reason: null | string;
+    sentinelPath: null | string;
+}
+/**
+ * Shell out to `aiw launch` with structured options.
+ * Returns parsed JSON result when --json is used.
+ */
+export declare function aiwLaunch(options: AiwLaunchOptions): Promise<AiwLaunchResult>;

package/dist/lib/runtime/aiw-cli.js

@@ -0,0 +1,76 @@
+/**
+ * Helper to discover and invoke the `aiw` CLI binary from template scripts.
+ *
+ * Reads the resolved binary path from `.aiwcli/.aiw-bin-path` (written by `aiw init`).
+ * Falls back to `aiw` on PATH if the file is missing.
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { getProjectRoot } from "./constants.js";
+import { execFileAsync } from "./subprocess-utils.js";
+function resolveAiwBin(cwd) {
+    const projectRoot = getProjectRoot(cwd ?? process.cwd());
+    const binPathFile = path.join(projectRoot, ".aiwcli", ".aiw-bin-path");
+    try {
+        const binPath = fs.readFileSync(binPathFile, "utf8").trim();
+        if (binPath && fs.existsSync(binPath))
+            return binPath;
+    }
+    catch {
+        // Fall through to PATH lookup
+    }
+    return "aiw";
+}
+/**
+ * Shell out to `aiw launch` with structured options.
+ * Returns parsed JSON result when --json is used.
+ */
+export async function aiwLaunch(options) {
+    const bin = resolveAiwBin(options.cwd);
+    const args = ["launch"];
+    if (options.codex)
+        args.push("--codex");
+    if (options.devin)
+        args.push("--devin");
+    if (options.wait)
+        args.push("--wait");
+    args.push("--json");
+    if (options.split)
+        args.push("--split", options.split);
+    if (options.env && Object.keys(options.env).length > 0) {
+        args.push("--env", JSON.stringify(options.env));
+    }
+    if (options.promptPath)
+        args.push("--prompt-path", options.promptPath);
+    const result = await execFileAsync(bin, args, {
+        timeout: options.timeoutMs ?? 14_400_000,
+        env: process.env,
+        shell: process.platform === "win32",
+    });
+    return parseJsonResult(result);
+}
+function parseJsonResult(result) {
+    try {
+        const lines = result.stdout.trim().split(/\r?\n/);
+        const lastLine = lines.at(-1) ?? "";
+        const parsed = JSON.parse(lastLine);
+        return {
+            launched: Boolean(parsed.launched),
+            backend: String(parsed.backend ?? "exec"),
+            paneId: parsed.handle ?? parsed.paneId ?? null,
+            sentinelPath: parsed.sentinelPath ?? null,
+            exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : null,
+            reason: parsed.reason ?? null,
+        };
+    }
+    catch {
+        return {
+            launched: false,
+            backend: "exec",
+            paneId: null,
+            sentinelPath: null,
+            exitCode: result.exitCode,
+            reason: `Failed to parse aiw launch output: ${result.stderr || result.stdout}`,
+        };
+    }
+}

package/dist/lib/runtime/atomic-write.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform atomic file writes with security.
+ * Crash-safe writes by writing to temp file then renaming.
+ * NOT for concurrent access — assumes single-session-per-context.
+ * See SPEC.md §4
+ */
+/**
+ * Write file atomically with retry logic.
+ * Creates temp file, writes, fsyncs, renames.
+ * Returns [success, error].
+ * See SPEC.md §4.2
+ */
+export declare function atomicWrite(filePath: string, content: string, maxAttempts?: number, backoffMs?: number[], fsync?: boolean): [boolean, null | string];
+/**
+ * Append to file with retry logic.
+ * For JSONL files where each line is independent.
+ * See SPEC.md §4.3
+ */
+export declare function atomicAppend(filePath: string, content: string, maxAttempts?: number, backoffMs?: number[], fsync?: boolean): [boolean, null | string];

package/dist/lib/runtime/atomic-write.js

@@ -0,0 +1,121 @@
+/**
+ * Cross-platform atomic file writes with security.
+ * Crash-safe writes by writing to temp file then renaming.
+ * NOT for concurrent access — assumes single-session-per-context.
+ * See SPEC.md §4
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import path from "node:path";
+/**
+ * Write file atomically with retry logic.
+ * Creates temp file, writes, fsyncs, renames.
+ * Returns [success, error].
+ * See SPEC.md §4.2
+ */
+export function atomicWrite(filePath, content, maxAttempts = 2, backoffMs = [500, 1000], fsync = true) {
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const stem = path.basename(filePath, path.extname(filePath));
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const tmpName = `.${stem}_${crypto.randomBytes(4).toString("hex")}.tmp`;
+        const tmpPath = path.join(dir, tmpName);
+        try {
+            // Write to temp file
+            const fd = fs.openSync(tmpPath, "w");
+            try {
+                fs.writeSync(fd, content, undefined, "utf8");
+                if (fsync)
+                    fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // Set restrictive permissions (best-effort)
+            try {
+                fs.chmodSync(tmpPath, 0o600);
+            }
+            catch {
+                // May fail on some filesystems
+            }
+            // Atomic rename (cross-platform on modern Node/Bun)
+            fs.renameSync(tmpPath, filePath);
+            return [true, null];
+        }
+        catch (error) {
+            // Clean up temp file
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Best-effort cleanup
+            }
+            if (attempt < maxAttempts - 1) {
+                const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs.at(-1) ?? 500;
+                sleepSync(waitMs);
+            }
+            else {
+                const errType = error?.constructor?.name ?? "Error";
+                const errMsg = String(error).split("\n")[0]?.slice(0, 200) ?? "";
+                return [false, `${errType}: ${errMsg}`];
+            }
+        }
+    }
+    return [false, "Max retry attempts exceeded"];
+}
+/**
+ * Append to file with retry logic.
+ * For JSONL files where each line is independent.
+ * See SPEC.md §4.3
+ */
+export function atomicAppend(filePath, content, maxAttempts = 2, backoffMs = [500, 1000], fsync = true) {
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const isNewFile = !fs.existsSync(filePath);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const fd = fs.openSync(filePath, "a");
+            try {
+                fs.writeSync(fd, content, undefined, "utf8");
+                if (fsync)
+                    fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // Set permissions on newly created files (best-effort)
+            if (isNewFile) {
+                try {
+                    fs.chmodSync(filePath, 0o600);
+                }
+                catch {
+                    // May fail on some filesystems
+                }
+            }
+            return [true, null];
+        }
+        catch (error) {
+            if (attempt < maxAttempts - 1) {
+                const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs.at(-1) ?? 500;
+                sleepSync(waitMs);
+            }
+            else {
+                const errType = error?.constructor?.name ?? "Error";
+                const errMsg = String(error).split("\n")[0]?.slice(0, 200) ?? "";
+                return [false, `${errType}: ${errMsg}`];
+            }
+        }
+    }
+    return [false, "Max retry attempts exceeded"];
+}
+/**
+ * Synchronous sleep for retry backoff.
+ * Uses Atomics.wait() for CPU-friendly blocking instead of busy-wait.
+ */
+function sleepSync(ms) {
+    const sab = new SharedArrayBuffer(4);
+    const i32 = new Int32Array(sab);
+    Atomics.wait(i32, 0, 0, ms);
+}

package/dist/lib/runtime/cli-args.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Centralized CLI argument construction for agent subprocesses.
+ * Single source of truth for Claude CLI and Codex CLI flag patterns,
+ * platform quoting, model tier resolution, and env setup.
+ */
+import type { PreflightCommandConfig } from "./preflight.js";
+export type InvocationMode = "structured" | "print" | "preflight";
+export type CliProvider = "claude" | "codex" | "devin";
+export type ModelTier = "fast" | "standard" | "smart";
+declare const VALID_SANDBOXES: readonly ["read-only", "workspace-write", "danger-full-access"];
+export type CodexSandbox = (typeof VALID_SANDBOXES)[number];
+export declare function isCodexSandbox(value: string): value is CodexSandbox;
+export interface CliArgSpec {
+    provider: CliProvider;
+    model: string | ModelTier;
+    mode: InvocationMode;
+    jsonSchema?: Record<string, unknown>;
+    maxTurns?: number;
+    systemPrompt?: string;
+    sandbox?: CodexSandbox;
+    outputSchemaPath?: string;
+    outputFilePath?: string;
+    extraArgs?: string[];
+}
+/** Codex REPL spec — model optional (Codex uses its default when omitted). */
+export interface CodexReplSpec {
+    provider: "codex";
+    mode: "repl";
+    model?: string | ModelTier;
+    sandbox?: CodexSandbox;
+    yolo?: boolean;
+    extraArgs?: string[];
+}
+export interface CliInvocation {
+    cliName: string;
+    args: string[];
+    needsShell: boolean;
+    env: Record<string, string | undefined>;
+}
+export declare const MODEL_TIERS: Record<ModelTier, string>;
+export declare const CODEX_MODEL_TIERS: Record<ModelTier, string>;
+export declare const DEVIN_MODEL_TIERS: Record<ModelTier, string>;
+export declare const TIER_TIMEOUTS: Record<ModelTier, number>;
+export declare function isModelTier(value: string): value is ModelTier;
+export declare function resolveModel(model: string | ModelTier): string;
+export declare function resolveModelForProvider(model: string | ModelTier, provider: CliProvider): string;
+export declare function getTierTimeout(tier: ModelTier): number;
+/** Resolve a Codex model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export declare function resolveCodexModel(input: string): string;
+/** Resolve a Devin model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export declare function resolveDevinModel(input: string): string;
+export declare function buildCliInvocation(spec: CliArgSpec | CodexReplSpec): CliInvocation;
+export declare function preflightSpec(provider: CliProvider, model: string): CliArgSpec;
+export declare function inferenceSpec(model: string | ModelTier): CliArgSpec;
+export declare function reviewSpec(provider: CliProvider, model: string, schema: Record<string, unknown>, systemPrompt?: string): CliArgSpec;
+export declare function codexReplSpec(model?: string, sandbox?: CodexSandbox, yolo?: boolean): CodexReplSpec;
+export declare function preflightCommandConfig(provider: CliProvider): PreflightCommandConfig;
+export { CLAUDE_MODELS, CODEX_MODELS, DEVIN_MODELS } from "./models.js";