limen-ai 1.0.0

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

@@ -0,0 +1,186 @@
+/**
+ * CheckpointHandler -- governance response during mission execution.
+ * S ref: S24 (respond_checkpoint), S20 (emit_event), S22 (request_budget),
+ *        SD-01 (lifecycle-phase grouping), SD-04 (LLM-preferred assessment)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 4 (CheckpointHandler)
+ *
+ * The CheckpointHandler is responsible for:
+ *   1. Responding to checkpoints via SC-10 (respond_checkpoint)
+ *   2. Emitting agent events via SC-6 (emit_event)
+ *   3. Requesting additional budget via SC-8 (request_budget)
+ *   4. Computing confidence and assessment (heuristic or LLM)
+ *   5. Deciding action: continue / replan / escalate / abort
+ *
+ * These three calls (respond_checkpoint, emit_event, request_budget) are
+ * the "governance" calls that maintain ALIGNMENT during execution. They
+ * are responses to system pressure, not agent-initiated planning.
+ *
+ * Invariants enforced: I-17 (governance boundary),
+ *                      I-24 (goal anchoring -- assessment against objective)
+ * Failure modes defended: FM-02 (budget request before exceeding),
+ *                         FM-14 (semantic drift -- checkpoint assessment),
+ *                         FM-16 (mission drift -- confidence-driven escalation)
+ */
+import type { MissionId, CheckpointResponseOutput, EventEmitOutput, BudgetRequestOutput, TaskGraphInput, AgentExecutionState, CheckpointAssessmentMode } from './reference_agent.types.js';
+import { SystemCallClient } from './system_call_client.js';
+import type { TimeProvider } from '../kernel/interfaces/time.js';
+/**
+ * SD-04: Expected shape of LLM assessment response.
+ * Used for runtime validation of the untyped `result` from requestCapability.
+ */
+interface LlmAssessmentResponse {
+    readonly assessment: string;
+    readonly confidence: number;
+    readonly suggestedAction: 'continue' | 'replan' | 'escalate' | 'abort';
+}
+/**
+ * SD-04: Validate that the LLM response matches the expected assessment schema.
+ * Returns the validated response or null if validation fails.
+ *
+ * Validation rules:
+ *   - assessment must be a non-empty string
+ *   - confidence must be a number (clamped to [0, 1] if outside range)
+ *   - suggestedAction must be one of: 'continue', 'replan', 'escalate', 'abort'
+ *
+ * @param result - Untyped result from requestCapability
+ * @returns Validated response with confidence clamped to [0, 1], or null
+ */
+export declare function validateLlmAssessmentResponse(result: unknown): LlmAssessmentResponse | null;
+/**
+ * SD-04: Compute confidence heuristically from execution state.
+ *
+ * Heuristic factors:
+ *   - Task completion ratio (completed / total)
+ *   - Budget consumption ratio (consumed / allocated)
+ *   - Artifact production (at least one artifact = positive signal)
+ *   - Plan stability (fewer revisions = higher confidence)
+ *
+ * @param state - Agent execution state
+ * @returns Confidence score in [0.0, 1.0]
+ */
+export declare function computeHeuristicConfidence(state: AgentExecutionState): number;
+/**
+ * SD-04: Generate a heuristic assessment string.
+ *
+ * I-24: The assessment always references the original objective
+ * to maintain goal anchoring.
+ *
+ * @param state - Agent execution state
+ * @param confidence - Computed confidence score
+ * @returns Human-readable assessment string
+ */
+export declare function generateHeuristicAssessment(state: AgentExecutionState, confidence: number): string;
+/**
+ * §24: Determine the appropriate checkpoint action based on state and trigger.
+ *
+ * FM-16: Escalates when confidence drops below ESCALATION_CONFIDENCE_THRESHOLD (0.5).
+ * FM-14: Replans when stale data is detected.
+ *
+ * @param trigger - What caused the checkpoint (BUDGET_THRESHOLD, TASK_FAILED, etc.)
+ * @param confidence - Current confidence score
+ * @param state - Agent execution state
+ * @returns The proposed action
+ */
+export declare function decideCheckpointAction(trigger: string, confidence: number, state: AgentExecutionState): 'continue' | 'replan' | 'escalate' | 'abort';
+/**
+ * SD-01: CheckpointHandler groups respond_checkpoint + emit_event + request_budget.
+ * These are the "governance" calls used during EXECUTING phase.
+ *
+ * Checkpoint handling flow:
+ *   1. Compute confidence from execution state
+ *   2. Generate assessment (heuristic or LLM)
+ *   3. Decide action based on trigger and confidence
+ *   4. Submit response via respond_checkpoint
+ *   5. Record checkpoint in history for self-reflection
+ */
+export declare class CheckpointHandler {
+    private readonly client;
+    readonly assessmentMode: CheckpointAssessmentMode;
+    private readonly clock;
+    constructor(client: SystemCallClient, assessmentMode?: CheckpointAssessmentMode, time?: TimeProvider);
+    /**
+     * §24, SC-10: Handle a checkpoint event.
+     *
+     * I-24: Assessment always references the mission objective.
+     * FM-14: Detects semantic drift via confidence computation.
+     * FM-16: Escalates on low confidence.
+     *
+     * @param checkpointId - The checkpoint to respond to
+     * @param trigger - What caused the checkpoint
+     * @param state - Agent execution state
+     * @param planRevision - Optional revised task graph (for replan action)
+     * @returns CheckpointResponseOutput from the system
+     */
+    handleCheckpoint(checkpointId: string, trigger: string, state: AgentExecutionState, planRevision?: TaskGraphInput): Promise<CheckpointResponseOutput>;
+    /**
+     * §20, SC-6: Emit an agent event.
+     *
+     * Only non-lifecycle events are allowed (§10 rule):
+     *   - 'data.invalid': Signal that data has changed
+     *   - 'plan.needs_revision': Signal need for replanning
+     *   - 'human.input_needed': Request human attention
+     *
+     * System/lifecycle events (system.*, lifecycle.*) are reserved for the
+     * orchestrator. The agent NEVER emits them (I-17, §10).
+     *
+     * SEC-P5-001: Agent-side namespace validation. The system also validates,
+     * but we fail fast to prevent the agent from even attempting to emit
+     * reserved events.
+     *
+     * @param eventType - The event type (must not start with 'system.' or 'lifecycle.')
+     * @param missionId - Mission context
+     * @param payload - Event payload
+     * @param propagation - How the event propagates (up/down/local)
+     * @returns EventEmitOutput
+     * @throws Error if eventType uses a reserved namespace
+     */
+    emitEvent(eventType: string, missionId: MissionId, payload: Record<string, unknown>, propagation?: 'up' | 'down' | 'local'): Promise<EventEmitOutput>;
+    /**
+     * §22, SC-8: Request additional budget.
+     *
+     * FM-02: The agent requests budget BEFORE exceeding allocation,
+     * not after. Budget can never go negative.
+     *
+     * @param missionId - Mission context
+     * @param amount - Amount of additional resources needed
+     * @param justification - Why additional budget is needed
+     * @returns BudgetRequestOutput with approval status
+     */
+    requestBudget(missionId: MissionId, amount: {
+        tokens?: number;
+        time?: number;
+        compute?: number;
+        storage?: number;
+    }, justification: string): Promise<BudgetRequestOutput>;
+    /**
+     * UC-12: Check if a budget checkpoint should be triggered.
+     *
+     * Budget checkpoints fire at 25%, 50%, 75%, 90% consumption.
+     * The agent tracks these internally because the system may or may
+     * not fire them at exact thresholds.
+     *
+     * DR-P5-012: Uses state.crossedBudgetThresholds Set for explicit tracking.
+     * The previous implementation used fragile checkpoint history counting.
+     *
+     * @param state - Agent execution state
+     * @returns The threshold that was just crossed, or null
+     */
+    checkBudgetThreshold(state: AgentExecutionState): number | null;
+    /**
+     * SD-04: Compute LLM-based assessment via requestCapability (SC-7).
+     *
+     * Builds an execution state summary and sends it to the LLM for assessment.
+     * The LLM returns confidence, assessment text, and a suggested action.
+     *
+     * I-24: The prompt includes the mission objective for goal anchoring.
+     * I-16: Returns null on ANY error, allowing the caller to fall back to heuristic.
+     *
+     * @param state - Agent execution state
+     * @returns Validated LLM assessment response, or null on any failure
+     */
+    private computeLlmAssessment;
+}
+export {};
+//# sourceMappingURL=checkpoint_handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint_handler.d.ts","sourceRoot":"","sources":["../../src/reference-agent/checkpoint_handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,SAAS,EACgB,wBAAwB,EACjC,eAAe,EACX,mBAAmB,EAEvC,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AAOpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AASjE;;;GAGG;AACH,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;CACxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,GACd,qBAAqB,GAAG,IAAI,CAqB9B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA2B7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,mBAAmB,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CAsBR;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,mBAAmB,GACzB,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CA6C9C;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,QAAQ,CAAC,cAAc,EAAE,wBAAwB,CAAC;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGnC,MAAM,EAAE,gBAAgB,EACxB,cAAc,GAAE,wBAAsC,EACtD,IAAI,CAAC,EAAE,YAAY;IAOrB;;;;;;;;;;;;OAYG;IACG,gBAAgB,CACpB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,EAC1B,YAAY,CAAC,EAAE,cAAc,GAC5B,OAAO,CAAC,wBAAwB,CAAC;IAyDpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,GAAE,IAAI,GAAG,MAAM,GAAG,OAAiB,GAC7C,OAAO,CAAC,eAAe,CAAC;IAmB3B;;;;;;;;;;OAUG;IACG,aAAa,CACjB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC9E,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAY/B;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI;IAgB/D;;;;;;;;;;;OAWG;YACW,oBAAoB;CA0DnC"}

package/dist/reference-agent/checkpoint_handler.js

@@ -0,0 +1,423 @@
+/**
+ * CheckpointHandler -- governance response during mission execution.
+ * S ref: S24 (respond_checkpoint), S20 (emit_event), S22 (request_budget),
+ *        SD-01 (lifecycle-phase grouping), SD-04 (LLM-preferred assessment)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 4 (CheckpointHandler)
+ *
+ * The CheckpointHandler is responsible for:
+ *   1. Responding to checkpoints via SC-10 (respond_checkpoint)
+ *   2. Emitting agent events via SC-6 (emit_event)
+ *   3. Requesting additional budget via SC-8 (request_budget)
+ *   4. Computing confidence and assessment (heuristic or LLM)
+ *   5. Deciding action: continue / replan / escalate / abort
+ *
+ * These three calls (respond_checkpoint, emit_event, request_budget) are
+ * the "governance" calls that maintain ALIGNMENT during execution. They
+ * are responses to system pressure, not agent-initiated planning.
+ *
+ * Invariants enforced: I-17 (governance boundary),
+ *                      I-24 (goal anchoring -- assessment against objective)
+ * Failure modes defended: FM-02 (budget request before exceeding),
+ *                         FM-14 (semantic drift -- checkpoint assessment),
+ *                         FM-16 (mission drift -- confidence-driven escalation)
+ */
+import { ESCALATION_CONFIDENCE_THRESHOLD, BUDGET_CHECKPOINT_THRESHOLDS, } from './reference_agent.types.js';
+// ============================================================================
+// LLM Assessment Response Validation (SD-04)
+// ============================================================================
+/** Valid actions that the LLM assessment can suggest. */
+const VALID_SUGGESTED_ACTIONS = new Set(['continue', 'replan', 'escalate', 'abort']);
+/**
+ * SD-04: Validate that the LLM response matches the expected assessment schema.
+ * Returns the validated response or null if validation fails.
+ *
+ * Validation rules:
+ *   - assessment must be a non-empty string
+ *   - confidence must be a number (clamped to [0, 1] if outside range)
+ *   - suggestedAction must be one of: 'continue', 'replan', 'escalate', 'abort'
+ *
+ * @param result - Untyped result from requestCapability
+ * @returns Validated response with confidence clamped to [0, 1], or null
+ */
+export function validateLlmAssessmentResponse(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const r = result;
+    // assessment: non-empty string
+    if (typeof r['assessment'] !== 'string' || r['assessment'].length === 0)
+        return null;
+    // confidence: number (will be clamped)
+    if (typeof r['confidence'] !== 'number' || Number.isNaN(r['confidence']))
+        return null;
+    // suggestedAction: valid enum
+    if (typeof r['suggestedAction'] !== 'string' || !VALID_SUGGESTED_ACTIONS.has(r['suggestedAction']))
+        return null;
+    // Clamp confidence to [0, 1]
+    const clampedConfidence = Math.min(1, Math.max(0, r['confidence']));
+    return {
+        assessment: r['assessment'],
+        confidence: clampedConfidence,
+        suggestedAction: r['suggestedAction'],
+    };
+}
+// ============================================================================
+// Confidence Computation (SD-04)
+// ============================================================================
+/**
+ * SD-04: Compute confidence heuristically from execution state.
+ *
+ * Heuristic factors:
+ *   - Task completion ratio (completed / total)
+ *   - Budget consumption ratio (consumed / allocated)
+ *   - Artifact production (at least one artifact = positive signal)
+ *   - Plan stability (fewer revisions = higher confidence)
+ *
+ * @param state - Agent execution state
+ * @returns Confidence score in [0.0, 1.0]
+ */
+export function computeHeuristicConfidence(state) {
+    const totalTasks = state.activeTaskIds.size + state.completedTaskIds.size;
+    if (totalTasks === 0)
+        return 0.5; // No tasks yet -- neutral
+    // Factor 1: Task completion (40% weight)
+    const completionRatio = state.completedTaskIds.size / totalTasks;
+    const completionScore = completionRatio * 0.4;
+    // Factor 2: Budget efficiency (30% weight)
+    // Good if we're on track: consumed / allocated roughly matches completion
+    const budgetRatio = state.budgetAllocated > 0
+        ? state.budgetConsumed / state.budgetAllocated
+        : 0;
+    const budgetEfficiency = completionRatio > 0
+        ? Math.min(1, completionRatio / Math.max(budgetRatio, 0.01))
+        : 1;
+    const budgetScore = budgetEfficiency * 0.3;
+    // Factor 3: Artifact production (15% weight)
+    const hasArtifacts = state.completedArtifactIds.length > 0;
+    const artifactScore = hasArtifacts ? 0.15 : 0;
+    // Factor 4: Plan stability (15% weight)
+    const planStability = Math.max(0, 1 - (state.planRevisionCount * 0.2));
+    const planScore = planStability * 0.15;
+    return Math.min(1, Math.max(0, completionScore + budgetScore + artifactScore + planScore));
+}
+/**
+ * SD-04: Generate a heuristic assessment string.
+ *
+ * I-24: The assessment always references the original objective
+ * to maintain goal anchoring.
+ *
+ * @param state - Agent execution state
+ * @param confidence - Computed confidence score
+ * @returns Human-readable assessment string
+ */
+export function generateHeuristicAssessment(state, confidence) {
+    const totalTasks = state.activeTaskIds.size + state.completedTaskIds.size;
+    const completedCount = state.completedTaskIds.size;
+    const artifactCount = state.completedArtifactIds.length;
+    const budgetPct = state.budgetAllocated > 0
+        ? Math.round((state.budgetConsumed / state.budgetAllocated) * 100)
+        : 0;
+    let assessment = `Mission "${state.objective}": `;
+    assessment += `${completedCount}/${totalTasks} tasks complete, `;
+    assessment += `${artifactCount} artifacts produced, `;
+    assessment += `${budgetPct}% budget consumed. `;
+    if (confidence >= 0.8) {
+        assessment += 'On track -- proceeding as planned.';
+    }
+    else if (confidence >= ESCALATION_CONFIDENCE_THRESHOLD) {
+        assessment += 'Progress is acceptable but slower than expected.';
+    }
+    else {
+        assessment += 'Confidence low -- mission may need replanning or escalation.';
+    }
+    return assessment;
+}
+// ============================================================================
+// Action Decision (§24, FM-14, FM-16)
+// ============================================================================
+/**
+ * §24: Determine the appropriate checkpoint action based on state and trigger.
+ *
+ * FM-16: Escalates when confidence drops below ESCALATION_CONFIDENCE_THRESHOLD (0.5).
+ * FM-14: Replans when stale data is detected.
+ *
+ * @param trigger - What caused the checkpoint (BUDGET_THRESHOLD, TASK_FAILED, etc.)
+ * @param confidence - Current confidence score
+ * @param state - Agent execution state
+ * @returns The proposed action
+ */
+export function decideCheckpointAction(trigger, confidence, state) {
+    // FM-16: Low confidence -> escalate
+    if (confidence < ESCALATION_CONFIDENCE_THRESHOLD) {
+        return 'escalate';
+    }
+    switch (trigger) {
+        case 'BUDGET_THRESHOLD': {
+            // UC-12: Budget checkpoints at 25/50/75/90%
+            const budgetRatio = state.budgetAllocated > 0
+                ? state.budgetConsumed / state.budgetAllocated
+                : 0;
+            if (budgetRatio >= 0.9) {
+                // 90%+ consumed: abort if confidence is not high
+                return confidence >= 0.8 ? 'continue' : 'escalate';
+            }
+            if (budgetRatio >= 0.75) {
+                // 75%+ consumed: consider replanning to reduce scope
+                return confidence >= 0.7 ? 'continue' : 'replan';
+            }
+            return 'continue';
+        }
+        case 'TASK_FAILED':
+            // A task failed: replan to work around the failure
+            return 'replan';
+        case 'TASK_COMPLETED':
+        case 'CHILD_MISSION_COMPLETED':
+            // Progress signal: continue if confident
+            return 'continue';
+        case 'PERIODIC':
+        case 'HEARTBEAT_MISSED':
+            // Routine check: continue if on track
+            return confidence >= 0.6 ? 'continue' : 'replan';
+        case 'HUMAN_INPUT_RECEIVED':
+            // Human provided input: continue with updated context
+            return 'continue';
+        default:
+            return 'continue';
+    }
+}
+// ============================================================================
+// CheckpointHandler Class
+// ============================================================================
+/**
+ * SD-01: CheckpointHandler groups respond_checkpoint + emit_event + request_budget.
+ * These are the "governance" calls used during EXECUTING phase.
+ *
+ * Checkpoint handling flow:
+ *   1. Compute confidence from execution state
+ *   2. Generate assessment (heuristic or LLM)
+ *   3. Decide action based on trigger and confidence
+ *   4. Submit response via respond_checkpoint
+ *   5. Record checkpoint in history for self-reflection
+ */
+export class CheckpointHandler {
+    client;
+    assessmentMode;
+    clock;
+    constructor(client, assessmentMode = 'heuristic', time) {
+        this.client = client;
+        this.assessmentMode = assessmentMode;
+        this.clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    }
+    /**
+     * §24, SC-10: Handle a checkpoint event.
+     *
+     * I-24: Assessment always references the mission objective.
+     * FM-14: Detects semantic drift via confidence computation.
+     * FM-16: Escalates on low confidence.
+     *
+     * @param checkpointId - The checkpoint to respond to
+     * @param trigger - What caused the checkpoint
+     * @param state - Agent execution state
+     * @param planRevision - Optional revised task graph (for replan action)
+     * @returns CheckpointResponseOutput from the system
+     */
+    async handleCheckpoint(checkpointId, trigger, state, planRevision) {
+        // SD-04: Assessment mode determines confidence/assessment computation.
+        // LLM-preferred uses requestCapability (SC-7) for richer assessment.
+        // Heuristic uses deterministic computation.
+        // I-16: LLM-preferred falls back to heuristic on ANY error.
+        let confidence;
+        let assessment;
+        if (this.assessmentMode === 'llm-preferred') {
+            const llmResult = await this.computeLlmAssessment(state);
+            if (llmResult !== null) {
+                // LLM assessment succeeded -- use LLM-provided values.
+                // Note: suggestedAction from LLM is informational. The deterministic
+                // decideCheckpointAction() still governs the actual action.
+                confidence = llmResult.confidence;
+                assessment = llmResult.assessment;
+            }
+            else {
+                // I-16: LLM assessment failed -- graceful degradation to heuristic.
+                confidence = computeHeuristicConfidence(state);
+                assessment = generateHeuristicAssessment(state, confidence);
+            }
+        }
+        else {
+            confidence = computeHeuristicConfidence(state);
+            assessment = generateHeuristicAssessment(state, confidence);
+        }
+        const proposedAction = decideCheckpointAction(trigger, confidence, state);
+        const response = {
+            checkpointId,
+            assessment,
+            confidence,
+            proposedAction,
+            ...(proposedAction === 'replan' && planRevision != null ? { planRevision } : {}),
+            ...(proposedAction === 'escalate'
+                ? { escalationReason: `Confidence ${confidence.toFixed(2)} below threshold ${ESCALATION_CONFIDENCE_THRESHOLD}. ` +
+                        `Objective: "${state.objective}"` }
+                : {}),
+        };
+        const result = await this.client.respondCheckpoint(response);
+        // Record checkpoint in history for self-reflection
+        const record = {
+            checkpointId,
+            trigger,
+            assessment,
+            confidence,
+            action: result.action,
+            timestamp: this.clock.nowMs(),
+        };
+        state.checkpointHistory.push(record);
+        return result;
+    }
+    /**
+     * §20, SC-6: Emit an agent event.
+     *
+     * Only non-lifecycle events are allowed (§10 rule):
+     *   - 'data.invalid': Signal that data has changed
+     *   - 'plan.needs_revision': Signal need for replanning
+     *   - 'human.input_needed': Request human attention
+     *
+     * System/lifecycle events (system.*, lifecycle.*) are reserved for the
+     * orchestrator. The agent NEVER emits them (I-17, §10).
+     *
+     * SEC-P5-001: Agent-side namespace validation. The system also validates,
+     * but we fail fast to prevent the agent from even attempting to emit
+     * reserved events.
+     *
+     * @param eventType - The event type (must not start with 'system.' or 'lifecycle.')
+     * @param missionId - Mission context
+     * @param payload - Event payload
+     * @param propagation - How the event propagates (up/down/local)
+     * @returns EventEmitOutput
+     * @throws Error if eventType uses a reserved namespace
+     */
+    async emitEvent(eventType, missionId, payload, propagation = 'local') {
+        // SEC-P5-001: Guard against reserved namespaces (I-17, §10).
+        if (eventType.startsWith('system.') || eventType.startsWith('lifecycle.')) {
+            throw new Error(`Agent cannot emit events in reserved namespace "${eventType.split('.')[0]}.*". ` +
+                `Only the orchestrator may emit system/lifecycle events (I-17, §10).`);
+        }
+        const input = {
+            eventType,
+            missionId,
+            payload,
+            propagation,
+        };
+        return this.client.emitEvent(input);
+    }
+    /**
+     * §22, SC-8: Request additional budget.
+     *
+     * FM-02: The agent requests budget BEFORE exceeding allocation,
+     * not after. Budget can never go negative.
+     *
+     * @param missionId - Mission context
+     * @param amount - Amount of additional resources needed
+     * @param justification - Why additional budget is needed
+     * @returns BudgetRequestOutput with approval status
+     */
+    async requestBudget(missionId, amount, justification) {
+        const input = {
+            missionId,
+            amount,
+            justification,
+        };
+        const result = await this.client.requestBudget(input);
+        return result;
+    }
+    /**
+     * UC-12: Check if a budget checkpoint should be triggered.
+     *
+     * Budget checkpoints fire at 25%, 50%, 75%, 90% consumption.
+     * The agent tracks these internally because the system may or may
+     * not fire them at exact thresholds.
+     *
+     * DR-P5-012: Uses state.crossedBudgetThresholds Set for explicit tracking.
+     * The previous implementation used fragile checkpoint history counting.
+     *
+     * @param state - Agent execution state
+     * @returns The threshold that was just crossed, or null
+     */
+    checkBudgetThreshold(state) {
+        if (state.budgetAllocated === 0)
+            return null;
+        const ratio = state.budgetConsumed / state.budgetAllocated;
+        for (const threshold of BUDGET_CHECKPOINT_THRESHOLDS) {
+            // DR-P5-012: Check if we crossed this threshold and haven't tracked it yet
+            if (ratio >= threshold && !state.crossedBudgetThresholds.has(threshold)) {
+                state.crossedBudgetThresholds.add(threshold);
+                return threshold;
+            }
+        }
+        return null;
+    }
+    /**
+     * SD-04: Compute LLM-based assessment via requestCapability (SC-7).
+     *
+     * Builds an execution state summary and sends it to the LLM for assessment.
+     * The LLM returns confidence, assessment text, and a suggested action.
+     *
+     * I-24: The prompt includes the mission objective for goal anchoring.
+     * I-16: Returns null on ANY error, allowing the caller to fall back to heuristic.
+     *
+     * @param state - Agent execution state
+     * @returns Validated LLM assessment response, or null on any failure
+     */
+    async computeLlmAssessment(state) {
+        try {
+            const syntheticTaskId = `task-${state.missionId.replace(/^mission-/, '')}-llm-assess`;
+            const totalTasks = state.activeTaskIds.size + state.completedTaskIds.size;
+            const executionSummary = {
+                objective: state.objective,
+                tasksCompleted: state.completedTaskIds.size,
+                tasksTotal: totalTasks,
+                budgetConsumed: state.budgetConsumed,
+                budgetAllocated: state.budgetAllocated,
+                artifactsProduced: state.completedArtifactIds.length,
+                planRevisionCount: state.planRevisionCount,
+                checkpointCount: state.checkpointHistory.length,
+            };
+            const input = {
+                capabilityType: 'api_call',
+                parameters: {
+                    prompt: `Assess the current execution state of a mission.\n\n` +
+                        `Objective: "${state.objective}"\n` +
+                        `Tasks completed: ${executionSummary.tasksCompleted}/${executionSummary.tasksTotal}\n` +
+                        `Budget consumed: ${executionSummary.budgetConsumed}/${executionSummary.budgetAllocated}\n` +
+                        `Artifacts produced: ${executionSummary.artifactsProduced}\n` +
+                        `Plan revisions: ${executionSummary.planRevisionCount}\n` +
+                        `Checkpoints so far: ${executionSummary.checkpointCount}\n\n` +
+                        `Return a JSON object with:\n` +
+                        `- assessment: string (human-readable assessment referencing the objective)\n` +
+                        `- confidence: number in [0.0, 1.0]\n` +
+                        `- suggestedAction: one of "continue", "replan", "escalate", "abort"`,
+                    schema: {
+                        assessment: 'string',
+                        confidence: 'number',
+                        suggestedAction: 'string',
+                    },
+                    executionSummary,
+                },
+                missionId: state.missionId,
+                taskId: syntheticTaskId,
+            };
+            const output = await this.client.requestCapability(input);
+            // F-S6-001 FIX: Guard against NaN/Infinity/negative token costs
+            const tokensCost = output.resourcesConsumed.tokens ?? 0;
+            if (Number.isFinite(tokensCost) && tokensCost > 0) {
+                state.budgetConsumed += tokensCost;
+            }
+            // Validate the response schema
+            return validateLlmAssessmentResponse(output.result);
+        }
+        catch (_error) {
+            // I-16: Graceful degradation -- any error returns null for heuristic fallback.
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=checkpoint_handler.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * Reference Agent public exports.
+ * S ref: S49 (developer experience), §41 (use cases)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD File Manifest -- public entry point
+ *
+ * This file is the SOLE public entry point for the reference agent.
+ * Consumers import from here. Internal modules are not exported.
+ *
+ * Usage:
+ *   import { createReferenceAgent } from './reference-agent/index.js';
+ *   import type { Limen } from './api/index.js';
+ *
+ *   const limen: Limen = await createLimen({ ... });
+ *   const agent = createReferenceAgent(limen, { name: 'strategist' });
+ *   const result = await agent.runMission({
+ *     objective: 'Analyze SEA drone delivery market',
+ *     constraints: { tokenBudget: 50000, deadline: '48h' },
+ *   });
+ *
+ * I-17: The reference agent imports ONLY from src/api/.
+ *       No kernel, substrate, or orchestration internals.
+ */
+import type { Limen } from '../api/index.js';
+import { ReferenceAgent } from './reference_agent.js';
+import type { ReferenceAgentConfig } from './reference_agent.types.js';
+/**
+ * S49: Create a reference agent instance.
+ *
+ * This is the canonical developer experience entry point.
+ * The agent is a library -- it does not run autonomously.
+ * The consumer drives execution by calling runMission().
+ *
+ * @param limen - A Limen engine instance (from createLimen())
+ * @param config - Agent configuration
+ * @returns ReferenceAgent instance ready to run missions
+ */
+export declare function createReferenceAgent(limen: Limen, config: ReferenceAgentConfig): ReferenceAgent;
+export { ReferenceAgent } from './reference_agent.js';
+export type { ReferenceAgentConfig, MissionRunOptions, AgentExecutionState, CheckpointRecord, DecompositionStrategy, CheckpointAssessmentMode, CheckpointCallback, TaskExecutionCallback, ErrorCategory, ClassifiedError, } from './reference_agent.types.js';
+export { DEFAULT_BUDGET_DECAY_FACTOR, MISSION_TREE_DEFAULTS, MAX_PLAN_REVISIONS, DEFAULT_MAX_TASK_RETRIES, ESCALATION_CONFIDENCE_THRESHOLD, BUDGET_CHECKPOINT_THRESHOLDS, } from './reference_agent.types.js';
+//# sourceMappingURL=index.d.ts.map