@agent-relay/hooks 0.1.0

package/dist/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/trajectory-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-hooks.d.ts","sourceRoot":"","sources":["../src/trajectory-hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,YAAY,CAAC;AAWpB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAsBrF;AA4ID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc,CAEvF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3F"}

package/dist/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 '@agent-relay/trajectory';
+/**
+ * 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

package/dist/trajectory-hooks.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Agent Relay Hook Types
+ *
+ * Core types for the agent-relay hooks system. Hooks allow agents to intercept
+ * and modify behavior at various points in the agent lifecycle.
+ */
+import type { SendPayload } from '@agent-relay/protocol/types';
+/**
+ * A message in the conversation history
+ */
+export interface ConversationMessage {
+    /** Role of the message sender */
+    role: 'user' | 'assistant' | 'system';
+    /** Message content */
+    content: string;
+    /** Timestamp when the message was created */
+    timestamp?: number;
+}
+/**
+ * Output from the agent (tool calls, responses, etc.)
+ */
+export interface AgentOutput {
+    /** Type of output */
+    type: 'text' | 'tool_call' | 'tool_result';
+    /** Content of the output */
+    content: string;
+    /** Tool name if type is tool_call or tool_result */
+    tool?: string;
+    /** Timestamp of the output */
+    timestamp: number;
+}
+/**
+ * Memory interface for persisting data across hook invocations
+ */
+export interface HookMemory {
+    /** Get a value from memory */
+    get<T = unknown>(key: string): T | undefined;
+    /** Set a value in memory */
+    set<T = unknown>(key: string, value: T): void;
+    /** Delete a value from memory */
+    delete(key: string): boolean;
+    /** Check if a key exists */
+    has(key: string): boolean;
+    /** Clear all memory */
+    clear(): void;
+}
+/**
+ * Relay interface for sending messages to other agents
+ */
+export interface HookRelay {
+    /** Send a message to a specific agent or broadcast */
+    send(to: string | '*', body: string, options?: Partial<SendPayload>): Promise<void>;
+    /** Check if connected to the relay daemon */
+    isConnected(): boolean;
+    /** Get the current agent's name in the relay */
+    getAgentName(): string | undefined;
+}
+/**
+ * Context provided to hooks during execution
+ *
+ * This interface provides hooks with access to the current execution context,
+ * allowing them to inspect and modify agent behavior.
+ */
+export interface HookContext {
+    /** Unique identifier for this agent instance */
+    agentId: string;
+    /** Session identifier for the current conversation */
+    sessionId: string;
+    /** Working directory of the agent */
+    workingDir: string;
+    /** Environment variables available to the hook */
+    env: Record<string, string | undefined>;
+    /**
+     * Inject content into the agent's input stream.
+     * This content will be processed as if it came from the user.
+     * @param content - The content to inject
+     */
+    inject(content: string): void;
+    /**
+     * Send a message through the relay to other agents.
+     * @param to - Target agent name or '*' for broadcast
+     * @param body - Message body
+     * @param options - Optional message options
+     */
+    send(to: string | '*', body: string, options?: Partial<SendPayload>): Promise<void>;
+    /** Persistent memory for storing data across hook invocations */
+    memory: HookMemory;
+    /** Relay interface for agent communication */
+    relay: HookRelay;
+    /** Array of outputs from the current agent turn */
+    output: AgentOutput[];
+    /** Conversation message history */
+    messages: ConversationMessage[];
+}
+/**
+ * Result returned by a hook execution
+ *
+ * Hooks can modify agent behavior by returning specific fields:
+ * - inject: Add content to the agent's input
+ * - suppress: Prevent the triggering action from executing
+ * - stop: Halt further hook processing
+ */
+export interface HookResult {
+    /**
+     * Content to inject into the agent's input stream.
+     * If provided, this content will be processed as user input.
+     */
+    inject?: string;
+    /**
+     * If true, suppress the action that triggered the hook.
+     * For example, on a Stop hook, this would prevent the agent from stopping.
+     */
+    suppress?: boolean;
+    /**
+     * If true, stop processing any remaining hooks in the chain.
+     * The current hook's result will be the final result.
+     */
+    stop?: boolean;
+}
+/**
+ * Hook event types that can trigger hook execution
+ */
+export type HookEventType = 'PreToolCall' | 'PostToolCall' | 'Stop' | 'Start' | 'Error' | 'Message';
+/**
+ * Configuration for a hook
+ */
+export interface HookConfig {
+    /** The event type that triggers this hook */
+    event: HookEventType;
+    /** Command to execute for the hook */
+    command: string;
+    /** Optional working directory for the command */
+    workingDir?: string;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+    /** Whether this hook is enabled */
+    enabled?: boolean;
+}
+/**
+ * Handler function signature for programmatic hooks
+ */
+export type HookHandler = (context: HookContext) => HookResult | Promise<HookResult>;
+/**
+ * Extended context for session start hooks
+ */
+export interface SessionStartContext extends HookContext {
+    /** Task description if agent was started with a task */
+    task?: string;
+    /** Task ID if linked to external system */
+    taskId?: string;
+    /** Task source (e.g., 'beads', 'linear', 'github') */
+    taskSource?: string;
+}
+/**
+ * Extended context for session end hooks
+ */
+export interface SessionEndContext extends HookContext {
+    /** Exit code if available */
+    exitCode?: number;
+    /** Duration of the session in milliseconds */
+    duration: number;
+    /** Whether the session ended gracefully */
+    graceful: boolean;
+}
+/**
+ * Extended context for output hooks
+ */
+export interface OutputContext extends HookContext {
+    /** Cleaned output (ANSI codes stripped) */
+    content: string;
+    /** Raw output with ANSI codes */
+    rawContent: string;
+    /** Whether this is a complete line */
+    isComplete: boolean;
+}
+/**
+ * Extended context for message received hooks
+ */
+export interface MessageReceivedContext extends HookContext {
+    /** Sender agent name */
+    from: string;
+    /** Message body */
+    body: string;
+    /** Message ID */
+    messageId: string;
+    /** Thread ID if threaded */
+    thread?: string;
+}
+/**
+ * Extended context for message sent hooks
+ */
+export interface MessageSentContext extends HookContext {
+    /** Target agent name */
+    to: string;
+    /** Message body */
+    body: string;
+    /** Thread ID if threaded */
+    thread?: string;
+}
+/**
+ * Extended context for idle hooks
+ */
+export interface IdleContext extends HookContext {
+    /** Duration of inactivity in milliseconds */
+    idleDuration: number;
+    /** Number of times idle hook has fired this session */
+    idleCount: number;
+}
+/**
+ * Extended context for error hooks
+ */
+export interface ErrorContext extends HookContext {
+    /** The error that occurred */
+    error: Error;
+    /** Phase where error occurred (e.g., 'output', 'message', 'tool') */
+    phase?: string;
+}
+/**
+ * Lifecycle hook handler types
+ */
+export type OnSessionStartHook = (ctx: SessionStartContext) => Promise<HookResult | void> | HookResult | void;
+export type OnSessionEndHook = (ctx: SessionEndContext) => Promise<HookResult | void> | HookResult | void;
+export type OnOutputHook = (ctx: OutputContext) => Promise<HookResult | void> | HookResult | void;
+export type OnMessageReceivedHook = (ctx: MessageReceivedContext) => Promise<HookResult | void> | HookResult | void;
+export type OnMessageSentHook = (ctx: MessageSentContext) => Promise<HookResult | void> | HookResult | void;
+export type OnIdleHook = (ctx: IdleContext) => Promise<HookResult | void> | HookResult | void;
+export type OnErrorHook = (ctx: ErrorContext) => Promise<HookResult | void> | HookResult | void;
+/**
+ * Lifecycle hook definitions for registration
+ */
+export interface LifecycleHooks {
+    onSessionStart?: OnSessionStartHook | OnSessionStartHook[];
+    onSessionEnd?: OnSessionEndHook | OnSessionEndHook[];
+    onOutput?: OnOutputHook | OnOutputHook[];
+    onMessageReceived?: OnMessageReceivedHook | OnMessageReceivedHook[];
+    onMessageSent?: OnMessageSentHook | OnMessageSentHook[];
+    onIdle?: OnIdleHook | OnIdleHook[];
+    onError?: OnErrorHook | OnErrorHook[];
+}
+/**
+ * Lifecycle hook event names
+ */
+export type LifecycleHookEvent = 'sessionStart' | 'sessionEnd' | 'output' | 'messageReceived' | 'messageSent' | 'idle' | 'error';
+/**
+ * Pattern handler for custom namespaces (e.g., @deploy:, @notify:)
+ */
+export type PatternHandler = (target: string, message: string, ctx: HookContext) => Promise<HookResult | void> | HookResult | void;
+/**
+ * Memory configuration for hooks
+ */
+export interface HooksMemoryConfig {
+    /** Memory adapter type: 'inmemory', 'supermemory', etc. */
+    type?: string;
+    /** API key for external memory services */
+    apiKey?: string;
+    /** Custom API endpoint */
+    endpoint?: string;
+    /** Whether to inject memories on session start */
+    injectOnStart?: boolean;
+    /** Maximum memories to inject on start */
+    maxStartMemories?: number;
+    /** Whether to prompt for memory save on session end */
+    promptOnEnd?: boolean;
+    /** Whether to auto-save detected learnings (default: true) */
+    autoSave?: boolean;
+    /** Whether to track learnings for session-end summary (default: true) */
+    autoSaveOnEnd?: boolean;
+}
+/**
+ * Full hooks configuration
+ */
+export interface HooksConfig {
+    /** Lifecycle hooks */
+    hooks?: LifecycleHooks;
+    /** Pattern handlers by namespace */
+    patterns?: Record<string, PatternHandler | 'builtin'>;
+    /** Idle timeout in milliseconds (default: 30000) */
+    idleTimeout?: number;
+    /** Whether to enable trajectory tracking hooks */
+    trajectoryTracking?: boolean;
+    /** Memory system configuration */
+    memory?: HooksMemoryConfig | boolean;
+}
+export declare const HOOK_ABI_VERSION = 1;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Agent Relay Hook Types
+ *
+ * Core types for the agent-relay hooks system. Hooks allow agents to intercept
+ * and modify behavior at various points in the agent lifecycle.
+ */
+import { PROTOCOL_VERSION } from '@agent-relay/protocol';
+// Hook ABI version aligns with protocol wire version
+export const HOOK_ABI_VERSION = PROTOCOL_VERSION;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA4UzD,qDAAqD;AACrD,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agent-relay/hooks",
+  "version": "0.1.0",
+  "description": "Hook emitter, registry, and trajectory hooks for Agent Relay",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./inbox-check": {
+      "types": "./dist/inbox-check/index.d.ts",
+      "import": "./dist/inbox-check/index.js",
+      "default": "./dist/inbox-check/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-relay/protocol": "^0.1.2",
+    "@agent-relay/config": "^0.1.0",
+    "@agent-relay/trajectory": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}