voratiq 0.1.0-beta.2 → 0.1.0-beta.20

package/README.md

@@ -1,58 +1,70 @@
 # Voratiq
 
-Run agents in parallel, compare results, and apply the best solution.
+Agent ensembles to design, generate, and select the best code for every task.
 
-![`voratiq run --spec specs/p1/agent-workspace-guardrails.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
+![`voratiq auto --spec .voratiq/spec/categorical-performance-by-taxonomy.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
+
+No single model wins every task. Run several, keep the best result. [Here's why that works](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:
+<details>
+<summary>Requirements</summary>
 
 - 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.1.63](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [>=0.107.0](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [>=0.31.0](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.
+
+</details>
 
 ## Quick Start
 
+Get started with a single command:
+
 ```bash
-# Initialize workspace
-voratiq init
+voratiq
+```
 
-# 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
+This drops you into an interactive session with an agent of your choice.
 
-# Run agents in parallel
-voratiq run --spec specs/fix-auth.md
+That agent gets access to Voratiq tools for orchestration and verification.
 
-# Review results
-voratiq review --run <run-id>
+Describe what you want built, and the agent can use those tools to:
 
-# Apply the best solution
-voratiq apply --run <run-id> --agent <agent-id>
-```
+- turn your request into a structured execution plan
+- delegate work to a custom-designed swarm or a multi-stage workflow
+- verify outputs and compare alternatives before choosing what to keep
+- track outcomes across runs to learn which agents and workflows work best
+
+You keep the native interactive workflow, with more execution depth and control.
+
+## Documentation
+
+Start here:
+
+- [Tutorial](https://github.com/voratiq/voratiq/blob/main/docs/tutorial.md) - End-to-end walkthrough
+- [CLI Reference](https://github.com/voratiq/voratiq/blob/main/docs/cli-reference.md) - Commands and options
+- [Core Concepts](https://github.com/voratiq/voratiq/blob/main/docs/core-concepts.md) - Workflow model and design rationale
+
+Configuration:
 
-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.
+- [Agents](https://github.com/voratiq/voratiq/blob/main/docs/configs/agents.md) - Agent catalog and invocation details
+- [Orchestration](https://github.com/voratiq/voratiq/blob/main/docs/configs/orchestration.md) - Which agents run at each stage
+- [Verification](https://github.com/voratiq/voratiq/blob/main/docs/configs/verification.md) - How agent outputs are checked and scored before selection
+- [Environment](https://github.com/voratiq/voratiq/blob/main/docs/configs/environment.md) - Runtime dependencies for agents
+- [Sandbox](https://github.com/voratiq/voratiq/blob/main/docs/configs/sandbox.md) - Network and filesystem restrictions
 
 ## License
 

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

@@ -0,0 +1,23 @@
+import { type ProviderTranscriptBaseline } from "../../workspace/chat/artifacts.js";
+import type { ChatArtifactFormat } from "../../workspace/chat/types.js";
+export interface LaunchArtifactCaptureResult {
+    readonly captured: boolean;
+    readonly format?: ChatArtifactFormat;
+    readonly artifactPath?: string;
+    readonly sourceCount?: number;
+    readonly error?: unknown;
+}
+export interface LaunchArtifactCaptureContext {
+    readonly searchEnv?: NodeJS.ProcessEnv;
+    readonly baseline?: ProviderTranscriptBaseline;
+}
+export declare function prepareProviderArtifactCaptureContext(options: {
+    providerId: string | undefined;
+    sessionRoot: string;
+    searchEnv?: NodeJS.ProcessEnv;
+}): Promise<LaunchArtifactCaptureContext | undefined>;
+export declare function collectProviderArtifacts(options: {
+    providerId: string | undefined;
+    sessionRoot: string;
+    captureContext?: LaunchArtifactCaptureContext;
+}): Promise<LaunchArtifactCaptureResult>;

package/dist/agents/launch/chat.js

@@ -0,0 +1,44 @@
+import { preserveProviderChatTranscripts, snapshotProviderTranscripts, } from "../../workspace/chat/artifacts.js";
+export async function prepareProviderArtifactCaptureContext(options) {
+    const providerId = options.providerId ?? "";
+    if (!providerId) {
+        return undefined;
+    }
+    return {
+        searchEnv: options.searchEnv,
+        baseline: await snapshotProviderTranscripts({
+            providerId,
+            agentRoot: options.sessionRoot,
+            searchEnv: options.searchEnv,
+        }),
+    };
+}
+export async function collectProviderArtifacts(options) {
+    const providerId = options.providerId ?? "";
+    if (!providerId) {
+        return { captured: false };
+    }
+    const result = await preserveProviderChatTranscripts({
+        providerId,
+        agentRoot: options.sessionRoot,
+        searchEnv: options.captureContext?.searchEnv,
+        baseline: options.captureContext?.baseline,
+    });
+    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/launch/environment.d.ts

@@ -0,0 +1,8 @@
+import { type EnvironmentConfig } from "../../configs/environment/types.js";
+export declare function composeLaunchEnvironment(options: {
+    baseEnv: Record<string, string>;
+    workspacePath: string;
+    environment: EnvironmentConfig;
+}): Promise<Record<string, string>>;
+export declare function mergePathEntries(prepends: readonly string[], existing: string): string;
+export declare function normalizeRelative(origin: string, target: string): string;

package/dist/{commands/run/agents/workspace-prep.js → agents/launch/environment.js}

@@ -1,30 +1,8 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { delimiter, dirname, relative as relativePath } from "node:path";
-import { getNodeDependencyRoots, getPythonEnvironmentPath, } from "../../../configs/environment/types.js";
-import { pathExists } from "../../../utils/fs.js";
-import { resolvePath } from "../../../utils/path.js";
-export async function writeAgentManifest(options) {
-    const { agent, workspacePaths, env = {}, environment } = options;
-    const { promptPath, runtimeManifestPath, workspacePath } = workspacePaths;
-    const manifestDir = dirname(runtimeManifestPath);
-    const manifestEnv = await composeManifestEnvironment({
-        baseEnv: env,
-        workspacePath,
-        environment,
-    });
-    const manifest = {
-        binary: agent.binary,
-        argv: [...agent.argv],
-        promptPath: normalizeRelative(manifestDir, promptPath),
-        workspace: normalizeRelative(manifestDir, workspacePath),
-        env: manifestEnv,
-    };
-    const manifestJson = `${JSON.stringify(manifest, null, 2)}\n`;
-    await mkdir(dirname(runtimeManifestPath), { recursive: true });
-    await writeFile(runtimeManifestPath, manifestJson, { encoding: "utf8" });
-    return manifestEnv;
-}
-export async function composeManifestEnvironment(options) {
+import { delimiter, relative as relativePath } from "node:path";
+import { getNodeDependencyRoots, getPythonEnvironmentPath, } from "../../configs/environment/types.js";
+import { pathExists } from "../../utils/fs.js";
+import { resolvePath } from "../../utils/path.js";
+export async function composeLaunchEnvironment(options) {
     const { baseEnv, workspacePath, environment } = options;
     const result = { ...baseEnv };
     const pathPrepends = [];

package/dist/agents/launch/prompt.d.ts

@@ -0,0 +1,6 @@
+export interface WriteStagedPromptOptions {
+    runtimePath: string;
+    prompt: string;
+    prefix?: string;
+}
+export declare function writeStagedPrompt(options: WriteStagedPromptOptions): Promise<string>;

package/dist/agents/launch/prompt.js

@@ -0,0 +1,12 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const PROMPT_TMP_PREFIX = "prompt.ephemeral";
+export async function writeStagedPrompt(options) {
+    const { runtimePath, prompt, prefix = PROMPT_TMP_PREFIX } = options;
+    const nonce = randomBytes(8).toString("hex");
+    const path = join(runtimePath, `${prefix}.${nonce}.txt`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, prompt, { encoding: "utf8" });
+    return path;
+}

package/dist/agents/launch/provider-state.d.ts

@@ -0,0 +1,39 @@
+import type { AuthProvider, AuthRuntimeContext } from "../../auth/providers/types.js";
+import type { AgentDefinition } from "../../configs/agents/types.js";
+export interface StagedProviderStateContext {
+    provider: AuthProvider;
+    sandboxPath: string;
+    runtime: AuthRuntimeContext;
+    agentId: string;
+}
+export interface StageProviderStateOptions {
+    agent: AgentDefinition;
+    agentRoot: string;
+    root: string;
+    runId?: string;
+    runtime?: AuthRuntimeContext;
+    includeConfigToml?: boolean;
+}
+export interface StageProviderStateResult {
+    env: Record<string, string>;
+    context: StagedProviderStateContext;
+}
+export type AgentProviderResolutionCode = "missing_provider" | "unknown_provider";
+export interface AgentProviderResolutionFailure {
+    ok: false;
+    code: AgentProviderResolutionCode;
+    message: string;
+}
+export interface AgentProviderResolutionSuccess {
+    ok: true;
+    provider: AuthProvider;
+}
+export type AgentProviderResolutionResult = AgentProviderResolutionFailure | AgentProviderResolutionSuccess;
+export declare function resolveAgentProviderForDefinition(agent: Pick<AgentDefinition, "id" | "provider">): AgentProviderResolutionResult;
+export declare function stageAgentProviderState(options: StageProviderStateOptions): Promise<StageProviderStateResult>;
+export declare function teardownProviderState(context: StagedProviderStateContext | undefined): Promise<void>;
+export declare function extractProviderErrorMessage(error: unknown): string;
+export declare class ProviderResolutionError extends Error {
+    readonly code: AgentProviderResolutionCode;
+    constructor(code: AgentProviderResolutionCode, message: string);
+}

package/dist/agents/launch/provider-state.js

@@ -0,0 +1,103 @@
+import { rm } from "node:fs/promises";
+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";
+export function resolveAgentProviderForDefinition(agent) {
+    const providerId = agent.provider?.trim();
+    if (!providerId) {
+        return {
+            ok: false,
+            code: "missing_provider",
+            message: `Agent \`${agent.id}\` is missing a provider.`,
+        };
+    }
+    const provider = resolveAuthProvider(providerId);
+    if (!provider) {
+        return {
+            ok: false,
+            code: "unknown_provider",
+            message: `Unknown auth provider \`${providerId}\`.`,
+        };
+    }
+    return { ok: true, provider };
+}
+export async function stageAgentProviderState(options) {
+    const runtime = options.runtime ?? buildAuthRuntimeContext();
+    const resolution = resolveAgentProviderForDefinition(options.agent);
+    if (!resolution.ok) {
+        throw new ProviderResolutionError(resolution.code, resolution.message);
+    }
+    const includeConfigToml = options.includeConfigToml ?? shouldIncludeCodexConfigToml(options.root);
+    const stageResult = await resolution.provider.stage({
+        agentId: options.agent.id,
+        agentRoot: options.agentRoot,
+        runtime,
+        runId: options.runId ?? "runtime",
+        root: options.root,
+        includeConfigToml,
+    });
+    return {
+        env: stageResult.env,
+        context: {
+            provider: resolution.provider,
+            sandboxPath: stageResult.sandboxPath,
+            runtime,
+            agentId: options.agent.id,
+        },
+    };
+}
+export async function teardownProviderState(context) {
+    if (!context) {
+        return;
+    }
+    if (tornDownContexts.has(context)) {
+        return;
+    }
+    tornDownContexts.add(context);
+    try {
+        if (context.provider.teardown) {
+            try {
+                await context.provider.teardown({
+                    sandboxPath: context.sandboxPath,
+                });
+            }
+            catch (error) {
+                if (!isIgnorableTeardownError(error)) {
+                    throw error;
+                }
+            }
+        }
+        await rm(context.sandboxPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        tornDownContexts.delete(context);
+        throw error;
+    }
+}
+export function extractProviderErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return toErrorMessage(error);
+}
+const tornDownContexts = new WeakSet();
+function shouldIncludeCodexConfigToml(root) {
+    const settings = loadRepoSettings({ root });
+    return settings.bounded.codex.globalConfigPolicy !== "ignore";
+}
+function isIgnorableTeardownError(error) {
+    if (!isFileSystemError(error)) {
+        return false;
+    }
+    return error.code === "ENOENT";
+}
+export class ProviderResolutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProviderResolutionError";
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { AuthRuntimeContext } from "../../auth/providers/types.js";
+import type { AgentDefinition } from "../../configs/agents/types.js";
+import { type StagedProviderStateContext } from "../launch/provider-state.js";
+export interface StagedAuthContext {
+    provider: StagedProviderStateContext["provider"];
+    sandboxPath: StagedProviderStateContext["sandboxPath"];
+    runtime: StagedProviderStateContext["runtime"];
+    agentId: StagedProviderStateContext["agentId"];
+}
+export interface StageAuthOptions {
+    agent: AgentDefinition;
+    agentRoot: string;
+    root: string;
+    runId?: string;
+    runtime?: AuthRuntimeContext;
+}
+export interface StageAuthResult {
+    env: Record<string, string>;
+    context: StagedAuthContext;
+}
+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/agents/runtime/auth.js

@@ -0,0 +1,72 @@
+import { resolveAuthProvider } from "../../auth/providers/index.js";
+import { buildAuthRuntimeContext } from "../../auth/runtime.js";
+import { extractProviderErrorMessage, ProviderResolutionError, stageAgentProviderState, teardownProviderState, } from "../launch/provider-state.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 [];
+    }
+    // Ensure platform and runtime dependencies are present.
+    checkPlatformSupport();
+    await getRunCommand();
+    const runtime = buildAuthRuntimeContext();
+    const issues = [];
+    for (const agent of agents) {
+        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,
+                message: `unknown auth provider \`${providerId}\``,
+            });
+            continue;
+        }
+        try {
+            await provider.verify({ agentId: agent.id, runtime });
+        }
+        catch (error) {
+            pushIssueLines(issues, agent.id, extractAuthProviderMessage(error));
+        }
+    }
+    return issues;
+}
+export async function stageAgentAuth(options) {
+    try {
+        return await stageAgentProviderState(options);
+    }
+    catch (error) {
+        if (error instanceof ProviderResolutionError) {
+            if (error.code === "missing_provider") {
+                throw new MissingAgentProviderError(options.agent.id);
+            }
+            const providerId = options.agent.provider?.trim() ?? "";
+            throw new UnknownAuthProviderError(providerId);
+        }
+        throw new AuthProviderStageError(extractAuthProviderMessage(error));
+    }
+}
+export async function teardownAuthContext(context) {
+    await teardownProviderState(context);
+}
+function extractAuthProviderMessage(error) {
+    return extractProviderErrorMessage(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,7 @@
+import { collectProviderArtifacts } from "../launch/chat.js";
+export async function captureAgentChatArtifacts(options) {
+    return await collectProviderArtifacts({
+        providerId: options.providerId,
+        sessionRoot: options.agentRoot,
+    });
+}

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}\` is missing a 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;