@njeybe/nativ 2.0.0

package/dist/providers/registry.d.ts

@@ -0,0 +1,38 @@
+import { type CompleteRequest, type Provider, type ProviderDeps, type ProviderId, type ProviderRole } from './types.js';
+/** Subscription login first (no key needed), then API keys. Claude is the default for every role. */
+export declare const DEFAULT_CHAIN: readonly ProviderId[];
+export interface ProviderConfig {
+    /** Per-role provider id, or an ordered list. Unknown ids are ignored. */
+    providers?: Partial<Record<ProviderRole, ProviderId | ProviderId[]>>;
+    /** Per-provider model override, e.g. { "claude-cli": "sonnet" }. */
+    models?: Partial<Record<ProviderId, string>>;
+}
+export interface RegistryOptions {
+    /** Explicit provider id(s); wins over config and the default chain. */
+    provider?: ProviderId | ProviderId[];
+    deps?: ProviderDeps;
+    /** Inline config, used instead of reading .nativ/config.json (tests, programmatic callers). */
+    config?: ProviderConfig;
+}
+export interface ChainResult {
+    provider: ProviderId;
+    model: string;
+    text: string;
+}
+export declare function createProviders(deps?: ProviderDeps): Record<ProviderId, Provider>;
+export declare function loadProviderConfig(root: string): ProviderConfig;
+export declare function setProviderCooldown(root: string, id: ProviderId, waitMs: number, now?: number): void;
+/** Milliseconds left on a provider's cooldown, or 0. Expired entries are pruned. */
+export declare function providerCooldownRemaining(root: string, id: ProviderId, now?: number): number;
+/**
+ * Providers to try for a role, in order: those with credentials that are not cooling down.
+ * An explicit or configured provider that is unavailable is skipped, not an error.
+ */
+export declare function resolveProviderChain(role: ProviderRole, root: string, options?: RegistryOptions): Provider[];
+export declare function resolveProvider(role: ProviderRole, root: string, options?: RegistryOptions): Provider | null;
+/**
+ * Runs the request against each provider in turn. A rate limit puts that provider on cooldown, and any
+ * ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
+ * last error when every provider failed, so the caller can drop to its deterministic path.
+ */
+export declare function completeWithChain(role: ProviderRole, root: string, request: CompleteRequest, options?: RegistryOptions): Promise<ChainResult>;

package/dist/providers/registry.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createClaudeApiProvider } from './claude-api.js';
+import { createClaudeCliProvider, DEFAULT_LIMIT_COOLDOWN_MS } from './claude-cli.js';
+import { createGeminiProvider } from './gemini.js';
+import { ProviderError, } from './types.js';
+/** Subscription login first (no key needed), then API keys. Claude is the default for every role. */
+export const DEFAULT_CHAIN = ['claude-cli', 'claude-api', 'gemini'];
+const CONFIG_FILE = path.join('.nativ', 'config.json');
+const STATE_FILE = path.join('.nativ', 'provider-state.json');
+export function createProviders(deps = {}) {
+    return {
+        'claude-cli': createClaudeCliProvider(deps),
+        'claude-api': createClaudeApiProvider(deps),
+        gemini: createGeminiProvider(deps),
+    };
+}
+function isProviderId(value) {
+    return typeof value === 'string' && DEFAULT_CHAIN.includes(value);
+}
+function toIds(value) {
+    const list = Array.isArray(value) ? value : value === undefined ? [] : [value];
+    return list.filter(isProviderId);
+}
+export function loadProviderConfig(root) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, CONFIG_FILE), 'utf8'));
+        return raw && typeof raw === 'object' ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readCooldowns(root) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, STATE_FILE), 'utf8'));
+        return raw.cooldownUntil && typeof raw.cooldownUntil === 'object' ? raw.cooldownUntil : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCooldowns(root, cooldownUntil) {
+    try {
+        const file = path.join(root, STATE_FILE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ cooldownUntil }, null, 2), 'utf8');
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Cooldown is an optimisation; failing to persist it must never fail the call.
+    }
+}
+export function setProviderCooldown(root, id, waitMs, now = Date.now()) {
+    const state = readCooldowns(root);
+    state[id] = now + waitMs;
+    writeCooldowns(root, state);
+}
+/** Milliseconds left on a provider's cooldown, or 0. Expired entries are pruned. */
+export function providerCooldownRemaining(root, id, now = Date.now()) {
+    const state = readCooldowns(root);
+    const until = state[id];
+    if (typeof until !== 'number')
+        return 0;
+    if (until <= now) {
+        delete state[id];
+        writeCooldowns(root, state);
+        return 0;
+    }
+    return until - now;
+}
+// ─── Resolution ────────────────────────────────────────────────────────────────────────────────────
+function orderedIds(role, root, options) {
+    const explicit = toIds(options.provider);
+    if (explicit.length)
+        return explicit;
+    const configured = toIds((options.config ?? loadProviderConfig(root)).providers?.[role]);
+    return configured.length ? configured : [...DEFAULT_CHAIN];
+}
+/**
+ * Providers to try for a role, in order: those with credentials that are not cooling down.
+ * An explicit or configured provider that is unavailable is skipped, not an error.
+ */
+export function resolveProviderChain(role, root, options = {}) {
+    const providers = createProviders(options.deps);
+    const now = options.deps?.now?.() ?? Date.now();
+    return orderedIds(role, root, options)
+        .map((id) => providers[id])
+        .filter((provider) => provider.hasCredentials(root) && providerCooldownRemaining(root, provider.id, now) === 0);
+}
+export function resolveProvider(role, root, options = {}) {
+    return resolveProviderChain(role, root, options)[0] ?? null;
+}
+/**
+ * Runs the request against each provider in turn. A rate limit puts that provider on cooldown, and any
+ * ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
+ * last error when every provider failed, so the caller can drop to its deterministic path.
+ */
+export async function completeWithChain(role, root, request, options = {}) {
+    const chain = resolveProviderChain(role, root, options);
+    if (!chain.length)
+        throw new ProviderError('NO_CREDENTIALS', 'No provider is available (no login, key or all cooling down).');
+    const models = (options.config ?? loadProviderConfig(root)).models ?? {};
+    const now = options.deps?.now ?? Date.now;
+    let lastError = null;
+    for (const provider of chain) {
+        const model = request.model ?? models[provider.id] ?? provider.defaultModel;
+        try {
+            const text = await provider.complete({ ...request, model }, root);
+            return { provider: provider.id, model, text };
+        }
+        catch (err) {
+            const failure = err instanceof ProviderError ? err : new ProviderError('BAD_RESPONSE', err instanceof Error ? err.message : String(err));
+            if (failure.code === 'RATE_LIMITED')
+                setProviderCooldown(root, provider.id, failure.retryAfterMs ?? DEFAULT_LIMIT_COOLDOWN_MS, now());
+            lastError = failure;
+        }
+    }
+    throw lastError ?? new ProviderError('BAD_RESPONSE', 'Every provider failed.');
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * nativ · Provider adapter contract.
+ *
+ * Every LLM call made by nativ itself goes through a `Provider`. Adding a vendor means adding one
+ * file in this directory and one entry in registry.ts; nothing outside src/providers/ changes.
+ */
+export type ProviderId = 'claude-cli' | 'claude-api' | 'gemini';
+/** Roles a provider can be assigned to in `.nativ/config.json`. */
+export type ProviderRole = 'architect' | 'pm' | 'worker' | 'verifier' | 'triage';
+export type ProviderErrorCode = 'NO_CREDENTIALS' | 'TIMEOUT' | 'RATE_LIMITED' | 'BAD_RESPONSE';
+/** Typed failure so callers can fall through the provider chain without string matching. */
+export declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    /** For RATE_LIMITED: how long the provider asked us to wait, when it said. */
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: ProviderErrorCode, message: string, 
+    /** For RATE_LIMITED: how long the provider asked us to wait, when it said. */
+    retryAfterMs?: number | undefined);
+}
+export interface CompleteRequest {
+    system?: string;
+    prompt: string;
+    /** Ask for a single JSON document; providers strip code fences from the reply. */
+    json?: boolean;
+    /** Overrides the provider's default model. */
+    model?: string;
+    /** Hard ceiling for the call. Defaults are provider-specific. */
+    timeoutMs?: number;
+}
+export interface Provider {
+    readonly id: ProviderId;
+    readonly defaultModel: string;
+    /** True when a call could plausibly succeed: a login, a binary on PATH, or an API key. Never reads the secret out. */
+    hasCredentials(root: string): boolean;
+    complete(request: CompleteRequest, root: string): Promise<string>;
+}
+export interface SpawnRequest {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    input: string;
+    timeoutMs: number;
+}
+export interface SpawnResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** True when the executable could not be started at all (ENOENT). */
+    notFound?: boolean;
+}
+/** Everything a provider touches outside the process, injectable so tests never hit a network or a real binary. */
+export interface ProviderDeps {
+    spawn?: (command: string, args: string[], request: SpawnRequest) => Promise<SpawnResult>;
+    hasBinary?: (name: string) => boolean;
+    fetch?: typeof fetch;
+    /** Minimal shape of the Anthropic SDK client used by claude-api. */
+    anthropicClient?: () => AnthropicLike;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}
+export interface AnthropicLike {
+    messages: {
+        create(body: Record<string, unknown>, options?: {
+            timeout?: number;
+        }): Promise<{
+            content: Array<{
+                type: string;
+                text?: string;
+            }>;
+        }>;
+    };
+}
+/** Strips a surrounding ```json fence, which models add even when told not to. */
+export declare function stripJsonFence(text: string): string;

package/dist/providers/types.js

@@ -0,0 +1,25 @@
+/**
+ * nativ · Provider adapter contract.
+ *
+ * Every LLM call made by nativ itself goes through a `Provider`. Adding a vendor means adding one
+ * file in this directory and one entry in registry.ts; nothing outside src/providers/ changes.
+ */
+/** Typed failure so callers can fall through the provider chain without string matching. */
+export class ProviderError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, message, 
+    /** For RATE_LIMITED: how long the provider asked us to wait, when it said. */
+    retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'ProviderError';
+    }
+}
+/** Strips a surrounding ```json fence, which models add even when told not to. */
+export function stripJsonFence(text) {
+    const trimmed = text.trim();
+    const fenced = /^```(?:json)?\s*\n?([\s\S]*?)\n?```$/i.exec(trimmed);
+    return (fenced ? fenced[1] : trimmed).trim();
+}

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

@@ -0,0 +1,363 @@
+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;
+    } | 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;
+/**
+ * Builds the autonomous prompt and arguments required by Claude Code CLI
+ * to execute non-interactively in a headless child process.
+ *
+ * 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;
+/**
+ * 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;
+/**
+ * Supervises autonomous agent runs: detached spawn inside an isolated git
+ * worktree, a timeout killswitch, a bounded streaming log buffer, and
+ * local-first persistence under `.nativ/runs/` (structure only, never secrets).
+ *
+ * Emits `runner_status` and `runner_log` events for SSE fan-out.
+ */
+export declare class AgentSupervisor extends EventEmitter {
+    private readonly rootDir;
+    private readonly runsDir;
+    private readonly defaultRunnerCommand;
+    private readonly defaultTimeoutSeconds;
+    private readonly maxLogBufferBytes;
+    private readonly killGraceMs;
+    private readonly idleTimeoutMs;
+    private readonly maxHistory;
+    private readonly defaultEngine;
+    private readonly defaultNativeModel;
+    private readonly nativeMaxTurns;
+    private readonly nativeToolTimeoutMs;
+    private readonly nativeAllowedCommands;
+    private readonly anthropicClientFactory;
+    private readonly toolShell;
+    private readonly active;
+    private history;
+    private closed;
+    constructor(options?: AgentSupervisorOptions);
+    get projectRoot(): string;
+    dispatch(options: DispatchOptions): Promise<RunnerRecord>;
+    abort(taskId: string, reason?: string): Promise<AbortResult>;
+    getRun(taskId: string): RunnerRecord | null;
+    isRunning(taskId: string): boolean;
+    listRuns(query?: ListRunsQuery): RunnerRecord[];
+    /**
+     * Returns the tail of a run's log. Live runs are served from the in-memory
+     * ring buffer; finished runs fall back to `.nativ/runs/<taskId>.log`.
+     */
+    getLogs(taskId: string, tail?: number): LogSlice;
+    /** Kills every in-flight runner and releases timers. Safe to call twice. */
+    shutdown(reason?: string): void;
+    private normalizeTimeout;
+    private requireTask;
+    private assertDependenciesMet;
+    /** Creates `.worktrees/task-<id>` on `agent/task-<id>`, reusing an existing one. */
+    private provisionWorktree;
+    private spawnRunner;
+    /** Terminates runs that go silent: a hung agent is caught long before the hard cap. */
+    private startIdleWatchdog;
+    private handleTimeout;
+    private handleExit;
+    /** Shared tail of a clean runner exit: optional verification, optional merge, then completion. */
+    private completeSuccessfulRun;
+    private consumeStreamJson;
+    private handleStreamLine;
+    /** Claude Code reports the run's total cost and tokens once, in its final result event. */
+    private recordStreamUsage;
+    private createAnthropicClient;
+    /** Cancels the in-flight API stream and reaps the running bash tool command, if any. */
+    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;
+    private resetLogFile;
+    private appendLog;
+    private clearTimers;
+    private finalize;
+    private emitStatus;
+    private persist;
+    /**
+     * Rebuilds the recent-run list from `.nativ/runs/*.json` so a restarted
+     * supervisor can still answer `/tasks/runs` and `/tasks/logs`. Records left
+     * in an active phase by a crashed supervisor are reconciled to `failed`.
+     */
+    private restoreHistory;
+}
+export default AgentSupervisor;