@almadar/agent 1.6.4 → 2.0.1

package/dist/{firestore-checkpointer-CkNKXoun.d.ts → persistence/firestore-checkpointer.d.ts}

@@ -1,47 +1,3 @@
-import { BaseCheckpointSaver, CheckpointTuple, CheckpointListOptions, Checkpoint, CheckpointMetadata, PendingWrite } from '@langchain/langgraph-checkpoint';
-import { RunnableConfig } from '@langchain/core/runnables';
-
-/**
- * Persistence Types
- *
- * Interfaces for pluggable persistence backends.
- * Consumers provide implementations (memory, Firestore, etc.)
- */
-/**
- * Session metadata stored by any backend.
- */
-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).
- */
-interface SessionRecord extends SessionMetadata {
-    threadId: string;
-}
-/**
- * Persistence mode for agent sessions.
- * - 'memory': In-memory storage (default, lost on restart)
- * - 'firestore': Firestore-backed storage (persistent)
- */
-type PersistenceMode = 'memory' | 'firestore';
-/**
- * Session data for Firestore storage.
- */
-interface Session {
-    threadId: string;
-    skill: string;
-    workDir: string;
-    userId?: string;
-    createdAt: Date;
-    lastActivityAt: Date;
-}
-
 /**
  * Firestore Checkpointer for LangGraph
  *
@@ -52,50 +8,51 @@ interface Session {
  * 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.
  */
-interface FirestoreDb {
+export interface FirestoreDb {
     collection(path: string): FirestoreCollectionRef;
     batch(): FirestoreBatch;
 }
-interface FirestoreCollectionRef {
+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;
 }
-interface FirestoreDocRef {
+export interface FirestoreDocRef {
     set(data: unknown): Promise<unknown>;
     get(): Promise<FirestoreDocSnapshot>;
     update(data: unknown): Promise<unknown>;
     delete(): Promise<unknown>;
     readonly ref: unknown;
 }
-interface FirestoreDocSnapshot {
+export interface FirestoreDocSnapshot {
     exists: boolean;
     data(): Record<string, unknown> | undefined;
     readonly ref: unknown;
 }
-interface FirestoreQuery {
+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>;
 }
-interface FirestoreQuerySnapshot {
+export interface FirestoreQuerySnapshot {
     empty: boolean;
     docs: FirestoreQueryDocSnapshot[];
     size: number;
 }
-interface FirestoreQueryDocSnapshot {
+export interface FirestoreQueryDocSnapshot {
     data(): Record<string, unknown>;
     readonly ref: unknown;
 }
-interface FirestoreBatch {
+export interface FirestoreBatch {
     set(ref: unknown, data: unknown): void;
     delete(ref: unknown): void;
     commit(): Promise<unknown>;
@@ -103,13 +60,13 @@ interface FirestoreBatch {
 /**
  * Firestore Timestamp-like interface.
  */
-interface FirestoreTimestamp {
+export interface FirestoreTimestamp {
     toDate(): Date;
 }
 /**
  * Options for FirestoreCheckpointer.
  */
-interface FirestoreCheckpointerOptions {
+export interface FirestoreCheckpointerOptions {
     /**
      * Firestore instance. Required — injected by consumer.
      */
@@ -146,7 +103,7 @@ interface FirestoreCheckpointerOptions {
  * });
  * ```
  */
-declare class FirestoreCheckpointer extends BaseCheckpointSaver {
+export declare class FirestoreCheckpointer extends BaseCheckpointSaver {
     private db;
     private checkpointsCollection;
     private writesCollection;
@@ -180,5 +137,3 @@ declare class FirestoreCheckpointer extends BaseCheckpointSaver {
      */
     deleteThread(threadId: string): Promise<void>;
 }
-
-export { FirestoreCheckpointer as F, type PersistenceMode as P, type SessionMetadata as S, type FirestoreCheckpointerOptions as a, type FirestoreDb as b, type FirestoreTimestamp as c, type Session as d, type SessionRecord as e };

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

@@ -1,201 +1,10 @@
-import { S as SessionMetadata, e as SessionRecord, b as FirestoreDb, d as Session } from '../firestore-checkpointer-CkNKXoun.js';
-export { F as FirestoreCheckpointer, a as FirestoreCheckpointerOptions, c as FirestoreTimestamp, P as PersistenceMode } from '../firestore-checkpointer-CkNKXoun.js';
-import { BaseStore, Operation, OperationResults } from '@langchain/langgraph-checkpoint';
-import '@langchain/core/runnables';
-
 /**
- * In-Memory Persistence Backend
+ * Persistence Module
  *
- * Provides in-memory session metadata storage for development.
- * Data is lost on process restart.
+ * Pluggable persistence backends for agent sessions, checkpoints, and memory.
  */
-
-/**
- * In-memory session metadata store.
- */
-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;
-}
-
-/**
- * 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.
- */
-
-/**
- * Options for FirestoreSessionStore.
- */
-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');
- * ```
- */
-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>;
-}
-
-/**
- * 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.
- */
-
-/**
- * Options for FirestoreStore.
- */
-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');
- * ```
- */
-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;
-}
-
-export { FirestoreDb, FirestoreSessionStore, type FirestoreSessionStoreOptions, FirestoreStore, type FirestoreStoreOptions, MemorySessionBackend, Session, SessionMetadata, SessionRecord };
+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;
+}