@framers/agentos 0.1.0

package/dist/core/hitl/IHumanInteractionManager.d.ts

@@ -0,0 +1,521 @@
+/**
+ * @file IHumanInteractionManager.ts
+ * @description Interface for Human-in-the-Loop (HITL) interactions in AgentOS.
+ * Enables agents to request human approval, input, and collaboration at key decision points.
+ *
+ * HITL is critical for:
+ * - High-stakes decisions requiring human judgment
+ * - Ambiguous situations needing clarification
+ * - Quality assurance and output review
+ * - Learning from human corrections
+ *
+ * @module AgentOS/HITL
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const hitlManager = new HumanInteractionManager(config);
+ *
+ * // Request approval before critical action
+ * const approval = await hitlManager.requestApproval({
+ *   actionId: 'delete-all-records',
+ *   description: 'Delete all customer records from database',
+ *   severity: 'critical',
+ *   context: { recordCount: 50000 },
+ * });
+ *
+ * if (approval.approved) {
+ *   await executeAction();
+ * }
+ * ```
+ */
+/**
+ * Severity levels for actions requiring approval.
+ */
+export type ActionSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * A pending action awaiting human approval.
+ */
+export interface PendingAction {
+    /** Unique action identifier */
+    actionId: string;
+    /** Human-readable description of the action */
+    description: string;
+    /** Action severity/risk level */
+    severity: ActionSeverity;
+    /** Category of action */
+    category?: 'data_modification' | 'external_api' | 'financial' | 'communication' | 'system' | 'other';
+    /** Agent requesting approval */
+    agentId: string;
+    /** Context/parameters of the action */
+    context: Record<string, unknown>;
+    /** Potential consequences if approved */
+    potentialConsequences?: string[];
+    /** Reversibility of the action */
+    reversible: boolean;
+    /** Estimated cost (if applicable) */
+    estimatedCost?: {
+        amount: number;
+        currency: string;
+    };
+    /** Timestamp when request was made */
+    requestedAt: Date;
+    /** Timeout for approval (ms) */
+    timeoutMs?: number;
+    /** Alternative actions available */
+    alternatives?: AlternativeAction[];
+}
+/**
+ * An alternative action that could be taken.
+ */
+export interface AlternativeAction {
+    /** Alternative identifier */
+    alternativeId: string;
+    /** Description of alternative */
+    description: string;
+    /** Trade-offs of this alternative */
+    tradeoffs?: string;
+}
+/**
+ * Human's decision on a pending action.
+ */
+export interface ApprovalDecision {
+    /** Original action ID */
+    actionId: string;
+    /** Whether approved */
+    approved: boolean;
+    /** If rejected, the reason */
+    rejectionReason?: string;
+    /** If alternative selected, which one */
+    selectedAlternativeId?: string;
+    /** Human's additional instructions */
+    instructions?: string;
+    /** Who made the decision */
+    decidedBy: string;
+    /** Timestamp of decision */
+    decidedAt: Date;
+    /** Feedback for agent learning */
+    feedback?: string;
+}
+/**
+ * A request for clarification from a human.
+ */
+export interface ClarificationRequest {
+    /** Unique request identifier */
+    requestId: string;
+    /** The question needing clarification */
+    question: string;
+    /** Context for the question */
+    context: string;
+    /** Agent requesting clarification */
+    agentId: string;
+    /** Type of clarification needed */
+    clarificationType: 'ambiguity' | 'missing_info' | 'preference' | 'verification' | 'guidance';
+    /** Suggested options (if multiple choice) */
+    options?: ClarificationOption[];
+    /** Whether free-form response is allowed */
+    allowFreeform: boolean;
+    /** Timestamp */
+    requestedAt: Date;
+    /** Timeout (ms) */
+    timeoutMs?: number;
+}
+/**
+ * An option for clarification.
+ */
+export interface ClarificationOption {
+    /** Option identifier */
+    optionId: string;
+    /** Option label */
+    label: string;
+    /** Option description */
+    description?: string;
+}
+/**
+ * Human's response to a clarification request.
+ */
+export interface ClarificationResponse {
+    /** Original request ID */
+    requestId: string;
+    /** Selected option ID (if applicable) */
+    selectedOptionId?: string;
+    /** Free-form response */
+    freeformResponse?: string;
+    /** Who responded */
+    respondedBy: string;
+    /** Timestamp */
+    respondedAt: Date;
+}
+/**
+ * Draft output for human review/editing.
+ */
+export interface DraftOutput {
+    /** Draft identifier */
+    draftId: string;
+    /** Type of content */
+    contentType: 'text' | 'code' | 'json' | 'markdown' | 'html';
+    /** The draft content */
+    content: string;
+    /** Agent that generated it */
+    agentId: string;
+    /** Purpose/context of the output */
+    purpose: string;
+    /** Specific areas to review */
+    reviewFocus?: string[];
+    /** Agent's confidence in the output */
+    confidence: number;
+    /** Timestamp */
+    generatedAt: Date;
+    /** Timeout (ms) */
+    timeoutMs?: number;
+}
+/**
+ * Human's edited version of draft output.
+ */
+export interface EditedOutput {
+    /** Original draft ID */
+    draftId: string;
+    /** Edited content */
+    editedContent: string;
+    /** Whether significant changes were made */
+    hasSignificantChanges: boolean;
+    /** Summary of changes */
+    changeSummary?: string;
+    /** Who edited */
+    editedBy: string;
+    /** Timestamp */
+    editedAt: Date;
+    /** Feedback for agent improvement */
+    feedback?: string;
+}
+/**
+ * Context for escalating to human control.
+ */
+export interface EscalationContext {
+    /** Escalation identifier */
+    escalationId: string;
+    /** Reason for escalation */
+    reason: EscalationReason;
+    /** Detailed explanation */
+    explanation: string;
+    /** Agent requesting escalation */
+    agentId: string;
+    /** Current task/goal state */
+    currentState: Record<string, unknown>;
+    /** What agent has tried so far */
+    attemptedActions: string[];
+    /** Agent's assessment of the situation */
+    assessment: string;
+    /** Recommended human actions */
+    recommendations?: string[];
+    /** Urgency level */
+    urgency: 'low' | 'medium' | 'high' | 'critical';
+    /** Timestamp */
+    escalatedAt: Date;
+}
+/**
+ * Reasons for escalation.
+ */
+export type EscalationReason = 'low_confidence' | 'repeated_failures' | 'ethical_concern' | 'out_of_scope' | 'resource_limit' | 'conflicting_instructions' | 'safety_concern' | 'user_requested' | 'policy_violation' | 'unknown_territory';
+/**
+ * Human response to escalation.
+ */
+export type EscalationDecision = {
+    type: 'human_takeover';
+    instructions?: string;
+} | {
+    type: 'agent_continue';
+    guidance: string;
+    adjustedParameters?: Record<string, unknown>;
+} | {
+    type: 'abort';
+    reason: string;
+} | {
+    type: 'delegate';
+    targetAgentId: string;
+    instructions: string;
+};
+/**
+ * Workflow state for checkpoint review.
+ */
+export interface WorkflowCheckpoint {
+    /** Checkpoint identifier */
+    checkpointId: string;
+    /** Workflow/plan identifier */
+    workflowId: string;
+    /** Current step/phase */
+    currentPhase: string;
+    /** Progress (0-1) */
+    progress: number;
+    /** Summary of work completed */
+    completedWork: string[];
+    /** Upcoming work */
+    upcomingWork: string[];
+    /** Any issues or concerns */
+    issues: string[];
+    /** Agent's notes */
+    notes?: string;
+    /** Timestamp */
+    checkpointAt: Date;
+}
+/**
+ * Human's decision at a checkpoint.
+ */
+export interface CheckpointDecision {
+    /** Checkpoint ID */
+    checkpointId: string;
+    /** Decision */
+    decision: 'continue' | 'pause' | 'modify' | 'abort';
+    /** Modifications if any */
+    modifications?: {
+        adjustedGoal?: string;
+        skipSteps?: string[];
+        addSteps?: string[];
+        parameterChanges?: Record<string, unknown>;
+    };
+    /** Instructions for agent */
+    instructions?: string;
+    /** Who decided */
+    decidedBy: string;
+    /** Timestamp */
+    decidedAt: Date;
+}
+/**
+ * Human feedback on agent performance.
+ */
+export interface HumanFeedback {
+    /** Feedback identifier */
+    feedbackId: string;
+    /** Agent receiving feedback */
+    agentId: string;
+    /** Type of feedback */
+    feedbackType: 'correction' | 'praise' | 'guidance' | 'preference' | 'complaint';
+    /** Specific aspect being addressed */
+    aspect: 'accuracy' | 'style' | 'speed' | 'judgment' | 'communication' | 'other';
+    /** Detailed feedback */
+    content: string;
+    /** Severity/importance (1-5) */
+    importance: number;
+    /** Context of the feedback */
+    context?: Record<string, unknown>;
+    /** Who provided feedback */
+    providedBy: string;
+    /** Timestamp */
+    providedAt: Date;
+}
+/**
+ * Statistics about HITL interactions.
+ */
+export interface HITLStatistics {
+    /** Total approval requests */
+    totalApprovalRequests: number;
+    /** Approval rate */
+    approvalRate: number;
+    /** Total clarifications requested */
+    totalClarifications: number;
+    /** Average response time (ms) */
+    avgResponseTimeMs: number;
+    /** Total escalations */
+    totalEscalations: number;
+    /** Escalations by reason */
+    escalationsByReason: Record<EscalationReason, number>;
+    /** Pending requests */
+    pendingRequests: number;
+    /** Timed out requests */
+    timedOutRequests: number;
+}
+/**
+ * Interface for the AgentOS Human-in-the-Loop Manager.
+ *
+ * The HITL Manager enables structured collaboration between AI agents
+ * and human operators, ensuring human oversight for critical decisions
+ * while maintaining efficient autonomous operation.
+ *
+ * Key capabilities:
+ * - **Approval Requests**: Seek human approval for high-risk actions
+ * - **Clarification**: Ask humans to resolve ambiguity
+ * - **Output Review**: Have humans review and edit agent outputs
+ * - **Escalation**: Transfer control when agents are uncertain
+ * - **Checkpoints**: Regular human review of ongoing work
+ * - **Feedback Loop**: Learn from human corrections
+ *
+ * @example
+ * ```typescript
+ * const hitl = new HumanInteractionManager({
+ *   notificationHandler: async (req) => {
+ *     // Send to UI/Slack/email
+ *     await notifyHuman(req);
+ *   },
+ *   defaultTimeoutMs: 300000, // 5 minutes
+ * });
+ *
+ * // Register response handler
+ * hitl.onApprovalResponse((decision) => {
+ *   console.log(`Action ${decision.actionId}: ${decision.approved ? 'Approved' : 'Rejected'}`);
+ * });
+ *
+ * // Request approval
+ * const decision = await hitl.requestApproval({
+ *   actionId: 'send-mass-email',
+ *   description: 'Send promotional email to 10,000 subscribers',
+ *   severity: 'high',
+ *   context: { recipientCount: 10000, template: 'promo-q4' },
+ *   reversible: false,
+ * });
+ * ```
+ */
+export interface IHumanInteractionManager {
+    /**
+     * Requests human approval before executing an action.
+     *
+     * @param action - The action requiring approval
+     * @returns Human's approval decision
+     *
+     * @example
+     * ```typescript
+     * const decision = await hitl.requestApproval({
+     *   actionId: 'delete-records',
+     *   description: 'Delete inactive user accounts older than 2 years',
+     *   severity: 'high',
+     *   category: 'data_modification',
+     *   agentId: 'cleanup-agent',
+     *   context: { accountCount: 5000, criteria: 'inactive > 2y' },
+     *   reversible: false,
+     *   potentialConsequences: ['Data loss', 'User complaints'],
+     * });
+     * ```
+     */
+    requestApproval(action: PendingAction): Promise<ApprovalDecision>;
+    /**
+     * Submits an approval decision (typically called by UI/webhook handler).
+     *
+     * @param decision - The approval decision
+     */
+    submitApprovalDecision(decision: ApprovalDecision): Promise<void>;
+    /**
+     * Requests clarification from a human for ambiguous situations.
+     *
+     * @param request - The clarification request
+     * @returns Human's clarification response
+     */
+    requestClarification(request: ClarificationRequest): Promise<ClarificationResponse>;
+    /**
+     * Submits a clarification response.
+     *
+     * @param response - The clarification response
+     */
+    submitClarification(response: ClarificationResponse): Promise<void>;
+    /**
+     * Requests human review and potential editing of agent output.
+     *
+     * @param draft - The draft output to review
+     * @returns Edited output (may be unchanged)
+     */
+    requestEdit(draft: DraftOutput): Promise<EditedOutput>;
+    /**
+     * Submits an edited output.
+     *
+     * @param edited - The edited output
+     */
+    submitEdit(edited: EditedOutput): Promise<void>;
+    /**
+     * Escalates a situation to human control.
+     *
+     * @param context - Escalation context
+     * @returns Human's decision on how to proceed
+     */
+    escalate(context: EscalationContext): Promise<EscalationDecision>;
+    /**
+     * Submits an escalation decision.
+     *
+     * @param escalationId - The escalation identifier
+     * @param decision - The human's decision
+     */
+    submitEscalationDecision(escalationId: string, decision: EscalationDecision): Promise<void>;
+    /**
+     * Creates a checkpoint for human review during long-running tasks.
+     *
+     * @param checkpoint - The checkpoint state
+     * @returns Human's checkpoint decision
+     */
+    checkpoint(checkpoint: WorkflowCheckpoint): Promise<CheckpointDecision>;
+    /**
+     * Submits a checkpoint decision.
+     *
+     * @param decision - The checkpoint decision
+     */
+    submitCheckpointDecision(decision: CheckpointDecision): Promise<void>;
+    /**
+     * Records human feedback for agent improvement.
+     *
+     * @param feedback - The feedback to record
+     */
+    recordFeedback(feedback: HumanFeedback): Promise<void>;
+    /**
+     * Gets feedback history for an agent.
+     *
+     * @param agentId - Agent identifier
+     * @param options - Query options
+     * @returns Feedback history
+     */
+    getFeedbackHistory(agentId: string, options?: {
+        limit?: number;
+        since?: Date;
+        type?: HumanFeedback['feedbackType'];
+    }): Promise<HumanFeedback[]>;
+    /**
+     * Gets all pending requests awaiting human response.
+     *
+     * @returns Pending requests by type
+     */
+    getPendingRequests(): Promise<{
+        approvals: PendingAction[];
+        clarifications: ClarificationRequest[];
+        edits: DraftOutput[];
+        escalations: EscalationContext[];
+        checkpoints: WorkflowCheckpoint[];
+    }>;
+    /**
+     * Cancels a pending request.
+     *
+     * @param requestId - Request identifier
+     * @param reason - Cancellation reason
+     */
+    cancelRequest(requestId: string, reason: string): Promise<void>;
+    /**
+     * Gets HITL interaction statistics.
+     *
+     * @returns Current statistics
+     */
+    getStatistics(): HITLStatistics;
+    /**
+     * Sets the notification handler for outgoing requests.
+     *
+     * @param handler - Handler function
+     */
+    setNotificationHandler(handler: HITLNotificationHandler): void;
+}
+/**
+ * Handler for sending notifications to humans.
+ */
+export type HITLNotificationHandler = (notification: HITLNotification) => Promise<void>;
+/**
+ * A notification sent to humans.
+ */
+export interface HITLNotification {
+    /** Notification type */
+    type: 'approval_required' | 'clarification_needed' | 'edit_requested' | 'escalation' | 'checkpoint';
+    /** Request ID */
+    requestId: string;
+    /** Agent ID */
+    agentId: string;
+    /** Summary */
+    summary: string;
+    /** Urgency */
+    urgency: 'low' | 'medium' | 'high' | 'critical';
+    /** Expiration time */
+    expiresAt?: Date;
+    /** Deep link to handle the request */
+    actionUrl?: string;
+}
+//# sourceMappingURL=IHumanInteractionManager.d.ts.map

package/dist/core/hitl/IHumanInteractionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IHumanInteractionManager.d.ts","sourceRoot":"","sources":["../../../src/core/hitl/IHumanInteractionManager.ts"],"names":[],"mappings":"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"}

package/dist/core/hitl/IHumanInteractionManager.js

@@ -0,0 +1,33 @@
+/**
+ * @file IHumanInteractionManager.ts
+ * @description Interface for Human-in-the-Loop (HITL) interactions in AgentOS.
+ * Enables agents to request human approval, input, and collaboration at key decision points.
+ *
+ * HITL is critical for:
+ * - High-stakes decisions requiring human judgment
+ * - Ambiguous situations needing clarification
+ * - Quality assurance and output review
+ * - Learning from human corrections
+ *
+ * @module AgentOS/HITL
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const hitlManager = new HumanInteractionManager(config);
+ *
+ * // Request approval before critical action
+ * const approval = await hitlManager.requestApproval({
+ *   actionId: 'delete-all-records',
+ *   description: 'Delete all customer records from database',
+ *   severity: 'critical',
+ *   context: { recordCount: 50000 },
+ * });
+ *
+ * if (approval.approved) {
+ *   await executeAction();
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=IHumanInteractionManager.js.map

package/dist/core/hitl/IHumanInteractionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IHumanInteractionManager.js","sourceRoot":"","sources":["../../../src/core/hitl/IHumanInteractionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/core/hitl/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file HITL Module Index
+ * @description Human-in-the-Loop (HITL) module exports for AgentOS.
+ *
+ * The HITL module enables structured collaboration between AI agents
+ * and human operators for:
+ * - Approval of high-risk actions
+ * - Clarification of ambiguous situations
+ * - Review and editing of outputs
+ * - Escalation handling
+ * - Workflow checkpoints
+ *
+ * @module AgentOS/HITL
+ */
+export type { IHumanInteractionManager, PendingAction, ApprovalDecision, ActionSeverity, AlternativeAction, ClarificationRequest, ClarificationResponse, ClarificationOption, DraftOutput, EditedOutput, EscalationContext, EscalationDecision, EscalationReason, WorkflowCheckpoint, CheckpointDecision, HumanFeedback, HITLStatistics, HITLNotificationHandler, HITLNotification, } from './IHumanInteractionManager';
+export { HumanInteractionManager, type HumanInteractionManagerConfig, } from './HumanInteractionManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/hitl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/hitl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,YAAY,EACV,wBAAwB,EACxB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,uBAAuB,EACvB,KAAK,6BAA6B,GACnC,MAAM,2BAA2B,CAAC"}

package/dist/core/hitl/index.js

@@ -0,0 +1,17 @@
+/**
+ * @file HITL Module Index
+ * @description Human-in-the-Loop (HITL) module exports for AgentOS.
+ *
+ * The HITL module enables structured collaboration between AI agents
+ * and human operators for:
+ * - Approval of high-risk actions
+ * - Clarification of ambiguous situations
+ * - Review and editing of outputs
+ * - Escalation handling
+ * - Workflow checkpoints
+ *
+ * @module AgentOS/HITL
+ */
+// Implementation
+export { HumanInteractionManager, } from './HumanInteractionManager.js';
+//# sourceMappingURL=index.js.map

package/dist/core/hitl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/hitl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyBH,iBAAiB;AACjB,OAAO,EACL,uBAAuB,GAExB,MAAM,2BAA2B,CAAC"}