agent-relay 1.1.0 → 1.2.3

package/dist/continuity/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Continuity System Types
+ *
+ * Core types for the CLI-agnostic session continuity system.
+ * Works with any CLI (Claude, Codex, Gemini, custom) via output
+ * pattern detection and PTY injection.
+ */
+import type { PDEROPhase } from '../trajectory/integration.js';
+/**
+ * A decision recorded during agent work
+ */
+export interface Decision {
+    /** The choice that was made */
+    decision: string;
+    /** Why this choice was made */
+    reasoning?: string;
+    /** Alternative options considered */
+    alternatives?: string[];
+    /** Confidence level (0-1) */
+    confidence?: number;
+    /** When the decision was made */
+    timestamp: Date;
+}
+/**
+ * A file reference with optional line numbers
+ */
+export interface FileRef {
+    /** Relative or absolute path */
+    path: string;
+    /** Line range [start, end] */
+    lines?: [number, number];
+    /** Brief description of what's relevant */
+    description?: string;
+}
+/**
+ * Ledger - Within-session state snapshot
+ *
+ * Ephemeral, overwritten each session. Captures current work state
+ * for context injection on restart/clear.
+ */
+export interface Ledger {
+    /** Agent name this ledger belongs to */
+    agentName: string;
+    /** Unique agent instance ID (persists across restarts for resume) */
+    agentId: string;
+    /** Unique session identifier */
+    sessionId: string;
+    /** CLI being used (claude, codex, gemini, custom) */
+    cli: string;
+    /** What the agent is currently working on */
+    currentTask: string;
+    /** Completed work items */
+    completed: string[];
+    /** Work in progress */
+    inProgress: string[];
+    /** Blocked items with reasons */
+    blocked: string[];
+    /** Key decisions made during session */
+    keyDecisions: Decision[];
+    /** Items marked as uncertain (need verification) */
+    uncertainItems: string[];
+    /** Recently touched files */
+    fileContext: FileRef[];
+    /** Active trajectory ID if using trail */
+    trajectoryId?: string;
+    /** Current PDERO phase */
+    pderoPhase?: PDEROPhase;
+    /** Last update timestamp */
+    updatedAt: Date;
+}
+/**
+ * Handoff - Cross-session transfer document
+ *
+ * Permanent, searchable. Created on trajectory completion,
+ * context limit, crash, or manual save.
+ */
+export interface Handoff {
+    /** Unique handoff identifier */
+    id: string;
+    /** Agent that created this handoff */
+    agentName: string;
+    /** Agent instance ID that created this handoff */
+    agentId?: string;
+    /** CLI used (for context) */
+    cli: string;
+    /** Brief summary of the handoff */
+    summary: string;
+    /** Task being worked on */
+    taskDescription: string;
+    /** Work completed before handoff */
+    completedWork: string[];
+    /** Recommended next steps */
+    nextSteps: string[];
+    /** Files relevant to the work */
+    fileReferences: FileRef[];
+    /** Key decisions made */
+    decisions: Decision[];
+    /** Links to related previous handoffs */
+    relatedHandoffs: string[];
+    /** When the handoff was created */
+    createdAt: Date;
+    /** What triggered the handoff */
+    triggerReason: HandoffTrigger;
+    /** Trajectory ID if created from trajectory completion */
+    trajectoryId?: string;
+    /** PDERO phase at handoff time */
+    pderoPhase?: PDEROPhase;
+    /** Confidence level from trajectory */
+    confidence?: number;
+    /** Learnings extracted from trajectory */
+    learnings?: string[];
+}
+/**
+ * What triggered handoff creation
+ */
+export type HandoffTrigger = 'manual' | 'trajectory_complete' | 'context_limit' | 'auto_restart' | 'crash' | 'session_end';
+/**
+ * Continuity command parsed from agent output
+ */
+export interface ContinuityCommand {
+    /** Command type */
+    type: 'save' | 'load' | 'search' | 'uncertain' | 'handoff';
+    /** Content for save commands */
+    content?: string;
+    /** Query for search commands */
+    query?: string;
+    /** Item for uncertain command */
+    item?: string;
+    /** Whether to create a handoff (for save) */
+    createHandoff?: boolean;
+}
+/**
+ * Context to inject on agent startup
+ */
+export interface StartupContext {
+    /** The ledger if available */
+    ledger?: Ledger;
+    /** The most recent handoff if available */
+    handoff?: Handoff;
+    /** Relevant learnings from past sessions */
+    learnings?: string[];
+    /** Formatted markdown to inject */
+    formatted: string;
+}
+/**
+ * Continuity storage paths
+ */
+export interface ContinuityPaths {
+    /** Base continuity directory */
+    base: string;
+    /** Ledgers directory */
+    ledgers: string;
+    /** Handoffs directory */
+    handoffs: string;
+    /** Artifact index database */
+    artifactDb: string;
+}
+/**
+ * Options for saving a ledger
+ */
+export interface SaveLedgerOptions {
+    /** Create a handoff as well */
+    createHandoff?: boolean;
+    /** Trigger reason if creating handoff */
+    triggerReason?: HandoffTrigger;
+}
+/**
+ * Options for searching handoffs
+ */
+export interface SearchOptions {
+    /** Filter by agent name */
+    agentName?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Filter by date range */
+    since?: Date;
+    /** Filter by trigger reason */
+    triggerReason?: HandoffTrigger;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/continuity/types.js

@@ -0,0 +1,9 @@
+/**
+ * Continuity System Types
+ *
+ * Core types for the CLI-agnostic session continuity system.
+ * Works with any CLI (Claude, Codex, Gemini, custom) via output
+ * pattern detection and PTY injection.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -3,13 +3,31 @@
  * Manages agents across workspaces with integrated resiliency.
  */
 import { EventEmitter } from 'events';
+import { type SummaryEvent, type SessionEndEvent } from '../wrapper/pty-wrapper.js';
 import type { Agent, SpawnAgentRequest } from './types.js';
+/**
+ * Optional cloud persistence handler.
+ * When set, agent-manager forwards PtyWrapper events to this handler.
+ */
+export interface CloudPersistenceHandler {
+    onSummary: (agentId: string, event: SummaryEvent) => Promise<void>;
+    onSessionEnd: (agentId: string, event: SessionEndEvent) => Promise<void>;
+    /** Optional cleanup method for tests and graceful shutdown */
+    destroy?: () => void;
+}
 export declare class AgentManager extends EventEmitter {
     private agents;
     private supervisor;
     private dataDir;
     private logsDir;
+    private cloudPersistence?;
     constructor(dataDir: string);
+    /**
+     * Set cloud persistence handler for forwarding PtyWrapper events.
+     * When set, 'summary' and 'session-end' events from agents are forwarded
+     * to the handler for cloud persistence (PostgreSQL/Redis).
+     */
+    setCloudPersistence(handler: CloudPersistenceHandler): void;
     /**
      * Spawn a new agent in a workspace
      */
@@ -62,6 +80,15 @@ export declare class AgentManager extends EventEmitter {
      * Handle agent exit
      */
     private handleAgentExit;
+    /**
+     * Bind PtyWrapper events to cloud persistence and daemon events.
+     *
+     * Events bound:
+     * - 'summary': Agent output a [[SUMMARY]] block
+     * - 'session-end': Agent output a [[SESSION_END]] block
+     * - 'injection-failed': Message injection failed after retries
+     */
+    private bindPtyEvents;
     /**
      * Setup supervisor event handlers
      */

package/dist/daemon/agent-manager.js

@@ -26,6 +26,7 @@ export class AgentManager extends EventEmitter {
     });
     dataDir;
     logsDir;
+    cloudPersistence;
     constructor(dataDir) {
         super();
         this.dataDir = dataDir;
@@ -40,6 +41,15 @@ export class AgentManager extends EventEmitter {
         this.supervisor.start();
         logger.info('Agent manager initialized');
     }
+    /**
+     * Set cloud persistence handler for forwarding PtyWrapper events.
+     * When set, 'summary' and 'session-end' events from agents are forwarded
+     * to the handler for cloud persistence (PostgreSQL/Redis).
+     */
+    setCloudPersistence(handler) {
+        this.cloudPersistence = handler;
+        logger.info('Cloud persistence handler set');
+    }
     /**
      * Spawn a new agent in a workspace
      */
@@ -97,6 +107,8 @@ export class AgentManager extends EventEmitter {
             await pty.start();
             agent.pid = pty.pid;
             agent.pty = pty;
+            // Subscribe to PtyWrapper events for cloud persistence
+            this.bindPtyEvents(agent.id, pty);
             // Inject initial task
             if (task && task.trim()) {
                 pty.write(task + '\r');
@@ -161,14 +173,12 @@ export class AgentManager extends EventEmitter {
         try {
             // Remove from supervisor
             this.supervisor.unsupervise(agent.name);
-            // Stop PTY
+            // Stop PTY (handles auto-save internally)
             if (agent.pty) {
-                agent.pty.stop();
-                // Wait for graceful shutdown
-                await new Promise((resolve) => setTimeout(resolve, 2000));
+                await agent.pty.stop();
                 // Force kill if still running
                 if (agent.pty.isRunning) {
-                    agent.pty.kill();
+                    await agent.pty.kill();
                 }
             }
             agent.status = 'stopped';
@@ -300,6 +310,8 @@ export class AgentManager extends EventEmitter {
             agent.pty = pty;
             agent.status = 'running';
             agent.spawnedAt = new Date();
+            // Re-bind events for the new PTY
+            this.bindPtyEvents(agent.id, pty);
             logger.info('Agent restarted', { id: agentId, name: agent.name, pid: agent.pid });
             this.emitEvent({
                 type: 'agent:restarted',
@@ -324,16 +336,104 @@ export class AgentManager extends EventEmitter {
         if (agent.status === 'running') {
             agent.status = code === 0 ? 'stopped' : 'crashed';
             if (agent.status === 'crashed') {
+                // Get the continuity agentId for resume info
+                const continuityAgentId = agent.agentId ?? agent.pty?.getAgentId();
                 this.emitEvent({
                     type: 'agent:crashed',
                     workspaceId: agent.workspaceId,
                     agentId,
-                    data: { name: agent.name, exitCode: code },
+                    data: {
+                        name: agent.name,
+                        exitCode: code,
+                        continuityAgentId,
+                        resumeInstructions: continuityAgentId
+                            ? `To resume this agent's work, use: --resume ${continuityAgentId}`
+                            : undefined,
+                    },
                     timestamp: new Date(),
                 });
             }
         }
     }
+    /**
+     * Bind PtyWrapper events to cloud persistence and daemon events.
+     *
+     * Events bound:
+     * - 'summary': Agent output a [[SUMMARY]] block
+     * - 'session-end': Agent output a [[SESSION_END]] block
+     * - 'injection-failed': Message injection failed after retries
+     */
+    bindPtyEvents(agentId, pty) {
+        const agent = this.agents.get(agentId);
+        if (!agent)
+            return;
+        // Forward summary events
+        pty.on('summary', async (event) => {
+            logger.info('Agent summary', {
+                agentId,
+                name: event.agentName,
+                task: event.summary.currentTask,
+            });
+            // Emit daemon event
+            this.emitEvent({
+                type: 'agent:summary',
+                workspaceId: agent.workspaceId,
+                agentId,
+                data: { summary: event.summary },
+                timestamp: new Date(),
+            });
+            // Forward to cloud persistence if configured
+            if (this.cloudPersistence) {
+                try {
+                    await this.cloudPersistence.onSummary(agentId, event);
+                }
+                catch (err) {
+                    logger.error('Cloud persistence failed for summary', { agentId, error: String(err) });
+                }
+            }
+        });
+        // Forward session-end events
+        pty.on('session-end', async (event) => {
+            logger.info('Agent session ended', {
+                agentId,
+                name: event.agentName,
+                summary: event.marker.summary,
+            });
+            // Emit daemon event
+            this.emitEvent({
+                type: 'agent:session-end',
+                workspaceId: agent.workspaceId,
+                agentId,
+                data: { marker: event.marker },
+                timestamp: new Date(),
+            });
+            // Forward to cloud persistence if configured
+            if (this.cloudPersistence) {
+                try {
+                    await this.cloudPersistence.onSessionEnd(agentId, event);
+                }
+                catch (err) {
+                    logger.error('Cloud persistence failed for session-end', { agentId, error: String(err) });
+                }
+            }
+        });
+        // Log injection failures
+        pty.on('injection-failed', (event) => {
+            logger.warn('Message injection failed', {
+                agentId,
+                messageId: event.messageId,
+                from: event.from,
+                attempts: event.attempts,
+            });
+            this.emitEvent({
+                type: 'agent:injection-failed',
+                workspaceId: agent.workspaceId,
+                agentId,
+                data: event,
+                timestamp: new Date(),
+            });
+        });
+    }
     /**
      * Setup supervisor event handlers
      */
@@ -384,6 +484,7 @@ export class AgentManager extends EventEmitter {
             lastHealthCheck: agent.lastHealthCheck,
             restartCount: agent.restartCount,
             logFile: agent.logFile,
+            agentId: agent.agentId ?? agent.pty?.getAgentId(),
         };
     }
     /**

package/dist/daemon/agent-registry.d.ts

@@ -2,6 +2,25 @@
  * Agent Registry
  * Persists agent metadata across daemon restarts.
  */
+/**
+ * Agent profile information for display and understanding agent behavior
+ */
+export interface AgentProfileRecord {
+    /** Display title/role (e.g., "Lead Developer", "Code Reviewer") */
+    title?: string;
+    /** Short description of what this agent does */
+    description?: string;
+    /** The prompt/task the agent was spawned with */
+    spawnPrompt?: string;
+    /** Agent profile/persona prompt (e.g., lead agent instructions) */
+    personaPrompt?: string;
+    /** Name of the persona preset used (e.g., "lead", "reviewer", "shadow-auditor") */
+    personaName?: string;
+    /** Capabilities or tools available to the agent */
+    capabilities?: string[];
+    /** Tags for categorization */
+    tags?: string[];
+}
 export interface AgentRecord {
     id: string;
     name: string;
@@ -15,6 +34,8 @@ export interface AgentRecord {
     lastSeen: string;
     messagesSent: number;
     messagesReceived: number;
+    /** Profile information for understanding agent behavior */
+    profile?: AgentProfileRecord;
 }
 type AgentInput = {
     name: string;
@@ -24,6 +45,7 @@ type AgentInput = {
     task?: string;
     workingDirectory?: string;
     team?: string;
+    profile?: AgentProfileRecord;
 };
 export declare class AgentRegistry {
     private registryPath;
@@ -53,6 +75,16 @@ export declare class AgentRegistry {
      * Get a snapshot of all agents.
      */
     getAgents(): AgentRecord[];
+    /**
+     * Remove an agent from the registry.
+     */
+    remove(agentName: string): boolean;
+    /**
+     * Remove agents that haven't been seen for longer than the threshold.
+     * @param thresholdMs - Time in milliseconds (default: 24 hours)
+     * @returns Number of agents removed
+     */
+    pruneStale(thresholdMs?: number): number;
     private ensureRecord;
     private ensureDir;
     load(): void;

package/dist/daemon/agent-registry.js

@@ -5,6 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { v4 as uuid } from 'uuid';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('registry');
 export class AgentRegistry {
     registryPath;
     agents = new Map(); // name -> record
@@ -26,6 +28,10 @@ export class AgentRegistry {
         const now = new Date().toISOString();
         const existing = this.agents.get(agent.name);
         if (existing) {
+            // Merge profile data if provided
+            const mergedProfile = agent.profile
+                ? { ...existing.profile, ...agent.profile }
+                : existing.profile;
             const updated = {
                 ...existing,
                 cli: agent.cli ?? existing.cli,
@@ -34,6 +40,7 @@ export class AgentRegistry {
                 task: agent.task ?? existing.task,
                 workingDirectory: agent.workingDirectory ?? existing.workingDirectory,
                 team: agent.team ?? existing.team,
+                profile: mergedProfile,
                 lastSeen: now,
             };
             this.agents.set(agent.name, updated);
@@ -49,6 +56,7 @@ export class AgentRegistry {
             task: agent.task,
             workingDirectory: agent.workingDirectory,
             team: agent.team,
+            profile: agent.profile,
             firstSeen: now,
             lastSeen: now,
             messagesSent: 0,
@@ -93,6 +101,37 @@ export class AgentRegistry {
     getAgents() {
         return Array.from(this.agents.values());
     }
+    /**
+     * Remove an agent from the registry.
+     */
+    remove(agentName) {
+        const deleted = this.agents.delete(agentName);
+        if (deleted) {
+            this.save();
+        }
+        return deleted;
+    }
+    /**
+     * Remove agents that haven't been seen for longer than the threshold.
+     * @param thresholdMs - Time in milliseconds (default: 24 hours)
+     * @returns Number of agents removed
+     */
+    pruneStale(thresholdMs = 24 * 60 * 60 * 1000) {
+        const cutoff = Date.now() - thresholdMs;
+        let removed = 0;
+        for (const [name, record] of this.agents) {
+            const lastSeenTime = new Date(record.lastSeen).getTime();
+            if (lastSeenTime < cutoff) {
+                this.agents.delete(name);
+                removed++;
+                log.info('Pruned stale agent', { name, lastSeen: record.lastSeen });
+            }
+        }
+        if (removed > 0) {
+            this.save();
+        }
+        return removed;
+    }
     ensureRecord(agentName) {
         const existing = this.agents.get(agentName);
         if (existing)
@@ -137,6 +176,7 @@ export class AgentRegistry {
                     task: raw.task,
                     workingDirectory: raw.workingDirectory,
                     team: raw.team,
+                    profile: raw.profile,
                     firstSeen: raw.firstSeen ?? new Date().toISOString(),
                     lastSeen: raw.lastSeen ?? new Date().toISOString(),
                     messagesSent: typeof raw.messagesSent === 'number' ? raw.messagesSent : 0,
@@ -146,7 +186,7 @@ export class AgentRegistry {
             }
         }
         catch (err) {
-            console.error('[registry] Failed to load agents.json:', err);
+            log.error('Failed to load agents.json', { error: String(err) });
         }
     }
     save() {
@@ -159,7 +199,7 @@ export class AgentRegistry {
             fs.renameSync(tempPath, this.registryPath);
         }
         catch (err) {
-            console.error('[registry] Failed to write agents.json:', err);
+            log.error('Failed to write agents.json', { error: String(err) });
         }
     }
 }

package/dist/daemon/api.d.ts

@@ -12,7 +12,19 @@ export declare class DaemonApi extends EventEmitter {
     private sessions;
     private routes;
     private config;
+    private allowedOrigins;
+    private allowAllOrigins;
     constructor(config: ApiDaemonConfig);
+    /**
+     * Resolve allowed origins from config/env (comma-separated list).
+     * Empty list means no cross-origin access is permitted.
+     */
+    private loadAllowedOrigins;
+    /**
+     * Return allowed origin for CORS or null if explicitly blocked.
+     * Undefined means no CORS header will be set (same-origin/server-to-server).
+     */
+    private resolveAllowedOrigin;
     /**
      * Start the API server
      */