@agent-relay/trajectory 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './integration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './integration.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/integration.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Trajectory Integration Module
+ *
+ * Integrates with the agent-trajectories package to provide
+ * PDERO paradigm tracking within agent-relay.
+ *
+ * This module provides a bridge between agent-relay and the
+ * external `trail` CLI / agent-trajectories library.
+ *
+ * Key integration points:
+ * - Auto-starts trajectory when agent is instantiated with a task
+ * - Records all inter-agent messages
+ * - Auto-detects PDERO phase transitions from output
+ * - Provides hooks for key agent lifecycle events
+ */
+/**
+ * PDERO phases for agent work lifecycle
+ */
+export type PDEROPhase = 'plan' | 'design' | 'execute' | 'review' | 'observe';
+/**
+ * Options for starting a trajectory
+ */
+export interface StartTrajectoryOptions {
+    task: string;
+    taskId?: string;
+    source?: string;
+    agentName: string;
+    phase?: PDEROPhase;
+}
+/**
+ * Options for completing a trajectory
+ */
+export interface CompleteTrajectoryOptions {
+    summary?: string;
+    confidence?: number;
+    challenges?: string[];
+    learnings?: string[];
+}
+/**
+ * Options for recording a decision
+ */
+export interface DecisionOptions {
+    choice: string;
+    question?: string;
+    alternatives?: string[];
+    reasoning?: string;
+    confidence?: number;
+}
+/**
+ * Check if trail CLI is available
+ */
+export declare function isTrailAvailable(): Promise<boolean>;
+/**
+ * Start a new trajectory
+ */
+export declare function startTrajectory(options: StartTrajectoryOptions): Promise<{
+    success: boolean;
+    trajectoryId?: string;
+    error?: string;
+}>;
+/**
+ * Get current trajectory status
+ * Reads directly from .trajectories/index.json instead of using CLI
+ */
+export declare function getTrajectoryStatus(): Promise<{
+    active: boolean;
+    trajectoryId?: string;
+    phase?: PDEROPhase;
+    task?: string;
+}>;
+/**
+ * Transition to a new PDERO phase
+ */
+export declare function transitionPhase(phase: PDEROPhase, reason?: string, agentName?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Record a decision
+ */
+export declare function recordDecision(options: DecisionOptions): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Record an event/observation
+ */
+export declare function recordEvent(content: string, type?: 'tool_call' | 'observation' | 'checkpoint' | 'error', agentName?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Record a message (sent or received)
+ */
+export declare function recordMessage(direction: 'sent' | 'received', from: string, to: string, body: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Complete the current trajectory
+ */
+export declare function completeTrajectory(options?: CompleteTrajectoryOptions): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Abandon the current trajectory
+ */
+export declare function abandonTrajectory(reason?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Trajectory step for dashboard display
+ */
+export interface TrajectoryStepData {
+    id: string;
+    timestamp: string | number;
+    type: 'tool_call' | 'decision' | 'message' | 'state_change' | 'error' | 'phase_transition';
+    phase?: PDEROPhase;
+    title: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    duration?: number;
+    status?: 'pending' | 'running' | 'success' | 'error';
+}
+/**
+ * List trajectory steps/events
+ * Returns steps for the current or specified trajectory
+ * Reads directly from filesystem instead of using CLI
+ */
+export declare function listTrajectorySteps(trajectoryId?: string): Promise<{
+    success: boolean;
+    steps: TrajectoryStepData[];
+    error?: string;
+}>;
+/**
+ * Trajectory history entry for dashboard display
+ */
+export interface TrajectoryHistoryEntry {
+    id: string;
+    title: string;
+    status: 'active' | 'completed' | 'abandoned';
+    startedAt: string;
+    completedAt?: string;
+    agents?: string[];
+    summary?: string;
+    confidence?: number;
+}
+/**
+ * Get trajectory history - list all trajectories
+ * Reads directly from filesystem
+ */
+export declare function getTrajectoryHistory(): Promise<{
+    success: boolean;
+    trajectories: TrajectoryHistoryEntry[];
+    error?: string;
+}>;
+/**
+ * Detect PDERO phase from content
+ */
+export declare function detectPhaseFromContent(content: string): PDEROPhase | undefined;
+/**
+ * Detected tool call information
+ */
+export interface DetectedToolCall {
+    tool: string;
+    args?: string;
+    status?: 'started' | 'completed' | 'failed';
+}
+/**
+ * Detected error information
+ */
+export interface DetectedError {
+    type: 'error' | 'warning' | 'failure';
+    message: string;
+    stack?: string;
+}
+/**
+ * Detect tool calls from agent output
+ *
+ * @example
+ * ```typescript
+ * const tools = detectToolCalls(output);
+ * // Returns: [{ tool: 'Read', args: 'file.ts' }, { tool: 'Bash', status: 'completed' }]
+ * ```
+ */
+export declare function detectToolCalls(content: string): DetectedToolCall[];
+/**
+ * Detect errors from agent output
+ *
+ * @example
+ * ```typescript
+ * const errors = detectErrors(output);
+ * // Returns: [{ type: 'error', message: 'TypeError: Cannot read property...' }]
+ * ```
+ */
+export declare function detectErrors(content: string): DetectedError[];
+/**
+ * TrajectoryIntegration class for managing trajectory state
+ *
+ * This class enforces trajectory tracking during agent lifecycle:
+ * - Auto-starts trajectory when agent is instantiated with a task
+ * - Records all inter-agent messages
+ * - Auto-detects PDERO phase transitions
+ * - Provides lifecycle hooks for tmux/pty wrappers
+ */
+export declare class TrajectoryIntegration {
+    private projectId;
+    private agentName;
+    private trailAvailable;
+    private currentPhase;
+    private trajectoryId;
+    private initialized;
+    private task;
+    constructor(projectId: string, agentName: string);
+    /**
+     * Check if trail is available (cached)
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if trail CLI is installed synchronously
+     */
+    isTrailInstalledSync(): boolean;
+    /**
+     * Initialize trajectory tracking for agent lifecycle
+     * Called automatically when agent starts with a task
+     */
+    initialize(task?: string, taskId?: string, source?: string): Promise<boolean>;
+    /**
+     * Start tracking a trajectory
+     */
+    start(task: string, taskId?: string, source?: string): Promise<boolean>;
+    /**
+     * Check if there's an active trajectory
+     */
+    hasActiveTrajectory(): boolean;
+    /**
+     * Get the current task
+     */
+    getTask(): string | null;
+    /**
+     * Get trajectory ID
+     */
+    getTrajectoryId(): string | null;
+    /**
+     * Record a message
+     */
+    message(direction: 'sent' | 'received', from: string, to: string, body: string): Promise<void>;
+    /**
+     * Transition to a new phase
+     */
+    transition(phase: PDEROPhase, reason?: string): Promise<boolean>;
+    /**
+     * Record a decision
+     */
+    decision(choice: string, options?: Partial<DecisionOptions>): Promise<boolean>;
+    /**
+     * Record an event
+     */
+    event(content: string, type?: 'tool_call' | 'observation' | 'checkpoint' | 'error'): Promise<boolean>;
+    /**
+     * Complete the trajectory
+     */
+    complete(options?: CompleteTrajectoryOptions): Promise<boolean>;
+    /**
+     * Abandon the trajectory
+     */
+    abandon(reason?: string): Promise<boolean>;
+    /**
+     * Get current phase
+     */
+    getPhase(): PDEROPhase | null;
+}
+/**
+ * Get or create a TrajectoryIntegration instance
+ */
+export declare function getTrajectoryIntegration(projectId: string, agentName: string): TrajectoryIntegration;
+/**
+ * Generate trail usage instructions for agents
+ */
+export declare function getTrailInstructions(): string[];
+/**
+ * Get a compact trail instruction string for injection
+ */
+export declare function getCompactTrailInstructions(): string;
+/**
+ * Get environment variables for trail CLI
+ * If dataDir is not provided, uses config-based storage location
+ */
+export declare function getTrailEnvVars(projectId: string, agentName: string, dataDir?: string): Record<string, string>;
+//# sourceMappingURL=integration.d.ts.map

package/dist/integration.d.ts.map

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