/** * Autonomy (Python parity: `Agent(autonomy=...)`, `agent/autonomy.py` * `AutonomyConfig`, `AUTONOMY_PRESETS`, `DoomLoopTracker`, and the * autonomy-to-approval bridge in `agent/agent.py`). * * Two observable behaviours are ported: * * 1. The autonomy *level* decides which tool calls need a human. Python * bridges `full_auto` to an auto-approve backend; here the level shapes * the agent's {@link ApprovalManager}: `full_auto` approves everything, * `auto_edit` approves read/edit style tools and prompts for the rest, * `suggest` prompts for every call. * 2. A {@link DoomLoopTracker} spots the model calling the same tool with * the same arguments over and over (or failing repeatedly) and, instead * of burning the iteration budget, feeds a recovery instruction back to * the model -- escalating to an abort when it keeps looping. */ import type { ApprovalManager } from '../../ai/tool-approval'; export type AutonomyLevel = 'suggest' | 'auto_edit' | 'full_auto'; export type AutonomyMode = 'caller' | 'iterative'; export declare const VALID_AUTONOMY_LEVELS: ReadonlySet; /** Python `AUTONOMY_PRESETS`. */ export declare const AUTONOMY_PRESETS: Readonly>; /** Resolved settings (Python `AutonomyConfig`; snake_case keys are accepted on input). */ export interface AutonomyConfig { enabled: boolean; level: AutonomyLevel; /** Python: `None` = smart default (`suggest`/`auto_edit` -> caller, `full_auto` -> iterative). */ mode: AutonomyMode; maxIterations: number; doomLoopThreshold: number; autoEscalate: boolean; observe: boolean; completionPromise?: string; clearContext: boolean; /** Python `effective_track_changes`: defaults to true for `full_auto`. */ trackChanges: boolean; /** Extra keys from a dict input are preserved (Python keeps them on `autonomy_config`). */ extra: Record; } /** * Resolve the constructor option. `true` -> level `suggest`; a preset name * selects the level; an unknown preset name disables autonomy (Python does * the same, silently -- the caller is told via the returned `undefined` and * a warning from the Agent); an object supplies fields. */ export declare function resolveAutonomy(input: boolean | string | Record | undefined | null): AutonomyConfig | undefined; /** * Tools an `auto_edit` agent may run without asking: reads and file edits. * Anything else (commands, network, deletes, deploys) still prompts. * * Matches only the exact verb (`edit`) or a `_file` / `_text` * variant. An open suffix such as `([_-].*)?` would auto-approve unrelated * tools like `write_to_s3`, `update_iam_policy`, or `get_secret`, so the * accepted suffix is a small closed set rather than "anything". */ export declare const AUTO_EDIT_TOOL_PATTERN: RegExp; /** Which tools the level lets through without approval. */ export declare function isAutoApprovedByLevel(level: AutonomyLevel, toolName: string): boolean; /** * Shape an approval manager to the level: `full_auto` auto-approves every * call, `auto_edit` auto-approves read/edit tools, `suggest` adds nothing so * every call reaches the manager's prompt. */ export declare function applyAutonomyToApproval(config: AutonomyConfig, manager: ApprovalManager): void; export type DoomLoopRecovery = 'continue' | 'retry_different' | 'escalate_model' | 'request_help' | 'abort'; /** * Python `DoomLoopTracker`: identical actions repeated `threshold` times, or * `threshold` consecutive failures, or the same response text repeated * `threshold` times, mean the agent is stuck. Recovery escalates on every * detection: retry_different -> escalate_model -> request_help -> abort. */ export declare class DoomLoopTracker { readonly threshold: number; private actions; private responses; private recoveryAttempts; constructor(threshold?: number); static actionKey(name: string, args: unknown): string; /** How many times the tail of the history is exactly this action. */ identicalRun(name: string, args: unknown): number; /** Whether executing this action would complete a doom loop. */ wouldLoop(name: string, args: unknown): boolean; record(name: string, args: unknown, _result: unknown, success: boolean): void; recordResponse(text: string): void; isDoomLoop(): boolean; getRecoveryAction(): DoomLoopRecovery; /** Forget the action history but keep the escalation count. */ clearActions(): void; reset(): void; } /** The instruction fed back to the model when a loop is detected. */ export declare function doomLoopMessage(toolName: string, repeats: number, recovery: DoomLoopRecovery): string;