@almadar/agent 2.0.0 → 2.0.2

package/dist/agent/event-budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event Budget Configuration
+ *
+ * Prevents runaway agent loops with soft/hard event limits per skill.
+ */
+/**
+ * Event budget limits for different skills.
+ * - soft: Warning threshold (agent reminded to finish up)
+ * - hard: Maximum events before forced completion
+ */
+export declare const EVENT_BUDGETS: Record<string, {
+    soft: number;
+    hard: number;
+}>;
+/**
+ * Get event budget for a skill.
+ */
+export declare function getEventBudget(skillName: string): {
+    soft: number;
+    hard: number;
+};
+/**
+ * Generate a budget warning message to inject into the agent.
+ */
+export declare function getBudgetWarningMessage(eventCount: number, budget: {
+    soft: number;
+    hard: number;
+}): string | null;

package/dist/agent/experimental/hitl-v2.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Human-in-the-Loop v2 - Phase 2.3
+ *
+ * Structured interrupts with memory and time-travel debugging.
+ * Interrupt types: confirm, edit, select, text
+ *
+ * @packageDocumentation
+ */
+import type { MemoryManager } from '../../memory/MemoryManager.js';
+export type InterruptType = 'confirm' | 'edit' | 'select' | 'text';
+export interface InterruptRequest<T = unknown> {
+    interruptId: string;
+    sessionId: string;
+    type: InterruptType;
+    title: string;
+    description: string;
+    context: InterruptContext;
+    payload: T;
+    timeoutMs?: number;
+    createdAt: Date;
+}
+export interface InterruptContext {
+    checkpointId: string;
+    currentState: string;
+    previousActions: string[];
+    relevantMemory?: string[];
+}
+export interface InterruptResponse<T = unknown> {
+    interruptId: string;
+    response: T;
+    respondedAt: Date;
+    userId?: string;
+}
+export interface ConfirmPayload {
+    question: string;
+    defaultValue?: boolean;
+    severity: 'info' | 'warning' | 'critical';
+}
+export interface EditPayload {
+    content: string;
+    format: 'json' | 'text' | 'code';
+    schema?: Record<string, unknown>;
+    validationRules?: string[];
+}
+export interface SelectPayload {
+    options: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        disabled?: boolean;
+    }>;
+    multiple?: boolean;
+    maxSelections?: number;
+}
+export interface TextPayload {
+    placeholder?: string;
+    multiline?: boolean;
+    maxLength?: number;
+    validation?: 'email' | 'url' | 'regex';
+    validationRegex?: string;
+}
+export interface HITLv2Options {
+    memoryManager?: MemoryManager;
+    defaultTimeoutMs?: number;
+    onInterrupt?: (request: InterruptRequest) => void;
+    onResponse?: (request: InterruptRequest, response: InterruptResponse) => void;
+}
+export declare class HITLv2Manager {
+    private options;
+    private pendingInterrupts;
+    private responses;
+    private checkpoints;
+    constructor(options?: HITLv2Options);
+    /**
+     * Create a confirmation interrupt
+     */
+    confirm(sessionId: string, question: string, options?: {
+        severity?: 'info' | 'warning' | 'critical';
+        defaultValue?: boolean;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<boolean>;
+    /**
+     * Create an edit interrupt
+     */
+    edit(sessionId: string, content: string, options?: {
+        format?: 'json' | 'text' | 'code';
+        title?: string;
+        description?: string;
+        schema?: Record<string, unknown>;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<string>;
+    /**
+     * Create a selection interrupt
+     */
+    select<T extends string>(sessionId: string, options: Array<{
+        id: T;
+        label: string;
+        description?: string;
+    }>, config?: {
+        title?: string;
+        description?: string;
+        multiple?: boolean;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<T | T[]>;
+    /**
+     * Create a text input interrupt
+     */
+    text(sessionId: string, options?: {
+        title?: string;
+        description?: string;
+        placeholder?: string;
+        multiline?: boolean;
+        maxLength?: number;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<string>;
+    /**
+     * Submit a response to an interrupt
+     */
+    submitResponse<T>(interruptId: string, response: T, userId?: string): Promise<void>;
+    /**
+     * Cancel an interrupt
+     */
+    cancelInterrupt(interruptId: string, reason?: string): void;
+    /**
+     * Save a checkpoint for time-travel
+     */
+    saveCheckpoint(checkpointId: string, state: unknown): void;
+    /**
+     * Restore a checkpoint
+     */
+    restoreCheckpoint<T>(checkpointId: string): T | null;
+    /**
+     * List available checkpoints
+     */
+    listCheckpoints(): string[];
+    /**
+     * Rewind to checkpoint and continue
+     */
+    rewindToCheckpoint<T>(checkpointId: string, sessionId: string, modifyFn?: (state: T) => T): Promise<T | null>;
+    /**
+     * Get interrupt statistics
+     */
+    getStats(): {
+        pendingCount: number;
+        totalHandled: number;
+        checkpointsCount: number;
+        averageResponseTimeMs: number;
+    };
+    /**
+     * Get pending interrupts for a session
+     */
+    getPendingForSession(sessionId: string): InterruptRequest[];
+    private createInterrupt;
+    private waitForResponse;
+    private storeInteraction;
+}
+export declare function createHITLv2Manager(options?: HITLv2Options): HITLv2Manager;

package/dist/agent/experimental/hitl-workflow-integration.d.ts

@@ -0,0 +1,182 @@
+/**
+ * HITL Workflow Integration - Phase 3.4
+ *
+ * Human-in-the-Loop with workflow-based conditional branching.
+ * Enables complex approval flows with human gates.
+ *
+ * @packageDocumentation
+ */
+import { HITLv2Manager } from './hitl-v2.js';
+import type { MemoryManager } from '../../memory/MemoryManager.js';
+/**
+ * Human gate types
+ */
+export type HumanGateType = 'approval' | 'edit' | 'select' | 'custom';
+/**
+ * Human gate configuration
+ */
+export interface HumanGate {
+    /** Gate ID */
+    id: string;
+    /** Gate type */
+    type: HumanGateType;
+    /** Display title */
+    title: string;
+    /** Description */
+    description: string;
+    /** Gate condition - when to show */
+    condition?: (context: unknown) => boolean;
+    /** Timeout in ms */
+    timeoutMs?: number;
+    /** Auto-approve if condition met */
+    autoApprove?: {
+        condition: (context: unknown) => boolean;
+        reason: string;
+    };
+    /** Gate-specific payload */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Human gate result
+ */
+export interface HumanGateResult {
+    gateId: string;
+    approved: boolean;
+    response: unknown;
+    respondedAt: number;
+    userId?: string;
+    autoApproved: boolean;
+}
+/**
+ * Workflow branch definition
+ */
+export interface WorkflowBranch {
+    /** Branch ID */
+    id: string;
+    /** Branch condition */
+    condition: (context: unknown) => boolean;
+    /** Steps to execute */
+    steps: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Human gate before branch */
+    gate?: HumanGate;
+}
+/**
+ * HITL workflow definition
+ */
+export interface HITLWorkflowDefinition {
+    /** Workflow name */
+    name: string;
+    /** Initial steps (before any gates) */
+    initialSteps: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Human gates with conditional branches */
+    gates: HumanGate[];
+    /** Branches based on gate outcomes */
+    branches: WorkflowBranch[];
+    /** Fallback if no branches match */
+    fallbackBranch?: WorkflowBranch;
+}
+/**
+ * HITL workflow result
+ */
+export interface HITLWorkflowResult {
+    success: boolean;
+    output: unknown;
+    gatesPassed: HumanGateResult[];
+    branchesTaken: string[];
+    durationMs: number;
+    wasInterrupted: boolean;
+}
+/**
+ * HITL workflow options
+ */
+export interface HITLWorkflowOptions {
+    /** HITL manager */
+    hitlManager: HITLv2Manager;
+    /** Tool executor */
+    toolExecutor: {
+        execute(tool: string, input: Record<string, unknown>): Promise<unknown>;
+    };
+    /** Memory manager */
+    memoryManager?: MemoryManager;
+    /** Default gate timeout */
+    defaultTimeoutMs?: number;
+    /** Enable auto-approval learning */
+    enableAutoApprove?: boolean;
+}
+export declare class HITLWorkflowEngine {
+    private workflowEngine;
+    private hitlManager;
+    private options;
+    private gateHistory;
+    constructor(options: HITLWorkflowOptions);
+    /**
+     * Execute a workflow with human gates
+     */
+    executeWorkflow(sessionId: string, workflow: HITLWorkflowDefinition, initialContext: Record<string, unknown>): Promise<HITLWorkflowResult>;
+    /**
+     * Execute initial workflow steps
+     */
+    private executeInitialSteps;
+    /**
+     * Execute a human gate
+     */
+    private executeHumanGate;
+    /**
+     * Execute approval gate
+     */
+    private executeApprovalGate;
+    /**
+     * Execute edit gate
+     */
+    private executeEditGate;
+    /**
+     * Execute select gate
+     */
+    private executeSelectGate;
+    /**
+     * Execute custom gate
+     */
+    private executeCustomGate;
+    /**
+     * Execute branch steps
+     */
+    private executeBranchSteps;
+    /**
+     * Wait for interrupt response
+     */
+    private waitForResponse;
+    /**
+     * Interpolate input with context
+     */
+    private interpolateInput;
+    /**
+     * Get value from path
+     */
+    private getValueFromPath;
+    /**
+     * Get gate history for a session
+     */
+    getGateHistory(sessionId: string): HumanGateResult[];
+    /**
+     * Clear gate history
+     */
+    clearGateHistory(sessionId?: string): void;
+}
+/**
+ * Schema generation with human review
+ */
+export declare function createSchemaGenerationHITLWorkflow(complexity: 'simple' | 'medium' | 'complex'): HITLWorkflowDefinition;
+/**
+ * Multi-stage approval workflow
+ */
+export declare function createMultiStageApprovalWorkflow(stages: Array<{
+    name: string;
+    approver: string;
+}>): HITLWorkflowDefinition;
+export declare function createHITLWorkflowEngine(options: HITLWorkflowOptions): HITLWorkflowEngine;

package/dist/agent/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent Module
+ *
+ * Agent factory, session management, event budgets, and interrupt configuration.
+ */
+export { createSkillAgent, resumeSkillAgent, Command, } from './skill-agent.js';
+export type { Skill, SkillLoader, SkillRefLoader, SkillAgentOptions, SkillAgentResult, SkillAgent, } from './skill-agent.js';
+export { SessionManager, } from './session-manager.js';
+export type { SessionMetadata, SessionRecord, PersistenceMode, SessionManagerOptions, } from './session-manager.js';
+export { EVENT_BUDGETS, getEventBudget, getBudgetWarningMessage, } from './event-budget.js';
+export { getInterruptConfig, } from './interrupt-config.js';
+export type { SkillMeta, } from './interrupt-config.js';
+export { createWorkflowToolWrapper, createEvalWorkflowWrapper, } from './workflow-tool-wrapper.js';
+export type { WorkflowToolWrapperOptions, ToolTelemetry, WorkflowToolWrapper, } from './workflow-tool-wrapper.js';