agent-relay 4.0.19 → 4.0.21

package/node_modules/agent-trajectories/dist/index-7tzw_CMS.d.ts

@@ -0,0 +1,1777 @@
+import { z } from 'zod';
+
+/**
+ * Core type definitions for Agent Trajectories
+ *
+ * These types define the shape of all trajectory data.
+ * They are used for TypeScript type checking and documentation.
+ * Runtime validation is handled by Zod schemas in schema.ts.
+ */
+/**
+ * Supported task source systems
+ */
+type TaskSourceSystem = "beads" | "github" | "linear" | "jira" | "plain" | string;
+/**
+ * Reference to an external task/issue
+ */
+interface TaskSource {
+    /** The task management system (e.g., 'github', 'linear') */
+    system: TaskSourceSystem;
+    /** The external ID (e.g., 'GH#123', 'ENG-456') */
+    id: string;
+    /** Optional URL to the external task */
+    url?: string;
+}
+/**
+ * Task reference - either standalone or linked to external system
+ */
+interface TaskReference {
+    /** Human-readable task title */
+    title: string;
+    /** Optional description */
+    description?: string;
+    /** Optional link to external task system */
+    source?: TaskSource;
+}
+/**
+ * Trajectory status
+ */
+type TrajectoryStatus = "active" | "completed" | "abandoned";
+/**
+ * Event types that can be recorded in a trajectory
+ */
+type TrajectoryEventType = "prompt" | "thinking" | "tool_call" | "tool_result" | "message_sent" | "message_received" | "decision" | "finding" | "reflection" | "note" | "error" | (string & {});
+/**
+ * Significance level for events
+ */
+type EventSignificance = "low" | "medium" | "high" | "critical";
+/**
+ * A single event in the trajectory timeline
+ */
+interface TrajectoryEvent {
+    /** Unix timestamp in milliseconds */
+    ts: number;
+    /** Type of event */
+    type: TrajectoryEventType;
+    /** Human-readable summary of the event */
+    content: string;
+    /** Full raw data (optional, for debugging) */
+    raw?: unknown;
+    /** Importance level */
+    significance?: EventSignificance;
+    /** Confidence level for this event (0-1) */
+    confidence?: number;
+    /** User-defined tags */
+    tags?: string[];
+}
+/**
+ * An alternative option that was considered
+ */
+interface Alternative {
+    /** The alternative option */
+    option: string;
+    /** Why this alternative was not chosen */
+    reason?: string;
+}
+/**
+ * A structured decision record
+ */
+interface Decision {
+    /** What was the choice/question? */
+    question: string;
+    /** What was chosen */
+    chosen: string;
+    /** What alternatives were considered */
+    alternatives: Alternative[];
+    /** Why this choice was made */
+    reasoning: string;
+    /** Confidence in this decision (0-1) */
+    confidence?: number;
+}
+/**
+ * Finding category types
+ */
+type FindingCategory = "bug" | "pattern" | "optimization" | "security" | "documentation" | "dependency" | "other";
+/**
+ * A structured finding record - captures discoveries made during exploration
+ */
+interface Finding {
+    /** What was found */
+    what: string;
+    /** Where it was found (file path, component, etc.) */
+    where: string;
+    /** Why this finding is significant */
+    significance: string;
+    /** Category of the finding */
+    category: FindingCategory;
+    /** Suggested action or follow-up */
+    suggestedAction?: string;
+    /** Confidence in this finding (0-1) */
+    confidence?: number;
+}
+/**
+ * Agent participation record
+ */
+interface AgentParticipation {
+    /** Agent identifier */
+    name: string;
+    /**
+     * Role in the trajectory. Common values are "lead", "contributor",
+     * "reviewer", but this is intentionally open-ended — the workforce
+     * workflow runner emits domain-specific roles like "workflow-runner"
+     * and "specialist" that we want to read without rejecting.
+     */
+    role: string;
+    /** When the agent joined */
+    joinedAt: string;
+    /** When the agent left (if applicable) */
+    leftAt?: string;
+}
+/**
+ * A chapter represents a logical phase of work
+ */
+interface Chapter {
+    /** Unique chapter ID */
+    id: string;
+    /** Chapter title (e.g., "Initial exploration", "Implementation") */
+    title: string;
+    /** Which agent is working in this chapter */
+    agentName: string;
+    /** When the chapter started (ISO timestamp) */
+    startedAt: string;
+    /** When the chapter ended (ISO timestamp, undefined if current) */
+    endedAt?: string;
+    /** Events that occurred in this chapter */
+    events: TrajectoryEvent[];
+}
+/**
+ * Retrospective reflection on the completed work
+ */
+interface Retrospective {
+    /** Brief summary of what was accomplished */
+    summary: string;
+    /** How the work was approached */
+    approach: string;
+    /** Key decisions made during the work */
+    decisions?: Decision[];
+    /** What was unexpectedly difficult */
+    challenges?: string[];
+    /** What was learned */
+    learnings?: string[];
+    /** Suggestions for improvement */
+    suggestions?: string[];
+    /** Agent's confidence in the solution (0-1) */
+    confidence: number;
+    /** Total time spent (human-readable) */
+    timeSpent?: string;
+}
+/**
+ * The main Trajectory type - represents the complete record of work on a task
+ */
+interface Trajectory {
+    /** Unique trajectory ID (format: traj_xxxxxxxxxxxx) */
+    id: string;
+    /** Schema version for forward compatibility */
+    version: 1;
+    /** The task being worked on */
+    task: TaskReference;
+    /** Current status */
+    status: TrajectoryStatus;
+    /** When work started (ISO timestamp) */
+    startedAt: string;
+    /** When work completed (ISO timestamp) */
+    completedAt?: string;
+    /** Agents who participated */
+    agents: AgentParticipation[];
+    /** Logical phases of work */
+    chapters: Chapter[];
+    /** Final reflection (only on completion) */
+    retrospective?: Retrospective;
+    /** Git commits produced */
+    commits: string[];
+    /** Files that were modified */
+    filesChanged: string[];
+    /** Project identifier. Optional — legacy trajectories may omit it. */
+    projectId?: string;
+    /** Opaque id set by the workflow runner via TRAJECTORIES_WORKFLOW_ID env var. Lets trail compact --workflow <id> collate all trajectories from a single workflow run. */
+    workflowId?: string;
+    /** User-defined tags */
+    tags: string[];
+    /** Trace information for code attribution */
+    _trace?: TrajectoryTraceRef;
+}
+/**
+ * Summary of a trajectory for listing/indexing
+ */
+interface TrajectorySummary {
+    id: string;
+    title: string;
+    status: TrajectoryStatus;
+    startedAt: string;
+    completedAt?: string;
+    confidence?: number;
+    chapterCount: number;
+    decisionCount: number;
+}
+/**
+ * Input for creating a new trajectory
+ */
+interface CreateTrajectoryInput {
+    /** Task title */
+    title: string;
+    /** Optional task description */
+    description?: string;
+    /** Optional external task reference */
+    source?: TaskSource;
+    /** Optional project ID (defaults to cwd) */
+    projectId?: string;
+    /** Opaque id set by the workflow runner via TRAJECTORIES_WORKFLOW_ID env var. Lets trail compact --workflow <id> collate all trajectories from a single workflow run. */
+    workflowId?: string;
+    /** Optional initial tags */
+    tags?: string[];
+}
+/**
+ * Input for adding a chapter
+ */
+interface AddChapterInput {
+    /** Chapter title */
+    title: string;
+    /** Agent name */
+    agentName: string;
+}
+/**
+ * Input for adding an event
+ */
+interface AddEventInput {
+    /** Event type */
+    type: TrajectoryEventType;
+    /** Human-readable content */
+    content: string;
+    /** Optional raw data */
+    raw?: unknown;
+    /** Optional significance */
+    significance?: EventSignificance;
+    /** Optional tags */
+    tags?: string[];
+}
+/**
+ * Input for completing a trajectory
+ */
+interface CompleteTrajectoryInput {
+    summary: string;
+    approach: string;
+    decisions?: Decision[];
+    challenges?: string[];
+    learnings?: string[];
+    suggestions?: string[];
+    confidence: number;
+}
+/**
+ * Query options for listing trajectories
+ */
+interface TrajectoryQuery {
+    /** Filter by status */
+    status?: TrajectoryStatus;
+    /** Filter by date range */
+    since?: string;
+    until?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort field */
+    sortBy?: "startedAt" | "completedAt" | "title";
+    /** Sort direction */
+    sortOrder?: "asc" | "desc";
+}
+/**
+ * Reference to trace information within a trajectory
+ */
+interface TrajectoryTraceRef {
+    /** Git ref (commit hash) when trace started */
+    startRef: string;
+    /** Git ref (commit hash) when trace ended */
+    endRef?: string;
+    /** ID of the associated trace record */
+    traceId?: string;
+}
+
+/**
+ * Storage adapter interface for trajectory persistence
+ *
+ * This interface defines the contract for storage backends.
+ * Implementations include FileStorage (default) and SQLiteStorage (optional).
+ */
+
+/**
+ * Storage configuration options
+ */
+interface StorageConfig {
+    /** Base directory for file storage */
+    baseDir?: string;
+    /** SQLite database path (for SQLite adapter) */
+    dbPath?: string;
+}
+/**
+ * Abstract storage adapter interface
+ *
+ * All storage implementations must implement this interface.
+ * This allows swapping storage backends without changing business logic.
+ */
+interface StorageAdapter {
+    /**
+     * Initialize the storage backend
+     * Creates necessary directories, tables, etc.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save a trajectory
+     * Creates if new, updates if exists
+     * Moves to completed directory if status is completed
+     * @param trajectory - The trajectory to save
+     */
+    save(trajectory: Trajectory): Promise<void>;
+    /**
+     * Get a trajectory by ID
+     * @param id - Trajectory ID
+     * @returns The trajectory or null if not found
+     */
+    get(id: string): Promise<Trajectory | null>;
+    /**
+     * Get the currently active trajectory
+     * @returns The active trajectory or null if none
+     */
+    getActive(): Promise<Trajectory | null>;
+    /**
+     * List trajectories with optional filtering
+     * @param query - Query options
+     * @returns Array of trajectory summaries
+     */
+    list(query: TrajectoryQuery): Promise<TrajectorySummary[]>;
+    /**
+     * Delete a trajectory
+     * @param id - Trajectory ID to delete
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Search trajectories by text
+     * @param text - Search query
+     * @param options - Search options
+     * @returns Matching trajectory summaries
+     */
+    search(text: string, options?: {
+        limit?: number;
+    }): Promise<TrajectorySummary[]>;
+    /**
+     * Close the storage connection
+     * Clean up resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * Export the StorageAdapter type for use in tests
+ */
+declare const StorageAdapter: StorageAdapter;
+
+/**
+ * Trajectory SDK Client
+ *
+ * High-level client for programmatically creating and managing trajectories.
+ * Provides a clean, developer-friendly API with automatic storage management.
+ */
+
+declare function compactWorkflow(workflowId: string, options?: {
+    markdown?: boolean;
+    mechanical?: boolean;
+    cwd?: string;
+}): Promise<{
+    compactedPath: string;
+    markdownPath?: string;
+}>;
+/**
+ * Options for configuring the TrajectoryClient
+ */
+interface TrajectoryClientOptions {
+    /** Storage adapter to use. Defaults to FileStorage. */
+    storage?: StorageAdapter;
+    /** Base directory for file storage. Defaults to .trajectories */
+    dataDir?: string;
+    /** Default agent name to use when not specified */
+    defaultAgent?: string;
+    /** Default project ID. Defaults to current working directory */
+    projectId?: string;
+    /** Whether to auto-save after each operation. Defaults to true */
+    autoSave?: boolean;
+    /**
+     * When set, session.complete() and session.done() automatically run compactWorkflow() against the trajectory's workflowId. Default false. Pass an object to control the flags passed to the CLI — e.g. { mechanical: true } skips the LLM for deterministic compaction, { markdown: false } skips the .md companion.
+     */
+    autoCompact?: boolean | {
+        mechanical?: boolean;
+        markdown?: boolean;
+    };
+}
+/**
+ * Active trajectory session for chainable operations
+ */
+declare class TrajectorySession {
+    private trajectory;
+    private client;
+    private autoSave;
+    constructor(trajectory: Trajectory, client: TrajectoryClient, autoSave: boolean);
+    /**
+     * Get the current trajectory data
+     */
+    get data(): Trajectory;
+    /**
+     * Get the trajectory ID
+     */
+    get id(): string;
+    private autoCompactIfConfigured;
+    /**
+     * Start a new chapter
+     * @param title - Chapter title
+     * @param agentName - Agent name (uses default if not specified)
+     */
+    chapter(title: string, agentName?: string): Promise<TrajectorySession>;
+    /**
+     * Record an event
+     * @param type - Event type
+     * @param content - Human-readable content
+     * @param options - Additional event options
+     */
+    event(type: TrajectoryEventType, content: string, options?: {
+        raw?: unknown;
+        significance?: EventSignificance;
+        tags?: string[];
+    }): Promise<TrajectorySession>;
+    /**
+     * Record a note
+     */
+    note(content: string, significance?: EventSignificance): Promise<TrajectorySession>;
+    /**
+     * Record a finding
+     */
+    finding(content: string, significance?: EventSignificance): Promise<TrajectorySession>;
+    /**
+     * Record a reflection — a higher-level synthesis of recent observations.
+     * Used by workflow orchestrators and lead agents to periodically
+     * synthesize worker progress and course-correct.
+     */
+    reflect(content: string, confidence?: number): Promise<TrajectorySession>;
+    /**
+     * Record an error
+     */
+    error(content: string): Promise<TrajectorySession>;
+    /**
+     * Record a decision
+     * @param decision - Structured decision record
+     */
+    decision(decision: Decision): Promise<TrajectorySession>;
+    /**
+     * Quick decision helper for simple choices
+     * @param question - What was the question/choice?
+     * @param chosen - What was chosen
+     * @param reasoning - Why this choice was made
+     * @param alternatives - Optional list of alternatives considered
+     */
+    decide(question: string, chosen: string, reasoning: string, alternatives?: Array<{
+        option: string;
+        reason?: string;
+    }>): Promise<TrajectorySession>;
+    /**
+     * Add a tag to the trajectory
+     */
+    tag(tag: string): Promise<TrajectorySession>;
+    /**
+     * Complete the trajectory with a retrospective
+     * @param input - Retrospective details
+     */
+    complete(input: CompleteTrajectoryInput): Promise<Trajectory>;
+    /**
+     * Quick complete with minimal required fields
+     * @param summary - What was accomplished
+     * @param confidence - Confidence level (0-1)
+     * @param options - Additional optional fields
+     */
+    done(summary: string, confidence: number, options?: Partial<Omit<CompleteTrajectoryInput, "summary" | "confidence">>): Promise<Trajectory>;
+    /**
+     * Abandon the trajectory
+     * @param reason - Reason for abandonment
+     */
+    abandon(reason?: string): Promise<Trajectory>;
+    /**
+     * Force save the current state
+     */
+    save(): Promise<void>;
+    /**
+     * Export to markdown
+     */
+    toMarkdown(): string;
+    /**
+     * Export to JSON
+     */
+    toJSON(compact?: boolean): string;
+    /**
+     * Export to timeline format
+     */
+    toTimeline(): string;
+    /**
+     * Export to PR summary format
+     */
+    toPRSummary(): string;
+}
+/**
+ * Main SDK client for trajectory management
+ *
+ * @example
+ * ```typescript
+ * import { TrajectoryClient } from 'agent-trajectories/sdk';
+ *
+ * const client = new TrajectoryClient({ defaultAgent: 'my-agent' });
+ * await client.init();
+ *
+ * // Start a new trajectory
+ * const session = await client.start('Implement feature X');
+ *
+ * // Record work
+ * await session
+ *   .chapter('Research')
+ *   .note('Found relevant documentation')
+ *   .decide('Use library A vs B', 'Library A', 'Better TypeScript support');
+ *
+ * // Complete with retrospective
+ * await session.done('Successfully implemented feature X', 0.9);
+ * ```
+ */
+declare class TrajectoryClient {
+    private storage;
+    private initialized;
+    readonly defaultAgent?: string;
+    private projectId?;
+    private autoSave;
+    private readonly autoCompactCwd?;
+    private readonly autoCompact;
+    constructor(options?: TrajectoryClientOptions);
+    getAutoCompactOptions(): false | {
+        mechanical: boolean;
+        markdown: boolean;
+    };
+    getAutoCompactCwd(): string | undefined;
+    /**
+     * Initialize the client (creates storage directories, etc.)
+     * Must be called before using other methods.
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure the client is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Start a new trajectory
+     * @param title - Task title
+     * @param options - Additional creation options
+     * @returns A session for the new trajectory
+     */
+    start(title: string, options?: Omit<CreateTrajectoryInput, "title">): Promise<TrajectorySession>;
+    /**
+     * Resume the currently active trajectory
+     * @returns Session for active trajectory, or null if none active
+     */
+    resume(): Promise<TrajectorySession | null>;
+    /**
+     * Get the active trajectory (without creating a session)
+     */
+    getActive(): Promise<Trajectory | null>;
+    /**
+     * Get a trajectory by ID
+     * @param id - Trajectory ID
+     */
+    get(id: string): Promise<Trajectory | null>;
+    /**
+     * Open a trajectory session by ID
+     * @param id - Trajectory ID
+     */
+    open(id: string): Promise<TrajectorySession | null>;
+    /**
+     * List trajectories with optional filtering
+     * @param query - Query options
+     */
+    list(query?: TrajectoryQuery): Promise<TrajectorySummary[]>;
+    /**
+     * Search trajectories by text
+     * @param text - Search text
+     * @param limit - Maximum results
+     */
+    search(text: string, limit?: number): Promise<TrajectorySummary[]>;
+    /**
+     * Delete a trajectory
+     * @param id - Trajectory ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Save a trajectory to storage
+     * @param trajectory - Trajectory to save
+     */
+    save(trajectory: Trajectory): Promise<void>;
+    /**
+     * Close the client and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Export a trajectory to markdown
+     * @param id - Trajectory ID
+     */
+    exportMarkdown(id: string): Promise<string | null>;
+    /**
+     * Export a trajectory to JSON
+     * @param id - Trajectory ID
+     * @param compact - Whether to use compact format
+     */
+    exportJSON(id: string, compact?: boolean): Promise<string | null>;
+    /**
+     * Export a trajectory to timeline format
+     * @param id - Trajectory ID
+     */
+    exportTimeline(id: string): Promise<string | null>;
+    /**
+     * Export a trajectory to PR summary format
+     * @param id - Trajectory ID
+     */
+    exportPRSummary(id: string): Promise<string | null>;
+}
+
+/**
+ * Trajectory Builder
+ *
+ * Fluent builder pattern for creating trajectories without storage.
+ * Useful for programmatically constructing trajectories in memory.
+ */
+
+/**
+ * Fluent builder for creating trajectories in memory
+ *
+ * @example
+ * ```typescript
+ * import { TrajectoryBuilder } from 'agent-trajectories/sdk';
+ *
+ * const trajectory = TrajectoryBuilder
+ *   .create('Implement feature X')
+ *   .withDescription('Add new authentication flow')
+ *   .withSource({ system: 'github', id: 'GH#123' })
+ *   .chapter('Research', 'claude')
+ *     .note('Found existing auth patterns')
+ *     .finding('Current implementation uses JWT')
+ *   .chapter('Implementation', 'claude')
+ *     .decide('JWT vs Session', 'JWT', 'Better for API clients')
+ *     .note('Implemented token refresh')
+ *   .complete({
+ *     summary: 'Added JWT-based authentication',
+ *     approach: 'Extended existing auth module',
+ *     confidence: 0.95
+ *   });
+ *
+ * console.log(trajectory.toMarkdown());
+ * ```
+ */
+declare class TrajectoryBuilder {
+    private trajectory;
+    private constructor();
+    /**
+     * Create a new trajectory builder
+     * @param title - Task title
+     */
+    static create(title: string): TrajectoryBuilder;
+    /**
+     * Set the task description
+     */
+    withDescription(description: string): TrajectoryBuilder;
+    /**
+     * Set the external task source
+     */
+    withSource(source: TaskSource): TrajectoryBuilder;
+    /**
+     * Set the project ID
+     */
+    withProject(projectId: string): TrajectoryBuilder;
+    /**
+     * Add tags
+     */
+    withTags(...tags: string[]): TrajectoryBuilder;
+    /**
+     * Add a single tag
+     */
+    tag(tag: string): TrajectoryBuilder;
+    /**
+     * Start a new chapter
+     * @param title - Chapter title
+     * @param agentName - Agent name
+     */
+    chapter(title: string, agentName: string): TrajectoryBuilder;
+    /**
+     * Add a generic event
+     */
+    event(type: TrajectoryEventType, content: string, options?: {
+        raw?: unknown;
+        significance?: EventSignificance;
+        tags?: string[];
+    }): TrajectoryBuilder;
+    /**
+     * Add a note event
+     */
+    note(content: string, significance?: EventSignificance): TrajectoryBuilder;
+    /**
+     * Add a finding event
+     */
+    finding(content: string, significance?: EventSignificance): TrajectoryBuilder;
+    /**
+     * Add a reflection event — a higher-level synthesis of recent observations.
+     * Reflections are always high significance since they represent
+     * periodic course-correction insights.
+     */
+    reflect(content: string, confidence?: number): TrajectoryBuilder;
+    /**
+     * Add an error event
+     */
+    error(content: string): TrajectoryBuilder;
+    /**
+     * Add a thinking event
+     */
+    thinking(content: string): TrajectoryBuilder;
+    /**
+     * Add a tool call event
+     */
+    toolCall(content: string, raw?: unknown): TrajectoryBuilder;
+    /**
+     * Add a tool result event
+     */
+    toolResult(content: string, raw?: unknown): TrajectoryBuilder;
+    /**
+     * Add a prompt event
+     */
+    prompt(content: string): TrajectoryBuilder;
+    /**
+     * Add a message sent event
+     */
+    messageSent(content: string): TrajectoryBuilder;
+    /**
+     * Add a message received event
+     */
+    messageReceived(content: string): TrajectoryBuilder;
+    /**
+     * Add a structured decision
+     */
+    decision(decision: Decision): TrajectoryBuilder;
+    /**
+     * Quick decision helper
+     */
+    decide(question: string, chosen: string, reasoning: string, alternatives?: Array<{
+        option: string;
+        reason?: string;
+    }>): TrajectoryBuilder;
+    /**
+     * Record git commits
+     */
+    commits(...hashes: string[]): TrajectoryBuilder;
+    /**
+     * Record files changed
+     */
+    filesChanged(...paths: string[]): TrajectoryBuilder;
+    /**
+     * Complete the trajectory with a retrospective
+     * @param input - Retrospective details
+     * @returns The completed trajectory
+     */
+    complete(input: CompleteTrajectoryInput): Trajectory;
+    /**
+     * Quick complete with minimal fields
+     */
+    done(summary: string, confidence: number, approach?: string): Trajectory;
+    /**
+     * Abandon the trajectory
+     */
+    abandon(reason?: string): Trajectory;
+    /**
+     * Get the current trajectory (without completing)
+     */
+    build(): Trajectory;
+    /**
+     * Export to markdown
+     */
+    toMarkdown(): string;
+    /**
+     * Export to JSON
+     */
+    toJSON(compact?: boolean): string;
+    /**
+     * Export to timeline format
+     */
+    toTimeline(): string;
+    /**
+     * Export to PR summary format
+     */
+    toPRSummary(): string;
+}
+/**
+ * Shorthand function to create a trajectory builder
+ *
+ * @example
+ * ```typescript
+ * import { trajectory } from 'agent-trajectories/sdk';
+ *
+ * const result = trajectory('Fix bug in auth')
+ *   .chapter('Investigation', 'claude')
+ *   .finding('Found null pointer in login handler')
+ *   .done('Fixed null pointer exception', 0.95);
+ * ```
+ */
+declare function trajectory(title: string): TrajectoryBuilder;
+
+/**
+ * Trajectory operations
+ *
+ * Pure functions for creating and manipulating trajectories.
+ * These functions return new trajectory objects (immutable updates).
+ */
+
+/**
+ * Custom error class for trajectory operations
+ */
+declare class TrajectoryError extends Error {
+    code: string;
+    suggestion?: string | undefined;
+    constructor(message: string, code: string, suggestion?: string | undefined);
+}
+/**
+ * Create a new trajectory
+ * @param input - Trajectory creation input
+ * @returns New trajectory object
+ * @throws TrajectoryError if validation fails
+ */
+declare function createTrajectory(input: CreateTrajectoryInput): Trajectory;
+/**
+ * Add a chapter to a trajectory
+ * @param trajectory - The trajectory to update
+ * @param input - Chapter creation input
+ * @returns Updated trajectory with new chapter
+ * @throws TrajectoryError if trajectory is completed
+ */
+declare function addChapter(trajectory: Trajectory, input: AddChapterInput): Trajectory;
+/**
+ * Add an event to the current chapter
+ * Auto-creates a chapter if none exists
+ * @param trajectory - The trajectory to update
+ * @param input - Event creation input
+ * @returns Updated trajectory with new event
+ */
+declare function addEvent(trajectory: Trajectory, input: AddEventInput): Trajectory;
+/**
+ * Add a structured decision to the trajectory
+ * @param trajectory - The trajectory to update
+ * @param decision - Decision details
+ * @returns Updated trajectory with decision event
+ */
+declare function addDecision(trajectory: Trajectory, decision: Decision): Trajectory;
+/**
+ * Complete a trajectory with retrospective
+ * @param trajectory - The trajectory to complete
+ * @param input - Retrospective input
+ * @returns Completed trajectory
+ * @throws TrajectoryError if already completed or validation fails
+ */
+declare function completeTrajectory(trajectory: Trajectory, input: CompleteTrajectoryInput): Trajectory;
+/**
+ * Abandon a trajectory without completing
+ * @param trajectory - The trajectory to abandon
+ * @param reason - Reason for abandonment
+ * @returns Abandoned trajectory
+ */
+declare function abandonTrajectory(trajectory: Trajectory, reason?: string): Trajectory;
+
+/**
+ * File system storage adapter for trajectories
+ *
+ * Stores trajectories as JSON files in a .trajectories directory.
+ * Active trajectories go in active/, completed in completed/YYYY-MM/.
+ */
+
+/**
+ * Aggregated counts emitted by reconcileIndex for observability. Exposed
+ * on the return value so tests and callers can assert on counts without
+ * parsing log output.
+ */
+interface ReconcileSummary {
+    scanned: number;
+    added: number;
+    alreadyIndexed: number;
+    skippedMalformedJson: number;
+    skippedSchemaViolation: number;
+    skippedIoError: number;
+}
+/**
+ * File system storage adapter
+ */
+declare class FileStorage implements StorageAdapter {
+    private baseDir;
+    private trajectoriesDir;
+    private activeDir;
+    private completedDir;
+    private indexPath;
+    constructor(baseDir?: string);
+    /**
+     * Initialize storage directories
+     */
+    initialize(): Promise<void>;
+    /**
+     * Scan active/ and completed/ recursively and add any trajectory files
+     * missing from the index. Existing entries are preserved — reconcile
+     * only adds, never removes.
+     *
+     * Handles three on-disk layouts in completed/:
+     *   - flat:      completed/{id}.json         (legacy workforce data)
+     *   - monthly:   completed/YYYY-MM/{id}.json (current save() writes)
+     *   - nested:    completed/.../{id}.json     (defensive — any depth)
+     *
+     * Returns a ReconcileSummary so tests and CLI wrappers can observe
+     * outcomes without parsing logs. Only writes the index if anything was
+     * added.
+     */
+    reconcileIndex(): Promise<ReconcileSummary>;
+    /**
+     * Recursively collect all .json file paths under `dir` into `out`.
+     * Silently treats a missing directory as empty.
+     */
+    private walkJsonFilesInto;
+    /**
+     * Save a trajectory.
+     *
+     * Validates the input against the trajectory schema before touching
+     * disk. Closes the historical read/write asymmetry where save() would
+     * happily write data that the reader then rejected, producing files
+     * that could never be loaded back.
+     */
+    save(input: Trajectory): Promise<void>;
+    /**
+     * Get a trajectory by ID
+     */
+    get(id: string): Promise<Trajectory | null>;
+    /**
+     * Get the currently active trajectory
+     */
+    getActive(): Promise<Trajectory | null>;
+    /**
+     * List trajectories with optional filtering
+     */
+    list(query: TrajectoryQuery): Promise<TrajectorySummary[]>;
+    /**
+     * Delete a trajectory
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Search trajectories by text
+     */
+    search(text: string, options?: {
+        limit?: number;
+    }): Promise<TrajectorySummary[]>;
+    /**
+     * Close storage (no-op for file storage)
+     */
+    close(): Promise<void>;
+    /**
+     * Read a trajectory file and return a tagged result so callers can
+     * distinguish missing files, malformed JSON, and schema violations.
+     *
+     * Does NOT log. Callers choose whether to warn, swallow, or throw.
+     */
+    private readTrajectoryFile;
+    /**
+     * Convenience wrapper for callers that only care whether they got a
+     * trajectory. Returns null for any failure and writes nothing to the
+     * console — so nothing leaks into test output or the CLI spinner.
+     */
+    private readTrajectoryOrNull;
+    private loadIndex;
+    private saveIndex;
+    private updateIndex;
+}
+
+/**
+ * Zod schemas for runtime validation of trajectory data
+ *
+ * These schemas validate input at system boundaries and ensure
+ * data integrity when reading from storage.
+ */
+
+/**
+ * Decision schema
+ * Note: alternatives supports both string[] (legacy) and Alternative[] (new)
+ */
+declare const DecisionSchema: z.ZodObject<{
+    question: z.ZodString;
+    chosen: z.ZodString;
+    alternatives: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        option: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        option: string;
+        reason?: string | undefined;
+    }, {
+        option: string;
+        reason?: string | undefined;
+    }>]>, "many">;
+    reasoning: z.ZodString;
+    confidence: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    chosen: string;
+    alternatives: (string | {
+        option: string;
+        reason?: string | undefined;
+    })[];
+    reasoning: string;
+    confidence?: number | undefined;
+}, {
+    question: string;
+    chosen: string;
+    alternatives: (string | {
+        option: string;
+        reason?: string | undefined;
+    })[];
+    reasoning: string;
+    confidence?: number | undefined;
+}>;
+/**
+ * Full trajectory schema
+ */
+declare const TrajectorySchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodLiteral<1>;
+    task: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodObject<{
+            system: z.ZodUnion<[z.ZodLiteral<"beads">, z.ZodLiteral<"github">, z.ZodLiteral<"linear">, z.ZodLiteral<"jira">, z.ZodLiteral<"plain">, z.ZodString]>;
+            id: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        }, {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        description?: string | undefined;
+        source?: {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        } | undefined;
+    }, {
+        title: string;
+        description?: string | undefined;
+        source?: {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        } | undefined;
+    }>;
+    status: z.ZodEnum<["active", "completed", "abandoned"]>;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    agents: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodString;
+        joinedAt: z.ZodString;
+        leftAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        role: string;
+        joinedAt: string;
+        leftAt?: string | undefined;
+    }, {
+        name: string;
+        role: string;
+        joinedAt: string;
+        leftAt?: string | undefined;
+    }>, "many">;
+    chapters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        agentName: z.ZodString;
+        startedAt: z.ZodString;
+        endedAt: z.ZodOptional<z.ZodString>;
+        events: z.ZodArray<z.ZodObject<{
+            ts: z.ZodNumber;
+            type: z.ZodUnion<[z.ZodLiteral<"prompt">, z.ZodLiteral<"thinking">, z.ZodLiteral<"tool_call">, z.ZodLiteral<"tool_result">, z.ZodLiteral<"message_sent">, z.ZodLiteral<"message_received">, z.ZodLiteral<"decision">, z.ZodLiteral<"finding">, z.ZodLiteral<"reflection">, z.ZodLiteral<"note">, z.ZodLiteral<"error">, z.ZodString]>;
+            content: z.ZodString;
+            raw: z.ZodOptional<z.ZodUnknown>;
+            significance: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            confidence: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }, {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        agentName: string;
+        startedAt: string;
+        events: {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }[];
+        endedAt?: string | undefined;
+    }, {
+        id: string;
+        title: string;
+        agentName: string;
+        startedAt: string;
+        events: {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }[];
+        endedAt?: string | undefined;
+    }>, "many">;
+    retrospective: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodString;
+        approach: z.ZodString;
+        decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            question: z.ZodString;
+            chosen: z.ZodString;
+            alternatives: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                option: z.ZodString;
+                reason: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                option: string;
+                reason?: string | undefined;
+            }, {
+                option: string;
+                reason?: string | undefined;
+            }>]>, "many">;
+            reasoning: z.ZodString;
+            confidence: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }, {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }>, "many">>;
+        challenges: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        learnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        confidence: z.ZodNumber;
+        timeSpent: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        confidence: number;
+        summary: string;
+        approach: string;
+        decisions?: {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }[] | undefined;
+        challenges?: string[] | undefined;
+        learnings?: string[] | undefined;
+        suggestions?: string[] | undefined;
+        timeSpent?: string | undefined;
+    }, {
+        confidence: number;
+        summary: string;
+        approach: string;
+        decisions?: {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }[] | undefined;
+        challenges?: string[] | undefined;
+        learnings?: string[] | undefined;
+        suggestions?: string[] | undefined;
+        timeSpent?: string | undefined;
+    }>>;
+    commits: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    filesChanged: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    projectId: z.ZodOptional<z.ZodString>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    _trace: z.ZodOptional<z.ZodObject<{
+        startRef: z.ZodString;
+        endRef: z.ZodOptional<z.ZodString>;
+        traceId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        startRef: string;
+        endRef?: string | undefined;
+        traceId?: string | undefined;
+    }, {
+        startRef: string;
+        endRef?: string | undefined;
+        traceId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    status: "active" | "completed" | "abandoned";
+    id: string;
+    tags: string[];
+    startedAt: string;
+    version: 1;
+    task: {
+        title: string;
+        description?: string | undefined;
+        source?: {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        } | undefined;
+    };
+    agents: {
+        name: string;
+        role: string;
+        joinedAt: string;
+        leftAt?: string | undefined;
+    }[];
+    chapters: {
+        id: string;
+        title: string;
+        agentName: string;
+        startedAt: string;
+        events: {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }[];
+        endedAt?: string | undefined;
+    }[];
+    commits: string[];
+    filesChanged: string[];
+    completedAt?: string | undefined;
+    retrospective?: {
+        confidence: number;
+        summary: string;
+        approach: string;
+        decisions?: {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }[] | undefined;
+        challenges?: string[] | undefined;
+        learnings?: string[] | undefined;
+        suggestions?: string[] | undefined;
+        timeSpent?: string | undefined;
+    } | undefined;
+    projectId?: string | undefined;
+    workflowId?: string | undefined;
+    _trace?: {
+        startRef: string;
+        endRef?: string | undefined;
+        traceId?: string | undefined;
+    } | undefined;
+}, {
+    status: "active" | "completed" | "abandoned";
+    id: string;
+    startedAt: string;
+    version: 1;
+    task: {
+        title: string;
+        description?: string | undefined;
+        source?: {
+            system: string;
+            id: string;
+            url?: string | undefined;
+        } | undefined;
+    };
+    agents: {
+        name: string;
+        role: string;
+        joinedAt: string;
+        leftAt?: string | undefined;
+    }[];
+    chapters: {
+        id: string;
+        title: string;
+        agentName: string;
+        startedAt: string;
+        events: {
+            type: string;
+            ts: number;
+            content: string;
+            raw?: unknown;
+            significance?: "low" | "medium" | "high" | "critical" | undefined;
+            tags?: string[] | undefined;
+            confidence?: number | undefined;
+        }[];
+        endedAt?: string | undefined;
+    }[];
+    tags?: string[] | undefined;
+    completedAt?: string | undefined;
+    retrospective?: {
+        confidence: number;
+        summary: string;
+        approach: string;
+        decisions?: {
+            question: string;
+            chosen: string;
+            alternatives: (string | {
+                option: string;
+                reason?: string | undefined;
+            })[];
+            reasoning: string;
+            confidence?: number | undefined;
+        }[] | undefined;
+        challenges?: string[] | undefined;
+        learnings?: string[] | undefined;
+        suggestions?: string[] | undefined;
+        timeSpent?: string | undefined;
+    } | undefined;
+    commits?: string[] | undefined;
+    filesChanged?: string[] | undefined;
+    projectId?: string | undefined;
+    workflowId?: string | undefined;
+    _trace?: {
+        startRef: string;
+        endRef?: string | undefined;
+        traceId?: string | undefined;
+    } | undefined;
+}>;
+/**
+ * Create trajectory input schema
+ */
+declare const CreateTrajectoryInputSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        system: z.ZodUnion<[z.ZodLiteral<"beads">, z.ZodLiteral<"github">, z.ZodLiteral<"linear">, z.ZodLiteral<"jira">, z.ZodLiteral<"plain">, z.ZodString]>;
+        id: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        system: string;
+        id: string;
+        url?: string | undefined;
+    }, {
+        system: string;
+        id: string;
+        url?: string | undefined;
+    }>>;
+    projectId: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    description?: string | undefined;
+    source?: {
+        system: string;
+        id: string;
+        url?: string | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+    projectId?: string | undefined;
+}, {
+    title: string;
+    description?: string | undefined;
+    source?: {
+        system: string;
+        id: string;
+        url?: string | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+    projectId?: string | undefined;
+}>;
+/**
+ * Complete trajectory input schema
+ */
+declare const CompleteTrajectoryInputSchema: z.ZodObject<{
+    summary: z.ZodString;
+    approach: z.ZodString;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        chosen: z.ZodString;
+        alternatives: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            option: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            option: string;
+            reason?: string | undefined;
+        }, {
+            option: string;
+            reason?: string | undefined;
+        }>]>, "many">;
+        reasoning: z.ZodString;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }, {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }>, "many">>;
+    challenges: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    learnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    confidence: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    confidence: number;
+    summary: string;
+    approach: string;
+    decisions?: {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    challenges?: string[] | undefined;
+    learnings?: string[] | undefined;
+    suggestions?: string[] | undefined;
+}, {
+    confidence: number;
+    summary: string;
+    approach: string;
+    decisions?: {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    challenges?: string[] | undefined;
+    learnings?: string[] | undefined;
+    suggestions?: string[] | undefined;
+}>;
+/**
+ * Validate a trajectory object
+ * @param data - The data to validate
+ * @returns Validation result with success flag and errors
+ */
+declare function validateTrajectory(data: unknown): {
+    success: boolean;
+    data?: z.infer<typeof TrajectorySchema>;
+    errors?: z.ZodError;
+};
+/**
+ * Validate create trajectory input
+ */
+declare function validateCreateInput(data: unknown): {
+    success: boolean;
+    data?: z.infer<typeof CreateTrajectoryInputSchema>;
+    errors?: z.ZodError;
+};
+/**
+ * Validate complete trajectory input
+ */
+declare function validateCompleteInput(data: unknown): {
+    success: boolean;
+    data?: z.infer<typeof CompleteTrajectoryInputSchema>;
+    errors?: z.ZodError;
+};
+/**
+ * Trajectory event schema
+ */
+declare const TrajectoryEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+    type: z.ZodUnion<[z.ZodLiteral<"prompt">, z.ZodLiteral<"thinking">, z.ZodLiteral<"tool_call">, z.ZodLiteral<"tool_result">, z.ZodLiteral<"message_sent">, z.ZodLiteral<"message_received">, z.ZodLiteral<"decision">, z.ZodLiteral<"finding">, z.ZodLiteral<"reflection">, z.ZodLiteral<"note">, z.ZodLiteral<"error">, z.ZodString]>;
+    content: z.ZodString;
+    raw: z.ZodOptional<z.ZodUnknown>;
+    significance: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    ts: number;
+    content: string;
+    raw?: unknown;
+    significance?: "low" | "medium" | "high" | "critical" | undefined;
+    tags?: string[] | undefined;
+    confidence?: number | undefined;
+}, {
+    type: string;
+    ts: number;
+    content: string;
+    raw?: unknown;
+    significance?: "low" | "medium" | "high" | "critical" | undefined;
+    tags?: string[] | undefined;
+    confidence?: number | undefined;
+}>;
+type TrajectoryEventSchema = z.infer<typeof TrajectoryEventSchema>;
+/**
+ * Chapter schema
+ */
+declare const ChapterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    agentName: z.ZodString;
+    startedAt: z.ZodString;
+    endedAt: z.ZodOptional<z.ZodString>;
+    events: z.ZodArray<z.ZodObject<{
+        ts: z.ZodNumber;
+        type: z.ZodUnion<[z.ZodLiteral<"prompt">, z.ZodLiteral<"thinking">, z.ZodLiteral<"tool_call">, z.ZodLiteral<"tool_result">, z.ZodLiteral<"message_sent">, z.ZodLiteral<"message_received">, z.ZodLiteral<"decision">, z.ZodLiteral<"finding">, z.ZodLiteral<"reflection">, z.ZodLiteral<"note">, z.ZodLiteral<"error">, z.ZodString]>;
+        content: z.ZodString;
+        raw: z.ZodOptional<z.ZodUnknown>;
+        significance: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        ts: number;
+        content: string;
+        raw?: unknown;
+        significance?: "low" | "medium" | "high" | "critical" | undefined;
+        tags?: string[] | undefined;
+        confidence?: number | undefined;
+    }, {
+        type: string;
+        ts: number;
+        content: string;
+        raw?: unknown;
+        significance?: "low" | "medium" | "high" | "critical" | undefined;
+        tags?: string[] | undefined;
+        confidence?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    agentName: string;
+    startedAt: string;
+    events: {
+        type: string;
+        ts: number;
+        content: string;
+        raw?: unknown;
+        significance?: "low" | "medium" | "high" | "critical" | undefined;
+        tags?: string[] | undefined;
+        confidence?: number | undefined;
+    }[];
+    endedAt?: string | undefined;
+}, {
+    id: string;
+    title: string;
+    agentName: string;
+    startedAt: string;
+    events: {
+        type: string;
+        ts: number;
+        content: string;
+        raw?: unknown;
+        significance?: "low" | "medium" | "high" | "critical" | undefined;
+        tags?: string[] | undefined;
+        confidence?: number | undefined;
+    }[];
+    endedAt?: string | undefined;
+}>;
+type ChapterSchema = z.infer<typeof ChapterSchema>;
+/**
+ * Retrospective schema
+ */
+declare const RetrospectiveSchema: z.ZodObject<{
+    summary: z.ZodString;
+    approach: z.ZodString;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        chosen: z.ZodString;
+        alternatives: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            option: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            option: string;
+            reason?: string | undefined;
+        }, {
+            option: string;
+            reason?: string | undefined;
+        }>]>, "many">;
+        reasoning: z.ZodString;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }, {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }>, "many">>;
+    challenges: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    learnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    confidence: z.ZodNumber;
+    timeSpent: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    confidence: number;
+    summary: string;
+    approach: string;
+    decisions?: {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    challenges?: string[] | undefined;
+    learnings?: string[] | undefined;
+    suggestions?: string[] | undefined;
+    timeSpent?: string | undefined;
+}, {
+    confidence: number;
+    summary: string;
+    approach: string;
+    decisions?: {
+        question: string;
+        chosen: string;
+        alternatives: (string | {
+            option: string;
+            reason?: string | undefined;
+        })[];
+        reasoning: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    challenges?: string[] | undefined;
+    learnings?: string[] | undefined;
+    suggestions?: string[] | undefined;
+    timeSpent?: string | undefined;
+}>;
+type RetrospectiveSchema = z.infer<typeof RetrospectiveSchema>;
+
+/**
+ * Git trailer utilities for linking commits to trajectories
+ *
+ * Appends structured metadata to commit messages using git's trailer convention:
+ *   Trajectory: traj_xxxxxxxxxxxx
+ *
+ * This creates a bidirectional link: trajectories reference commits,
+ * and commits reference trajectories.
+ */
+/** Trailer key for trajectory ID */
+declare const TRAJECTORY_TRAILER_KEY = "Trajectory";
+/**
+ * Format a trajectory trailer for appending to a commit message
+ * @param trajectoryId - The trajectory ID to link
+ * @returns Formatted trailer string (e.g., "Trajectory: traj_abc123")
+ */
+declare function formatTrailer(trajectoryId: string): string;
+/**
+ * Parse trajectory ID from a commit message's trailers
+ * @param commitMessage - Full commit message text
+ * @returns The trajectory ID if found, null otherwise
+ */
+declare function parseTrajectoryFromMessage(commitMessage: string): string | null;
+/**
+ * Get the trajectory ID linked to a specific commit
+ * @param commitHash - Git commit hash
+ * @returns The trajectory ID if found, null otherwise
+ */
+declare function getTrajectoryFromCommit(commitHash: string): string | null;
+/**
+ * Commit info returned by getCommitsBetween
+ */
+interface CommitInfo {
+    /** Short commit hash */
+    hash: string;
+    /** Full commit hash */
+    fullHash: string;
+    /** Commit subject line */
+    subject: string;
+    /** Commit author */
+    author: string;
+    /** Commit timestamp (ISO) */
+    date: string;
+}
+/**
+ * Get all commits between two git refs
+ * @param startRef - Starting commit (exclusive)
+ * @param endRef - Ending commit (inclusive, defaults to HEAD)
+ * @returns Array of commit info objects
+ */
+declare function getCommitsBetween(startRef: string, endRef?: string): CommitInfo[];
+/**
+ * Get file paths changed between two git refs
+ * @param startRef - Starting commit (exclusive)
+ * @param endRef - Ending commit (inclusive, defaults to HEAD)
+ * @returns Array of changed file paths
+ */
+declare function getFilesChangedBetween(startRef: string, endRef?: string): string[];
+
+export { type AddChapterInput as A, addDecision as B, type Chapter as C, type Decision as D, type EventSignificance as E, FileStorage as F, addEvent as G, completeTrajectory as H, createTrajectory as I, formatTrailer as J, getCommitsBetween as K, getFilesChangedBetween as L, getTrajectoryFromCommit as M, parseTrajectoryFromMessage as N, trajectory as O, validateCompleteInput as P, validateCreateInput as Q, type Retrospective as R, StorageAdapter as S, type Trajectory as T, validateTrajectory as U, type Alternative as V, type Finding as W, type FindingCategory as X, compactWorkflow as Y, type AddEventInput as a, type AgentParticipation as b, ChapterSchema as c, type CommitInfo as d, type CompleteTrajectoryInput as e, type CreateTrajectoryInput as f, DecisionSchema as g, RetrospectiveSchema as h, type StorageConfig as i, TRAJECTORY_TRAILER_KEY as j, type TaskReference as k, type TaskSource as l, TrajectoryBuilder as m, TrajectoryClient as n, type TrajectoryClientOptions as o, TrajectoryError as p, type TrajectoryEvent as q, TrajectoryEventSchema as r, type TrajectoryEventType as s, type TrajectoryQuery as t, TrajectorySchema as u, TrajectorySession as v, type TrajectoryStatus as w, type TrajectorySummary as x, abandonTrajectory as y, addChapter as z };