limen-ai 1.0.0

package/dist/reference-agent/reference_agent.d.ts

@@ -0,0 +1,130 @@
+/**
+ * ReferenceAgent -- the cognitive agent entry point and execution orchestrator.
+ * S ref: S41 (UC-10, UC-11, UC-12), S14-S24 (10 system calls),
+ *        SD-06 (integration harness), S49 (developer experience)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 6 (Integration Harness)
+ *
+ * The ReferenceAgent is the top-level orchestrator that:
+ *   1. Registers the agent via limen.agents.register() (S12)
+ *   2. Creates missions via limen.missions.create() (SC-1)
+ *   3. Coordinates planning (MissionPlanner), execution (TaskExecutor),
+ *      artifact management (ArtifactManager), checkpoint handling
+ *      (CheckpointHandler), and result aggregation (ResultAggregator)
+ *   4. Handles recursive delegation (UC-10) by spawning child agents
+ *   5. Responds to reality changes (UC-11) via replan flow
+ *   6. Manages long-horizon execution (UC-12) with budget checkpoints
+ *
+ * This is a LIBRARY -- it exports a factory function. It does NOT run
+ * autonomously. It is driven by tests or by the consumer.
+ *
+ * Invariants enforced: I-17 (all state through system calls),
+ *                      I-20 (mission tree limits respected),
+ *                      I-21 (bounded cognitive state),
+ *                      I-22 (capability immutability),
+ *                      I-24 (goal anchoring),
+ *                      I-25 (deterministic replay for deterministic paths)
+ * Failure modes defended: FM-02 (cost explosion -- budget tracking),
+ *                         FM-13 (unbounded autonomy -- structural limits),
+ *                         FM-14 (semantic drift -- objective alignment),
+ *                         FM-15 (artifact entropy -- purposeful creation),
+ *                         FM-16 (mission drift -- confidence monitoring),
+ *                         FM-17 (plan explosion -- revision limits),
+ *                         FM-19 (delegation cycle -- system enforces)
+ */
+import type { MissionHandle, MissionResult, AgentExecutionState, ReferenceAgentConfig, MissionRunOptions, TaskGraphInput, TaskGraphOutput } from './reference_agent.types.js';
+import type { Limen } from '../api/index.js';
+import { MissionPlanner } from './mission_planner.js';
+import { CheckpointHandler } from './checkpoint_handler.js';
+/**
+ * §41, S49: The reference cognitive agent.
+ *
+ * Usage:
+ *   const limen = await createLimen({ ... });
+ *   const agent = createReferenceAgent(limen, { name: 'strategist' });
+ *   const result = await agent.runMission({ objective: '...', constraints: { ... } });
+ *
+ * The agent is a library. It does not run autonomously.
+ * The consumer drives execution by calling runMission().
+ */
+export declare class ReferenceAgent {
+    private readonly limen;
+    private readonly config;
+    private registered;
+    constructor(limen: Limen, config: ReferenceAgentConfig);
+    /**
+     * §12: Register the agent with the Limen engine.
+     *
+     * Must be called before runMission(). Registers the agent identity
+     * with the system so it can be assigned to missions.
+     *
+     * DL-2: Agent starts in 'registered' status with 'untrusted' trust level.
+     */
+    register(): Promise<void>;
+    /**
+     * §41 UC-10/UC-11/UC-12: Run a mission end-to-end.
+     *
+     * This is the primary entry point for the reference agent. It:
+     *   1. Creates a mission via limen.missions.create()
+     *   2. Plans: decomposes objective into task DAG
+     *   3. Executes tasks in dependency order
+     *   4. Creates artifacts from task outputs
+     *   5. Handles checkpoints during execution
+     *   6. Submits final result
+     *
+     * For UC-10 recursive missions, delegation happens during execution
+     * when a task warrants spawning a child mission.
+     *
+     * @param options - Mission configuration
+     * @returns MissionResult from the completed mission
+     */
+    runMission(options: MissionRunOptions): Promise<MissionResult>;
+    /**
+     * UC-10: Delegate a sub-task to a child mission.
+     *
+     * Creates a child mission with:
+     *   - Budget: parent remaining * DEFAULT_BUDGET_DECAY_FACTOR (0.3)
+     *   - Capabilities: subset of parent capabilities
+     *   - parentMissionId linking to parent mission
+     *
+     * I-20: The system enforces depth, children, and tree size limits.
+     * I-22: Child capabilities must be subset of parent.
+     * FM-19: System detects delegation cycles via visited set.
+     * SEC-P5-002: Agent-side depth tracking prevents unbounded recursion.
+     * DR-P5-006: Pre-flight check against I-20 limits before spawning.
+     *
+     * @param parentState - Parent mission execution state
+     * @param childObjective - What the child mission should accomplish
+     * @param childCapabilities - Capabilities for the child (must be subset of parent)
+     * @param childAgentName - Agent name for the child mission
+     * @param currentDepth - Current delegation depth (SEC-P5-002)
+     * @returns MissionResult from the completed child mission
+     */
+    delegateToChild(parentState: AgentExecutionState, childObjective: string, childCapabilities: readonly string[], childAgentName: string, currentDepth?: number): Promise<MissionResult>;
+    /**
+     * UC-11: Handle a reality change during execution.
+     *
+     * DR-P5-007: Fully wired replan flow. When new information invalidates previous work:
+     *   1. Emit 'data.invalid' event
+     *   2. Trigger replanning via the MissionPlanner
+     *   3. If replan succeeds, return the revised graph for the caller to re-execute
+     *   4. If replan is exhausted (FM-17), return null -- caller submits with current plan
+     *
+     * @param missionHandle - The active mission handle
+     * @param state - Current execution state
+     * @param reason - What changed and why
+     * @param checkpointHandler - Handler for responding to checkpoints
+     * @param planner - MissionPlanner for producing revised task graphs
+     * @returns The revised TaskGraphInput for re-execution, or null if replan exhausted
+     */
+    handleRealityChange(_missionHandle: MissionHandle, state: AgentExecutionState, reason: string, checkpointHandler: CheckpointHandler, planner?: MissionPlanner): Promise<{
+        graphInput: TaskGraphInput;
+        graphOutput: TaskGraphOutput;
+    } | null>;
+    /** Get the agent name. */
+    get name(): string;
+    /** Check if the agent is registered. */
+    get isRegistered(): boolean;
+}
+//# sourceMappingURL=reference_agent.d.ts.map

package/dist/reference-agent/reference_agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference_agent.d.ts","sourceRoot":"","sources":["../../src/reference-agent/reference_agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EACV,aAAa,EAAE,aAAa,EAG5B,mBAAmB,EACnB,oBAAoB,EAAE,iBAAiB,EACvC,cAAc,EAAE,eAAe,EAChC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,KAAK,EAAqB,MAAM,iBAAiB,CAAC;AAIhE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA6F5D;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,UAAU,CAAkB;gBAExB,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB;IAatD;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAc/B;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAwHpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,CACnB,WAAW,EAAE,mBAAmB,EAChC,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,cAAc,EAAE,MAAM,EACtB,YAAY,GAAE,MAAU,GACvB,OAAO,CAAC,aAAa,CAAC;IAmDzB;;;;;;;;;;;;;;;OAeG;IACG,mBAAmB,CACvB,cAAc,EAAE,aAAa,EAC7B,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IAqB/E,0BAA0B;IAC1B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wCAAwC;IACxC,IAAI,YAAY,IAAI,OAAO,CAE1B;CACF"}

package/dist/reference-agent/reference_agent.js

@@ -0,0 +1,360 @@
+/**
+ * ReferenceAgent -- the cognitive agent entry point and execution orchestrator.
+ * S ref: S41 (UC-10, UC-11, UC-12), S14-S24 (10 system calls),
+ *        SD-06 (integration harness), S49 (developer experience)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 6 (Integration Harness)
+ *
+ * The ReferenceAgent is the top-level orchestrator that:
+ *   1. Registers the agent via limen.agents.register() (S12)
+ *   2. Creates missions via limen.missions.create() (SC-1)
+ *   3. Coordinates planning (MissionPlanner), execution (TaskExecutor),
+ *      artifact management (ArtifactManager), checkpoint handling
+ *      (CheckpointHandler), and result aggregation (ResultAggregator)
+ *   4. Handles recursive delegation (UC-10) by spawning child agents
+ *   5. Responds to reality changes (UC-11) via replan flow
+ *   6. Manages long-horizon execution (UC-12) with budget checkpoints
+ *
+ * This is a LIBRARY -- it exports a factory function. It does NOT run
+ * autonomously. It is driven by tests or by the consumer.
+ *
+ * Invariants enforced: I-17 (all state through system calls),
+ *                      I-20 (mission tree limits respected),
+ *                      I-21 (bounded cognitive state),
+ *                      I-22 (capability immutability),
+ *                      I-24 (goal anchoring),
+ *                      I-25 (deterministic replay for deterministic paths)
+ * Failure modes defended: FM-02 (cost explosion -- budget tracking),
+ *                         FM-13 (unbounded autonomy -- structural limits),
+ *                         FM-14 (semantic drift -- objective alignment),
+ *                         FM-15 (artifact entropy -- purposeful creation),
+ *                         FM-16 (mission drift -- confidence monitoring),
+ *                         FM-17 (plan explosion -- revision limits),
+ *                         FM-19 (delegation cycle -- system enforces)
+ */
+import { DEFAULT_BUDGET_DECAY_FACTOR, MISSION_TREE_DEFAULTS } from './reference_agent.types.js';
+import { SystemCallClient, toClassifiedError } from './system_call_client.js';
+import { MissionPlanner } from './mission_planner.js';
+import { TaskExecutor } from './task_executor.js';
+import { ArtifactManager } from './artifact_manager.js';
+import { CheckpointHandler } from './checkpoint_handler.js';
+import { ResultAggregator } from './result_aggregator.js';
+// ============================================================================
+// Input Sanitization (SEC-P5-003, SEC-P5-007)
+// ============================================================================
+/** SEC-P5-003: Maximum allowed objective length to prevent prompt injection via oversized input. */
+const MAX_OBJECTIVE_LENGTH = 4096;
+/**
+ * SEC-P5-003: Sanitize an objective string before interpolation into task descriptions.
+ * Strips control characters (except newlines/tabs), truncates to MAX_OBJECTIVE_LENGTH.
+ * Prevents prompt injection via objective fields.
+ *
+ * @param objective - Raw objective string
+ * @returns Sanitized objective string
+ */
+function sanitizeObjective(objective) {
+    // Strip control characters except \n (0x0A) and \t (0x09)
+    const cleaned = objective.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+    // Truncate to maximum length
+    if (cleaned.length > MAX_OBJECTIVE_LENGTH) {
+        return cleaned.slice(0, MAX_OBJECTIVE_LENGTH);
+    }
+    return cleaned;
+}
+/**
+ * SEC-P5-007: Sanitize error messages before exposing in result submissions.
+ * Strips stack traces, file paths, and internal identifiers.
+ *
+ * @param message - Raw error message
+ * @returns Sanitized message safe for external consumption
+ */
+function sanitizeErrorMessage(message) {
+    // Strip file paths (Unix and Windows patterns)
+    let safe = message.replace(/(?:\/[\w.-]+)+\.\w+/g, '[path]');
+    safe = safe.replace(/(?:[A-Z]:\\[\w\\.-]+)+/g, '[path]');
+    // Strip stack trace lines
+    safe = safe.replace(/\s+at\s+.+/g, '');
+    // Truncate to reasonable length
+    if (safe.length > 512) {
+        safe = safe.slice(0, 512);
+    }
+    return safe.trim();
+}
+// ============================================================================
+// Agent Execution State Factory
+// ============================================================================
+/**
+ * SDD §5: Create initial agent execution state for a mission.
+ *
+ * @param missionId - The mission ID
+ * @param objective - The mission objective
+ * @param successCriteria - Success criteria
+ * @param scopeBoundaries - Scope boundaries
+ * @param budgetAllocated - Initial budget allocation
+ * @returns Fresh AgentExecutionState
+ */
+function createExecutionState(missionId, objective, successCriteria, scopeBoundaries, budgetAllocated, capabilities) {
+    return {
+        missionId,
+        objective,
+        successCriteria,
+        scopeBoundaries,
+        capabilities,
+        budgetAllocated,
+        budgetConsumed: 0,
+        currentPlanVersion: 0,
+        planRevisionCount: 0,
+        activeTaskIds: new Set(),
+        completedTaskIds: new Set(),
+        completedArtifactIds: [],
+        childMissionResults: new Map(),
+        checkpointHistory: [],
+        crossedBudgetThresholds: new Set(),
+    };
+}
+// ============================================================================
+// ReferenceAgent Class
+// ============================================================================
+/**
+ * §41, S49: The reference cognitive agent.
+ *
+ * Usage:
+ *   const limen = await createLimen({ ... });
+ *   const agent = createReferenceAgent(limen, { name: 'strategist' });
+ *   const result = await agent.runMission({ objective: '...', constraints: { ... } });
+ *
+ * The agent is a library. It does not run autonomously.
+ * The consumer drives execution by calling runMission().
+ */
+export class ReferenceAgent {
+    limen;
+    config;
+    registered = false;
+    constructor(limen, config) {
+        this.limen = limen;
+        this.config = {
+            name: config.name,
+            decompositionStrategy: config.decompositionStrategy ?? 'heuristic',
+            maxRetryAttempts: config.maxRetryAttempts ?? 3,
+            checkpointAssessmentMode: config.checkpointAssessmentMode ?? 'heuristic',
+            systemPrompt: config.systemPrompt ?? '',
+            domains: config.domains ?? [],
+            capabilities: config.capabilities ?? [],
+        };
+    }
+    /**
+     * §12: Register the agent with the Limen engine.
+     *
+     * Must be called before runMission(). Registers the agent identity
+     * with the system so it can be assigned to missions.
+     *
+     * DL-2: Agent starts in 'registered' status with 'untrusted' trust level.
+     */
+    async register() {
+        if (this.registered)
+            return;
+        const registration = {
+            name: this.config.name,
+            ...(this.config.systemPrompt ? { systemPrompt: this.config.systemPrompt } : {}),
+            ...(this.config.domains.length > 0 ? { domains: this.config.domains } : {}),
+            ...(this.config.capabilities.length > 0 ? { capabilities: this.config.capabilities } : {}),
+        };
+        await this.limen.agents.register(registration);
+        this.registered = true;
+    }
+    /**
+     * §41 UC-10/UC-11/UC-12: Run a mission end-to-end.
+     *
+     * This is the primary entry point for the reference agent. It:
+     *   1. Creates a mission via limen.missions.create()
+     *   2. Plans: decomposes objective into task DAG
+     *   3. Executes tasks in dependency order
+     *   4. Creates artifacts from task outputs
+     *   5. Handles checkpoints during execution
+     *   6. Submits final result
+     *
+     * For UC-10 recursive missions, delegation happens during execution
+     * when a task warrants spawning a child mission.
+     *
+     * @param options - Mission configuration
+     * @returns MissionResult from the completed mission
+     */
+    async runMission(options) {
+        // Ensure agent is registered
+        await this.register();
+        // SEC-P5-003: Sanitize objective to prevent prompt injection via interpolation.
+        const sanitizedObjective = sanitizeObjective(options.objective);
+        // Step 1: Create mission via limen.missions.create()
+        const createOptions = {
+            agent: this.config.name,
+            objective: sanitizedObjective,
+            ...(options.successCriteria != null
+                ? { successCriteria: [...options.successCriteria] }
+                : {}),
+            ...(options.scopeBoundaries != null
+                ? { scopeBoundaries: [...options.scopeBoundaries] }
+                : {}),
+            constraints: {
+                tokenBudget: options.constraints.tokenBudget,
+                deadline: options.constraints.deadline,
+                ...(options.constraints.capabilities != null
+                    ? { capabilities: [...options.constraints.capabilities] }
+                    : {}),
+                maxTasks: options.constraints.maxTasks ?? MISSION_TREE_DEFAULTS.maxTasks,
+                maxChildren: options.constraints.maxChildren ?? MISSION_TREE_DEFAULTS.maxChildren,
+                maxDepth: options.constraints.maxDepth ?? MISSION_TREE_DEFAULTS.maxDepth,
+            },
+            ...(options.deliverables != null ? { deliverables: options.deliverables } : {}),
+            ...(options.parentMissionId != null ? { parentMissionId: options.parentMissionId } : {}),
+        };
+        const missionHandle = await this.limen.missions.create(createOptions);
+        // Initialize execution state
+        // DR-P5-002: Thread capabilities from constraints into state so decompose() uses them.
+        const state = createExecutionState(missionHandle.id, sanitizedObjective, options.successCriteria ?? [], options.scopeBoundaries ?? [], missionHandle.budget.allocated, options.constraints.capabilities ?? []);
+        // Create module instances for this mission
+        const client = new SystemCallClient(missionHandle, this.config.maxRetryAttempts);
+        const planner = new MissionPlanner(client, this.config.decompositionStrategy);
+        const executor = new TaskExecutor(client, options.onTaskExecution);
+        const artifactManager = new ArtifactManager(client);
+        const resultAggregator = new ResultAggregator(client);
+        // DR-P5-004: Instantiate CheckpointHandler for UC-11/UC-12 budget checkpoints.
+        const checkpointHandler = new CheckpointHandler(client, this.config.checkpointAssessmentMode);
+        try {
+            // Step 2: Plan -- decompose objective into task graph
+            // DR-P5-001: planMission() now returns the exact TaskGraphInput it proposed.
+            // We use THIS graph for execution -- no second decomposition.
+            const { graphInput } = await planner.planMission(state);
+            const taskDescriptions = new Map(graphInput.tasks.map(t => [t.id, t.description]));
+            // Step 3: Execute tasks in dependency order
+            // DR-P5-001: Uses the graphInput from planMission(), not a second heuristicDecompose().
+            const completedTasks = await executor.executeTaskGraph(graphInput.tasks, graphInput.dependencies, state, taskDescriptions, 
+            // DR-P5-004: Pass checkpoint handler and planner for budget checkpoint polling
+            checkpointHandler, options.onCheckpoint);
+            // SEC-P5-005: Sync budget from authoritative source after execution.
+            state.budgetConsumed = missionHandle.budget.consumed;
+            // Step 4: Create artifacts from completed tasks
+            for (const taskId of completedTasks) {
+                const description = taskDescriptions.get(taskId) ?? taskId;
+                await artifactManager.createTaskOutput(state.missionId, taskId, description, `Output of task: ${description}`, state);
+            }
+            // Step 5: Submit result via SC-9
+            await resultAggregator.submitResult(state);
+            // Step 6: Wait for mission completion and return result
+            const result = await missionHandle.wait();
+            return result;
+        }
+        catch (error) {
+            // On failure, attempt to submit a failed result
+            const classified = toClassifiedError(error);
+            // SEC-P5-007: Sanitize error messages before submitting to system.
+            const safeMessage = sanitizeErrorMessage(classified.message);
+            try {
+                await resultAggregator.submitCustomResult(state, `Mission failed: ${safeMessage}`, 0, [`Mission terminated due to error: ${safeMessage}`], ['Investigate root cause and retry mission']);
+            }
+            catch {
+                // Submit itself failed -- nothing more we can do
+            }
+            throw error;
+        }
+    }
+    /**
+     * UC-10: Delegate a sub-task to a child mission.
+     *
+     * Creates a child mission with:
+     *   - Budget: parent remaining * DEFAULT_BUDGET_DECAY_FACTOR (0.3)
+     *   - Capabilities: subset of parent capabilities
+     *   - parentMissionId linking to parent mission
+     *
+     * I-20: The system enforces depth, children, and tree size limits.
+     * I-22: Child capabilities must be subset of parent.
+     * FM-19: System detects delegation cycles via visited set.
+     * SEC-P5-002: Agent-side depth tracking prevents unbounded recursion.
+     * DR-P5-006: Pre-flight check against I-20 limits before spawning.
+     *
+     * @param parentState - Parent mission execution state
+     * @param childObjective - What the child mission should accomplish
+     * @param childCapabilities - Capabilities for the child (must be subset of parent)
+     * @param childAgentName - Agent name for the child mission
+     * @param currentDepth - Current delegation depth (SEC-P5-002)
+     * @returns MissionResult from the completed child mission
+     */
+    async delegateToChild(parentState, childObjective, childCapabilities, childAgentName, currentDepth = 0) {
+        // SEC-P5-002: Agent-side delegation depth check.
+        // The system also enforces this (DEPTH_EXCEEDED), but we fail fast
+        // to avoid wasting resources on a delegation that will be rejected.
+        const maxDepth = MISSION_TREE_DEFAULTS.maxDepth;
+        if (currentDepth + 1 >= maxDepth) {
+            throw Object.assign(new Error(`Delegation depth ${currentDepth + 1} would exceed maximum depth ${maxDepth}. ` +
+                `Cannot delegate further.`), { code: 'DEPTH_EXCEEDED' });
+        }
+        // DR-P5-006: Pre-flight check on children count (I-20).
+        const maxChildren = MISSION_TREE_DEFAULTS.maxChildren;
+        if (parentState.childMissionResults.size >= maxChildren) {
+            throw Object.assign(new Error(`Parent mission already has ${parentState.childMissionResults.size} children, ` +
+                `which meets or exceeds the maximum of ${maxChildren}.`), { code: 'CHILDREN_EXCEEDED' });
+        }
+        // §11: Budget decay -- child gets parent remaining * 0.3
+        const parentRemaining = parentState.budgetAllocated - parentState.budgetConsumed;
+        const childBudget = Math.floor(parentRemaining * DEFAULT_BUDGET_DECAY_FACTOR);
+        // Create child agent and run child mission
+        const childAgent = new ReferenceAgent(this.limen, {
+            name: childAgentName,
+            decompositionStrategy: this.config.decompositionStrategy,
+            maxRetryAttempts: this.config.maxRetryAttempts,
+            checkpointAssessmentMode: this.config.checkpointAssessmentMode,
+        });
+        const childResult = await childAgent.runMission({
+            objective: childObjective,
+            constraints: {
+                tokenBudget: childBudget,
+                deadline: '24h',
+                capabilities: childCapabilities,
+            },
+            parentMissionId: parentState.missionId,
+            // SEC-P5-002: Propagate delegation depth to child
+            delegationDepth: currentDepth + 1,
+        });
+        // Record child result in parent state
+        parentState.childMissionResults.set(childResult.missionId, childResult);
+        return childResult;
+    }
+    /**
+     * UC-11: Handle a reality change during execution.
+     *
+     * DR-P5-007: Fully wired replan flow. When new information invalidates previous work:
+     *   1. Emit 'data.invalid' event
+     *   2. Trigger replanning via the MissionPlanner
+     *   3. If replan succeeds, return the revised graph for the caller to re-execute
+     *   4. If replan is exhausted (FM-17), return null -- caller submits with current plan
+     *
+     * @param missionHandle - The active mission handle
+     * @param state - Current execution state
+     * @param reason - What changed and why
+     * @param checkpointHandler - Handler for responding to checkpoints
+     * @param planner - MissionPlanner for producing revised task graphs
+     * @returns The revised TaskGraphInput for re-execution, or null if replan exhausted
+     */
+    async handleRealityChange(_missionHandle, state, reason, checkpointHandler, planner) {
+        // Step 1: Emit data.invalid event
+        await checkpointHandler.emitEvent('data.invalid', state.missionId, { reason, affectedTasks: [...state.activeTaskIds] }, 'up');
+        // Step 2: Trigger replanning if planner is available.
+        // DR-P5-007: This is the follow-through that was structurally missing.
+        // The planner proposes a revised task graph; the orchestrator validates and
+        // cancels affected PENDING tasks. The returned graph drives re-execution.
+        if (planner) {
+            const replanResult = await planner.replan(state, reason);
+            return replanResult; // null if FM-17 revision limit reached
+        }
+        return null;
+    }
+    /** Get the agent name. */
+    get name() {
+        return this.config.name;
+    }
+    /** Check if the agent is registered. */
+    get isRegistered() {
+        return this.registered;
+    }
+}
+//# sourceMappingURL=reference_agent.js.map

package/dist/reference-agent/reference_agent.js.map

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