@njeybe/nativ 2.4.1 → 2.5.1

package/dist/runner/agent-supervisor.d.ts

@@ -1,296 +1,12 @@
 import { EventEmitter } from 'node:events';
-import Anthropic from '@anthropic-ai/sdk';
-import { type ActualTokenUsage } from '../core/telemetry.js';
-import type { MasterPlanTask } from '../scanner/types.js';
-/**
- * Lifecycle phases broadcast on the `runner_status` channel. These mirror the
- * phases declared in .ai/api_contracts.json (sseChannels → runner_status).
- */
-export type RunnerStatus = 'spawning_worktree' | 'running' | 'verifying' | 'merging' | 'completed' | 'failed' | 'aborted';
-export declare const ACTIVE_RUNNER_STATUSES: readonly RunnerStatus[];
-export declare function isActiveStatus(status: RunnerStatus): boolean;
-/**
- * `native` drives the Messages API in-process with local bash/editor tools;
- * `cli` spawns a runner command (Claude Code by default).
- */
-export type RunnerEngine = 'native' | 'cli';
-export type ThinkingEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
-export interface RunnerThinking {
-    /** The dispatch's `thinkingBudget`, echoed back; null when unset. */
-    budget: number | null;
-    /** `output_config.effort` sent to adaptive-thinking models; null otherwise. */
-    effort: ThinkingEffort | null;
-    /** Literal `budget_tokens` (legacy models) or `MAX_THINKING_TOKENS` (cli); null otherwise. */
-    budgetTokens: number | null;
-}
-/** Payload of the `runner_token_usage` channel, emitted after every native turn. */
-export interface RunnerTokenUsageEvent {
-    runId: string;
-    taskId: string;
-    /** Model that served this turn (differs from the requested one after a refusal fallback). */
-    model: string;
-    turn: number;
-    delta: ActualTokenUsage;
-    total: ActualTokenUsage & {
-        cacheHitRate: number;
-    };
-    at: string;
-}
-/** Persisted, serializable state of a single agent execution. */
-export interface RunnerRecord {
-    runId: string;
-    taskId: string;
-    status: RunnerStatus;
-    engine: RunnerEngine;
-    /** Requested model; null for cli runs that keep the runner's own default. */
-    model: string | null;
-    thinking: RunnerThinking | null;
-    /** API-reported usage accumulated across turns; null for cli runs. */
-    usage: ActualTokenUsage | null;
-    /** PID of the spawned process-group leader; null before spawn and after exit. */
-    pid: number | null;
-    /** Branch backing the isolated worktree, or null when running in place. */
-    branch: string | null;
-    /** Absolute worktree path, or the project root when `useWorktree` is false. */
-    worktreeDir: string;
-    command: string;
-    startedAt: string;
-    endedAt: string | null;
-    durationMs: number | null;
-    exitCode: number | null;
-    signal: string | null;
-    timeoutSeconds: number;
-    timedOut: boolean;
-    logBytes: number;
-    logFile: string;
-    error: string | null;
-    abortReason: string | null;
-    verification: {
-        command: string;
-        success: boolean;
-        exitCode: number;
-        durationMs: number;
-        skipped: boolean;
-        /** Why it failed: a named phase, an unreadable config, or the code-shape block. */
-        error?: string;
-        phases?: Array<{
-            name: string;
-            success: boolean;
-            durationMs: number;
-        }>;
-    } | null;
-}
-export interface DispatchOptions {
-    taskId: string;
-    /** Defaults to the supervisor's `defaultEngine` (`cli` unless configured). */
-    runnerEngine?: RunnerEngine;
-    /** Shell command that launches the agent (cli engine only). Defaults to `defaultRunnerCommand`. */
-    runnerCommand?: string;
-    /**
-     * Reasoning budget in tokens. Adaptive-thinking models receive it as an
-     * `effort` level (they reject `budget_tokens`); legacy models receive it
-     * literally; the Claude Code CLI receives it as `MAX_THINKING_TOKENS`.
-     */
-    thinkingBudget?: number;
-    /** Model ID. Native runs default to `defaultNativeModel`; cli runs pass it as `--model`. */
-    model?: string;
-    /** Killswitch budget in seconds. Defaults to the supervisor's `defaultTimeoutSeconds`. */
-    timeoutSeconds?: number;
-    /** Run inside `.worktrees/task-<id>` on branch `agent/task-<id>`. Default true. */
-    useWorktree?: boolean;
-    /** Run the task's `verificationCommand` after a clean exit. Default false. */
-    verify?: boolean;
-    /** Merge the agent branch back after a passing verification. Default false. */
-    autoMerge?: boolean;
-    /** Extra environment variables handed to the child (never logged or persisted). */
-    env?: Record<string, string>;
-    /** Extra permission rules for the default cli runner, e.g. `Bash(pnpm test *)`. Added to the per-task allowlist. */
-    allowedTools?: string[];
-}
-export interface AbortResult {
-    taskId: string;
-    runId: string;
-    status: 'aborted';
-    message: string;
-}
-export interface LogSlice {
-    taskId: string;
-    runId: string | null;
-    status: RunnerStatus | null;
-    totalBytes: number;
-    log: string;
-    truncated: boolean;
-}
-export interface ListRunsQuery {
-    taskId?: string;
-    activeOnly?: boolean;
-}
-export interface AgentSupervisorOptions {
-    /** Directory used to resolve the project root holding `.ai/`. Defaults to `process.cwd()`. */
-    cwd?: string;
-    defaultRunnerCommand?: string;
-    defaultTimeoutSeconds?: number;
-    /** Hard cap on the in-memory log ring buffer per run. */
-    maxLogBufferBytes?: number;
-    /** Grace period between SIGTERM and the forced kill during abort/timeout. */
-    killGraceMs?: number;
-    /**
-     * Inactivity watchdog: terminate a run that emits no output for this many seconds. Defaults to
-     * `NATIV_RUNNER_IDLE_TIMEOUT`, then `DEFAULT_IDLE_TIMEOUT_SECONDS`; 0 disables it.
-     */
-    idleTimeoutSeconds?: number;
-    /** How many finished runs to keep in memory. */
-    maxHistory?: number;
-    /** Engine used when a dispatch omits `runnerEngine`. Defaults to `NATIV_RUNNER_ENGINE`, then `cli`. */
-    defaultEngine?: RunnerEngine;
-    /** Model used by native runs that omit `model`. Defaults to `NATIV_NATIVE_MODEL`, then `DEFAULT_NATIVE_MODEL`. */
-    defaultNativeModel?: string;
-    /** Hard cap on API round-trips per native run. */
-    nativeMaxTurns?: number;
-    /** Per-command budget for the native bash tool. */
-    nativeToolTimeoutMs?: number;
-    /** Executables the native bash tool may invoke. */
-    nativeAllowedCommands?: readonly string[];
-    /** Builds the Claude API client for native runs; injectable for tests. */
-    anthropicClientFactory?: () => Anthropic;
-    /**
-     * Shell for the native bash tool: a path to bash, or `true` for the platform default shell.
-     * Defaults to NATIV_BASH_PATH, then Git Bash on Windows, then /bin/bash.
-     */
-    nativeShell?: string | boolean;
-}
-/** Structured failure carrying the `{ code, message }` shape used by the pipeline API. */
-export declare class SupervisorError extends Error {
-    readonly code: string;
-    readonly status: number;
-    constructor(code: string, message: string, status?: number);
-}
-export declare const DEFAULT_RUNNER_COMMAND = "claude";
-/** Hard cap per run. Real agent tasks routinely take tens of minutes; hung runs are caught by the idle watchdog. */
-export declare const DEFAULT_TIMEOUT_SECONDS = 3600;
-/** A run that produces no output (log lines, tool activity, API turns) for this long is treated as hung. */
-export declare const DEFAULT_IDLE_TIMEOUT_SECONDS = 900;
-export declare const DEFAULT_MAX_LOG_BUFFER_BYTES: number;
-export declare const DEFAULT_KILL_GRACE_MS = 5000;
-export declare const DEFAULT_MAX_HISTORY = 50;
-export declare const DEFAULT_RUNNER_ENGINE: RunnerEngine;
-export declare const DEFAULT_NATIVE_MODEL = "claude-opus-5-5";
-export declare const DEFAULT_NATIVE_EFFORT: ThinkingEffort;
-export declare const DEFAULT_NATIVE_MAX_TURNS = 150;
-export declare const DEFAULT_NATIVE_TOOL_TIMEOUT_MS: number;
-export declare const NATIVE_MAX_OUTPUT_TOKENS = 64000;
-/** Characters of tool output handed back to the model per call. */
-export declare const NATIVE_TOOL_OUTPUT_LIMIT = 30000;
-export declare const DEFAULT_NATIVE_ALLOWED_COMMANDS: readonly string[];
-/** Extracts the executable binary or command name, handling quoted Windows paths. */
-export declare function extractBinary(cmd: string): string;
-/** Pre-flight check verifying whether a command binary exists in PATH or on the filesystem. */
-export declare function isExecutableInPath(cmd: string): boolean;
-/** The pieces of a compound command as Claude Code matches them: each must satisfy an allow rule on its own. */
-export declare function splitCompoundCommand(command: string): string[];
-/** Operator-supplied extra rules from NATIV_RUNNER_ALLOW, comma separated, e.g. `Bash(pnpm test *),Bash(cargo test *)`. */
-export declare function parseRunnerAllowList(raw: string | undefined): string[];
-export interface RunnerPermissions {
-    permissions: {
-        allow: string[];
-        deny: string[];
-        ask: string[];
-    };
-    /** Omitted when the project's own settings already run the enforcement hook, so it never runs (and logs) twice. */
-    hooks?: {
-        PreToolUse: Array<{
-            matcher: string;
-            hooks: Array<{
-                type: 'command';
-                command: string;
-                timeout: number;
-            }>;
-        }>;
-    };
-}
-/**
- * Settings handed to a dispatched agent with `--settings`. The deny and ask rules and the enforcement hook come
- * from the same source as `nativ setup`, so a dispatched agent is guarded even in a project where setup never ran.
- */
-export declare function buildRunnerPermissions(task: Pick<MasterPlanTask, 'verificationCommand'>, rootDir: string, extraAllowed?: readonly string[]): RunnerPermissions;
-/** Where a task's runner settings live: a subdirectory, because run history parses every top-level .json in runs/. */
-export declare function runnerSettingsPath(runsDir: string, taskId: string): string;
-export declare function writeRunnerSettings(runsDir: string, taskId: string, settings: RunnerPermissions): string;
-/** The instructions text handed to the agent on its standard input. */
-export declare function buildRunnerPrompt(task: MasterPlanTask): string;
-/**
- * Arguments for Claude Code CLI to run headless. The prompt goes on stdin, never in this string:
- * quotes or symbols in task text would break the shell.
- *
- * It runs in `acceptEdits` mode with the rules in `settingsFile` (see buildRunnerPermissions); it does not bypass
- * permissions. Without a settings file only the file-edit tools and read-only commands are pre-approved.
- */
-export declare function buildDefaultClaudeCommand(_task: MasterPlanTask, model?: string | null, settingsFile?: string): string;
-/** True when a runner command asks Claude Code for its line-delimited JSON event stream. */
-export declare function usesClaudeStreamJson(command: string): boolean;
-/** Final `result` event of a Claude Code stream: grounded usage for cli runs. */
-export interface ClaudeStreamResult {
-    isError: boolean;
-    turns: number;
-    costUsd: number | null;
-    inputTokens: number;
-    outputTokens: number;
-    cacheCreationTokens: number;
-    cacheReadTokens: number;
-}
-export interface ClaudeStreamLine {
-    /** Human-readable log text (newline-terminated), or null when the event is not worth showing. */
-    text: string | null;
-    model?: string;
-    result?: ClaudeStreamResult;
-}
-/**
- * Turns one line of `claude -p --output-format stream-json` into a log line. Anything that is not
- * a recognised event (warnings, custom runners, future event types) passes through or is dropped,
- * never thrown on.
- */
-export declare function formatClaudeStreamLine(line: string): ClaudeStreamLine;
-/** Models that predate adaptive thinking and still take `thinking.budget_tokens`. */
-export declare function usesLegacyThinkingBudget(model: string): boolean;
-/**
- * Buckets a token budget into an effort level. Current models reject `budget_tokens`, so the
- * contract's numeric `thinkingBudget` maps onto effort. The buckets follow the Studio's budget
- * chips: 0 ("None, fast") is the least thinking a model allows, 2,048 ("Standard") is the
- * standard effort, 4,096 ("Deep") is high, and larger budgets reach xhigh and max.
- */
-export declare function thinkingBudgetToEffort(budget: number): ThinkingEffort;
-export declare function resolveNativeThinking(model: string, budget: number | null): RunnerThinking;
-/**
- * Effort used when a dispatch sets no `thinkingBudget`. Claude Opus 5.5 at
- * `medium` outperforms Claude Opus 5 at `high` on coding work, so it starts lower.
- */
-export declare function defaultNativeEffort(model: string): ThinkingEffort;
-/** Models that opt into server-side refusal fallbacks by default. */
-export declare function supportsServerFallback(model: string): boolean;
-/** Keeps stored text from closing the block it sits in and passing as instructions. */
-export declare function untag(text: string, tag: string): string;
-export declare function buildNativeTaskPrompt(task: MasterPlanTask, roleGuide: string | null, useWorktree: boolean, rootDir?: string): string;
-/**
- * Environment for cli runners. The agent inside can run the commands its allowlist permits (and any custom
- * runner command runs unrestricted), so it can print anything it inherits: credential-looking variables are
- * withheld, except the ones Claude
- * Code itself authenticates with (and AWS credentials when it is configured for Bedrock).
- * NATIV_RUNNER_PASS_ENV="NAME1,NAME2" passes extra variables through deliberately; variables an
- * operator hands to dispatch() explicitly are also passed as-is.
- */
-export declare function buildRunnerEnv(base: NodeJS.ProcessEnv, explicit?: Record<string, string>): NodeJS.ProcessEnv;
-/**
- * Best-effort policy for model-authored shell commands. The worktree is the
- * real boundary (as with the cli engine); this blocks the obvious escapes and
- * keeps every executable on an allowlist. Returns the rejection reason, or null.
- */
-export declare function checkNativeBashCommand(command: string, allowed: ReadonlySet<string>): string | null;
-/**
- * Confines a model-supplied editor path to the workspace. Reads may follow the
- * `.ai/` and `node_modules/` junctions the supervisor mounts into worktrees;
- * writes may not touch them at all.
- */
-export declare function resolveEditorPath(workspace: string, projectRoot: string, raw: unknown, mode: 'read' | 'write'): string;
+import { type AbortResult, type AgentSupervisorOptions, type DispatchOptions, type ListRunsQuery, type LogSlice, type RunnerRecord } from './types.js';
+export * from './types.js';
+export * from './process-utils.js';
+export * from './cli-config.js';
+export * from './native-tools.js';
+export * from './native-engine.js';
+export * from './native-driver.js';
+export * from './run-lifecycle.js';
 /**
  * Supervises autonomous agent runs: detached spawn inside an isolated git
  * worktree, a timeout killswitch, a bounded streaming log buffer, and
@@ -352,16 +68,6 @@ export declare class AgentSupervisor extends EventEmitter {
     private interruptNative;
     private startNativeRun;
     private driveNativeRun;
-    /**
-     * Manual agentic loop over the Messages API: stream a turn, capture usage,
-     * execute the requested local tools, repeat until the model ends its turn.
-     */
-    private runNativeLoop;
-    private recordTurnUsage;
-    private executeNativeTool;
-    /** Runs one model-authored command in a fresh shell at the workspace root. */
-    private runBashTool;
-    private readRoleGuide;
     private runVerification;
     /** Quiet counterpart to `nativ worktree merge`: same safe merge, no stdout noise inside a server. */
     private mergeWorktree;