agent-relay 1.1.0 → 1.2.3

package/dist/hooks/registry.js

@@ -0,0 +1,476 @@
+/**
+ * Hook Registry
+ *
+ * Manages lifecycle hooks and pattern handlers for agent sessions.
+ * Provides a centralized way to register, unregister, and dispatch hooks.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Simple in-memory implementation of HookMemory
+ */
+class InMemoryHookMemory {
+    store = new Map();
+    get(key) {
+        return this.store.get(key);
+    }
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+/**
+ * HookRegistry manages lifecycle hooks and dispatches events
+ */
+export class HookRegistry {
+    sessionId;
+    agentId;
+    agentName;
+    workingDir;
+    projectId;
+    env;
+    task;
+    taskId;
+    taskSource;
+    memory;
+    relay;
+    outputHistory = [];
+    messageHistory = [];
+    sessionStartHooks = [];
+    sessionEndHooks = [];
+    outputHooks = [];
+    messageReceivedHooks = [];
+    messageSentHooks = [];
+    idleHooks = [];
+    errorHooks = [];
+    patternHandlers = new Map();
+    idleTimeout;
+    idleTimer;
+    idleCount = 0;
+    lastActivityTime = Date.now();
+    sessionStartTime = Date.now();
+    injectFn;
+    sendFn;
+    constructor(options = {}) {
+        this.sessionId = randomUUID();
+        this.agentId = options.agentId ?? randomUUID();
+        this.agentName = options.agentName ?? 'agent';
+        this.workingDir = options.workingDir ?? process.cwd();
+        this.projectId = options.projectId ?? 'default';
+        this.env = options.env ?? {};
+        this.task = options.task;
+        this.taskId = options.taskId;
+        this.taskSource = options.taskSource;
+        this.idleTimeout = options.idleTimeout ?? 30000;
+        this.injectFn = options.inject;
+        this.sendFn = options.send;
+        this.memory = new InMemoryHookMemory();
+        // Create relay interface (using arrow functions to capture 'this')
+        this.relay = {
+            send: async (to, body) => {
+                if (this.sendFn) {
+                    await this.sendFn(to, body);
+                }
+            },
+            isConnected: () => {
+                return !!this.sendFn;
+            },
+            getAgentName: () => {
+                return this.agentName;
+            },
+        };
+    }
+    /**
+     * Register hooks from a configuration object
+     */
+    registerHooks(config) {
+        if (config.hooks) {
+            this.registerLifecycleHooks(config.hooks);
+        }
+        if (config.patterns) {
+            for (const [namespace, handler] of Object.entries(config.patterns)) {
+                if (handler !== 'builtin') {
+                    this.registerPattern(namespace, handler);
+                }
+            }
+        }
+        if (config.idleTimeout !== undefined) {
+            this.idleTimeout = config.idleTimeout;
+        }
+        // Register memory hooks if configured
+        if (config.memory) {
+            this.registerMemoryHooksFromConfig(config.memory);
+        }
+    }
+    /**
+     * Register memory hooks from configuration
+     */
+    async registerMemoryHooksFromConfig(config) {
+        try {
+            // Dynamic import to avoid circular dependencies
+            const { createMemoryHooks } = await import('../memory/memory-hooks.js');
+            // Handle boolean config (true = use defaults)
+            if (config === true || config === false) {
+                if (!config)
+                    return; // false means disabled
+                const hooks = createMemoryHooks({
+                    agentId: this.agentId,
+                    projectId: this.projectId,
+                });
+                this.registerLifecycleHooks(hooks);
+                return;
+            }
+            // Handle object config
+            const hooks = createMemoryHooks({
+                config: {
+                    type: config.type,
+                    apiKey: config.apiKey,
+                    endpoint: config.endpoint,
+                },
+                agentId: this.agentId,
+                projectId: this.projectId,
+                injectOnStart: config.injectOnStart,
+                maxStartMemories: config.maxStartMemories,
+                promptOnEnd: config.promptOnEnd,
+                autoSave: config.autoSave,
+                autoSaveOnEnd: config.autoSaveOnEnd,
+            });
+            this.registerLifecycleHooks(hooks);
+        }
+        catch (error) {
+            console.error('[hooks] Failed to register memory hooks:', error);
+        }
+    }
+    /**
+     * Register memory hooks with custom options
+     */
+    async registerMemoryHooks(options) {
+        await this.registerMemoryHooksFromConfig(options ?? {});
+    }
+    /**
+     * Register lifecycle hooks
+     */
+    registerLifecycleHooks(hooks) {
+        if (hooks.onSessionStart) {
+            this.addHooks('sessionStart', hooks.onSessionStart);
+        }
+        if (hooks.onSessionEnd) {
+            this.addHooks('sessionEnd', hooks.onSessionEnd);
+        }
+        if (hooks.onOutput) {
+            this.addHooks('output', hooks.onOutput);
+        }
+        if (hooks.onMessageReceived) {
+            this.addHooks('messageReceived', hooks.onMessageReceived);
+        }
+        if (hooks.onMessageSent) {
+            this.addHooks('messageSent', hooks.onMessageSent);
+        }
+        if (hooks.onIdle) {
+            this.addHooks('idle', hooks.onIdle);
+        }
+        if (hooks.onError) {
+            this.addHooks('error', hooks.onError);
+        }
+    }
+    /**
+     * Add hooks for a specific event
+     */
+    addHooks(event, hooks) {
+        const hookArray = Array.isArray(hooks) ? hooks : [hooks];
+        switch (event) {
+            case 'sessionStart':
+                this.sessionStartHooks.push(...hookArray);
+                break;
+            case 'sessionEnd':
+                this.sessionEndHooks.push(...hookArray);
+                break;
+            case 'output':
+                this.outputHooks.push(...hookArray);
+                break;
+            case 'messageReceived':
+                this.messageReceivedHooks.push(...hookArray);
+                break;
+            case 'messageSent':
+                this.messageSentHooks.push(...hookArray);
+                break;
+            case 'idle':
+                this.idleHooks.push(...hookArray);
+                break;
+            case 'error':
+                this.errorHooks.push(...hookArray);
+                break;
+        }
+    }
+    /**
+     * Register a pattern handler
+     */
+    registerPattern(namespace, handler) {
+        this.patternHandlers.set(namespace, handler);
+    }
+    /**
+     * Get the base hook context
+     */
+    getBaseContext() {
+        return {
+            agentId: this.agentId,
+            sessionId: this.sessionId,
+            workingDir: this.workingDir,
+            env: this.env,
+            inject: (content) => {
+                if (this.injectFn) {
+                    this.injectFn(content);
+                }
+            },
+            send: async (to, body) => {
+                if (this.sendFn) {
+                    await this.sendFn(to, body);
+                }
+            },
+            memory: this.memory,
+            relay: this.relay,
+            output: [...this.outputHistory],
+            messages: [...this.messageHistory],
+        };
+    }
+    /**
+     * Run hooks and collect results
+     */
+    async runHooks(hooks, context) {
+        const combinedResult = {};
+        for (const hook of hooks) {
+            try {
+                const result = await hook(context);
+                if (result) {
+                    if (result.inject) {
+                        combinedResult.inject = (combinedResult.inject ?? '') + result.inject;
+                    }
+                    if (result.suppress) {
+                        combinedResult.suppress = true;
+                    }
+                    if (result.stop) {
+                        combinedResult.stop = true;
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                console.error('[hooks] Hook execution error:', err);
+            }
+        }
+        // Execute injection if any
+        if (combinedResult.inject && this.injectFn) {
+            this.injectFn(combinedResult.inject);
+        }
+        return combinedResult;
+    }
+    /**
+     * Dispatch session start event
+     */
+    async dispatchSessionStart() {
+        this.sessionStartTime = Date.now();
+        this.startIdleTimer();
+        const context = {
+            ...this.getBaseContext(),
+            task: this.task,
+            taskId: this.taskId,
+            taskSource: this.taskSource,
+        };
+        return this.runHooks(this.sessionStartHooks, context);
+    }
+    /**
+     * Dispatch session end event
+     */
+    async dispatchSessionEnd(exitCode, graceful = true) {
+        this.stopIdleTimer();
+        const context = {
+            ...this.getBaseContext(),
+            exitCode,
+            duration: Date.now() - this.sessionStartTime,
+            graceful,
+        };
+        return this.runHooks(this.sessionEndHooks, context);
+    }
+    /**
+     * Dispatch output event
+     */
+    async dispatchOutput(content, rawContent, isComplete = true) {
+        this.resetIdleTimer();
+        // Record in history
+        this.outputHistory.push({
+            type: 'text',
+            content,
+            timestamp: Date.now(),
+        });
+        const context = {
+            ...this.getBaseContext(),
+            content,
+            rawContent,
+            isComplete,
+        };
+        // Check for patterns
+        await this.checkPatterns(content, context);
+        return this.runHooks(this.outputHooks, context);
+    }
+    /**
+     * Dispatch message received event
+     */
+    async dispatchMessageReceived(from, body, messageId, thread) {
+        this.resetIdleTimer();
+        // Record in history
+        this.messageHistory.push({
+            role: 'user',
+            content: `[${from}]: ${body}`,
+            timestamp: Date.now(),
+        });
+        const context = {
+            ...this.getBaseContext(),
+            from,
+            body,
+            messageId,
+            thread,
+        };
+        return this.runHooks(this.messageReceivedHooks, context);
+    }
+    /**
+     * Dispatch message sent event
+     */
+    async dispatchMessageSent(to, body, thread) {
+        this.resetIdleTimer();
+        // Record in history
+        this.messageHistory.push({
+            role: 'assistant',
+            content: `[to ${to}]: ${body}`,
+            timestamp: Date.now(),
+        });
+        const context = {
+            ...this.getBaseContext(),
+            to,
+            body,
+            thread,
+        };
+        return this.runHooks(this.messageSentHooks, context);
+    }
+    /**
+     * Dispatch idle event
+     */
+    async dispatchIdle() {
+        this.idleCount++;
+        const context = {
+            ...this.getBaseContext(),
+            idleDuration: Date.now() - this.lastActivityTime,
+            idleCount: this.idleCount,
+        };
+        const result = await this.runHooks(this.idleHooks, context);
+        // Restart idle timer
+        this.startIdleTimer();
+        return result;
+    }
+    /**
+     * Dispatch error event
+     */
+    async dispatchError(error, phase) {
+        const context = {
+            ...this.getBaseContext(),
+            error,
+            phase,
+        };
+        return this.runHooks(this.errorHooks, context);
+    }
+    /**
+     * Check content for pattern matches
+     */
+    async checkPatterns(content, baseContext) {
+        // Match patterns like @namespace:target message
+        const patternRegex = /@(\w+):(\S+)\s*(.*)/g;
+        let match;
+        while ((match = patternRegex.exec(content)) !== null) {
+            const [, namespace, target, message] = match;
+            const handler = this.patternHandlers.get(namespace);
+            if (handler) {
+                try {
+                    const result = await handler(target, message.trim(), baseContext);
+                    if (result?.inject && this.injectFn) {
+                        this.injectFn(result.inject);
+                    }
+                }
+                catch (err) {
+                    console.error(`[hooks] Pattern handler error for @${namespace}:`, err);
+                }
+            }
+        }
+    }
+    /**
+     * Start idle timer
+     */
+    startIdleTimer() {
+        this.stopIdleTimer();
+        if (this.idleHooks.length > 0 && this.idleTimeout > 0) {
+            this.idleTimer = setTimeout(() => {
+                this.dispatchIdle().catch(console.error);
+            }, this.idleTimeout);
+        }
+    }
+    /**
+     * Stop idle timer
+     */
+    stopIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = undefined;
+        }
+    }
+    /**
+     * Reset idle timer on activity
+     */
+    resetIdleTimer() {
+        this.lastActivityTime = Date.now();
+        this.startIdleTimer();
+    }
+    /**
+     * Get session info
+     */
+    getSessionInfo() {
+        return {
+            sessionId: this.sessionId,
+            agentId: this.agentId,
+            startTime: new Date(this.sessionStartTime),
+            duration: Date.now() - this.sessionStartTime,
+        };
+    }
+    /**
+     * Update inject function
+     */
+    setInjectFn(fn) {
+        this.injectFn = fn;
+    }
+    /**
+     * Update send function
+     */
+    setSendFn(fn) {
+        this.sendFn = fn;
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        this.stopIdleTimer();
+        this.memory.clear();
+        this.sessionStartHooks = [];
+        this.sessionEndHooks = [];
+        this.outputHooks = [];
+        this.messageReceivedHooks = [];
+        this.messageSentHooks = [];
+        this.idleHooks = [];
+        this.errorHooks = [];
+        this.patternHandlers.clear();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/hooks/trajectory-hooks.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Trajectory Hooks
+ *
+ * Provides trajectory tracking hooks that integrate with the PDERO paradigm.
+ * These hooks automatically track agent work when registered with a HookRegistry.
+ */
+import type { LifecycleHooks } from './types.js';
+/**
+ * Options for trajectory hooks
+ */
+export interface TrajectoryHooksOptions {
+    /** Project identifier */
+    projectId: string;
+    /** Agent name */
+    agentName: string;
+    /** Whether to auto-detect phase transitions */
+    autoDetectPhase?: boolean;
+    /** Whether to detect and record tool calls */
+    detectTools?: boolean;
+    /** Whether to detect and record errors */
+    detectErrors?: boolean;
+    /** Whether to inject trail instructions on session start */
+    injectInstructions?: boolean;
+    /** Whether to prompt for retrospective on session end */
+    promptRetrospective?: boolean;
+}
+/**
+ * Create trajectory hooks for automatic PDERO tracking
+ *
+ * @example
+ * ```typescript
+ * const hooks = createTrajectoryHooks({
+ *   projectId: 'my-project',
+ *   agentName: 'Alice',
+ * });
+ *
+ * registry.registerLifecycleHooks(hooks);
+ * ```
+ */
+export declare function createTrajectoryHooks(options: TrajectoryHooksOptions): LifecycleHooks;
+/**
+ * Get trajectory hooks for a project/agent combination
+ *
+ * This is a convenience function that creates trajectory hooks
+ * with default options.
+ */
+export declare function getTrajectoryHooks(projectId: string, agentName: string): LifecycleHooks;
+/**
+ * Utility to check if trajectory tracking is available
+ */
+export declare function isTrajectoryTrackingAvailable(projectId: string, agentName: string): boolean;
+//# sourceMappingURL=trajectory-hooks.d.ts.map

package/dist/hooks/trajectory-hooks.js

@@ -0,0 +1,183 @@
+/**
+ * Trajectory Hooks
+ *
+ * Provides trajectory tracking hooks that integrate with the PDERO paradigm.
+ * These hooks automatically track agent work when registered with a HookRegistry.
+ */
+import { getTrajectoryIntegration, detectPhaseFromContent, detectToolCalls, detectErrors, getCompactTrailInstructions, } from '../trajectory/integration.js';
+/**
+ * Create trajectory hooks for automatic PDERO tracking
+ *
+ * @example
+ * ```typescript
+ * const hooks = createTrajectoryHooks({
+ *   projectId: 'my-project',
+ *   agentName: 'Alice',
+ * });
+ *
+ * registry.registerLifecycleHooks(hooks);
+ * ```
+ */
+export function createTrajectoryHooks(options) {
+    const state = {
+        trajectory: getTrajectoryIntegration(options.projectId, options.agentName),
+        seenTools: new Set(),
+        seenErrors: new Set(),
+        options: {
+            autoDetectPhase: true,
+            detectTools: true,
+            detectErrors: true,
+            injectInstructions: true,
+            promptRetrospective: true,
+            ...options,
+        },
+    };
+    return {
+        onSessionStart: createSessionStartHook(state),
+        onSessionEnd: createSessionEndHook(state),
+        onOutput: createOutputHook(state),
+        onMessageReceived: createMessageReceivedHook(state),
+        onMessageSent: createMessageSentHook(state),
+    };
+}
+/**
+ * Session start hook - initializes trajectory tracking
+ */
+function createSessionStartHook(state) {
+    return async (ctx) => {
+        const { trajectory, options } = state;
+        // Initialize trajectory with task if provided
+        if (ctx.task) {
+            const success = await trajectory.initialize(ctx.task, ctx.taskId, ctx.taskSource);
+            if (success) {
+                console.log(`[trajectory] Started tracking: ${ctx.task}`);
+            }
+        }
+        else {
+            await trajectory.initialize();
+        }
+        // Inject trail instructions if enabled and trail is available
+        if (options.injectInstructions && trajectory.isTrailInstalledSync()) {
+            const instructions = getCompactTrailInstructions();
+            return { inject: `\n${instructions}\n` };
+        }
+    };
+}
+/**
+ * Session end hook - completes or abandons trajectory
+ */
+function createSessionEndHook(state) {
+    return async (ctx) => {
+        const { trajectory, options } = state;
+        if (!trajectory.hasActiveTrajectory()) {
+            return;
+        }
+        if (ctx.graceful) {
+            // Prompt for retrospective if enabled
+            if (options.promptRetrospective) {
+                const durationSeconds = Math.round(ctx.duration / 1000);
+                const result = {
+                    inject: `
+[SESSION ENDING]
+Complete your trajectory with a summary:
+  trail complete --summary "What you accomplished" --confidence 0.9
+
+Or if you need to document learnings:
+  trail decision "Key choice" --reasoning "Why"
+`,
+                };
+                // Also complete the trajectory
+                await trajectory.complete({
+                    summary: `Session ended after ${durationSeconds}s`,
+                });
+                return result;
+            }
+            else {
+                await trajectory.complete({
+                    summary: `Session ended gracefully`,
+                });
+            }
+        }
+        else {
+            await trajectory.abandon('Session terminated');
+        }
+    };
+}
+/**
+ * Output hook - auto-detects PDERO phase transitions, tool calls, and errors
+ */
+function createOutputHook(state) {
+    return async (ctx) => {
+        const { trajectory, options } = state;
+        // Detect and record phase transitions
+        if (options.autoDetectPhase) {
+            const detectedPhase = detectPhaseFromContent(ctx.content);
+            if (detectedPhase && detectedPhase !== state.lastDetectedPhase) {
+                state.lastDetectedPhase = detectedPhase;
+                await trajectory.transition(detectedPhase, 'Auto-detected from output');
+            }
+        }
+        // Detect and record tool calls
+        // Note: We deduplicate by tool+status to record each unique tool type once per session
+        // (e.g., "Read" started, "Read" completed). This provides a summary of tools used
+        // without flooding the trajectory with every individual invocation.
+        if (options.detectTools) {
+            const tools = detectToolCalls(ctx.content);
+            for (const tool of tools) {
+                const key = `${tool.tool}:${tool.status || 'started'}`;
+                if (!state.seenTools.has(key)) {
+                    state.seenTools.add(key);
+                    const statusLabel = tool.status === 'completed' ? ' (completed)' : '';
+                    await trajectory.event(`Tool: ${tool.tool}${statusLabel}`, 'tool_call');
+                }
+            }
+        }
+        // Detect and record errors
+        if (options.detectErrors) {
+            const errors = detectErrors(ctx.content);
+            for (const error of errors) {
+                // Deduplicate by message content
+                if (!state.seenErrors.has(error.message)) {
+                    state.seenErrors.add(error.message);
+                    const prefix = error.type === 'warning' ? 'Warning' : 'Error';
+                    await trajectory.event(`${prefix}: ${error.message}`, 'error');
+                }
+            }
+        }
+    };
+}
+/**
+ * Message received hook - records incoming messages
+ */
+function createMessageReceivedHook(state) {
+    return async (ctx) => {
+        const { trajectory, options } = state;
+        await trajectory.message('received', ctx.from, options.agentName, ctx.body);
+    };
+}
+/**
+ * Message sent hook - records outgoing messages
+ */
+function createMessageSentHook(state) {
+    return async (ctx) => {
+        const { trajectory, options } = state;
+        await trajectory.message('sent', options.agentName, ctx.to, ctx.body);
+    };
+}
+/**
+ * Get trajectory hooks for a project/agent combination
+ *
+ * This is a convenience function that creates trajectory hooks
+ * with default options.
+ */
+export function getTrajectoryHooks(projectId, agentName) {
+    return createTrajectoryHooks({ projectId, agentName });
+}
+/**
+ * Utility to check if trajectory tracking is available
+ */
+export function isTrajectoryTrackingAvailable(projectId, agentName) {
+    const trajectory = getTrajectoryIntegration(projectId, agentName);
+    return trajectory.isTrailInstalledSync();
+}
+//# sourceMappingURL=trajectory-hooks.js.map