agent-afk 5.1.0 → 5.2.0

package/dist/agent/routing-directive.d.ts

@@ -0,0 +1,5 @@
+export declare const ROUTING_DIRECTIVE = "[skill-routing: active]\n\nRoute recurring work through registered skills instead of rolling ad-hoc solutions:\n\n- Before non-trivial implementation (multi-file edits, new features, config/build changes \u2014 anything that writes) \u2192 `/ground-state` first. Do NOT substitute inline `git status`/`get_runtime_state` \u2014 the skill triangulates git + infra + prior-session memory in parallel, which the inline checks miss. If `/ground-state` dispatch fails (depth limit, unavailable), fall back to inline checks AND note the coverage gap.\n- Bugs, failing tests, or regressions \u2192 `/diagnose`\n- High-stakes sub-agent output that will drive edits or commits \u2192 `/shadow-verify` before acting\n- Refactor needing parallel waves \u2192 `/parallelize`\n- Parallel or dependent multi-task work \u2192 `compose` tool (DAG of subagent nodes)\n- Greenfield feature where a written spec would genuinely help (novel scope, multi-day work, or external stakeholders involved) \u2192 `/mint`\n\nDo NOT reach for `/mint` for: bug fixes (use `/diagnose`), refactors with known shape, single-feature edits, work already spec'd in chat, or anything where the spec/approve pause would feel like ceremony. Implement directly in those cases.\n\nCommon composed sequences \u2014 reach for these when the task shape matches:\n\n- Bug with failing test and non-trivial fix \u2192 `/diagnose` \u2192 `/shadow-verify` on the proposed fix\n- Refactor needing parallel waves \u2192 plan \u2192 `/parallelize` \u2192 build waves\n- Diagnose + fix in parallel \u2192 `compose` with two independent nodes\n- Research \u2192 implement \u2192 verify pipeline \u2192 `compose` with edges: research\u2192implement\u2192verify\n- Multiple independent investigations \u2192 `compose` with N nodes, no edges\n\nReach for context-isolated investigators when the task is exploratory:\n\n- Map an unfamiliar module before editing \u2192 `/gather` or `/research`\n- Re-derive a load-bearing claim independently \u2192 `/shadow-verify`\n- Audit a diff before merge \u2192 `/review`\n- Generate alternatives before committing to a plan \u2192 `/devils-advocate`\n\nOr dispatch a raw `agent` call when no skill matches but the work is parallelizable, verification-heavy, or would otherwise consume substantial inline context.\n\nSkip orchestration for: single-line edits, trivial Q&A, and direct tool calls the user explicitly requested. The goal is leverage, not ceremony. If a skill would add overhead without adding value, don't invoke it.\n\nDefault to acting autonomously. `ask_question` is a last resort, not a first move \u2014 every question blocks on the operator, who is often away from keyboard.\n\nBefore you ask, you MUST exhaust the tools you have: read the files, check git, search the codebase and docs, inspect runtime state. If any tool can get you the answer, use the tool \u2014 never ask the operator for something you can discover yourself. When a wrong guess would be cheap or reversible, make a reasonable assumption, proceed, and state the assumption instead of asking.\n\n**Answerability \u2014 a question only helps if a human will actually answer it:**\n\n`surface` (from `get_runtime_state`, view `\"self\"`) is a partial signal, not a guarantee:\n- `daemon`, or any session started by a scheduler, cron job, or another agent, has no human watching \u2014 never block on `ask_question` here.\n- `cli` is ambiguous: the interactive REPL and the Telegram bot can reach a human, but one-shot `chat` runs and sub-agent forks report the same `cli` and have no elicitation handler \u2014 there `ask_question` returns `{ action: 'decline' }` instantly.\n- Even when a handler exists, the operator is usually away, so a blocking question can stall until the turn aborts.\n\nSo treat `ask_question` as best-effort: a `decline` or `cancel` result means \"no answer is coming,\" not a failure to abort the task on. When you cannot be sure a human will answer, instead of asking:\n1. **Proceed on a stated assumption** \u2014 pick the most reasonable interpretation, act on it, and record the assumption in your Done/Blocked terminal state for async review.\n2. **Emit a Blocked artifact** \u2014 if no safe assumption exists and proceeding would be irreversible, end the turn with a **Blocked** terminal state naming exactly what the operator must supply before the next run.\n\nReserve `ask_question` for the narrow set of things no tool can resolve: a genuinely ambiguous requirement whose readings lead to materially different work, a decision with significant or irreversible consequences, or context that lives only in the operator's head (a preference, a secret, an external constraint):\n\n- Question types: `text` (open-ended), `confirm` (yes/no), `choice` (single pick from list), `multi_choice` (multi-pick), `number` (numeric with optional bounds). When `allow_custom: true`, the result may include `custom_value` instead of `value` \u2014 check `content.custom_value !== undefined` to detect a free-form answer.\n- Ask one focused question at a time. Do NOT ask multiple questions in a single call, and do NOT stack several ask_question calls across a turn \u2014 fold the genuine unknowns into the single most decision-relevant question.\n- Do NOT use when the user has already provided sufficient context \u2014 infer and proceed instead.\n- The result `action` will be `accept` (answered), `cancel` (user interrupted), `decline` (no handler), or `skip` (optional question skipped).\n- `allow_custom` (choice/multi_choice only): opt-in to a free-form entry affordance. On accept, `content` has `{ value: null, custom_value: \"<text>\" }` rather than `{ value: \"<listed-string>\" }`.\n- After a `cancel` or `decline`, stop and tell the user what information you need \u2014 do not loop and re-ask.";
+export declare const END_OF_TURN_DIRECTIVE = "[end-of-turn protocol]\n\nEvery turn must end in one externally identifiable terminal state. AFK users need inspectable artifacts, not ceremony. Write each bullet as a single sentence.\n\n**Done**\n- What was done\n- Evidence that exists, named by a durable location (file path, commit SHA, trace path, test output, or memory key) \u2014 never transcript-only\n- What changed in the world\n- Anything still pending or deferred, with why\n- If files were written or edited but no `git commit` ran, say so explicitly \u2014 name the uncommitted paths and why (e.g. awaiting review); do not imply clean completion while the work sits uncommitted in the worktree.\n\n**Blocked**\n- What blocks\n- What must change to unblock\n- What has already been done\n\n**Asking**\n- One precise question\n- The assumption it resolves\n- What you will do once answered\n\n**Interrupted**\n- What you were doing\n- Where state was saved\n- What resumption requires\n\nNever end a turn mid-loop without one of these. The terminal-state heading must be the last block of the response, with no trailing prose after it.";
+export type PromptSurface = 'repl' | 'telegram' | 'one-shot' | 'subagent';
+export declare function pendingBriefContext(briefsDir?: string): string | undefined;
+export declare function assembleSystemPrompt(base: string | undefined, autoRouting: boolean, surface?: PromptSurface, briefContext?: string): string | undefined;

package/dist/agent/routing-telemetry.d.ts

@@ -0,0 +1,36 @@
+import type { TraceOrigin, TraceActor } from './session/session-identity.js';
+export interface RoutingDecisionEntry {
+    event: string;
+    origin?: TraceOrigin | undefined;
+    actor?: TraceActor | undefined;
+    subagent_id?: string | undefined;
+    id_prefix?: string | undefined;
+    parent_session_id?: string | undefined;
+    parent_subagent_id?: string | undefined;
+    status?: string | undefined;
+    duration_ms?: number | undefined;
+    content_chars?: number | undefined;
+    error_message?: string | undefined;
+    schema_error?: string | undefined;
+    partial_output_chars?: number | undefined;
+    depth?: number | undefined;
+    reason?: string | undefined;
+    requested_name?: string | undefined;
+    model?: string | undefined;
+    mode?: string | undefined;
+    max_turns?: number | undefined;
+    node_count?: number | undefined;
+    edge_count?: number | undefined;
+    succeeded?: number | undefined;
+    failed?: number | undefined;
+    skipped?: number | undefined;
+    tool_call_count?: number | undefined;
+    thinking_present?: boolean | undefined;
+    tool_names?: string | undefined;
+    is_gate?: boolean | undefined;
+    tool?: string | undefined;
+    total_bytes?: number | undefined;
+    stream?: string | undefined;
+}
+export declare function buildRoutingDecisionRow(entry: RoutingDecisionEntry): Record<string, unknown>;
+export declare function appendRoutingDecision(entry: RoutingDecisionEntry): Promise<void>;

package/dist/agent/session/agent-session.d.ts

@@ -0,0 +1,95 @@
+import type { ContentBlockParam } from '@anthropic-ai/sdk/resources';
+import type { HookRegistry } from '../hooks.js';
+import type { ProviderCompactResult, ProviderQuery } from '../provider.js';
+import { type ZodType } from 'zod';
+import type { AccountInfo, AgentConfig, AgentInfo, AgentModelInput, IAgentSession, InputStreamRef, McpServerStatus, Message, ModelInfo, OutputEvent, PermissionMode, ResponseMetadata, RewindFilesResult, SDKControlGetContextUsageResponse, SendMessageOptions, SessionIdentity, SessionMetadata, SessionState, SlashCommand, StructuredMessageOptions } from '../types.js';
+import type { ElicitationRequest } from '../types/sdk-types.js';
+export declare class AgentSession implements IAgentSession {
+    private config;
+    private _pendingPlanExitSeed;
+    private currentState;
+    private providerQuery;
+    private providerIterator;
+    private conversationHistory;
+    private turnCount;
+    private lastResponseMetadata;
+    private initPromise;
+    private inputStream;
+    private readonly abortController;
+    private readonly _hookRegistry;
+    private sessionEndDispatched;
+    private stateManager;
+    private sessionRunningCostUsd;
+    private sessionRunningTokens;
+    private lastStopReason;
+    private maxTurnsHit;
+    private hookBlocked;
+    private sawProviderError;
+    private readonly sessionStartedAt;
+    private subagentCompletedCount;
+    private subagentRunningTokens;
+    private subagentRunningCostUsd;
+    private ledger;
+    private ledgerInitAttempted;
+    constructor(config: AgentConfig);
+    private initSdkLifecycle;
+    private pullInitialization;
+    private buildTransformDeps;
+    get state(): SessionState;
+    get sessionId(): string | undefined;
+    get cwd(): string | undefined;
+    get abortSignal(): AbortSignal;
+    get hookRegistry(): HookRegistry | undefined;
+    abort(reason: string): void;
+    sendMessage(content: string, options?: SendMessageOptions): Promise<Message>;
+    sendMessageStructured<T>(content: string, schema: ZodType<T>, options?: StructuredMessageOptions): Promise<T>;
+    sendMessageStream(content: string | ContentBlockParam[]): AsyncIterableIterator<OutputEvent>;
+    private sendMessageStreamInternal;
+    private ensureLedger;
+    private sealLedger;
+    recordLedgerElicitation(reqId: string, request: ElicitationRequest): void;
+    private summarizeContentBlocks;
+    interrupt(): Promise<void>;
+    reset(): Promise<void>;
+    private onAbort;
+    setModel(model?: AgentModelInput): Promise<void>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    takePendingPlanExitSeed(): Promise<string | undefined>;
+    setCwd(cwd: string): void;
+    reauth(): Promise<{
+        accountId: string;
+        swapped: boolean;
+    } | null>;
+    waitForInitialization(): Promise<SessionMetadata>;
+    getSessionIdentity(): SessionIdentity;
+    getSessionMetadata(): SessionMetadata;
+    getQuery(): ProviderQuery;
+    supportedCommands(): Promise<SlashCommand[]>;
+    supportedModels(): Promise<ModelInfo[]>;
+    supportedAgents(): Promise<AgentInfo[]>;
+    getContextUsage(): Promise<SDKControlGetContextUsageResponse>;
+    mcpServerStatus(): Promise<McpServerStatus[]>;
+    accountInfo(): Promise<AccountInfo>;
+    rewindFiles(userMessageId: string, options?: {
+        dryRun?: boolean;
+    }): Promise<RewindFilesResult>;
+    compact(): Promise<ProviderCompactResult>;
+    getLastResponseMetadata(): ResponseMetadata | null;
+    getOutputStream(): AsyncIterable<OutputEvent>;
+    getInputStreamRef(): Pick<InputStreamRef, 'pushUserMessage'>;
+    getHistory(): readonly Message[];
+    getTurnCount(): number;
+    close(): Promise<void>;
+    private dispatchSessionEndOnce;
+    private emitClosure;
+    private deriveClosureReason;
+    private sealTraceWriter;
+    recordSubagentCompletion(usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheCreationTokens?: number;
+    }, costUsd?: number): void;
+    private deriveSealStatus;
+    private assertCanSend;
+}

package/dist/agent/session/closure-guidance.d.ts

@@ -0,0 +1,3 @@
+import type { ClosureReason } from '../trace/index.js';
+export declare const CLOSURE_ABORT_RECOVERY_HINT: string;
+export declare function buildClosureGuidance(reason: ClosureReason): string | null;

package/dist/agent/session/closure-reason.d.ts

@@ -0,0 +1,11 @@
+import type { ClosureReason } from '../trace/index.js';
+export declare function isTruncationStopReason(stopReason: string | undefined): boolean;
+export interface ClosureReasonInputs {
+    dispatchReason: string;
+    maxTurnsHit: boolean;
+    hookBlocked: boolean;
+    abort: 'budget_exceeded' | 'timeout' | 'abort' | null;
+    lastStopReason: string | undefined;
+    sawProviderError: boolean;
+}
+export declare function classifyClosureReason(i: ClosureReasonInputs): ClosureReason;

package/dist/agent/session/hooks-dispatch.d.ts

@@ -0,0 +1,9 @@
+import type { HookRegistry, SessionEndContext, SessionStartContext } from '../hooks.js';
+import type { TraceWriter } from '../trace/index.js';
+export interface SessionHookDispatchOptions {
+    signal?: AbortSignal;
+    onError?: (err: Error) => void;
+    traceWriter?: TraceWriter;
+}
+export declare function dispatchSessionStart(registry: HookRegistry | undefined, context: SessionStartContext, options?: SessionHookDispatchOptions): Promise<void>;
+export declare function dispatchSessionEnd(registry: HookRegistry | undefined, context: SessionEndContext, options?: SessionHookDispatchOptions): Promise<void>;

package/dist/agent/session/input-iterable.d.ts

@@ -0,0 +1,10 @@
+import type { ContentBlockParam } from '@anthropic-ai/sdk/resources';
+import type { ProviderUserTurn } from '../provider.js';
+export declare class QueryInputStream {
+    private pendingResolve;
+    private bufferedMessages;
+    private getSessionId;
+    constructor(getSessionId: () => string | undefined);
+    pushUserMessage(content: string | ContentBlockParam[]): void;
+    createIterable(): AsyncIterable<ProviderUserTurn>;
+}

package/dist/agent/session/model-resolution.d.ts

@@ -0,0 +1,5 @@
+import type { AgentModelInput, ClaudeModel } from '../types.js';
+export declare const MODEL_MAP: Readonly<Record<ClaudeModel, string>>;
+export declare function isValidModel(model: string): model is ClaudeModel;
+export declare function getModelId(shortName: ClaudeModel): string;
+export declare function resolveModelId(model: AgentModelInput | undefined): string | undefined;

package/dist/agent/session/model-slots.d.ts

@@ -0,0 +1,24 @@
+export type SlotName = 'local' | 'small' | 'medium' | 'large';
+export declare const SLOT_NAMES: readonly SlotName[];
+export type SlotProvider = 'anthropic' | 'openai';
+export interface ModelSlotBinding {
+    id: string;
+    name?: string;
+    provider?: SlotProvider;
+    baseUrl?: string;
+    apiKey?: string;
+}
+export type ModelSlots = Record<SlotName, ModelSlotBinding>;
+export declare const DEFAULT_SLOT_BINDINGS: ModelSlots;
+export declare const AUTO_SENTINEL = "auto";
+export declare const CLAUDE_FABLE_5_ID = "claude-fable-5";
+export declare const DIRECT_MODEL_ALIASES: Readonly<Record<string, string>>;
+export declare function setSlotBindings(bindings: ModelSlots | undefined): void;
+export declare function resetSlotBindings(): void;
+export declare function computeSlotBindings(fileOverrides?: Partial<Record<SlotName, ModelSlotBinding>>): ModelSlots;
+export declare function getSlotBindings(override?: ModelSlots): ModelSlots;
+export declare function slotForInput(input: string, bindings?: ModelSlots): SlotName | undefined;
+export declare function resolveBinding(input: string | undefined, bindings?: ModelSlots): ModelSlotBinding;
+export declare function resolveModelInput(input: string | undefined, bindings?: ModelSlots): string | undefined;
+export declare function unconfiguredSlotError(input: string | undefined, bindings?: ModelSlots): string | undefined;
+export declare function parseModelsConfig(raw: unknown): Partial<Record<SlotName, ModelSlotBinding>>;

package/dist/agent/session/phase-reducer.d.ts

@@ -0,0 +1,3 @@
+import type { OutputEvent, SubagentProgressMeta } from '../types.js';
+export type Phase = 'idle' | 'investigating' | 'editing' | 'testing' | 'building' | 'waiting_on_subagent' | 'risky_pending' | 'blocked_by_hook' | 'interrupted' | 'ready_for_review';
+export declare function reducePhase(prev: Phase, event: OutputEvent, meta: SubagentProgressMeta | undefined, now: number, lastEventAt: number): Phase;

package/dist/agent/session/prompt-dump.d.ts

@@ -0,0 +1,33 @@
+export type PromptShape = 'string' | 'string[]' | 'preset' | 'undefined';
+export interface SystemPromptProvenance {
+    source: string;
+    shape: PromptShape;
+    length?: number;
+}
+export interface Provenance {
+    systemPrompt?: SystemPromptProvenance;
+    model?: {
+        source: string;
+    };
+    apiKey?: {
+        source: string;
+    };
+}
+export type ResolutionKind = 'custom-string' | 'custom-string-array' | 'preset-claude-code' | 'undefined';
+export interface Resolution {
+    kind: ResolutionKind;
+    note: string;
+    append?: {
+        length: number;
+    };
+    excludeDynamicSections?: boolean;
+}
+export interface DumpPayload {
+    prompt: unknown;
+    options: unknown;
+    provenance: Provenance;
+}
+export declare const DUMP_FILE_BANNER = "# AFK PROMPT DUMP \u2014 May contain secrets. Inspect before sharing.\n";
+export declare function redactInlineSecrets(text: string): string;
+export declare function deriveResolution(systemPrompt: unknown): Resolution;
+export declare function dumpIfEnabled(payload: DumpPayload): void;

package/dist/agent/session/session-identity.d.ts

@@ -0,0 +1,6 @@
+import type { Surface } from '../awareness/types.js';
+export type TraceOrigin = 'cli' | 'telegram' | 'daemon' | 'unknown';
+export type TraceActor = 'main' | 'subagent';
+export declare function deriveOrigin(surface: Surface | undefined): TraceOrigin;
+export declare function deriveActor(parentSessionId: string | null | undefined): TraceActor;
+export declare function actorFromDepth(depth: number | undefined): TraceActor;

package/dist/agent/session/session-setup.d.ts

@@ -0,0 +1,6 @@
+import type { AgentConfig, SessionIdentity, SessionMetadata } from '../types.js';
+export declare function wireAbortSignal(external: AbortSignal | undefined, internal: AbortController, onAbort: () => void): void;
+export declare function buildInitialState(config: AgentConfig, resolvedModel: string): {
+    sessionIdentity: SessionIdentity;
+    metadata: SessionMetadata;
+};

package/dist/agent/session/session-state.d.ts

@@ -0,0 +1,20 @@
+import type { SessionIdentity, SessionMetadata } from '../types.js';
+export declare class SessionStateManager {
+    private initializationPromise;
+    private resolveInitialization;
+    private rejectInitialization;
+    private initializationSettled;
+    private sessionMetadata;
+    private sessionIdentity;
+    constructor(sessionIdentity: SessionIdentity, initialMetadata: SessionMetadata);
+    waitForInitialization(): Promise<SessionMetadata>;
+    getSessionIdentity(): SessionIdentity;
+    getSessionMetadata(): SessionMetadata;
+    getSessionId(): string | undefined;
+    updateSessionIdentity(sessionId?: string): void;
+    setSessionMetadata(updater: (prev: SessionMetadata) => SessionMetadata): void;
+    resolveInitializationIfNeeded(): void;
+    resolveInitializationOnce(): void;
+    rejectInitializationOnce(error: Error): void;
+    isInitializationSettled(): boolean;
+}

package/dist/agent/session/slot-credentials.d.ts

@@ -0,0 +1,8 @@
+import { type ModelSlots } from './model-slots.js';
+export interface SlotCredentialTarget {
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    openaiBaseUrl?: string;
+}
+export declare function applySlotCredentials(config: SlotCredentialTarget, bindings?: ModelSlots): void;

package/dist/agent/session/stream-consumer.d.ts

@@ -0,0 +1,22 @@
+import type { ProviderEvent, ProviderUsage } from '../provider.js';
+import type { Message, OutputEvent, ResponseMetadata, SessionMetadata } from '../types.js';
+import type { TraceWriter } from '../trace/index.js';
+export type TransformDeps = {
+    conversationHistory: Message[];
+    getSessionMetadata: () => SessionMetadata;
+    setSessionMetadata: (updater: (prev: SessionMetadata) => SessionMetadata) => void;
+    updateSessionIdentity: (sessionId?: string) => void;
+    resolveInitialization: () => void;
+    setLastResponseMetadata: (metadata: ResponseMetadata) => void;
+    maxBudgetUsd?: number;
+    abortBudget?: (reason: string) => void;
+    _runningCostUsd?: number;
+    traceWriter?: TraceWriter;
+};
+export declare function parsePersistedOutput(content: string): {
+    sizeLabel: string;
+    sizeBytes: number;
+    absolutePath: string;
+} | null;
+export declare function usageToMetadata(usage: ProviderUsage, sessionId: string | undefined): ResponseMetadata;
+export declare function transformProviderEvent(event: ProviderEvent, deps: TransformDeps): OutputEvent | null;

package/dist/agent/session-ledger.d.ts

@@ -0,0 +1,81 @@
+import type { OutputEvent } from './types/session-types.js';
+import type { ElicitationRequest, ElicitationResult } from './types/sdk-types.js';
+export type LedgerRecord = {
+    v: 1;
+    ts: number;
+} & LedgerPayload;
+export type LedgerPayload = {
+    kind: 'meta';
+    sessionId: string;
+    model: string;
+    cwd?: string;
+    surface?: string;
+} | {
+    kind: 'user';
+    text: string;
+} | {
+    kind: 'assistant';
+    text: string;
+} | {
+    kind: 'tool';
+    toolName: string;
+    input: string;
+} | {
+    kind: 'tool_error';
+    toolName?: string;
+    content: string;
+} | {
+    kind: 'done';
+    costUsd?: number;
+    durationMs?: number;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'paused';
+    resetsAt?: string;
+} | {
+    kind: 'resumed';
+} | {
+    kind: 'elicitation';
+    reqId: string;
+    request: ElicitationRequest;
+} | {
+    kind: 'elicitation_response';
+    reqId: string;
+    result: ElicitationResult;
+    hmac: string;
+} | {
+    kind: 'abort_request';
+    nonce: string;
+    hmac: string;
+} | {
+    kind: 'closed';
+    reason?: string;
+};
+export declare function projectOutputEvent(event: OutputEvent): LedgerPayload | null;
+export declare class SessionLedgerWriter {
+    private readonly sessionId;
+    private readonly ledgerPath;
+    private stream;
+    private errored;
+    private closed;
+    private streamReady;
+    private pendingLines;
+    private readyPromise;
+    private readyResolve;
+    constructor(sessionId: string);
+    get active(): boolean;
+    record(payload: LedgerPayload): void;
+    recordEvent(event: OutputEvent): void;
+    recordUser(text: string): void;
+    private _openStream;
+    private _writeLine;
+    close(reason?: string): Promise<void>;
+}
+export declare function ledgerExists(sessionId: string): Promise<boolean>;
+export declare function readLedger(sessionId: string): AsyncGenerator<LedgerRecord>;
+export declare function tailLedger(sessionId: string, opts?: {
+    fromStart?: boolean;
+    signal?: AbortSignal;
+}): AsyncGenerator<LedgerRecord>;

package/dist/agent/session-ref.d.ts

@@ -0,0 +1,4 @@
+import type { AgentSession } from './session.js';
+export interface SessionRef {
+    current: AgentSession;
+}

package/dist/agent/session.d.ts

@@ -0,0 +1 @@
+export { AgentSession } from './session/agent-session.js';

package/dist/agent/shadow-verify-nudge.d.ts

@@ -0,0 +1,2 @@
+import type { HookContext, HookDecision } from './hooks.js';
+export declare function shadowVerifyNudge(context: HookContext): HookDecision;

package/dist/agent/shell-jobs/index.d.ts

@@ -0,0 +1,2 @@
+export { startShell, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES, type StartShellOptions, type ShellHandle, type ShellResult, type ShellErrorReason, } from './streamer.js';
+export { ShellJobRegistry, type ShellJob, type ShellJobStatus, type ShellJobRegistryEvents, type StartJobOptions, } from './registry.js';

package/dist/agent/shell-jobs/registry.d.ts

@@ -0,0 +1,36 @@
+import { EventEmitter } from 'node:events';
+import { type ShellHandle, type ShellResult, type StartShellOptions } from './streamer.js';
+export type ShellJobStatus = 'running' | 'completed' | 'failed' | 'killed';
+export interface ShellJob {
+    readonly id: string;
+    readonly command: string;
+    readonly pid: number | undefined;
+    readonly startedAt: number;
+    readonly mode: 'foreground' | 'background';
+    status: ShellJobStatus;
+    result?: ShellResult;
+}
+export interface ShellJobRegistryEvents {
+    complete: [job: ShellJob];
+}
+export type StartJobOptions = Omit<StartShellOptions, 'onChunk' | 'abort'> & {
+    onChunk?: StartShellOptions['onChunk'];
+    mode: 'foreground' | 'background';
+};
+export declare class ShellJobRegistry extends EventEmitter<ShellJobRegistryEvents> {
+    private readonly jobs;
+    private readonly handles;
+    private readonly aborts;
+    private counter;
+    start(opts: StartJobOptions): {
+        job: ShellJob;
+        handle: ShellHandle;
+    };
+    get(id: string): ShellJob | undefined;
+    list(): readonly ShellJob[];
+    running(): readonly ShellJob[];
+    kill(id: string): boolean;
+    killAll(): readonly ShellJob[];
+    runningCount(): number;
+    private pruneHistory;
+}

package/dist/agent/shell-jobs/streamer.d.ts

@@ -0,0 +1,33 @@
+export interface AnsiStripper {
+    strip(text: string): string;
+    flush(): string;
+}
+export declare function makeAnsiStripper(): AnsiStripper;
+export declare function utf8SafeTruncate(buf: Buffer, maxBytes: number): Buffer;
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare const DEFAULT_MAX_BYTES = 100000;
+export interface StartShellOptions {
+    command: string;
+    cwd?: string;
+    abort: AbortSignal;
+    timeoutMs?: number;
+    maxBytes?: number;
+    onChunk?: (chunk: Buffer, stream: 'stdout' | 'stderr') => void;
+    env?: Record<string, string>;
+}
+export type ShellErrorReason = 'timeout' | 'abort' | 'overflow' | 'spawn-failed' | 'nonzero-exit' | 'signal-killed';
+export interface ShellResult {
+    exitCode: number | null;
+    durationMs: number;
+    displayCaptured: string;
+    modelCaptured: string;
+    truncated: boolean;
+    errorReason?: ShellErrorReason;
+    errorMessage?: string;
+}
+export interface ShellHandle {
+    readonly pid: number | undefined;
+    readonly promise: Promise<ShellResult>;
+    kill(signal?: NodeJS.Signals): void;
+}
+export declare function startShell(opts: StartShellOptions): ShellHandle;

package/dist/agent/signal-block.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export declare const StanceSchema: z.ZodEnum<{
+    supports: "supports";
+    opposes: "opposes";
+    uncertain: "uncertain";
+    blocks: "blocks";
+}>;
+export type Stance = z.infer<typeof StanceSchema>;
+export declare const SignalSchema: z.ZodObject<{
+    issue: z.ZodString;
+    stance: z.ZodEnum<{
+        supports: "supports";
+        opposes: "opposes";
+        uncertain: "uncertain";
+        blocks: "blocks";
+    }>;
+    confidence: z.ZodNumber;
+    evidence: z.ZodArray<z.ZodString>;
+    claim: z.ZodString;
+}, z.core.$strip>;
+export type Signal = z.infer<typeof SignalSchema>;
+export declare const SignalBlockSchema: z.ZodObject<{
+    signal: z.ZodObject<{
+        issue: z.ZodString;
+        stance: z.ZodEnum<{
+            supports: "supports";
+            opposes: "opposes";
+            uncertain: "uncertain";
+            blocks: "blocks";
+        }>;
+        confidence: z.ZodNumber;
+        evidence: z.ZodArray<z.ZodString>;
+        claim: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$loose>;
+export type SignalBlock = z.infer<typeof SignalBlockSchema>;
+export type ParseSignalResult = {
+    ok: true;
+    signal: Signal;
+} | {
+    ok: false;
+    reason: 'absent' | 'malformed';
+};
+export declare function extractSignalBlock(content: string): unknown;
+export declare function parseSignal(content: string): ParseSignalResult;

package/dist/agent/subagent/handle.d.ts

@@ -0,0 +1,51 @@
+import type { ZodType } from 'zod';
+import { AbortGraph } from '../abort-graph.js';
+import type { HookRegistry } from '../hooks.js';
+import type { IAgentSession, Message } from '../types.js';
+import type { OutputEvent, SubagentProgressSink } from '../types/session-types.js';
+import type { TraceWriter } from '../trace/index.js';
+import { type SubagentResult, type SubagentStatus, type SubagentTrace } from './result.js';
+export interface SubagentHandle<T = unknown> {
+    readonly id: string;
+    readonly status: SubagentStatus;
+    readonly session: IAgentSession;
+    run(prompt: string): Promise<Message>;
+    runToResult(prompt: string): Promise<SubagentResult<T>>;
+    runInBackground(prompt: string, onResult?: (result: SubagentResult<T>) => void, onProgress?: (event: OutputEvent) => void): void;
+    cancel(): Promise<void>;
+    teardown(): Promise<void>;
+}
+export declare class SubagentHandleImpl<T> implements SubagentHandle<T> {
+    readonly id: string;
+    readonly session: IAgentSession;
+    private readonly controller;
+    private readonly abortGraph;
+    private readonly outputSchema;
+    private readonly timeoutMs;
+    private readonly hookRegistry;
+    private readonly onTerminal;
+    private readonly parentInputStreamRef?;
+    private readonly parentAbortSignal?;
+    private readonly agentType?;
+    private readonly traceWriter?;
+    private readonly onSubagentSucceeded?;
+    private currentStatus;
+    private inFlight;
+    private lastMessage;
+    private lastDurationMs;
+    private latestTerminalStatus;
+    private stopDispatched;
+    private readonly progressSink;
+    private parentId;
+    private currentTrace;
+    private lastStreamedContent;
+    constructor(id: string, session: IAgentSession, controller: AbortController, abortGraph: AbortGraph, outputSchema: ZodType<T> | undefined, timeoutMs: number, hookRegistry: HookRegistry | undefined, onTerminal: () => void, parentInputStreamRef?: ReturnType<IAgentSession["getInputStreamRef"]> | undefined, parentAbortSignal?: AbortSignal | undefined, agentType?: string | undefined, progressSink?: SubagentProgressSink, parentId?: string, traceWriter?: TraceWriter | undefined, onSubagentSucceeded?: ((usage: SubagentTrace["usage"], costUsd: number | undefined) => void) | undefined);
+    get status(): SubagentStatus;
+    run(prompt: string, sinkOverride?: SubagentProgressSink): Promise<Message>;
+    private streamToFinalMessage;
+    runToResult(prompt: string, sinkOverride?: SubagentProgressSink): Promise<SubagentResult<T>>;
+    runInBackground(prompt: string, onResult?: (result: SubagentResult<T>) => void, onProgress?: (event: OutputEvent) => void): void;
+    cancel(): Promise<void>;
+    teardown(): Promise<void>;
+    private dispatchStopAndRelease;
+}

package/dist/agent/subagent/result.d.ts

@@ -0,0 +1,51 @@
+import type { ZodError, ZodType } from 'zod';
+import type { Message } from '../types.js';
+import { type Signal } from '../signal-block.js';
+export type SubagentStatus = 'idle' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export interface SubagentToolCall {
+    id: string;
+    name: string;
+    inputBytes?: number;
+}
+export interface SubagentToolResult {
+    toolUseId: string;
+    isError?: boolean;
+    truncated?: boolean;
+    sizeBytes?: number;
+}
+export interface SubagentTrace {
+    toolCalls: SubagentToolCall[];
+    toolResults: SubagentToolResult[];
+    thinkingPresent: boolean;
+    turnCount: number;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheCreationTokens?: number;
+    };
+}
+export declare function createEmptyTrace(): SubagentTrace;
+export interface SubagentResult<T = unknown> {
+    id: string;
+    status: SubagentStatus;
+    message?: Message;
+    output?: T;
+    error?: Error;
+    schemaError?: ZodError;
+    partialOutput?: T | string;
+    completionPercent?: number;
+    trace?: SubagentTrace;
+    signal?: Signal;
+}
+export declare function buildResultFromMessage<T>(id: string, status: SubagentStatus, message: Message, outputSchema: ZodType<T> | undefined, trace?: SubagentTrace): SubagentResult<T>;
+export declare function buildResultFromError<T>(id: string, status: SubagentStatus, err: unknown, trace?: SubagentTrace): SubagentResult<T>;
+export declare function describeFailure(result: Pick<SubagentResult, 'status' | 'error'>): string;
+export interface SubagentExecutionError extends Error {
+    partialOutput?: unknown;
+    subagentId?: string;
+}
+export declare function attachSubagentContext(err: Error, context: {
+    partialOutput?: unknown;
+    subagentId?: string;
+}): SubagentExecutionError;