agent-relay 1.1.0 → 1.2.0

package/dist/continuity/manager.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Continuity Manager
+ *
+ * Central service for managing session continuity.
+ * Coordinates ledger storage, handoff creation, and context injection.
+ */
+import { type ParsedHandoffContent } from './parser.js';
+import type { Ledger, Handoff, HandoffTrigger, ContinuityPaths, StartupContext, SaveLedgerOptions, SearchOptions, ContinuityCommand } from './types.js';
+/**
+ * Options for ContinuityManager
+ */
+export interface ContinuityManagerOptions {
+    /** Base directory for continuity data (default: ~/.agent-relay/continuity) */
+    basePath?: string;
+    /** Default CLI type for new ledgers */
+    defaultCli?: string;
+}
+/**
+ * ContinuityManager - Central service for session continuity
+ */
+export declare class ContinuityManager {
+    private paths;
+    private ledgerStore;
+    private handoffStore;
+    private defaultCli;
+    private initialized;
+    constructor(options?: ContinuityManagerOptions);
+    /**
+     * Initialize the continuity system (create directories)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate a session ID
+     */
+    private generateSessionId;
+    /**
+     * Generate a unique agent ID using UUID v4
+     */
+    generateAgentId(): string;
+    /**
+     * Get or create a ledger for an agent
+     */
+    getOrCreateLedger(agentName: string, cli?: string, agentId?: string): Promise<Ledger>;
+    /**
+     * Find a ledger by agent ID (for resume functionality)
+     */
+    findLedgerByAgentId(agentId: string): Promise<Ledger | null>;
+    /**
+     * Get a ledger for an agent (returns null if not exists)
+     */
+    getLedger(agentName: string): Promise<Ledger | null>;
+    /**
+     * Save a ledger, optionally creating a handoff
+     */
+    saveLedger(agentName: string, content: string | Partial<Ledger>, options?: SaveLedgerOptions): Promise<Ledger>;
+    /**
+     * Update specific fields in a ledger
+     */
+    updateLedger(agentName: string, updates: Partial<Omit<Ledger, 'agentName' | 'updatedAt'>>): Promise<Ledger | null>;
+    /**
+     * Add an uncertain item to the ledger
+     */
+    addUncertainItem(agentName: string, item: string): Promise<boolean>;
+    /**
+     * Delete a ledger
+     */
+    deleteLedger(agentName: string): Promise<boolean>;
+    /**
+     * Create a handoff from a ledger
+     */
+    createHandoffFromLedger(ledger: Ledger, triggerReason: HandoffTrigger): Promise<Handoff>;
+    /**
+     * Create a handoff from parsed content
+     */
+    createHandoff(agentName: string, content: string | ParsedHandoffContent, triggerReason?: HandoffTrigger): Promise<Handoff>;
+    /**
+     * Get the latest handoff for an agent
+     */
+    getLatestHandoff(agentName: string): Promise<Handoff | null>;
+    /**
+     * Get a handoff by ID
+     */
+    getHandoff(handoffId: string): Promise<Handoff | null>;
+    /**
+     * List handoffs for an agent
+     */
+    listHandoffs(agentName: string, limit?: number): Promise<Handoff[]>;
+    /**
+     * Search handoffs (basic text search - FTS to be added)
+     */
+    searchHandoffs(query: string, options?: SearchOptions): Promise<Handoff[]>;
+    /**
+     * Get startup context for an agent (for injection on spawn).
+     * Applies defensive filtering to remove any placeholder values.
+     */
+    getStartupContext(agentName: string): Promise<StartupContext | null>;
+    /**
+     * Filter placeholder values from a ledger (defensive)
+     */
+    private filterLedgerPlaceholders;
+    /**
+     * Filter placeholder values from a handoff (defensive)
+     */
+    private filterHandoffPlaceholders;
+    /**
+     * Format a ledger for display/injection
+     */
+    formatLedger(ledger: Ledger, compact?: boolean): string;
+    /**
+     * Format a handoff for display/injection
+     */
+    formatHandoff(handoff: Handoff, compact?: boolean): string;
+    /**
+     * Format search results
+     */
+    formatSearchResults(handoffs: Handoff[], query: string): string;
+    /**
+     * Get a brief status summary
+     */
+    getBriefStatus(agentName: string): Promise<string>;
+    /**
+     * Handle a continuity command from agent output
+     */
+    handleCommand(agentName: string, command: ContinuityCommand): Promise<string | null>;
+    /**
+     * Auto-save current state (called by wrapper on agent exit)
+     * @param agentName - Name of the agent
+     * @param reason - Why the save is happening
+     * @param sessionEndData - Optional data from [[SESSION_END]] block to populate handoff
+     */
+    autoSave(agentName: string, reason: 'crash' | 'restart' | 'session_end', sessionEndData?: {
+        summary?: string;
+        completedTasks?: string[];
+    }): Promise<void>;
+    /**
+     * Clean placeholder data from all ledgers.
+     * Removes known placeholder/template values that were incorrectly saved.
+     * Returns the number of ledgers that were cleaned.
+     */
+    cleanupPlaceholders(): Promise<{
+        cleaned: number;
+        agents: string[];
+    }>;
+    /**
+     * Clear all continuity data for an agent
+     */
+    clearAgent(agentName: string): Promise<void>;
+    /**
+     * List all agents with continuity data
+     */
+    listAgents(): Promise<string[]>;
+    /**
+     * Get continuity paths
+     */
+    getPaths(): ContinuityPaths;
+}
+/**
+ * Get the singleton ContinuityManager instance (sync version)
+ *
+ * Note: This is safe for most uses since ContinuityManager methods
+ * call initialize() internally. The race condition only matters
+ * if multiple calls happen before the first completes AND they
+ * pass different options (which is unlikely in practice).
+ */
+export declare function getContinuityManager(options?: ContinuityManagerOptions): ContinuityManager;
+/**
+ * Get the singleton ContinuityManager instance (async version)
+ *
+ * This is the thread-safe version that ensures only one instance
+ * is created even with concurrent calls. Use this in async contexts
+ * where race conditions are possible.
+ */
+export declare function getContinuityManagerAsync(options?: ContinuityManagerOptions): Promise<ContinuityManager>;
+/**
+ * Reset the singleton instance (for testing)
+ */
+export declare function resetContinuityManager(): void;
+//# sourceMappingURL=manager.d.ts.map

package/dist/continuity/manager.d.ts.map

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