safeloop 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+export interface BreakerConfig {
+    maxRetries?: number;
+    maxRepeatedErrors?: number;
+    tokenBudget?: {
+        perStep?: number;
+        perTask?: number;
+    };
+    scopeFreeze?: boolean;
+}
+export interface BreakerResult {
+    success: boolean;
+    stoppedBy: string;
+    attempts: number;
+    tokenEstimate: number;
+    lastError: string | null;
+    escalationMessage: string | null;
+    auditEntries: AuditEntry[];
+    data?: unknown;
+}
+export interface AuditEntry {
+    timestamp: number;
+    type: 'attempt' | 'retry' | 'failure' | 'budget_check' | 'breaker_trip' | 'kill_switch' | 'escalation' | 'scope_denied' | 'scope_proposed' | 'token_usage';
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BreakerStatus {
+    isTripped: boolean;
+    isKilled: boolean;
+    attempts: number;
+    tripReason: string | null;
+}
+export interface BreakerContext {
+    attempt: number;
+    tokenUsed: number;
+    signal: AbortSignal;
+    log: (entry: {
+        type: AuditEntry['type'];
+        message: string;
+        metadata?: Record<string, unknown>;
+    }) => void;
+    recordTokenUsage: (cost: number) => void;
+    proposeScopeChange: (description: string, newGoals: string[]) => boolean;
+}
+export interface Breaker {
+    run<T>(taskFn: (ctx: BreakerContext) => Promise<T>): Promise<BreakerResult>;
+    trip(reason: string): void;
+    reset(): void;
+    status(): BreakerStatus;
+    log(): AuditEntry[];
+}
+export type AgentRunLedgerCloseStatus = 'completed' | 'failed' | 'blocked' | 'escalated';
+export type AgentRunLedgerValidationStatus = 'passed' | 'failed' | 'skipped';
+export type AgentRunLedgerApprovalDecision = 'approved' | 'rejected' | 'needs_changes';
+export interface AgentRunLedgerMetadata {
+    runId?: string;
+    agent: string;
+    executor: string;
+    repo: string;
+    task?: string;
+    allowedFiles?: string[];
+    startedAt?: string;
+}
+export interface AgentRunLedgerCommandResult {
+    exitCode?: number;
+    summary?: string;
+}
+export interface AgentRunLedgerScopeCheck {
+    ok: boolean;
+    allowed?: string[] | boolean;
+    requiresApproval?: boolean;
+    reasons?: string[];
+    violations?: string[];
+    message?: string;
+    oversightMode?: OversightMode;
+    risk?: PolicyRisk;
+}
+export interface AgentRunLedgerScopeCheckInput {
+    ok?: boolean;
+    allowed?: string[] | boolean;
+    requiresApproval?: boolean;
+    reasons?: string[];
+    violations?: string[];
+    message?: string;
+    oversightMode?: OversightMode;
+    risk?: PolicyRisk;
+}
+export interface AgentRunLedgerApproval {
+    approver: string;
+    decision: AgentRunLedgerApprovalDecision;
+    note?: string;
+}
+export interface AgentRunLedgerValidation {
+    name: string;
+    status: AgentRunLedgerValidationStatus;
+    details?: string;
+}
+export interface AgentRunLedgerCommand {
+    command: string;
+    result?: AgentRunLedgerCommandResult;
+}
+export interface AgentRunLedgerPromptEvent {
+    timestamp: number;
+    type: 'prompt';
+    data: {
+        prompt: string;
+    };
+}
+export interface AgentRunLedgerCommandEvent {
+    timestamp: number;
+    type: 'command';
+    data: {
+        command: string;
+        result?: AgentRunLedgerCommandResult;
+    };
+}
+export interface AgentRunLedgerChangedFilesEvent {
+    timestamp: number;
+    type: 'changed_files';
+    data: {
+        files: string[];
+    };
+}
+export interface AgentRunLedgerValidationEvent {
+    timestamp: number;
+    type: 'validation';
+    data: AgentRunLedgerValidation;
+}
+export interface AgentRunLedgerScopeCheckEvent {
+    timestamp: number;
+    type: 'scope_check';
+    data: AgentRunLedgerScopeCheck;
+}
+export interface AgentRunLedgerApprovalEvent {
+    timestamp: number;
+    type: 'approval';
+    data: AgentRunLedgerApproval;
+}
+export interface AgentRunLedgerCloseEvent {
+    timestamp: number;
+    type: 'close';
+    data: {
+        status: AgentRunLedgerCloseStatus;
+    };
+}
+export type AgentRunLedgerEvent = AgentRunLedgerPromptEvent | AgentRunLedgerCommandEvent | AgentRunLedgerChangedFilesEvent | AgentRunLedgerValidationEvent | AgentRunLedgerScopeCheckEvent | AgentRunLedgerApprovalEvent | AgentRunLedgerCloseEvent;
+export interface AgentRunLedgerJSON {
+    metadata: AgentRunLedgerMetadata;
+    status: AgentRunLedgerCloseStatus | 'open';
+    closedAt: string | null;
+    prompts: string[];
+    commands: AgentRunLedgerCommand[];
+    changedFiles: string[][];
+    validations: AgentRunLedgerValidation[];
+    scopeChecks: AgentRunLedgerScopeCheck[];
+    approvals: AgentRunLedgerApproval[];
+    events: AgentRunLedgerEvent[];
+}
+export interface AgentRunLedger {
+    recordPrompt(prompt: string): void;
+    recordCommand(command: string, result?: AgentRunLedgerCommandResult): void;
+    recordChangedFiles(files: string[]): void;
+    recordValidation(name: string, status: AgentRunLedgerValidationStatus, details?: string): void;
+    recordScopeCheck(result: AgentRunLedgerScopeCheckInput): void;
+    recordApproval(approver: string, decision: AgentRunLedgerApprovalDecision, note?: string): void;
+    close(status: AgentRunLedgerCloseStatus): void;
+    toJSON(): AgentRunLedgerJSON;
+    toMarkdown(): string;
+}
+export type OversightMode = 'HITL' | 'HOTL' | 'HOOTL';
+export type PolicyRisk = 'low' | 'medium' | 'high';
+export interface PolicyGateConfig {
+    oversightMode: OversightMode;
+    allowedFiles?: string[];
+    allowedCommands?: string[];
+    blockedCommands?: string[];
+    requireApprovalFor?: string[];
+    maxRisk?: PolicyRisk;
+}
+export interface PolicyGateRequest {
+    task: string;
+    requestedFiles?: string[];
+    requestedCommands?: string[];
+    risk?: PolicyRisk;
+    hasHumanApproval?: boolean;
+}
+export interface PolicyGateDecision {
+    allowed: boolean;
+    requiresApproval: boolean;
+    reasons: string[];
+    violations: string[];
+    oversightMode: OversightMode;
+    risk: PolicyRisk;
+    message: string;
+}
+export interface PolicyGate {
+    evaluate(request: PolicyGateRequest): PolicyGateDecision;
+}
+export declare const DEFAULTS: {
+    readonly maxRetries: 3;
+    readonly maxRepeatedErrors: 2;
+    readonly tokenBudget: {
+        readonly perStep: number;
+        readonly perTask: number;
+    };
+    readonly scopeFreeze: true;
+};
+export declare const BREAKER_PRESETS: {
+    conservativeCodingAgent: {
+        maxRetries: number;
+        maxRepeatedErrors: number;
+        tokenBudget: {
+            perStep: number;
+            perTask: number;
+        };
+        scopeFreeze: true;
+    };
+    standardCodingAgent: {
+        maxRetries: number;
+        maxRepeatedErrors: number;
+        tokenBudget: {
+            perStep: number;
+            perTask: number;
+        };
+        scopeFreeze: true;
+    };
+    exploratoryResearchAgent: {
+        maxRetries: number;
+        maxRepeatedErrors: number;
+        tokenBudget: {
+            perStep: number;
+            perTask: number;
+        };
+        scopeFreeze: false;
+    };
+};
+export declare function createCodingAgentBreaker(config?: BreakerConfig): Breaker;
+export declare function createPolicyGate(policy: PolicyGateConfig): PolicyGate;
+export declare function createAgentRunLedger(initialMetadata: AgentRunLedgerMetadata): AgentRunLedger;
+export declare function toMarkdownReport(result: BreakerResult): string;
+export declare function createBreaker(config?: BreakerConfig): Breaker;