agent-afk 5.256.0 → 5.257.0

package/dist/whatif/args.d.ts

@@ -0,0 +1,28 @@
+import type { Change, ChangeSpec } from './types.js';
+export { WHATIF_USAGE } from './args.usage.js';
+export declare function tokenizeSlashArgs(raw: string): string[];
+export interface WhatifFlagOptions {
+    agentModel?: string;
+    analystModel?: string;
+    verify: boolean;
+    turns: number;
+    samples: number;
+    maxUsd: number;
+    judge: 'auto' | 'jev' | 'claude';
+    concurrency: number;
+    maxTurns: number;
+    episodeTimeoutMs: number;
+    keepSandboxes: boolean;
+}
+export interface ParsedWhatifArgs {
+    flagChanges: Change[];
+    text?: string;
+    specFile?: string;
+    options: WhatifFlagOptions;
+    yes: boolean;
+    json: boolean;
+}
+export type ParseResult = ParsedWhatifArgs | string;
+export declare function parseWhatifArgs(argv: string[]): ParseResult;
+export declare function buildFlagSpecTitle(flagChanges: Change[], text?: string): string;
+export declare function loadSpecFile(filePath: string): ChangeSpec;

package/dist/whatif/args.usage.d.ts

@@ -0,0 +1 @@
+export declare const WHATIF_USAGE = "afk whatif \u2014 predict the behavioural impact of a proposed change.\n\nUSAGE\n  afk whatif [change text...]  [flags]\n  /whatif [change text...]  [flags]\n\nEXAMPLES\n  # Plain English \u2014 compiled to a ChangeSpec, confirmed before running\n  afk whatif \"turn off auto-routing\"\n  afk whatif \"always ask before using tools\"\n\n  # Explicit flags (can be combined and repeated)\n  afk whatif --append \"Always ask a clarifying question before running tools.\"\n  afk whatif --model claude-haiku-4-5 --verify\n  afk whatif --memory-add \"prefers pnpm test:file\" --memory-category preference\n\n  # Load a prepared ChangeSpec file\n  afk whatif --spec ./my-change.json\n\n  # Quick single-turn estimate\n  afk whatif \"disable diagnose skill\" --quick\n\n  # Full verification with custom judge and budget\n  afk whatif --append \"Never use bash\" --verify --judge claude --max-usd 3\n\nCHANGE FLAGS (accumulate in order)\n  --append <text>              Append text to your AFK.md (user scope)\n  --append-project <text>      Append text to project AFK.md\n  --file <path>=<localfile>    Set a file (path: home:<rel> or project:<rel>)\n  --hot <localfile>            Replace HOT.md with a local file's content\n  --memory-add <text>          Add a memory fact\n  --memory-category <cat>      Category for the next --memory-add\n                               (preference|convention|decision|learning; default: preference)\n  --memory-remove <id>         Remove a memory fact by numeric id\n  --disable-skill <name>       Disable a skill by name\n  --disable-plugin <name>      Disable a plugin by name\n  --model <id>                 Test a different candidate model\n  --effort <level>             Test a different effort level\n  --env KEY=VALUE              Set an env var in the candidate sandbox\n  --spec <file.json>           Load a full ChangeSpec from a JSON file\n\nRUN OPTIONS\n  --agent-model <id>           Model the agent under test uses (default: current)\n  --analyst-model <id>         Model for compile/predict/judge (default: sonnet)\n  --verify                     Run episodes and verify predictions empirically\n  --quick                      Single-turn episodes (sets --max-turns 1)\n  --turns <n>                  Real turns to replay (default: 12)\n  --samples <n>                Samples per episode per environment (default: 3)\n  --max-usd <n>                Budget cap in USD (default: 5)\n  --judge auto|jev|claude      Judge to use (default: auto)\n  --concurrency <n>            Parallel episodes (default: 4)\n  --max-turns <n>              Max turns per episode (default: 3)\n  --timeout <sec>              Episode timeout in seconds (default: 180)\n  --keep-sandboxes             Keep sandbox directories after run\n  --yes                        Skip confirmation of compiled spec\n  --json                       Print results as JSON to stdout\n";

package/dist/whatif/compile.d.ts

@@ -0,0 +1,6 @@
+import type { ChangeSpec, CompleteFn } from './types.js';
+export interface CompileCtx {
+    skills: string[];
+    plugins: string[];
+}
+export declare function compileChangeSpec(text: string, complete: CompleteFn, model: string, ctx: CompileCtx): Promise<ChangeSpec>;

package/dist/whatif/complete.d.ts

@@ -0,0 +1,2 @@
+import type { CompleteFn } from './types.js';
+export declare function createAnthropicComplete(token: string): CompleteFn;

package/dist/whatif/complete.retry.d.ts

@@ -0,0 +1,8 @@
+export declare function isRetryableAnalystError(err: unknown): boolean;
+export interface RetryOptions {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    signal?: AbortSignal;
+}
+export declare function withAnalystRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/whatif/cost.d.ts

@@ -0,0 +1,27 @@
+export interface VerifyCostInput {
+    episodes: number;
+    samples: number;
+    agentModel: string;
+    analystModel: string;
+    systemTokens: {
+        baseline: number;
+        candidate: number;
+    };
+    judgeExternal: boolean;
+}
+export interface VerifyCostEstimate {
+    usd: number;
+    calls: number;
+    breakdown: Record<string, number>;
+    approximate?: boolean;
+}
+export declare function estimateVerifyCost(input: VerifyCostInput): VerifyCostEstimate;
+export declare class BudgetTracker {
+    private _spent;
+    private readonly _max;
+    constructor(maxUsd: number);
+    add(usd: number): void;
+    get spent(): number;
+    get exceeded(): boolean;
+    remaining(): number;
+}

package/dist/whatif/discover.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { CompleteFn, Prediction } from './types.js';
+declare const DiffSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    question: z.ZodString;
+}, z.core.$strip>;
+export type DiscoveredDiff = z.infer<typeof DiffSchema>;
+export interface OutputPair {
+    prompt: string;
+    baseline: string;
+    candidate: string;
+}
+export declare function discoverDifferences(pairs: OutputPair[], known: Prediction[], complete: CompleteFn, model: string): Promise<DiscoveredDiff[]>;
+export {};

package/dist/whatif/episodes.d.ts

@@ -0,0 +1,12 @@
+import type { Episode, Prediction } from './types.js';
+interface CollectOpts {
+    limit: number;
+    excludeSessionIds?: string[];
+    sessionsDir?: string;
+    now?: Date;
+    maxAgeDays?: number;
+}
+export declare function collectRealTurns(opts: CollectOpts): Promise<Episode[]>;
+export declare function syntheticEpisodes(predictions: Prediction[]): Episode[];
+export declare function loadSuiteEpisodes(dir: string): Promise<Episode[]>;
+export {};

package/dist/whatif/index.d.ts

@@ -0,0 +1,11 @@
+export { runWhatif, WhatifBudgetError } from './run.js';
+export { computeStructuralImpact } from './structural.js';
+export type { Change, ChangeKind, ChangeSpec, LaunchSettings, Environment, OperatorContext, ChangeOperator, RequestSnapshot, StructuralImpact, PredictionDirection, Confidence, Prediction, Episode, ToolRequest, EpisodeTrace, RunnerOptions, AgentRunner, EpisodeFeatures, JudgeQuestion, JudgeInput, JudgeResult, Judge, RateComparison, Verdict, VerifiedPrediction, DiscoveredDifference, FeatureDelta, VerifyResult, WhatifReport, WhatifStage, WhatifProgress, CompleteFn, WhatifOptions, WhatifDeps, } from './types.js';
+export { renderTerminal, renderMarkdown } from './report.js';
+export { createAfkRunner } from './runner/afk-runner.js';
+export { createAnthropicComplete } from './complete.js';
+export { resolveJudge } from './judge/index.js';
+export { connectJev } from './judge/jev-connect.js';
+export { createClaudeJudge } from './judge/claude.js';
+export { compileChangeSpec } from './compile.js';
+export { describeChange } from './operators/index.js';

package/dist/whatif/json-extract.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare function extractJson(text: string): unknown;
+export declare function extractJsonAs<T>(text: string, schema: z.ZodType<T>): T;

package/dist/whatif/judge/claude.d.ts

@@ -0,0 +1,2 @@
+import type { CompleteFn, Judge } from '../types.js';
+export declare function createClaudeJudge(complete: CompleteFn, model: string): Judge;

package/dist/whatif/judge/index.d.ts

@@ -0,0 +1,8 @@
+import type { CompleteFn, Judge } from '../types.js';
+import type { connectJev } from './jev-connect.js';
+export interface ResolveJudgeDeps {
+    complete: CompleteFn;
+    model: string;
+    connectJev: typeof connectJev;
+}
+export declare function resolveJudge(choice: 'auto' | 'jev' | 'claude', deps: ResolveJudgeDeps): Promise<Judge>;

package/dist/whatif/judge/jev-connect.d.ts

@@ -0,0 +1,5 @@
+export interface JevConnection {
+    callTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function connectJev(): Promise<JevConnection | undefined>;

package/dist/whatif/judge/jev.d.ts

@@ -0,0 +1,9 @@
+import type { Judge, JudgeQuestion, JudgeResult } from '../types.js';
+export interface JevCallToolFn {
+    (name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+export interface JevJudgeOpts {
+    callTool: JevCallToolFn;
+}
+export declare function parseJevResult(raw: unknown, questions: JudgeQuestion[]): JudgeResult;
+export declare function createJevJudge(opts: JevJudgeOpts): Judge;

package/dist/whatif/ledger.d.ts

@@ -0,0 +1,10 @@
+import type { Prediction, Verdict } from './types.js';
+export interface CalibrationRecord {
+    ts: string;
+    changeKinds: string[];
+    prediction: Prediction;
+    verdict: Verdict;
+    delta: number;
+}
+export declare function appendCalibration(records: CalibrationRecord[], file?: string): Promise<void>;
+export declare function trackRecordSummary(changeKinds: string[], file?: string): Promise<string | undefined>;

package/dist/whatif/observe.d.ts

@@ -0,0 +1,6 @@
+import type { EpisodeFeatures, EpisodeTrace } from './types.js';
+export declare const FEATURE_LABELS: readonly string[];
+export declare function extractFeatures(trace: EpisodeTrace): EpisodeFeatures;
+export declare function featureIndicators(f: EpisodeFeatures): Record<string, boolean>;
+export declare function meanToolCalls(samples: EpisodeFeatures[]): number;
+export declare function meanResponseChars(samples: EpisodeFeatures[]): number;

package/dist/whatif/operators/content-ops.d.ts

@@ -0,0 +1,4 @@
+import type { ChangeOperator } from '../types.js';
+export declare const appendOperator: ChangeOperator<'append'>;
+export declare const fileOperator: ChangeOperator<'file'>;
+export declare const hotOperator: ChangeOperator<'hot'>;

package/dist/whatif/operators/index.d.ts

@@ -0,0 +1,6 @@
+import type { Change, ChangeKind, ChangeOperator, ChangeSpec, Environment, OperatorContext } from '../types.js';
+export declare function getOperator<K extends ChangeKind>(kind: K): ChangeOperator<K>;
+export declare function applyChanges(spec: ChangeSpec, env: Environment, ctx: OperatorContext): Promise<void>;
+export declare function describeChange(change: Change): string;
+export declare function specTouchesProject(spec: ChangeSpec): boolean;
+export declare function homePathsToCopyFor(spec: ChangeSpec): string[];

package/dist/whatif/operators/launch-ops.d.ts

@@ -0,0 +1,4 @@
+import type { ChangeOperator } from '../types.js';
+export declare const modelOperator: ChangeOperator<'model'>;
+export declare const effortOperator: ChangeOperator<'effort'>;
+export declare const envOperator: ChangeOperator<'env'>;

package/dist/whatif/operators/memory-ops.d.ts

@@ -0,0 +1,3 @@
+import type { ChangeOperator } from '../types.js';
+export declare const memoryAddOperator: ChangeOperator<'memory-add'>;
+export declare const memoryRemoveOperator: ChangeOperator<'memory-remove'>;

package/dist/whatif/operators/sandbox-guard.d.ts

@@ -0,0 +1,2 @@
+import type { Environment } from '../types.js';
+export declare function assertInsideSandbox(dir: string, env: Environment): void;

package/dist/whatif/operators/skill-plugin-ops.d.ts

@@ -0,0 +1,3 @@
+import type { ChangeOperator } from '../types.js';
+export declare const disableSkillOperator: ChangeOperator<'disable-skill'>;
+export declare const disablePluginOperator: ChangeOperator<'disable-plugin'>;

package/dist/whatif/predict.d.ts

@@ -0,0 +1,11 @@
+import type { CompleteFn, Prediction, StructuralImpact } from './types.js';
+export interface PredictInput {
+    spec: {
+        title: string;
+        changes: unknown[];
+    };
+    changeDescriptions: string[];
+    structural: StructuralImpact;
+    trackRecord?: string;
+}
+export declare function predictChanges(input: PredictInput, complete: CompleteFn, model: string): Promise<Prediction[]>;

package/dist/whatif/report.d.ts

@@ -0,0 +1,9 @@
+import type { ThemePalette } from '../cli/palette.js';
+import type { WhatifReport } from './types.js';
+export declare function buildHeadline(report: Omit<WhatifReport, 'headline'>): string;
+export declare function renderMarkdown(report: WhatifReport): string;
+export declare function renderTerminal(report: WhatifReport, palette: ThemePalette): string[];
+export declare function standardLimits(opts: {
+    verified: boolean;
+    judgeExternal: boolean;
+}): string[];

package/dist/whatif/run.d.ts

@@ -0,0 +1,9 @@
+import type { WhatifDeps, WhatifOptions, WhatifReport } from './types.js';
+export declare class WhatifBudgetError extends Error {
+    readonly estimateUsd: number;
+    readonly maxUsd: number;
+    constructor(estimateUsd: number, maxUsd: number);
+}
+export declare function runWhatif(options: WhatifOptions & {
+    sessionsDir?: string;
+}, deps: WhatifDeps): Promise<WhatifReport>;

package/dist/whatif/run.limits.d.ts

@@ -0,0 +1,2 @@
+import type { VerifyResult } from './types.js';
+export declare function verifyShortfallLimits(v: VerifyResult): string[];

package/dist/whatif/run.persist.d.ts

@@ -0,0 +1,2 @@
+import type { EpisodeTrace, WhatifReport } from './types.js';
+export declare function persistRun(runDir: string, report: WhatifReport, traces: EpisodeTrace[]): Promise<void>;

package/dist/whatif/run.verify.d.ts

@@ -0,0 +1,30 @@
+import type { AgentRunner, CompleteFn, Episode, EpisodeTrace, Environment, Judge, Prediction, StructuralImpact, VerifyResult, WhatifProgress } from './types.js';
+export interface VerifyRunInput {
+    episodes: Episode[];
+    baseline: Environment;
+    candidate: Environment;
+    predictions: Prediction[];
+    structural: StructuralImpact;
+    judge: Judge;
+    crossCheckJudge: Judge | undefined;
+    runner: AgentRunner;
+    complete: CompleteFn;
+    analystModel: string;
+    options: {
+        samples: number;
+        concurrency: number;
+        maxTurns: number;
+        episodeTimeoutMs: number;
+        maxUsdRemaining: number;
+        changeKinds: string[];
+        calibrationFile?: string;
+    };
+    onProgress?: (p: WhatifProgress) => void;
+    signal?: AbortSignal;
+}
+export interface VerifyRunOutput {
+    verifyResult: VerifyResult;
+    allTraces: EpisodeTrace[];
+    analystCostUsd: number;
+}
+export declare function verifyRun(input: VerifyRunInput): Promise<VerifyRunOutput>;

package/dist/whatif/runner/afk-runner.d.ts

@@ -0,0 +1,10 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { AgentRunner } from '../types.js';
+export interface AfkRunnerOptions {
+    cliEntry?: {
+        command: string;
+        args: string[];
+    };
+    spawnImpl?: typeof nodeSpawn;
+}
+export declare function createAfkRunner(opts?: AfkRunnerOptions): AgentRunner;

package/dist/whatif/runner/afk-runner.run.d.ts

@@ -0,0 +1,16 @@
+import type { SpawnOptions } from 'node:child_process';
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { EpisodeTrace } from '../types.js';
+export type SpawnFn = typeof nodeSpawn;
+export interface RunEpisodeChildArgs {
+    command: string;
+    spawnArgs: string[];
+    spawnOptions: SpawnOptions;
+    spawnImpl: SpawnFn;
+    episodeId: string;
+    envLabel: 'baseline' | 'candidate';
+    sample: number;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+export declare function runEpisodeChild(args: RunEpisodeChildArgs): Promise<EpisodeTrace>;

package/dist/whatif/runner/afk-runner.snapshot.d.ts

@@ -0,0 +1,4 @@
+import type { RequestSnapshot } from '../types.js';
+import type { CapturedRequest } from './capture-server.js';
+export declare function buildSnapshotFromRequests(requests: CapturedRequest[], stderrTail: string): RequestSnapshot;
+export declare function buildSnapshotCliArgs(baseEntryArgs: string[], prompt: string, model?: string, effort?: string): string[];

package/dist/whatif/runner/capture-server.d.ts

@@ -0,0 +1,9 @@
+export interface CapturedRequest {
+    body: unknown;
+}
+export interface CaptureServer {
+    port: number;
+    requests: CapturedRequest[];
+    close(): Promise<void>;
+}
+export declare function startCaptureServer(): Promise<CaptureServer>;

package/dist/whatif/runner/child-env.d.ts

@@ -0,0 +1,2 @@
+import type { Environment } from '../types.js';
+export declare function buildChildEnv(env: Environment, extra: Record<string, string>): Record<string, string>;

package/dist/whatif/runner/tool-log.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRequest } from '../types.js';
+export declare function readToolLog(path: string): Promise<ToolRequest[]>;

package/dist/whatif/sandbox.d.ts

@@ -0,0 +1,14 @@
+import type { Environment, LaunchSettings, ChangeSpec } from './types.js';
+export interface MaterializeOptions {
+    realHome: string;
+    realCwd: string;
+    runDir: string;
+    spec: ChangeSpec;
+    baseLaunch: LaunchSettings;
+}
+export interface SandboxResult {
+    baseline: Environment;
+    candidate: Environment;
+    cleanup(): Promise<void>;
+}
+export declare function materializeSandboxes(opts: MaterializeOptions): Promise<SandboxResult>;

package/dist/whatif/sandbox.home.d.ts

@@ -0,0 +1,3 @@
+export declare function sandboxedAfkEnvKeys(realHome: string): string[];
+export declare function buildSandboxHome(realHome: string, sandboxHome: string): void;
+export declare function materializeSymlinks(sandboxHome: string, relPaths: string[]): void;

package/dist/whatif/stats.d.ts

@@ -0,0 +1,7 @@
+import type { Prediction, RateComparison, Verdict } from './types.js';
+export declare function compareRates(baseline: number[], candidate: number[]): RateComparison;
+export declare function verdictFor(pred: Prediction, rates: RateComparison): Verdict;
+export declare function predictionAccuracy(verified: ReadonlyArray<{
+    verdict: Verdict;
+}>): number | undefined;
+export declare function agreementRate(a: number[], b: number[]): number;

package/dist/whatif/structural.d.ts

@@ -0,0 +1,2 @@
+import type { RequestSnapshot, StructuralImpact } from './types.js';
+export declare function computeStructuralImpact(baseline: RequestSnapshot, candidate: RequestSnapshot): StructuralImpact;

package/dist/whatif/structural.normalize.d.ts

@@ -0,0 +1,5 @@
+import type { Environment, RequestSnapshot } from './types.js';
+export declare function normalizeSnapshot(snap: RequestSnapshot, env: Environment, real: {
+    home: string;
+    cwd: string;
+}): RequestSnapshot;

package/dist/whatif/surface.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedWhatifArgs } from './args.js';
+import type { ChangeSpec, CompleteFn, WhatifDeps, WhatifProgress } from './types.js';
+export interface ResolveSpecDeps {
+    complete: CompleteFn;
+    analystModel: string;
+    realHome: string;
+    skills: string[];
+    plugins: string[];
+}
+export declare function resolveSpec(parsed: ParsedWhatifArgs, deps: ResolveSpecDeps): Promise<ChangeSpec>;
+export interface BuildWhatifDepsOptions {
+    token: string;
+    analystModel: string;
+    onProgress?: (p: WhatifProgress) => void;
+    signal?: AbortSignal;
+}
+export declare function buildWhatifDeps(opts: BuildWhatifDepsOptions): WhatifDeps;
+export declare function readDirNames(dir: string): string[];