@almadar/agent 2.0.0 → 2.0.2

package/dist/agent/interrupt-config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Interrupt Configuration
+ *
+ * Human-in-the-loop configuration for agent tools.
+ *
+ * Threshold-gated actions (require k-of-n approval):
+ *
+ * | Action                                       | Risk                  | Gate  |
+ * |----------------------------------------------|-----------------------|-------|
+ * | pnpm publish / npm publish                   | Irreversible registry | 2-of-2 |
+ * | git push to main / production deploy         | Live users affected   | 2-of-2 |
+ * | rm -rf / destructive file ops                | Data loss             | 2-of-2 |
+ * | Database migration / persist delete-all      | Production data       | 2-of-2 |
+ * | Read/write .env, secrets, service accounts   | Credential exposure   | 2-of-2 |
+ * | Cross-user data operations                   | Privacy violation     | 2-of-2 |
+ * | Schema deploy to production orbital          | Breaking change risk  | 1-of-2 |
+ *
+ * Routine actions (no gate): compile, validate, read files, npm install.
+ */
+/**
+ * Skill metadata (minimal interface for interrupt config).
+ */
+export interface SkillMeta {
+    name: string;
+    allowedTools?: string[];
+}
+/** Risk level of an agent action. */
+export type ActionGate = 'none' | 'sensitive' | 'critical';
+/**
+ * Maps tool names / command patterns to their required approval gate.
+ * Used by the security layer to decide when ThresholdAuthorizer is needed.
+ */
+export declare const TOOL_GATES: Record<string, ActionGate>;
+/**
+ * Command patterns that classify a shell command as critical.
+ * Matched against the command string before execution.
+ */
+export declare const CRITICAL_COMMAND_PATTERNS: RegExp[];
+/**
+ * Classify a shell command's risk level.
+ * Returns 'critical' if the command matches any CRITICAL_COMMAND_PATTERNS,
+ * 'sensitive' otherwise.
+ */
+export declare function classifyCommand(command: string): ActionGate;
+/**
+ * Get interrupt configuration for a skill.
+ *
+ * Default: require approval for execute tool.
+ * Skills can override via frontmatter (future enhancement).
+ */
+export declare function getInterruptConfig(_skill: SkillMeta): Record<string, boolean>;

package/dist/agent/session-manager.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Session Manager
+ *
+ * Unified session management API with pluggable persistence backends.
+ * Supports in-memory (development) and Firestore (production) backends.
+ */
+import type { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
+import type { SessionMetadata, SessionRecord, PersistenceMode } from '../persistence/types.js';
+import { type FirestoreDb } from '../persistence/firestore-checkpointer.js';
+import type { MemoryManager } from '../memory/index.js';
+import { type ContextCompactionConfig } from '../context-compaction.js';
+export type { SessionMetadata, SessionRecord, PersistenceMode };
+export interface SessionManagerOptions {
+    /**
+     * Persistence mode.
+     * @default 'memory'
+     */
+    mode?: PersistenceMode;
+    /**
+     * Firestore database instance. Required when mode is 'firestore'.
+     */
+    firestoreDb?: FirestoreDb;
+    /**
+     * Memory manager for session-to-memory sync (GAP-002D).
+     * When provided, completed sessions are recorded to orbital memory.
+     */
+    memoryManager?: MemoryManager;
+    /**
+     * Context compaction configuration (GAP-005).
+     * When provided, enables automatic context length management.
+     */
+    compactionConfig?: ContextCompactionConfig;
+}
+/**
+ * Unified session management for agent sessions.
+ *
+ * Handles both session metadata and LangGraph checkpointers.
+ */
+export declare class SessionManager {
+    private mode;
+    private memoryBackend;
+    private memoryCheckpointers;
+    private firestoreCheckpointer;
+    private firestoreSessionStore;
+    private memoryManager;
+    private compactionConfig;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Get the persistence mode.
+     */
+    getMode(): PersistenceMode;
+    /**
+     * Get or create a checkpointer for a session.
+     */
+    getCheckpointer(threadId: string): BaseCheckpointSaver<any>;
+    /**
+     * Store session metadata.
+     */
+    store(threadId: string, metadata: SessionMetadata): void;
+    /**
+     * Get session metadata (sync, memory only).
+     */
+    get(threadId: string): SessionMetadata | undefined;
+    /**
+     * Get session metadata (async, supports Firestore).
+     */
+    getAsync(threadId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Clear a session's checkpointer and metadata.
+     */
+    clear(threadId: string): boolean;
+    /**
+     * List all sessions (sync, memory only).
+     */
+    list(): SessionRecord[];
+    /**
+     * List all sessions (async, supports Firestore).
+     */
+    listAsync(): Promise<SessionRecord[]>;
+    /**
+     * Sync a completed session to orbital memory.
+     * This enables the agent to learn from past sessions.
+     *
+     * @param threadId - The session thread ID
+     * @param userId - The user ID for memory association
+     * @param sessionData - Additional session data to record
+     * @returns Promise that resolves when sync is complete
+     */
+    syncSessionToMemory(threadId: string, userId: string, sessionData: {
+        appId: string;
+        inputDescription: string;
+        generatedOrbital?: string;
+        patternsUsed?: string[];
+        entities?: string[];
+        success: boolean;
+        errorMessage?: string;
+    }): Promise<void>;
+    /**
+     * Record an interrupt decision to memory.
+     * This enables learning from HITL (Human-in-the-Loop) decisions.
+     *
+     * @param sessionId - The session thread ID
+     * @param userId - The user who made the decision
+     * @param interruptData - The interrupt decision data
+     * @returns Promise that resolves when sync is complete
+     */
+    recordInterruptDecision(sessionId: string, userId: string, interruptData: {
+        toolName: string;
+        toolArgs: Record<string, unknown>;
+        decision: 'approved' | 'rejected' | 'modified';
+        modifiedArgs?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get interrupt history for a session.
+     */
+    getSessionInterrupts(sessionId: string): Promise<import('../memory/types.js').InterruptRecord[]>;
+    /**
+     * Check if a tool should be auto-approved for a user.
+     */
+    shouldAutoApproveTool(userId: string, toolName: string): Promise<boolean>;
+    /**
+     * Record a checkpoint to memory for learning.
+     *
+     * @param userId - The user who owns this checkpoint
+     * @param checkpointData - Checkpoint information
+     * @returns Promise that resolves when checkpoint is recorded
+     */
+    recordCheckpoint(userId: string, checkpointData: {
+        checkpointId: string;
+        threadId: string;
+        parentCheckpointId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Record a rollback to a checkpoint.
+     *
+     * @param userId - The user who performed the rollback
+     * @param checkpointId - The checkpoint rolled back to
+     * @param reason - Optional reason for rollback
+     * @returns Promise that resolves when rollback is recorded
+     */
+    recordRollback(userId: string, checkpointId: string, reason?: string): Promise<void>;
+    /**
+     * Mark a checkpoint as successful (terminal state).
+     *
+     * @param userId - The user who owns this checkpoint
+     * @param checkpointId - The checkpoint that was successful
+     * @returns Promise that resolves when success is recorded
+     */
+    markCheckpointSuccessful(userId: string, checkpointId: string): Promise<void>;
+    /**
+     * Get checkpoint history for a thread.
+     *
+     * @param threadId - The thread to get checkpoints for
+     * @returns Array of checkpoint records
+     */
+    getThreadCheckpoints(threadId: string): Promise<import('../memory/types.js').CheckpointRecord[]>;
+    /**
+     * Get frequently rolled-back checkpoints (problem areas).
+     *
+     * @param userId - The user to get problem checkpoints for
+     * @param minRollbackCount - Minimum rollback count (default: 2)
+     * @returns Array of checkpoint records with rollback issues
+     */
+    getProblemCheckpoints(userId: string, minRollbackCount?: number): Promise<import('../memory/types.js').CheckpointRecord[]>;
+    /**
+     * Get the context compaction configuration.
+     * @returns The compaction configuration or null if not configured.
+     */
+    getCompactionConfig(): ContextCompactionConfig | null;
+    /**
+     * Check if a session's messages need compaction based on token count.
+     * Uses character-based estimation for quick checks.
+     *
+     * @param messages - Array of messages to check
+     * @returns True if compaction is recommended
+     */
+    shouldCompactMessages(messages: {
+        content: string | unknown;
+    }[]): boolean;
+    /**
+     * Record a compaction event for a session.
+     * This helps track when and why compaction occurs.
+     *
+     * @param threadId - The session thread ID
+     * @param originalMessageCount - Number of messages before compaction
+     * @param compactedMessageCount - Number of messages after compaction
+     * @param reason - Reason for compaction
+     */
+    recordCompaction(threadId: string, originalMessageCount: number, compactedMessageCount: number, reason?: string): Promise<void>;
+    /**
+     * Get compaction history for a session.
+     *
+     * @param threadId - The session thread ID
+     * @returns Array of compaction events
+     */
+    getCompactionHistory(threadId: string): Array<{
+        timestamp: number;
+        originalMessageCount: number;
+        compactedMessageCount: number;
+        reason: string;
+    }>;
+}

package/dist/agent/skill-agent.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Skill-Based DeepAgent Factory
+ *
+ * Creates DeepAgent instances that use skills as the primary prompt source.
+ * No custom system prompts - all agent behavior is defined through skills.
+ *
+ * Uses deepagents library primitives:
+ * - createDeepAgent() for agent creation
+ * - FilesystemBackend for file operations
+ *
+ * Skill loading is injected via SkillLoader functions, keeping this package
+ * independent of any specific skill registry location.
+ */
+import { Command } from '@langchain/langgraph';
+import { type LLMProvider } from '@almadar/llm';
+import { type SubagentEventCallback, type OrbitalCompleteCallback, type DomainOrbitalCompleteCallback } from '../tools/index.js';
+import { SessionManager } from './session-manager.js';
+import { MemoryManager, type UserPreference, type ProjectContext } from '../memory/index.js';
+export { Command };
+/**
+ * Skill definition loaded by the consumer.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    content: string;
+    allowedTools?: string[];
+    version?: string;
+    references: string[];
+    path?: string;
+}
+/**
+ * Function to load a skill by name.
+ */
+export type SkillLoader = (name: string) => Skill | null;
+/**
+ * Function to load a skill reference by skill name and ref name.
+ */
+export type SkillRefLoader = (skillName: string, refName: string) => string | null;
+/**
+ * Options for creating a skill agent.
+ */
+export interface SkillAgentOptions {
+    /** Required: The skill(s) to use. Can be a single skill or array of skills. */
+    skill: string | string[];
+    /** Required: Working directory for the agent */
+    workDir: string;
+    /** Required: Function to load skills */
+    skillLoader: SkillLoader;
+    /** Optional: Function to load skill references */
+    skillRefLoader?: SkillRefLoader;
+    /** Optional: Thread ID for session continuity */
+    threadId?: string;
+    /** Optional: LLM provider for main agent */
+    provider?: LLMProvider;
+    /** Optional: Model name for main agent */
+    model?: string;
+    /** Optional: LLM provider for subagents (orbital, trait, domain generation). Defaults to 'anthropic' */
+    subagentProvider?: LLMProvider;
+    /** Optional: Model name for subagents. Defaults to 'claude-sonnet-4-20250514' */
+    subagentModel?: string;
+    /** Optional: Enable verbose logging */
+    verbose?: boolean;
+    /** Optional: Disable human-in-the-loop interrupts (for eval/testing) */
+    noInterrupt?: boolean;
+    /** Optional: Callback for subagent events (orbital generation) */
+    onSubagentEvent?: SubagentEventCallback;
+    /** Optional: Session manager instance (shared across requests) */
+    sessionManager?: SessionManager;
+    /** Optional: Extracted requirements from analysis phase (for orbital skill) */
+    requirements?: {
+        entities?: string[];
+        states?: string[];
+        events?: string[];
+        guards?: string[];
+        pages?: string[];
+        effects?: string[];
+        rawRequirements?: string[];
+    };
+    /** Optional: GitHub integration configuration */
+    githubConfig?: {
+        /** GitHub personal access token */
+        token: string;
+        /** Repository owner (e.g., 'octocat') */
+        owner?: string;
+        /** Repository name (e.g., 'hello-world') */
+        repo?: string;
+    };
+    /** Optional: Memory manager for user/project memory (GAP-001) */
+    memoryManager?: MemoryManager;
+    /** Optional: User ID for memory lookup */
+    userId?: string;
+    /** Optional: App ID for project context */
+    appId?: string;
+    /** Optional: Tool wrapper for workflow execution (adds retry, telemetry) */
+    toolWrapper?: <T extends {
+        name: string;
+        invoke: (...args: any[]) => Promise<any>;
+    }>(tool: T) => T;
+    /** Optional: Use orchestrated generation/fixing with complexity-based routing */
+    useOrchestration?: boolean;
+}
+/**
+ * Agent interface with stream method (simplified from DeepAgent)
+ */
+export interface SkillAgent {
+    stream: (input: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+    }, config: {
+        configurable: {
+            thread_id: string;
+        };
+    }) => Promise<AsyncIterable<{
+        events?: Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+        model_request?: {
+            messages?: Array<{
+                kwargs?: {
+                    content?: Array<{
+                        type: string;
+                    }>;
+                };
+            }>;
+        };
+    }>>;
+}
+/**
+ * Result from creating a skill agent.
+ */
+export interface SkillAgentResult {
+    /** The agent instance (from deepagents library) */
+    agent: SkillAgent;
+    /** Thread ID for session resumption */
+    threadId: string;
+    /** The loaded skill(s) - primary skill when single, all skills when multiple */
+    skill: Skill;
+    /** All loaded skills (same as skill when single) */
+    skills: Skill[];
+    /** Working directory */
+    workDir: string;
+    /** Orbital tool setter for wiring SSE callback (if orbital tool enabled) */
+    setOrbitalEventCallback?: (callback: SubagentEventCallback) => void;
+    /** Orbital tool setter for wiring persistence callback */
+    setOrbitalCompleteCallback?: (callback: OrbitalCompleteCallback) => void;
+    /** Domain orbital callback for lean skill Firestore persistence */
+    setDomainCompleteCallback?: (callback: DomainOrbitalCompleteCallback) => void;
+    /** User preferences loaded from memory (GAP-001) */
+    userPreferences?: UserPreference | null;
+    /** Project context loaded from memory (GAP-001) */
+    projectContext?: ProjectContext | null;
+    /** Memory manager instance (GAP-001) */
+    memoryManager?: MemoryManager;
+}
+/**
+ * Create a skill-based DeepAgent.
+ *
+ * Uses the specified skill's content as the system prompt.
+ * When multiple skills are provided, the agent sees all skill descriptions
+ * and can choose the appropriate one based on the user's request.
+ *
+ * @throws Error if any skill is not found
+ */
+export declare function createSkillAgent(options: SkillAgentOptions): Promise<SkillAgentResult>;
+/**
+ * Resume a skill agent session.
+ *
+ * Loads the skill from session metadata and creates agent with same threadId.
+ *
+ * @throws Error if session not found
+ */
+export declare function resumeSkillAgent(threadId: string, options: {
+    verbose?: boolean;
+    noInterrupt?: boolean;
+    skillLoader: SkillLoader;
+    skillRefLoader?: SkillRefLoader;
+    sessionManager?: SessionManager;
+}): Promise<SkillAgentResult>;

package/dist/agent/workflow-middleware.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Workflow Middleware for DeepAgent
+ *
+ * Wraps tool execution with workflow engine capabilities:
+ * - Retry on failure
+ * - Parallel execution of independent tools
+ * - Per-tool telemetry
+ *
+ * Usage:
+ * ```typescript
+ * const agent = createDeepAgent({
+ *   skill: 'kflow-orbitals',
+ *   middleware: [createWorkflowMiddleware({ maxRetries: 3, enableParallel: true })],
+ * });
+ * ```
+ */
+/** Local middleware interface matching DeepAgent's middleware shape */
+interface AgentMiddleware {
+    name: string;
+    beforeModel?: (state: Record<string, unknown>) => Promise<{
+        state: Record<string, unknown>;
+    }>;
+    afterModel?: (state: Record<string, unknown>, response: Record<string, unknown>) => Promise<{
+        state: Record<string, unknown>;
+        response: Record<string, unknown>;
+    }>;
+    wrapTool?: (tool: {
+        name: string;
+        invoke: (...args: unknown[]) => Promise<unknown>;
+    }) => {
+        name: string;
+        invoke: (...args: unknown[]) => Promise<unknown>;
+    };
+}
+export interface WorkflowMiddlewareOptions {
+    /** Max retry attempts per tool */
+    maxRetries?: number;
+    /** Enable parallel execution of independent tools */
+    enableParallel?: boolean;
+    /** Collect telemetry */
+    enableTelemetry?: boolean;
+    /** Max execution time per tool (ms) */
+    timeoutMs?: number;
+}
+export interface ToolTelemetry {
+    toolName: string;
+    durationMs: number;
+    retries: number;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Create workflow middleware for DeepAgent
+ *
+ * This middleware intercepts tool calls and executes them through
+ * the WorkflowEngine for retry, parallel execution, and telemetry.
+ */
+export declare function createWorkflowMiddleware(options?: WorkflowMiddlewareOptions): AgentMiddleware;
+/**
+ * Get telemetry from workflow middleware
+ */
+export declare function getWorkflowTelemetry(_middleware: AgentMiddleware): ToolTelemetry[];
+export {};

package/dist/agent/workflow-tool-wrapper.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Workflow Tool Wrapper
+ *
+ * Wraps tool execution with workflow capabilities:
+ * - Retry on failure with exponential backoff
+ * - Per-tool telemetry (duration, retries, success/failure)
+ * - Timeout handling
+ *
+ * Usage:
+ * ```typescript
+ * const wrapper = createWorkflowToolWrapper({ maxRetries: 3 });
+ *
+ * const { agent } = await createSkillAgent({
+ *   skill: 'kflow-orbitals',
+ *   toolWrapper: wrapper.wrap,
+ * });
+ *
+ * // After execution
+ * const telemetry = wrapper.getTelemetry();
+ * ```
+ */
+export interface WorkflowToolWrapperOptions {
+    /** Max retry attempts per tool (default: 3) */
+    maxRetries?: number;
+    /** Enable telemetry collection (default: true) */
+    enableTelemetry?: boolean;
+    /** Max execution time per tool in ms (default: 60000) */
+    timeoutMs?: number;
+    /** Initial backoff in ms (default: 1000) */
+    backoffMs?: number;
+}
+export interface ToolTelemetry {
+    toolName: string;
+    durationMs: number;
+    retries: number;
+    success: boolean;
+    error?: string;
+}
+export interface WorkflowToolWrapper {
+    /** Wrap a tool with retry/telemetry */
+    wrap<T extends {
+        name: string;
+        invoke: (...args: any[]) => Promise<any>;
+    }>(tool: T): T;
+    /** Get collected telemetry */
+    getTelemetry(): ToolTelemetry[];
+    /** Reset telemetry */
+    resetTelemetry(): void;
+}
+/**
+ * Create a workflow tool wrapper
+ *
+ * @param options - Wrapper configuration
+ * @returns Wrapper with wrap() and getTelemetry() methods
+ *
+ * @example
+ * ```typescript
+ * const workflow = createWorkflowToolWrapper({ maxRetries: 3 });
+ *
+ * const { agent } = await createSkillAgent({
+ *   skill: 'kflow-orbitals',
+ *   toolWrapper: workflow.wrap,
+ * });
+ *
+ * // Run agent...
+ *
+ * // Get results
+ * console.log(workflow.getTelemetry());
+ * // [{ toolName: 'generate_orbital', durationMs: 5000, retries: 1, success: true }]
+ * ```
+ */
+export declare function createWorkflowToolWrapper(options?: WorkflowToolWrapperOptions): WorkflowToolWrapper;
+/**
+ * Create a workflow wrapper specifically for evaluation comparison
+ *
+ * This wrapper logs telemetry to console for debugging
+ */
+export declare function createEvalWorkflowWrapper(options?: WorkflowToolWrapperOptions): {
+    wrap: <T extends {
+        name: string;
+        invoke: (...args: any[]) => Promise<any>;
+    }>(tool: T) => T;
+    /** Get collected telemetry */
+    getTelemetry(): ToolTelemetry[];
+    /** Reset telemetry */
+    resetTelemetry(): void;
+};