@almadar/agent 2.0.0 → 2.0.2

package/dist/persistence/firestore-checkpointer.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Firestore Checkpointer for LangGraph
+ *
+ * Custom implementation of BaseCheckpointSaver using Firebase Firestore.
+ * This is required because LangGraph only provides Postgres/Redis savers.
+ *
+ * IMPORTANT: This module does NOT import firebase-admin directly.
+ * The Firestore `db` instance must be injected via constructor options.
+ * This keeps the @almadar/agent package free of firebase-admin as a direct dependency.
+ */
+import { BaseCheckpointSaver, type Checkpoint, type CheckpointTuple, type CheckpointMetadata, type CheckpointListOptions, type PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { RunnableConfig } from '@langchain/core/runnables';
+/**
+ * Minimal Firestore interface to avoid importing firebase-admin.
+ * Consumers pass their own Firestore instance.
+ */
+export interface FirestoreDb {
+    collection(path: string): FirestoreCollectionRef;
+    batch(): FirestoreBatch;
+}
+export interface FirestoreCollectionRef {
+    doc(id: string): FirestoreDocRef;
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+}
+export interface FirestoreDocRef {
+    set(data: unknown): Promise<unknown>;
+    get(): Promise<FirestoreDocSnapshot>;
+    update(data: unknown): Promise<unknown>;
+    delete(): Promise<unknown>;
+    readonly ref: unknown;
+}
+export interface FirestoreDocSnapshot {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+    readonly ref: unknown;
+}
+export interface FirestoreQuery {
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+    startAfter(doc: unknown): FirestoreQuery;
+    get(): Promise<FirestoreQuerySnapshot>;
+}
+export interface FirestoreQuerySnapshot {
+    empty: boolean;
+    docs: FirestoreQueryDocSnapshot[];
+    size: number;
+}
+export interface FirestoreQueryDocSnapshot {
+    data(): Record<string, unknown>;
+    readonly ref: unknown;
+}
+export interface FirestoreBatch {
+    set(ref: unknown, data: unknown): void;
+    delete(ref: unknown): void;
+    commit(): Promise<unknown>;
+}
+/**
+ * Firestore Timestamp-like interface.
+ */
+export interface FirestoreTimestamp {
+    toDate(): Date;
+}
+/**
+ * Options for FirestoreCheckpointer.
+ */
+export interface FirestoreCheckpointerOptions {
+    /**
+     * Firestore instance. Required — injected by consumer.
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for checkpoints.
+     * @default 'agent_checkpoints'
+     */
+    checkpointsCollection?: string;
+    /**
+     * Collection name for pending writes.
+     * @default 'agent_writes'
+     */
+    writesCollection?: string;
+}
+/**
+ * Firestore-backed checkpointer for LangGraph agents.
+ *
+ * Provides persistent checkpoint storage across server restarts.
+ * Thread checkpoints are stored as Firestore documents.
+ *
+ * @example
+ * ```typescript
+ * import { getFirestore } from 'firebase-admin/firestore';
+ *
+ * const checkpointer = new FirestoreCheckpointer({
+ *   db: getFirestore(),
+ *   checkpointsCollection: 'agent_checkpoints',
+ * });
+ *
+ * const agent = createDeepAgent({
+ *   // ...
+ *   checkpointer,
+ * });
+ * ```
+ */
+export declare class FirestoreCheckpointer extends BaseCheckpointSaver {
+    private db;
+    private checkpointsCollection;
+    private writesCollection;
+    constructor(options: FirestoreCheckpointerOptions);
+    /**
+     * Get thread ID from config.
+     */
+    private getThreadId;
+    /**
+     * Get checkpoint ID from config, or undefined for latest.
+     */
+    private getCheckpointId;
+    /**
+     * Get checkpoint by config.
+     */
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * List checkpoints for a thread.
+     */
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    /**
+     * Save a checkpoint.
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: Record<string, number | string>): Promise<RunnableConfig>;
+    /**
+     * Store pending writes for a checkpoint.
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    /**
+     * Delete all checkpoints and writes for a thread.
+     */
+    deleteThread(threadId: string): Promise<void>;
+}

package/dist/persistence/firestore-session-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Firestore Session Store for DeepAgent
+ *
+ * Provides persistent session storage for skill-based agents.
+ * Sessions are stored in Firestore and persist across server restarts.
+ *
+ * IMPORTANT: This module does NOT import firebase-admin directly.
+ * The Firestore `db` instance must be injected via constructor options.
+ */
+import type { Session } from './types.js';
+import type { FirestoreDb } from './firestore-checkpointer.js';
+/**
+ * Options for FirestoreSessionStore.
+ */
+export interface FirestoreSessionStoreOptions {
+    /**
+     * Firestore instance. Required — injected by consumer.
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for sessions.
+     * @default 'agent_sessions'
+     */
+    collection?: string;
+}
+/**
+ * Firestore-backed session store for skill agents.
+ *
+ * @example
+ * ```typescript
+ * const sessionStore = new FirestoreSessionStore({ db: getFirestore() });
+ *
+ * await sessionStore.save({
+ *   threadId: 'abc-123',
+ *   skill: 'kflow-generating-m',
+ *   workDir: '/tmp/workspace',
+ *   createdAt: new Date(),
+ *   lastActivityAt: new Date(),
+ * });
+ *
+ * const session = await sessionStore.get('abc-123');
+ * ```
+ */
+export declare class FirestoreSessionStore {
+    private db;
+    private collection;
+    constructor(options: FirestoreSessionStoreOptions);
+    /**
+     * Save a session.
+     */
+    save(session: Session): Promise<void>;
+    /**
+     * Get a session by thread ID.
+     */
+    get(threadId: string): Promise<Session | null>;
+    /**
+     * Update session's last activity timestamp.
+     */
+    touch(threadId: string): Promise<void>;
+    /**
+     * Delete a session.
+     */
+    delete(threadId: string): Promise<void>;
+    /**
+     * List sessions, optionally filtered by user ID.
+     */
+    list(options?: {
+        userId?: string;
+        limit?: number;
+    }): Promise<Session[]>;
+    /**
+     * Delete expired sessions (older than specified hours).
+     */
+    deleteExpired(maxAgeHours?: number): Promise<number>;
+}

package/dist/persistence/firestore-store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Firestore Store for LangGraph
+ *
+ * Custom implementation of BaseStore using Firebase Firestore.
+ * This provides persistent key-value storage for agent memories.
+ *
+ * IMPORTANT: This module does NOT import firebase-admin directly.
+ * The Firestore `db` instance must be injected via constructor options.
+ */
+import { BaseStore, type Operation, type OperationResults } from '@langchain/langgraph-checkpoint';
+import type { FirestoreDb } from './firestore-checkpointer.js';
+/**
+ * Options for FirestoreStore.
+ */
+export interface FirestoreStoreOptions {
+    /**
+     * Firestore instance. Required — injected by consumer.
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for store items.
+     * @default 'agent_memories'
+     */
+    collection?: string;
+}
+/**
+ * Firestore-backed store for LangGraph agent memories.
+ *
+ * Provides persistent key-value storage that can be shared across threads.
+ * Items are organized by hierarchical namespaces.
+ *
+ * @example
+ * ```typescript
+ * import { getFirestore } from 'firebase-admin/firestore';
+ *
+ * const store = new FirestoreStore({
+ *   db: getFirestore(),
+ *   collection: 'agent_memories',
+ * });
+ *
+ * // Store a memory
+ * await store.put(['agent', 'patterns'], 'schema-best-practices', {
+ *   content: 'Always validate schemas before saving',
+ * });
+ *
+ * // Retrieve a memory
+ * const item = await store.get(['agent', 'patterns'], 'schema-best-practices');
+ * ```
+ */
+export declare class FirestoreStore extends BaseStore {
+    private db;
+    private collection;
+    constructor(options: FirestoreStoreOptions);
+    /**
+     * Create document ID from namespace and key.
+     */
+    private makeDocId;
+    /**
+     * Create namespace key for querying.
+     */
+    private makeNamespaceKey;
+    /**
+     * Execute multiple operations in a batch.
+     */
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    /**
+     * Get an item by namespace and key.
+     */
+    private getItem;
+    /**
+     * Put an item.
+     */
+    private putItem;
+    /**
+     * Delete an item.
+     */
+    private deleteItem;
+    /**
+     * Search for items.
+     */
+    private searchItems;
+    /**
+     * List namespaces.
+     */
+    private listNamespacesItems;
+}

package/dist/persistence/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Persistence Module
+ *
+ * Pluggable persistence backends for agent sessions, checkpoints, and memory.
+ */
+export type { SessionMetadata, SessionRecord, PersistenceMode, Session, } from './types.js';
+export { MemorySessionBackend } from './memory-backend.js';
+export { FirestoreCheckpointer, type FirestoreCheckpointerOptions, type FirestoreDb, type FirestoreTimestamp, } from './firestore-checkpointer.js';
+export { FirestoreSessionStore, type FirestoreSessionStoreOptions, } from './firestore-session-store.js';
+export { FirestoreStore, type FirestoreStoreOptions, } from './firestore-store.js';

package/dist/persistence/memory-backend.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-Memory Persistence Backend
+ *
+ * Provides in-memory session metadata storage for development.
+ * Data is lost on process restart.
+ */
+import type { SessionMetadata, SessionRecord } from './types.js';
+/**
+ * In-memory session metadata store.
+ */
+export declare class MemorySessionBackend {
+    private sessions;
+    /**
+     * Store session metadata.
+     */
+    store(threadId: string, metadata: SessionMetadata): void;
+    /**
+     * Get session metadata.
+     */
+    get(threadId: string): SessionMetadata | undefined;
+    /**
+     * Delete session metadata.
+     */
+    delete(threadId: string): boolean;
+    /**
+     * List all sessions.
+     */
+    list(): SessionRecord[];
+    /**
+     * Check if a session exists.
+     */
+    has(threadId: string): boolean;
+}

package/dist/persistence/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Persistence Types
+ *
+ * Interfaces for pluggable persistence backends.
+ * Consumers provide implementations (memory, Firestore, etc.)
+ */
+/**
+ * Session metadata stored by any backend.
+ */
+export interface SessionMetadata {
+    skill: string;
+    workDir: string;
+    createdAt: number;
+    lastActivityAt: number;
+    /** If true, auto-approve all future interrupts without user interaction */
+    approveAll?: boolean;
+}
+/**
+ * Session record with thread ID (for listing).
+ */
+export interface SessionRecord extends SessionMetadata {
+    threadId: string;
+}
+/**
+ * Persistence mode for agent sessions.
+ * - 'memory': In-memory storage (default, lost on restart)
+ * - 'firestore': Firestore-backed storage (persistent)
+ */
+export type PersistenceMode = 'memory' | 'firestore';
+/**
+ * Session data for Firestore storage.
+ */
+export interface Session {
+    threadId: string;
+    skill: string;
+    workDir: string;
+    userId?: string;
+    createdAt: Date;
+    lastActivityAt: Date;
+}

package/dist/security/audit-log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AuditLog — Hash-chained append-only audit ledger.
+ *
+ * TypeScript port of saezbaldo/ic-agi `ic_agi/audit_log.py`.
+ * See: https://github.com/saezbaldo/ic-agi
+ *
+ * Each entry is cryptographically linked to the previous one via
+ * SHA-256 chaining. Any tampering with historical entries will
+ * break chain verification.
+ */
+export interface AuditEntry {
+    /** Zero-based position in the chain. */
+    index: number;
+    /** Unix epoch seconds — set by append(), never caller-supplied. */
+    timestamp: number;
+    /** Arbitrary event data. */
+    data: Record<string, unknown>;
+    /** SHA-256 of the previous entry (or GENESIS_HASH for the first entry). */
+    prevHash: string;
+    /** SHA-256 of this entry's canonical form. */
+    entryHash: string;
+}
+export declare class AuditLog {
+    private entries;
+    /**
+     * Append a new entry to the chain.
+     * The timestamp is set here — callers cannot supply it.
+     */
+    append(data: Record<string, unknown>): AuditEntry;
+    /**
+     * Verify the integrity of the entire chain.
+     * Recomputes every entry hash and checks chain linkage.
+     * Returns false immediately on the first mismatch.
+     */
+    verify(): boolean;
+    /** Return entries, optionally filtered by source, event type, or count limit. */
+    getEntries(filter?: {
+        source?: string;
+        event?: string;
+        limit?: number;
+    }): AuditEntry[];
+    getEntry(index: number): AuditEntry | undefined;
+    get length(): number;
+}

package/dist/state-sync.d.ts

@@ -0,0 +1,171 @@
+/**
+ * State Synchronization Support - GAP-010
+ *
+ * Provides agent-side support for real-time state synchronization.
+ * The actual transport (WebSocket/SSE) is handled by @almadar/server.
+ *
+ * This module provides:
+ * - State change notifications
+ * - Conflict resolution utilities
+ * - State serialization for sync
+ * - Event emitters for server integration
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+import type { Checkpoint } from '@langchain/langgraph-checkpoint';
+/**
+ * State change event types
+ */
+export type StateChangeType = 'checkpoint_created' | 'checkpoint_updated' | 'session_started' | 'session_ended' | 'tool_executed' | 'memory_updated' | 'interrupt_triggered' | 'interrupt_resolved';
+/**
+ * State change event
+ */
+export interface StateChangeEvent {
+    /** Change type */
+    type: StateChangeType;
+    /** Thread/session ID */
+    threadId: string;
+    /** User ID */
+    userId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Change payload */
+    payload: Record<string, unknown>;
+    /** Version vector for conflict resolution */
+    version: VersionVector;
+    /** Source client ID */
+    sourceClientId?: string;
+}
+/**
+ * Version vector for conflict resolution
+ */
+export interface VersionVector {
+    /** Logical timestamp */
+    timestamp: number;
+    /** Sequence number */
+    sequence: number;
+    /** Node/client ID */
+    nodeId: string;
+}
+/**
+ * Sync state snapshot
+ */
+export interface StateSyncSnapshot {
+    /** Thread ID */
+    threadId: string;
+    /** Current checkpoint */
+    checkpoint?: Checkpoint;
+    /** Session metadata */
+    sessionMetadata?: Record<string, unknown>;
+    /** Memory state */
+    memoryState?: Record<string, unknown>;
+    /** Version vector */
+    version: VersionVector;
+    /** Last updated */
+    lastUpdated: number;
+}
+/**
+ * Conflict resolution result
+ */
+export interface ConflictResolution {
+    /** Whether conflict was resolved */
+    resolved: boolean;
+    /** Winning state if resolved */
+    winningState?: StateSyncSnapshot;
+    /** Conflicting changes if not resolved */
+    conflicts?: Array<{
+        clientA: StateChangeEvent;
+        clientB: StateChangeEvent;
+    }>;
+    /** Resolution strategy used */
+    strategy: 'last_write_wins' | 'merge' | 'manual';
+}
+/**
+ * Sync configuration
+ */
+export interface StateSyncConfig {
+    /** Enable sync */
+    enabled: boolean;
+    /** Conflict resolution strategy */
+    conflictStrategy: 'last_write_wins' | 'merge' | 'manual';
+    /** Throttle interval (ms) */
+    throttleInterval: number;
+    /** Max retry attempts */
+    maxRetries: number;
+    /** Client ID */
+    clientId: string;
+}
+export declare class StateSyncManager extends EventEmitter {
+    private config;
+    private sequenceNumber;
+    private pendingChanges;
+    private throttleTimer;
+    constructor(config?: Partial<StateSyncConfig>);
+    /**
+     * Notify that state has changed (called by agent internals)
+     */
+    notifyStateChange(type: StateChangeType, threadId: string, payload: Record<string, unknown>, userId?: string): void;
+    /**
+     * Receive state change from server (called by server transport)
+     */
+    receiveRemoteChange(event: StateChangeEvent): void;
+    /**
+     * Create sync snapshot for current state
+     */
+    createSnapshot(threadId: string, state: {
+        checkpoint?: Checkpoint;
+        sessionMetadata?: Record<string, unknown>;
+        memoryState?: Record<string, unknown>;
+    }): StateSyncSnapshot;
+    /**
+     * Compare two version vectors
+     * Returns: -1 if a < b, 0 if concurrent/equal, 1 if a > b
+     */
+    compareVersions(a: VersionVector, b: VersionVector): number;
+    /**
+     * Check if there are pending changes to sync
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * Get and clear pending changes
+     */
+    flushPendingChanges(): StateChangeEvent[];
+    /**
+     * Get sync configuration
+     */
+    getConfig(): StateSyncConfig;
+    /**
+     * Update sync configuration
+     */
+    updateConfig(config: Partial<StateSyncConfig>): void;
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+    private generateClientId;
+    private createVersionVector;
+    private scheduleSync;
+    private findConflicts;
+    private resolveConflicts;
+}
+/**
+ * Get or create global state sync manager
+ */
+export declare function getStateSyncManager(config?: Partial<StateSyncConfig>): StateSyncManager;
+/**
+ * Reset global state sync manager
+ */
+export declare function resetStateSyncManager(): void;
+/**
+ * Create a synchronized wrapper for session operations
+ */
+export declare function withSync<T extends (...args: unknown[]) => unknown>(fn: T, syncManager: StateSyncManager, options: {
+    threadId: string;
+    type: StateChangeType;
+    getPayload: (...args: unknown[]) => Record<string, unknown>;
+}): T;
+/**
+ * Debounce sync notifications
+ */
+export declare function debounceSync(syncManager: StateSyncManager, delay?: number): (type: StateChangeType, threadId: string, payload: Record<string, unknown>) => void;

package/dist/subagents.d.ts

@@ -0,0 +1,38 @@
+/**
+ * KFlow DeepAgent Subagents
+ *
+ * Specialized subagents for complex schema generation tasks.
+ * These are spawned via the `task()` built-in tool.
+ *
+ * Uses @almadar/skills for schema reference documentation.
+ *
+ * @packageDocumentation
+ */
+import type { SubAgent } from './types.js';
+/**
+ * Create the Schema Generator Subagent configuration.
+ *
+ * Focused agent for generating KFlow schemas from requirements.
+ * Writes schema to file and verifies it exists.
+ */
+export declare function createSchemaGeneratorSubagent(): SubAgent;
+/**
+ * Create the Error Fixer Subagent configuration.
+ *
+ * Focused agent for fixing validation and compilation errors.
+ */
+export declare function createErrorFixerSubagent(): SubAgent;
+/**
+ * Create the Test Analyzer Subagent configuration.
+ *
+ * Focused agent for analyzing test failures and suggesting fixes.
+ */
+export declare function createTestAnalyzerSubagent(): SubAgent;
+/**
+ * Create all subagent configurations.
+ */
+export declare function createSubagents(): SubAgent[];
+/**
+ * Create subagent configs as a record for easy lookup.
+ */
+export declare function createSubagentConfigs(): Record<string, SubAgent>;