@vercel/factory 0.0.0 → 0.0.1

package/dist/eve/index.d.ts

@@ -1,16 +1,424 @@
+import * as eve_hooks from 'eve/hooks';
 import * as eve_tools from 'eve/tools';
-import { F as FactoryStores } from '../engine-BXVTLiXU.js';
+import { z } from 'zod';
+import { F as FactoryStores, A as ApprovalPolicy, a as Finding } from '../approval-Z7iaWibT.js';
 import '../common-CaHaEOAS.js';
-import 'zod';
 import '../driver-tRNggCCJ.js';
 
+/** The subset of the eve sandbox handle a credentialed git operation needs. */
+interface CommandSandbox {
+    run(options: {
+        command: string;
+    }): PromiseLike<{
+        stdout: string;
+        stderr?: string;
+        exitCode?: number;
+    }>;
+}
+interface FetchPullRequestOptions<S extends CommandSandbox = CommandSandbox> {
+    /**
+     * Runs one git command against `slug` with a credential the sandbox does not
+     * otherwise have, and removes it again before resolving. Supplied by the
+     * app, which owns how credentials are minted and where they are injected;
+     * the library only decides what is fetched.
+     */
+    withCredential: (sandbox: S, slug: string, command: string) => Promise<{
+        stdout: string;
+        stderr?: string;
+        exitCode?: number;
+    }>;
+    /** Path of the checkout inside the sandbox. Defaults to `repo`. */
+    repoPath?: string;
+    /** Fetch depth for the pull request head. Defaults to 50. */
+    depth?: number;
+}
+type FetchPullRequestResult = {
+    fetched: false;
+    reason: string;
+} | {
+    fetched: true;
+    prNumber: number;
+    prUrl: string;
+    branch: string;
+    headSha: string;
+};
+/**
+ * The verifier's way in to the change under review. The sandbox has no
+ * GitHub credential while the agent runs, so trusted code does the one fetch
+ * the agent cannot: the pull request number and repository come from the
+ * change record, never from the agent, and the credential is gone again
+ * before control returns. Mirrors how publication reads commits out of the
+ * sandbox instead of letting the agent push.
+ */
+declare function fetchPullRequestTool<S extends CommandSandbox>(stores: FactoryStores, options: FetchPullRequestOptions<S>): eve_tools.ToolDefinition<{
+    changeId: string;
+}, FetchPullRequestResult> & {
+    execute(input: {
+        changeId: string;
+    }, ctx: eve_tools.ToolContext): Promise<FetchPullRequestResult>;
+};
+
+interface RecordFindingOptions {
+    /** Signal source the findings are recorded under. Defaults to security_scan. */
+    source?: string;
+    /** Which resulting tasks wait for a human. Defaults to the standard policy. */
+    approval?: ApprovalPolicy;
+}
+type RecordFindingResult = {
+    recorded: false;
+    reason: string;
+    duplicate?: true;
+    signalId?: string;
+} | {
+    recorded: true;
+    signalId: string;
+    taskId: string;
+    approval: "required" | "not_required";
+};
+/**
+ * Turn one finding into a signal and a fix task. The fingerprint is the
+ * signal's delivery id, so the same problem reported twice is a no-op. The
+ * signal is accepted on the reporter's own verification (a human gate follows
+ * when the approval policy says so), and the task carries the approval
+ * decision from the moment it exists. Shared by record_finding and scanner
+ * tools that record on the agent's behalf.
+ */
+declare function recordFinding(stores: FactoryStores, repositoryId: string, finding: Finding, options?: RecordFindingOptions): Promise<RecordFindingResult>;
+/**
+ * The scanner's outcome tool: turns one finding into a signal and a fix task
+ * in a single deterministic step. The finding's fingerprint is the signal's
+ * delivery id, so reporting the same problem twice is a no-op. The signal is
+ * accepted on the reporter's own verification (a human gate follows when the
+ * approval policy says so), and the task carries the approval decision from
+ * the moment it exists.
+ */
+declare function recordFindingTool(stores: FactoryStores, options?: RecordFindingOptions): eve_tools.ToolDefinition<{
+    repositoryId: string;
+    finding: {
+        title: string;
+        body: string;
+        priority: "P0" | "P1" | "P2" | "P3";
+        category: "security" | "correctness" | "reliability" | "performance" | "compatibility" | "accessibility" | "documentation" | "maintainability" | "testing" | "usability";
+        verification: {
+            level: "unverified" | "supported" | "confirmed";
+            method: "documentation" | "code_inspection" | "static_analysis" | "manual_reproduction" | "unit_test" | "integration_test" | "e2e_test" | "runtime_observation";
+            summary: string;
+            limitations?: string | undefined;
+        };
+        path?: string | undefined;
+        line?: number | undefined;
+        endLine?: number | undefined;
+        tool?: string | undefined;
+        ruleId?: string | undefined;
+    };
+}, RecordFindingResult> & {
+    execute(input: {
+        repositoryId: string;
+        finding: {
+            title: string;
+            body: string;
+            priority: "P0" | "P1" | "P2" | "P3";
+            category: "security" | "correctness" | "reliability" | "performance" | "compatibility" | "accessibility" | "documentation" | "maintainability" | "testing" | "usability";
+            verification: {
+                level: "unverified" | "supported" | "confirmed";
+                method: "documentation" | "code_inspection" | "static_analysis" | "manual_reproduction" | "unit_test" | "integration_test" | "e2e_test" | "runtime_observation";
+                summary: string;
+                limitations?: string | undefined;
+            };
+            path?: string | undefined;
+            line?: number | undefined;
+            endLine?: number | undefined;
+            tool?: string | undefined;
+            ruleId?: string | undefined;
+        };
+    }, ctx: eve_tools.ToolContext): Promise<RecordFindingResult>;
+};
+
+interface DeepsecScanOptions<S extends CommandSandbox = CommandSandbox> extends RecordFindingOptions {
+    /**
+     * Runs one shell command with the model credential deepsec's gateway route
+     * expects, and removes it again before resolving. Supplied by the app, which
+     * owns where the credential comes from: on Vercel it is the deployment's own
+     * OIDC identity (VERCEL_OIDC_TOKEN), so nothing has to be configured.
+     */
+    withModelCredential: (sandbox: S, command: string) => Promise<{
+        stdout: string;
+        stderr?: string;
+        exitCode?: number;
+    }>;
+    /** deepsec agent backend: claude, codex, or pi. */
+    agent?: "claude" | "codex" | "pi";
+    /** Model deepsec's investigation agent uses, through the AI Gateway (e.g. claude-sonnet-4-6). */
+    model?: string;
+    /** Reasoning effort for the investigation: minimal, low, medium, high, or xhigh. */
+    thinkingLevel?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    /** Parallel investigation batches. */
+    concurrency?: number;
+    /** deepsec version to install. */
+    version?: string;
+    /** Repository checkout inside the sandbox. Defaults to `repo`. */
+    repoPath?: string;
+    /** deepsec workspace inside the sandbox. Defaults to `deepsec`. */
+    workspacePath?: string;
+    /** Shell run before every deepsec command, e.g. to put a Node 24 on PATH. */
+    commandPrefix?: string;
+    /**
+     * Candidate files investigated per run. deepsec keeps state, so successive
+     * scans continue where the last one stopped; the cap keeps one run inside
+     * the deployment's time limit on large repositories. Defaults to 40.
+     */
+    filesPerRun?: number;
+}
+/** deepsec's exported finding shape, as far as we depend on it. */
+declare const deepsecFindingSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    severity: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{
+        filePath: z.ZodOptional<z.ZodString>;
+        lineNumbers: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        vulnSlug: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Convert one deepsec finding into the factory's Finding. Pure; exported for tests. */
+declare function findingFromDeepsec(raw: z.infer<typeof deepsecFindingSchema>): Finding;
+/**
+ * Runs deepsec (vercel-labs/deepsec) against the sandbox checkout and records
+ * what it finds through the same path as record_finding, so every deepsec
+ * finding becomes a fix task subject to the approval policy. Trusted code
+ * owns the command sequence and the credential; the agent chooses when to
+ * scan and reports the outcome.
+ */
+declare function deepsecScanTool<S extends CommandSandbox>(stores: FactoryStores, options: DeepsecScanOptions<S>): eve_tools.ToolDefinition<{
+    repositoryId: string;
+    limit?: number | undefined;
+}, {
+    scanned: false;
+    reason: string;
+    tool?: undefined;
+    found?: undefined;
+    recorded?: undefined;
+    duplicates?: undefined;
+    awaitingApproval?: undefined;
+    findings?: undefined;
+} | {
+    scanned: true;
+    tool: string;
+    found: number;
+    recorded: number;
+    duplicates: number;
+    awaitingApproval: number;
+    findings: ({
+        taskId: string;
+        approval: "required" | "not_required";
+        title: string;
+        priority: "P0" | "P1" | "P2" | "P3";
+        path: string | undefined;
+        line: number | undefined;
+    } | {
+        duplicate: boolean;
+        title: string;
+        priority: "P0" | "P1" | "P2" | "P3";
+        path: string | undefined;
+        line: number | undefined;
+    })[];
+    reason?: undefined;
+}> & {
+    execute(input: {
+        repositoryId: string;
+        limit?: number | undefined;
+    }, ctx: eve_tools.ToolContext): Promise<{
+        scanned: false;
+        reason: string;
+        tool?: undefined;
+        found?: undefined;
+        recorded?: undefined;
+        duplicates?: undefined;
+        awaitingApproval?: undefined;
+        findings?: undefined;
+    } | {
+        scanned: true;
+        tool: string;
+        found: number;
+        recorded: number;
+        duplicates: number;
+        awaitingApproval: number;
+        findings: ({
+            taskId: string;
+            approval: "required" | "not_required";
+            title: string;
+            priority: "P0" | "P1" | "P2" | "P3";
+            path: string | undefined;
+            line: number | undefined;
+        } | {
+            duplicate: boolean;
+            title: string;
+            priority: "P0" | "P1" | "P2" | "P3";
+            path: string | undefined;
+            line: number | undefined;
+        })[];
+        reason?: undefined;
+    }>;
+};
+
+interface InvokeAgentOptions {
+    /** The factory task kind the handoff creates, e.g. "verification". */
+    kind: string;
+    /** Model-facing description of what the target agent does and when to invoke it. */
+    description: string;
+    /**
+     * Base URL of the target agent's eve transport, e.g.
+     * `https://factory.example.com/eve/agents/verifier`. Resolved at call time so
+     * a deployment can derive it from its own origin.
+     */
+    targetUrl: () => string;
+    /** Bearer token for the target agent's eve channel, when it requires auth. */
+    token?: () => Promise<string | undefined>;
+    /** Extra headers for the session request, e.g. a deployment protection bypass. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+}
+/**
+ * A tool that lets one agent hand work to another, NMA-style: the caller
+ * decides to invoke; trusted code owns the how. The handoff is recorded as a
+ * factory task (single-winner dispatch, receipts), then a fresh session is
+ * started on the target agent carrying only the task id — never the caller's
+ * context. The session start is create-once on the task id, so a retried
+ * tool call cannot start a second session.
+ */
+declare function invokeAgentTool(stores: FactoryStores, options: InvokeAgentOptions): eve_tools.ToolDefinition<{
+    repositoryIds: string[];
+    channel: string;
+    address: string;
+    brief: string;
+    parentTaskId?: string | undefined;
+    changeId?: string | undefined;
+}, {
+    taskId: string;
+    kind: string;
+    state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+}> & {
+    execute(input: {
+        repositoryIds: string[];
+        channel: string;
+        address: string;
+        brief: string;
+        parentTaskId?: string | undefined;
+        changeId?: string | undefined;
+    }, ctx: eve_tools.ToolContext): Promise<{
+        taskId: string;
+        kind: string;
+        state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    }>;
+};
+
+/**
+ * The verifier's outcome tool. Writes evidence onto the change and moves it
+ * to ready only when the verdict is pass; a failed verdict leaves the change
+ * verifying with the evidence recorded, and the verification task itself
+ * ends with a receipt either way. The change's own code_change task follows
+ * the verdict too: succeeded on pass, failed on fail with the verifier's
+ * summary as the reason, so the ledger never shows a verified-and-rejected fix
+ * as still in progress. Fail closed: the agent cannot mark a change ready
+ * without supplying every evidence field.
+ */
+declare function recordVerificationTool(stores: FactoryStores): eve_tools.ToolDefinition<{
+    taskId: string;
+    changeId: string;
+    verdict: "pass" | "fail";
+    evidence: {
+        reproVerified: boolean;
+        testsAdded: number;
+        checksGreen: boolean;
+        attackPassed: boolean;
+        scopeMatches: boolean;
+        previewUrl?: string | undefined;
+    };
+    confidence: "low" | "medium" | "high";
+    summary: string;
+}, {
+    recorded: false;
+    reason: string;
+    verdict?: undefined;
+    changeState?: undefined;
+    taskState?: undefined;
+} | {
+    recorded: true;
+    verdict: "pass" | "fail";
+    changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
+    taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    reason?: undefined;
+}> & {
+    execute(input: {
+        taskId: string;
+        changeId: string;
+        verdict: "pass" | "fail";
+        evidence: {
+            reproVerified: boolean;
+            testsAdded: number;
+            checksGreen: boolean;
+            attackPassed: boolean;
+            scopeMatches: boolean;
+            previewUrl?: string | undefined;
+        };
+        confidence: "low" | "medium" | "high";
+        summary: string;
+    }, ctx: eve_tools.ToolContext): Promise<{
+        recorded: false;
+        reason: string;
+        verdict?: undefined;
+        changeState?: undefined;
+        taskState?: undefined;
+    } | {
+        recorded: true;
+        verdict: "pass" | "fail";
+        changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
+        taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        reason?: undefined;
+    }>;
+};
+
+declare const recordChangeInputSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    repositoryId: z.ZodString;
+    prNumber: z.ZodNumber;
+    prUrl: z.ZodURL;
+    risk: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    confidence: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    summary: z.ZodString;
+}, z.core.$strip>;
+type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;
+type GateVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+interface FactoryToolsOptions {
+    /**
+     * Pre-action gate for record_change, run as an eve approval policy before
+     * the tool executes. Refusals reach the model as a denial with the reason.
+     * Gates must fail closed: when they cannot verify, they refuse.
+     */
+    recordChangeGate?: (input: RecordChangeInput) => Promise<GateVerdict>;
+}
 /**
  * The factory's store operations wrapped as eve tools. Expose a tool to an
  * agent by re-exporting it from a file under agent/tools/, e.g.
  * `export default factoryTools(stores).get_task;`. Every write goes through
  * the engine, so agents inherit transition legality and receipts.
  */
-declare function factoryTools(stores: FactoryStores): {
+declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptions): {
     get_task: eve_tools.ToolDefinition<{
         taskId: string;
     }, {
@@ -32,6 +440,7 @@ declare function factoryTools(stores: FactoryStores): {
         updatedAt: string;
         repositoryIds?: string[] | undefined;
         area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
         dependsOn?: string[] | undefined;
         devbox?: {
             devboxId: string;
@@ -73,6 +482,7 @@ declare function factoryTools(stores: FactoryStores): {
             updatedAt: string;
             repositoryIds?: string[] | undefined;
             area?: string | undefined;
+            approval?: "required" | "granted" | "denied" | undefined;
             dependsOn?: string[] | undefined;
             devbox?: {
                 devboxId: string;
@@ -191,6 +601,7 @@ declare function factoryTools(stores: FactoryStores): {
             updatedAt: string;
             repositoryIds?: string[] | undefined;
             area?: string | undefined;
+            approval?: "required" | "granted" | "denied" | undefined;
             dependsOn?: string[] | undefined;
             devbox?: {
                 devboxId: string;
@@ -261,6 +672,7 @@ declare function factoryTools(stores: FactoryStores): {
                 updatedAt: string;
                 repositoryIds?: string[] | undefined;
                 area?: string | undefined;
+                approval?: "required" | "granted" | "denied" | undefined;
                 dependsOn?: string[] | undefined;
                 devbox?: {
                     devboxId: string;
@@ -280,6 +692,31 @@ declare function factoryTools(stores: FactoryStores): {
             };
         }>;
     };
+    finish_task: eve_tools.ToolDefinition<{
+        taskId: string;
+        summary: string;
+    }, {
+        finished: false;
+        reason: string;
+        taskState?: undefined;
+    } | {
+        finished: true;
+        taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        reason?: undefined;
+    }> & {
+        execute(input: {
+            taskId: string;
+            summary: string;
+        }, ctx: eve_tools.ToolContext): Promise<{
+            finished: false;
+            reason: string;
+            taskState?: undefined;
+        } | {
+            finished: true;
+            taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+            reason?: undefined;
+        }>;
+    };
     report_blocked: eve_tools.ToolDefinition<{
         taskId: string;
         reason: string;
@@ -302,6 +739,7 @@ declare function factoryTools(stores: FactoryStores): {
         updatedAt: string;
         repositoryIds?: string[] | undefined;
         area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
         dependsOn?: string[] | undefined;
         devbox?: {
             devboxId: string;
@@ -341,6 +779,7 @@ declare function factoryTools(stores: FactoryStores): {
             updatedAt: string;
             repositoryIds?: string[] | undefined;
             area?: string | undefined;
+            approval?: "required" | "granted" | "denied" | undefined;
             dependsOn?: string[] | undefined;
             devbox?: {
                 devboxId: string;
@@ -387,6 +826,7 @@ declare function factoryTools(stores: FactoryStores): {
         updatedAt: string;
         repositoryIds?: string[] | undefined;
         area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
         dependsOn?: string[] | undefined;
         devbox?: {
             devboxId: string;
@@ -432,6 +872,7 @@ declare function factoryTools(stores: FactoryStores): {
             updatedAt: string;
             repositoryIds?: string[] | undefined;
             area?: string | undefined;
+            approval?: "required" | "granted" | "denied" | undefined;
             dependsOn?: string[] | undefined;
             devbox?: {
                 devboxId: string;
@@ -503,5 +944,19 @@ declare function factoryTools(stores: FactoryStores): {
     };
 };
 type FactoryTools = ReturnType<typeof factoryTools>;
+/**
+ * Observe-only eve hooks that keep the ledger honest about session outcomes.
+ * Mount by re-exporting from agent/hooks/, e.g.
+ * `export default factoryHooks(stores).factory;`.
+ *
+ * turn.completed: a turn that ends while its task is still running means the
+ * agent finished talking without recording an outcome; the task moves to
+ * needs_human instead of rotting. The task is found by the session's
+ * channel address, which dispatch set from the task's replyTo.
+ */
+declare function factoryHooks(stores: FactoryStores): {
+    factory: eve_hooks.HookDefinition<"turn.completed">;
+};
+type FactoryHooks = ReturnType<typeof factoryHooks>;
 
-export { type FactoryTools, factoryTools };
+export { type CommandSandbox, type DeepsecScanOptions, type FactoryHooks, type FactoryTools, type FactoryToolsOptions, type FetchPullRequestOptions, type FetchPullRequestResult, type GateVerdict, type InvokeAgentOptions, type RecordChangeInput, type RecordFindingOptions, type RecordFindingResult, deepsecScanTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, recordFinding, recordFindingTool, recordVerificationTool };