voratiq 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -1,58 +1,84 @@
 # Voratiq
 
-Run multiple AI coding agents in parallel, compare their results, and apply the best solution.
+Run coding agents against each other. Merge the winner.
 
-![`voratiq run --spec specs/p1/agent-workspace-guardrails.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
+![`voratiq run --spec .voratiq/specs/standardize-docker-test-scripts.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
+
+Why? Because no single model is best for every task. We use selection because it leads to [higher quality code](https://voratiq.com/blog/selection-rather-than-prediction/).
 
 ## Installation
 
-Voratiq is in public beta. Install via npm:
+Install via npm:
 
 ```bash
-npm install -g voratiq@beta
+npm install -g voratiq
 ```
 
 ### Requirements
 
-Core:
-
 - Node 20+
 - git
-- 1+ AI coding agent (Claude [(>=2.0.55)](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [(>=0.66.0)](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [(>=0.19.4)](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
-
-Platform-specific:
-
+- 1+ AI coding agent (Claude [>=2.0.55](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [>=0.66.0](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [>=0.19.4](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
 - macOS: `ripgrep`
 - Linux (Debian/Ubuntu): `bubblewrap`, `socat`, `ripgrep`
 
-See the [sandbox runtime docs](https://github.com/anthropic-experimental/sandbox-runtime/blob/1bafa66a2c3ebc52569fc0c1a868e85e778f66a0/README.md#platform-specific-dependencies) for installation instructions.
+See the [sandbox runtime docs](https://github.com/anthropic-experimental/sandbox-runtime/blob/1bafa66a2c3ebc52569fc0c1a868e85e778f66a0/README.md#platform-specific-dependencies) for guidance on the platform-specific dependencies.
 
-Note: Windows is not currently supported.
+Windows is not currently supported.
 
 ## Quick Start
 
 ```bash
 # Initialize workspace
-voratiq init
+voratiq init --yes
 
-# Write a spec
-cat > specs/fix-auth.md <<EOF
-# Fix Session Timeout Bug
-Users are logged out after 5 minutes instead of 30.
-Sessions should honor SESSION_TIMEOUT_MS (default 30 minutes).
-EOF
+# Generate a spec
+voratiq spec \
+  --description "add dark mode toggle with localStorage persistence" \
+  --agent <agent-id> \
+  --yes
 
-# Run agents in parallel
-voratiq run --spec specs/fix-auth.md
+# Run agent ensemble against that spec
+voratiq run --spec .voratiq/specs/add-dark-mode-toggle.md
 
 # Review results
-voratiq review --run <run-id>
+voratiq review --run <run-id> --agent <agent-id>
 
 # Apply the best solution
 voratiq apply --run <run-id> --agent <agent-id>
+
+# Clean up workspace
+voratiq prune --run <run-id>
 ```
 
-See the [docs](https://github.com/voratiq/voratiq/blob/main/docs/index.md) for core concepts, CLI reference, and guides on configuring agents, evals, runtime environments, and sandbox restrictions.
+For a detailed walkthrough, see the [tutorial](https://github.com/voratiq/voratiq/blob/main/docs/tutorial.md).
+
+## How It Works
+
+Voratiq positions you as the architect and reviewer, and shifts implementation onto an ensemble of agents.
+
+In practice, the same spec goes to all agents, evals run automatically, and you pick the winner.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/voratiq/voratiq/main/assets/voratiq-workflow.svg" alt="Voratiq workflow" width="500">
+</p>
+
+Every run (diffs, logs, eval results, and agent summaries) is local, configurable, inspectable, and fully auditable.
+
+## Documentation
+
+Learn about the Voratiq workflow and CLI:
+
+- [Tutorial](https://github.com/voratiq/voratiq/blob/main/docs/tutorial.md) - End-to-end walkthrough
+- [Core Concepts](https://github.com/voratiq/voratiq/blob/main/docs/core-concepts.md) - Mental model and design philosophy
+- [CLI Reference](https://github.com/voratiq/voratiq/blob/main/docs/cli-reference.md) - All commands and options
+
+How to configure agents, evaluations, and execution environments:
+
+- [Agents](https://github.com/voratiq/voratiq/blob/main/docs/configs/agents.md) - Define which agents run and how to invoke them
+- [Environment](https://github.com/voratiq/voratiq/blob/main/docs/configs/environment.md) - Configure runtime environments
+- [Evals](https://github.com/voratiq/voratiq/blob/main/docs/configs/evals.md) - Define checks that gate agent output
+- [Sandbox](https://github.com/voratiq/voratiq/blob/main/docs/configs/sandbox.md) - Network and filesystem restrictions
 
 ## License
 

package/dist/{commands/run/agents/auth-stage.d.ts → agents/runtime/auth.d.ts}

@@ -1,23 +1,26 @@
-import type { AuthProvider, AuthRuntimeContext } from "../../../auth/providers/types.js";
-import type { AgentDefinition } from "../../../configs/agents/types.js";
+import type { AuthProvider, AuthRuntimeContext } from "../../auth/providers/types.js";
+import type { AgentDefinition } from "../../configs/agents/types.js";
 export interface StagedAuthContext {
     provider: AuthProvider;
     sandboxPath: string;
     runtime: AuthRuntimeContext;
     agentId: string;
-    runId: string;
 }
 export interface StageAuthOptions {
     agent: AgentDefinition;
     agentRoot: string;
-    runId: string;
     root: string;
+    runId?: string;
     runtime?: AuthRuntimeContext;
 }
 export interface StageAuthResult {
     env: Record<string, string>;
     context: StagedAuthContext;
 }
-export declare function verifyAgentProviders(agents: readonly AgentDefinition[]): Promise<void>;
+export interface AgentProviderPreflightIssue {
+    readonly agentId: string;
+    readonly message: string;
+}
+export declare function verifyAgentProviders(agents: readonly Pick<AgentDefinition, "id" | "provider">[]): Promise<readonly AgentProviderPreflightIssue[]>;
 export declare function stageAgentAuth(options: StageAuthOptions): Promise<StageAuthResult>;
 export declare function teardownAuthContext(context: StagedAuthContext | undefined): Promise<void>;

package/dist/{commands/run/agents/auth-stage.js → agents/runtime/auth.js}

@@ -1,40 +1,57 @@
 import { rm } from "node:fs/promises";
-import { resolveAuthProvider } from "../../../auth/providers/index.js";
-import { buildAuthRuntimeContext } from "../../../auth/runtime.js";
-import { toErrorMessage } from "../../../utils/errors.js";
-import { isFileSystemError } from "../../../utils/fs.js";
-import { AuthProviderStageError, AuthProviderVerificationError, MissingAgentProviderError, RunCommandError, UnknownAuthProviderError, } from "../errors.js";
-import { getRunCommand } from "./sandbox-launcher.js";
+import { resolveAuthProvider } from "../../auth/providers/index.js";
+import { buildAuthRuntimeContext } from "../../auth/runtime.js";
+import { loadRepoSettings } from "../../configs/settings/loader.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { isFileSystemError } from "../../utils/fs.js";
+import { AuthProviderStageError, MissingAgentProviderError, UnknownAuthProviderError, } from "./errors.js";
+import { getRunCommand } from "./launcher.js";
+import { checkPlatformSupport } from "./sandbox.js";
 export async function verifyAgentProviders(agents) {
     if (agents.length === 0) {
-        return;
+        return [];
     }
+    // Ensure platform and runtime dependencies are present.
+    checkPlatformSupport();
     await getRunCommand();
     const runtime = buildAuthRuntimeContext();
+    const issues = [];
     for (const agent of agents) {
-        const provider = resolveAgentProvider(agent);
-        try {
-            await provider.verify({
+        const providerId = agent.provider?.trim();
+        if (!providerId) {
+            issues.push({ agentId: agent.id, message: "missing provider" });
+            continue;
+        }
+        const provider = resolveAuthProvider(providerId);
+        if (!provider) {
+            issues.push({
                 agentId: agent.id,
-                runtime,
+                message: `unknown auth provider "${providerId}"`,
             });
+            continue;
+        }
+        try {
+            await provider.verify({ agentId: agent.id, runtime });
         }
         catch (error) {
-            throw new AuthProviderVerificationError(extractAuthProviderMessage(error));
+            pushIssueLines(issues, agent.id, extractAuthProviderMessage(error));
         }
     }
+    return issues;
 }
 export async function stageAgentAuth(options) {
-    const { agent, agentRoot, runId } = options;
+    const { agent, agentRoot, runId, root } = options;
     const provider = resolveAgentProvider(agent);
     const runtime = options.runtime ?? buildAuthRuntimeContext();
+    const includeConfigToml = shouldIncludeCodexConfigToml(root);
     try {
         const stageResult = await provider.stage({
             agentId: agent.id,
             agentRoot,
             runtime,
-            runId,
-            root: options.root,
+            runId: runId ?? "runtime",
+            root,
+            includeConfigToml,
         });
         return {
             env: stageResult.env,
@@ -43,7 +60,6 @@ export async function stageAgentAuth(options) {
                 sandboxPath: stageResult.sandboxPath,
                 runtime,
                 agentId: agent.id,
-                runId,
             },
         };
     }
@@ -80,6 +96,10 @@ export async function teardownAuthContext(context) {
     }
 }
 const tornDownContexts = new WeakSet();
+function shouldIncludeCodexConfigToml(root) {
+    const settings = loadRepoSettings({ root });
+    return settings.codex.globalConfigPolicy !== "ignore";
+}
 function isIgnorableTeardownError(error) {
     if (!isFileSystemError(error)) {
         return false;
@@ -98,11 +118,21 @@ function resolveAgentProvider(agent) {
     return provider;
 }
 function extractAuthProviderMessage(error) {
-    if (error instanceof RunCommandError) {
-        return error.messageForDisplay();
-    }
     if (error instanceof Error && error.message) {
         return error.message;
     }
     return toErrorMessage(error);
 }
+function pushIssueLines(issues, agentId, message) {
+    const lines = message
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        issues.push({ agentId, message: "unknown error" });
+        return;
+    }
+    for (const line of lines) {
+        issues.push({ agentId, message: line });
+    }
+}

package/dist/agents/runtime/chat.d.ts

@@ -0,0 +1,5 @@
+import type { AgentRuntimeChatResult } from "./types.js";
+export declare function captureAgentChatArtifacts(options: {
+    providerId: string | undefined;
+    agentRoot: string;
+}): Promise<AgentRuntimeChatResult>;

package/dist/agents/runtime/chat.js

@@ -0,0 +1,28 @@
+import { preserveProviderChatTranscripts } from "../../workspace/chat/artifacts.js";
+export async function captureAgentChatArtifacts(options) {
+    const providerId = options.providerId ?? "";
+    if (!providerId) {
+        return { captured: false };
+    }
+    const result = await preserveProviderChatTranscripts({
+        providerId,
+        agentRoot: options.agentRoot,
+    });
+    const format = result.format;
+    if ((result.status === "captured" || result.status === "already-exists") &&
+        format) {
+        return {
+            captured: true,
+            format,
+            artifactPath: result.artifactPath,
+            sourceCount: result.sourceCount,
+        };
+    }
+    if (result.status === "not-found") {
+        return { captured: false };
+    }
+    return {
+        captured: false,
+        error: result.status === "error" ? result.error : undefined,
+    };
+}

package/dist/agents/runtime/errors.d.ts

@@ -0,0 +1,27 @@
+import { DisplayableError } from "../../utils/errors.js";
+export type AgentRuntimeErrorKind = "auth" | "manifest" | "sandbox" | "process";
+export declare class AgentRuntimeError extends DisplayableError {
+    readonly kind: AgentRuntimeErrorKind;
+    constructor(kind: AgentRuntimeErrorKind, message: string);
+}
+export declare class MissingAgentProviderError extends AgentRuntimeError {
+    constructor(agentId: string);
+}
+export declare class UnknownAuthProviderError extends AgentRuntimeError {
+    constructor(providerId: string);
+}
+export declare class AuthProviderVerificationError extends AgentRuntimeError {
+    constructor(detail: string);
+}
+export declare class AuthProviderStageError extends AgentRuntimeError {
+    constructor(detail: string);
+}
+export declare class AgentRuntimeManifestError extends AgentRuntimeError {
+    constructor(detail: string);
+}
+export declare class AgentRuntimeSandboxError extends AgentRuntimeError {
+    constructor(detail: string);
+}
+export declare class AgentRuntimeProcessError extends AgentRuntimeError {
+    constructor(detail: string);
+}

package/dist/agents/runtime/errors.js

@@ -0,0 +1,51 @@
+import { DisplayableError } from "../../utils/errors.js";
+export class AgentRuntimeError extends DisplayableError {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "AgentRuntimeError";
+    }
+}
+export class MissingAgentProviderError extends AgentRuntimeError {
+    constructor(agentId) {
+        super("auth", `Agent "${agentId}" missing provider.`);
+        this.name = "MissingAgentProviderError";
+    }
+}
+export class UnknownAuthProviderError extends AgentRuntimeError {
+    constructor(providerId) {
+        super("auth", `Unknown auth provider "${providerId}".`);
+        this.name = "UnknownAuthProviderError";
+    }
+}
+export class AuthProviderVerificationError extends AgentRuntimeError {
+    constructor(detail) {
+        super("auth", detail);
+        this.name = "AuthProviderVerificationError";
+    }
+}
+export class AuthProviderStageError extends AgentRuntimeError {
+    constructor(detail) {
+        super("auth", detail);
+        this.name = "AuthProviderStageError";
+    }
+}
+export class AgentRuntimeManifestError extends AgentRuntimeError {
+    constructor(detail) {
+        super("manifest", detail);
+        this.name = "AgentRuntimeManifestError";
+    }
+}
+export class AgentRuntimeSandboxError extends AgentRuntimeError {
+    constructor(detail) {
+        super("sandbox", detail);
+        this.name = "AgentRuntimeSandboxError";
+    }
+}
+export class AgentRuntimeProcessError extends AgentRuntimeError {
+    constructor(detail) {
+        super("process", detail);
+        this.name = "AgentRuntimeProcessError";
+    }
+}

package/dist/{commands/run/agents → agents/runtime}/failures.d.ts

@@ -1,5 +1,4 @@
 export interface AgentFailureDetectionInput {
-    agentId: string;
     provider: string;
     stdoutPath: string;
     stderrPath: string;

package/dist/agents/runtime/failures.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import { CLAUDE_OAUTH_RELOGIN_HINT, CLAUDE_PROVIDER_ID, } from "../../auth/providers/claude/constants.js";
+const GEMINI_PROVIDER_ID = "gemini";
+const CODEX_PROVIDER_ID = "codex";
+const CLAUDE_FAILURE_PATTERNS = [
+    /Please run \/login/i,
+    /OAuth token has expired/i,
+];
+const JSON_MESSAGE_PATTERN = /"message"\s*:\s*"((?:\\.|[^"\\])*)"/;
+export async function detectAgentProcessFailureDetail(input) {
+    if (input.provider !== CLAUDE_PROVIDER_ID &&
+        input.provider !== GEMINI_PROVIDER_ID &&
+        input.provider !== CODEX_PROVIDER_ID) {
+        return undefined;
+    }
+    const combinedLogs = await readCombinedLogs(input.stdoutPath, input.stderrPath);
+    if (!combinedLogs) {
+        return undefined;
+    }
+    if (input.provider === CLAUDE_PROVIDER_ID) {
+        if (CLAUDE_FAILURE_PATTERNS.some((pattern) => pattern.test(combinedLogs))) {
+            return CLAUDE_OAUTH_RELOGIN_HINT;
+        }
+        return undefined;
+    }
+    if (input.provider === GEMINI_PROVIDER_ID) {
+        return (extractFirstJsonMessage(combinedLogs) ??
+            extractGeminiFallbackLine(combinedLogs));
+    }
+    if (input.provider === CODEX_PROVIDER_ID) {
+        return (extractFirstJsonMessage(combinedLogs) ??
+            findFirstMatchingLine(combinedLogs, [
+                /invalid_request_error/,
+                /unsupported_value/,
+                /thread .* panicked/i,
+            ]));
+    }
+    return undefined;
+}
+function extractFirstJsonMessage(text) {
+    const match = JSON_MESSAGE_PATTERN.exec(text);
+    if (!match) {
+        return undefined;
+    }
+    const raw = match[1]?.trim();
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(`"${raw}"`);
+        return isMeaningfulMessage(parsed) ? parsed : undefined;
+    }
+    catch {
+        return isMeaningfulMessage(raw) ? raw : undefined;
+    }
+}
+function isMeaningfulMessage(message) {
+    const normalized = message.trim();
+    if (!normalized) {
+        return false;
+    }
+    if (normalized === "[object Object]") {
+        return false;
+    }
+    return true;
+}
+function findFirstMatchingLine(text, matchers) {
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        for (const matcher of matchers) {
+            const match = matcher.exec(trimmed);
+            if (match) {
+                return trimmed.slice(match.index).trim();
+            }
+        }
+    }
+    return undefined;
+}
+function extractGeminiFallbackLine(text) {
+    return findFirstMatchingLine(text, [
+        /TerminalQuotaError:/,
+        /PERMISSION_DENIED/,
+        /RESOURCE_EXHAUSTED/,
+        /No capacity available/i,
+        /You have exhausted your capacity/i,
+        /exhausted your capacity/i,
+    ]);
+}
+async function readCombinedLogs(stdoutPath, stderrPath) {
+    const [stdout, stderr] = await Promise.all([
+        safeRead(stdoutPath),
+        safeRead(stderrPath),
+    ]);
+    return `${stdout}\n${stderr}`;
+}
+async function safeRead(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/agents/runtime/harness.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRuntimeHarnessInput, AgentRuntimeHarnessResult } from "./types.js";
+export declare function runSandboxedAgent(input: AgentRuntimeHarnessInput): Promise<AgentRuntimeHarnessResult>;

package/dist/agents/runtime/harness.js

@@ -0,0 +1,125 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { loadSandboxProviderConfig } from "../../configs/sandbox/loader.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { stageAgentAuth } from "./auth.js";
+import { captureAgentChatArtifacts } from "./chat.js";
+import { AgentRuntimeError, AgentRuntimeProcessError, AgentRuntimeSandboxError, } from "./errors.js";
+import { configureSandboxSettings, runAgentProcess } from "./launcher.js";
+import { writeAgentManifest } from "./manifest.js";
+import { registerStagedAuthContext, teardownRegisteredAuthContext, } from "./registry.js";
+import { DEFAULT_DENIAL_BACKOFF } from "./sandbox.js";
+const PROMPT_TMP_PREFIX = "prompt.ephemeral";
+export async function runSandboxedAgent(input) {
+    const { root, agent, prompt, environment, paths, sessionId, sandboxProviderId, sandboxPolicyOverrides, extraWriteProtectedPaths, extraReadProtectedPaths, captureChat = true, onWatchdogTrigger, } = input;
+    const providerId = sandboxProviderId ?? agent.provider ?? "";
+    if (!providerId) {
+        throw new AgentRuntimeSandboxError(`Agent "${agent.id}" missing provider.`);
+    }
+    await mkdir(dirname(paths.runtimeManifestPath), { recursive: true });
+    await mkdir(dirname(paths.sandboxSettingsPath), { recursive: true });
+    await mkdir(dirname(paths.stdoutPath), { recursive: true });
+    await mkdir(dirname(paths.stderrPath), { recursive: true });
+    const promptPath = await writeEphemeralPrompt({
+        runtimePath: paths.runtimePath,
+        prompt,
+    });
+    let authContext;
+    try {
+        const staged = await stageAgentAuth({
+            agent,
+            agentRoot: paths.agentRoot,
+            root,
+            runId: sessionId,
+        });
+        authContext = staged.context;
+        if (sessionId) {
+            registerStagedAuthContext(sessionId, authContext);
+        }
+        const manifestEnv = await writeAgentManifest({
+            agent,
+            runtimeManifestPath: paths.runtimeManifestPath,
+            promptPath,
+            workspacePath: paths.workspacePath,
+            env: staged.env,
+            environment,
+        });
+        const denialBackoff = resolveDenialBackoff({
+            root,
+            providerId,
+            override: input.denialBackoff,
+        });
+        const { sandboxSettings } = await configureSandboxSettings({
+            sandboxHomePath: paths.sandboxHomePath,
+            workspacePath: paths.workspacePath,
+            providerId,
+            root,
+            sandboxSettingsPath: paths.sandboxSettingsPath,
+            runtimePath: paths.runtimePath,
+            artifactsPath: paths.artifactsPath,
+            policyOverrides: sandboxPolicyOverrides,
+            extraWriteProtectedPaths,
+            extraReadProtectedPaths,
+        });
+        const processResult = await runAgentProcess({
+            runtimeManifestPath: paths.runtimeManifestPath,
+            agentRoot: paths.agentRoot,
+            stdoutPath: paths.stdoutPath,
+            stderrPath: paths.stderrPath,
+            sandboxSettingsPath: paths.sandboxSettingsPath,
+            providerId,
+            denialBackoff,
+            onWatchdogTrigger,
+        });
+        const chat = captureChat
+            ? await captureAgentChatArtifacts({
+                providerId: agent.provider,
+                agentRoot: paths.agentRoot,
+            })
+            : undefined;
+        return {
+            exitCode: processResult.exitCode,
+            errorMessage: processResult.errorMessage,
+            signal: processResult.signal,
+            watchdog: processResult.watchdog,
+            failFast: processResult.failFast,
+            sandboxSettings,
+            manifestEnv,
+            ...(chat ? { chat } : {}),
+        };
+    }
+    catch (error) {
+        if (error instanceof AgentRuntimeError) {
+            throw error;
+        }
+        throw new AgentRuntimeProcessError(error instanceof Error ? error.message : toErrorMessage(error));
+    }
+    finally {
+        await rm(promptPath, { force: true }).catch(() => { });
+        await teardownRegisteredAuthContext(sessionId ?? "runtime", authContext).catch(() => { });
+    }
+}
+async function writeEphemeralPrompt(options) {
+    const { runtimePath, prompt } = options;
+    const nonce = randomBytes(8).toString("hex");
+    const path = join(runtimePath, `${PROMPT_TMP_PREFIX}.${nonce}.txt`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, prompt, { encoding: "utf8" });
+    return path;
+}
+function resolveDenialBackoff(options) {
+    if (options.override) {
+        return options.override;
+    }
+    try {
+        const config = loadSandboxProviderConfig({
+            root: options.root,
+            providerId: options.providerId,
+        });
+        return config.denialBackoff;
+    }
+    catch {
+        return DEFAULT_DENIAL_BACKOFF;
+    }
+}

package/dist/{commands/run/agents/sandbox-launcher.d.ts → agents/runtime/launcher.d.ts}

@@ -1,5 +1,7 @@
-import type { WatchdogMetadata } from "../../../records/types.js";
-import type { AgentWorkspacePaths } from "../../../workspace/layout.js";
+import type { DenialBackoffConfig } from "../../configs/sandbox/types.js";
+import type { WatchdogMetadata } from "../../runs/records/types.js";
+import { generateSandboxSettings, type SandboxFailFastInfo } from "./sandbox.js";
+import type { SandboxPolicyOverrides } from "./types.js";
 import { type WatchdogTrigger } from "./watchdog.js";
 export interface AgentProcessOptions {
     runtimeManifestPath: string;
@@ -7,11 +9,12 @@ export interface AgentProcessOptions {
     stdoutPath: string;
     stderrPath: string;
     sandboxSettingsPath: string;
+    denialBackoff?: DenialBackoffConfig;
     resolveRunInvocation?: RunInvocationResolver;
     /** Provider ID for watchdog fatal pattern matching. */
     providerId?: string;
     /** Callback fired immediately when watchdog triggers, before process exits. */
-    onWatchdogTrigger?: (trigger: WatchdogTrigger, reason: string) => void;
+    onWatchdogTrigger?: (trigger: WatchdogTrigger, reason: string, failFast?: SandboxFailFastInfo) => void;
 }
 export interface AgentProcessResult {
     exitCode: number;
@@ -19,6 +22,8 @@ export interface AgentProcessResult {
     signal?: NodeJS.Signals | null;
     /** Watchdog metadata showing enforced limits and trigger reason. */
     watchdog?: WatchdogMetadata;
+    /** Sandbox fail-fast metadata when repeated denials trigger an abort. */
+    failFast?: SandboxFailFastInfo;
 }
 export interface RunInvocationContext {
     agentRoot: string;
@@ -32,11 +37,21 @@ export interface RunInvocation {
 }
 export type RunInvocationResolver = (context: RunInvocationContext) => Promise<RunInvocation> | RunInvocation;
 export interface SandboxSettingsInput {
-    workspacePaths: AgentWorkspacePaths;
+    sandboxHomePath: string;
+    workspacePath: string;
     providerId: string;
     root: string;
+    repoRootPath?: string;
+    sandboxSettingsPath: string;
+    runtimePath: string;
+    artifactsPath: string;
+    policyOverrides?: SandboxPolicyOverrides;
+    extraWriteProtectedPaths?: readonly string[];
+    extraReadProtectedPaths?: readonly string[];
 }
-export declare function configureSandboxSettings(input: SandboxSettingsInput): Promise<void>;
+export declare function configureSandboxSettings(input: SandboxSettingsInput): Promise<{
+    sandboxSettings: ReturnType<typeof generateSandboxSettings>;
+}>;
 export declare function getRunCommand(): Promise<string>;
 export declare function runAgentProcess(options: AgentProcessOptions): Promise<AgentProcessResult>;
 export declare function stageManifestForSandbox(options: {