limen-ai 1.0.0

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

@@ -0,0 +1,199 @@
+/**
+ * Reference Agent internal type definitions.
+ * S ref: S6-S11, S14-S24 (types consumed from API surface),
+ *        SD-03 (single types file for DX simplicity)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: §6.1 of Synthesized SDD (Core Types)
+ *
+ * All API types are imported from src/api/. This file defines ONLY
+ * agent-internal types that are NOT part of the public API surface.
+ * The agent never creates its own branded ID types -- it uses the ones
+ * from the API surface exclusively.
+ *
+ * Invariants enforced: I-17 (governance boundary -- types import only from API)
+ * Failure modes defended: FM-14 (semantic drift -- types match spec exactly)
+ */
+import type { MissionId, TaskId, ArtifactId, AgentId, MissionHandle, MissionResult, MissionCreateOptions, TaskGraphInput, TaskGraphOutput, TaskSpec, TaskExecutionInput, TaskExecutionOutput, ArtifactCreateInput, ArtifactCreateOutput, ArtifactReadInput, ArtifactReadOutput, EventEmitInput, EventEmitOutput, CapabilityRequestInput, CapabilityRequestOutput, BudgetRequestInput, BudgetRequestOutput, ResultSubmitInput, ResultSubmitOutput, CheckpointResponseInput, CheckpointResponseOutput, LimenErrorCode, MissionState } from '../api/index.js';
+export type { MissionId, TaskId, ArtifactId, AgentId, MissionHandle, MissionResult, MissionCreateOptions, TaskGraphInput, TaskGraphOutput, TaskSpec, TaskExecutionInput, TaskExecutionOutput, ArtifactCreateInput, ArtifactCreateOutput, ArtifactReadInput, ArtifactReadOutput, EventEmitInput, EventEmitOutput, CapabilityRequestInput, CapabilityRequestOutput, BudgetRequestInput, BudgetRequestOutput, ResultSubmitInput, ResultSubmitOutput, CheckpointResponseInput, CheckpointResponseOutput, LimenErrorCode, MissionState, };
+/**
+ * SD-02: Decomposition strategy determines how the agent decomposes
+ * objectives into task graphs. Heuristic is deterministic (for testing).
+ * LLM-augmented uses request_capability for richer decomposition.
+ */
+export type DecompositionStrategy = 'heuristic' | 'llm-augmented';
+/**
+ * SD-04: Checkpoint assessment mode. LLM-preferred produces richer
+ * assessments but requires capability access. Heuristic fallback
+ * ensures I-16 graceful degradation.
+ */
+export type CheckpointAssessmentMode = 'heuristic' | 'llm-preferred';
+/**
+ * §41, SD-02, SD-04: Reference agent configuration.
+ * Passed to createReferenceAgent() factory.
+ */
+export interface ReferenceAgentConfig {
+    /** Agent name used for registration and mission assignment. */
+    readonly name: string;
+    /** SD-02: How objectives are decomposed into task graphs. Default: 'heuristic'. */
+    readonly decompositionStrategy?: DecompositionStrategy;
+    /** Maximum retry attempts for retryable errors. Default: 3. */
+    readonly maxRetryAttempts?: number;
+    /** SD-04: How checkpoint assessments are computed. Default: 'heuristic'. */
+    readonly checkpointAssessmentMode?: CheckpointAssessmentMode;
+    /** System prompt for agent registration. Optional. */
+    readonly systemPrompt?: string;
+    /** Agent domains for registration. Optional. */
+    readonly domains?: readonly string[];
+    /** Agent capabilities for registration. Optional. */
+    readonly capabilities?: readonly string[];
+}
+/**
+ * SDD §5: In-memory agent state maintained during mission execution.
+ * This state is transient -- NOT persisted by the agent.
+ * All authoritative state lives in the Limen engine (L1/L2).
+ *
+ * This shadow state is reconstructable from system call return values
+ * and checkpoint events. If the agent crashes, it resumes from the
+ * last checkpoint (S7), not from this state.
+ *
+ * Invariants: I-21 (bounded cognitive state)
+ */
+export interface AgentExecutionState {
+    readonly missionId: MissionId;
+    readonly objective: string;
+    readonly successCriteria: readonly string[];
+    readonly scopeBoundaries: readonly string[];
+    /** DR-P5-002: Capabilities from mission constraints, threaded through to decompose(). */
+    readonly capabilities: readonly string[];
+    budgetAllocated: number;
+    budgetConsumed: number;
+    currentPlanVersion: number;
+    planRevisionCount: number;
+    readonly activeTaskIds: Set<string>;
+    readonly completedTaskIds: Set<string>;
+    readonly completedArtifactIds: ArtifactId[];
+    readonly childMissionResults: Map<string, MissionResult>;
+    readonly checkpointHistory: CheckpointRecord[];
+    /** DR-P5-012: Explicit tracking of crossed budget thresholds to prevent re-triggering. */
+    readonly crossedBudgetThresholds: Set<number>;
+}
+/**
+ * §24: Record of a checkpoint interaction for self-reflection.
+ */
+export interface CheckpointRecord {
+    readonly checkpointId: string;
+    readonly trigger: string;
+    readonly assessment: string;
+    readonly confidence: number;
+    readonly action: string;
+    readonly timestamp: number;
+}
+/**
+ * SD-05: Three-category error taxonomy derived from S14-S24.
+ * Every error code from the 10 system calls is classified here.
+ */
+export type ErrorCategory = 'retryable' | 'recoverable' | 'terminal';
+/**
+ * SD-05: Classified error with category and original code.
+ */
+export interface ClassifiedError {
+    readonly code: LimenErrorCode;
+    readonly message: string;
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+}
+/**
+ * §41: Options for running a mission through the reference agent.
+ */
+export interface MissionRunOptions {
+    /** Mission objective. */
+    readonly objective: string;
+    /** Success criteria for the mission. */
+    readonly successCriteria?: readonly string[];
+    /** Scope boundaries for the mission. */
+    readonly scopeBoundaries?: readonly string[];
+    /** Mission constraints (budget, deadline, capabilities). */
+    readonly constraints: {
+        readonly tokenBudget: number;
+        readonly deadline: string;
+        readonly capabilities?: readonly string[];
+        readonly maxTasks?: number;
+        readonly maxChildren?: number;
+        readonly maxDepth?: number;
+    };
+    /** Deliverables expected from this mission. */
+    readonly deliverables?: ReadonlyArray<{
+        readonly type: string;
+        readonly name: string;
+    }>;
+    /** Parent mission ID for recursive delegation (UC-10). */
+    readonly parentMissionId?: MissionId;
+    /**
+     * SEC-P5-002: Current delegation depth for cycle/depth prevention.
+     * Incremented on each delegation. Checked against MISSION_TREE_DEFAULTS.maxDepth.
+     * Default: 0 (top-level mission).
+     */
+    readonly delegationDepth?: number;
+    /**
+     * Checkpoint handler callback. When the system fires a checkpoint,
+     * this callback is invoked. If not provided, the agent uses its
+     * internal heuristic/LLM handler.
+     */
+    readonly onCheckpoint?: CheckpointCallback;
+    /**
+     * Task execution callback. Invoked when a task needs execution.
+     * The agent drives execution through this callback. If not provided,
+     * the agent uses its internal executor.
+     */
+    readonly onTaskExecution?: TaskExecutionCallback;
+}
+/**
+ * §24: Callback invoked when the system fires a checkpoint.
+ */
+export type CheckpointCallback = (checkpointId: string, trigger: string, state: AgentExecutionState) => Promise<CheckpointResponseInput>;
+/**
+ * §17: Callback invoked when a task is ready for execution.
+ * Returns the task output content as a string.
+ */
+export type TaskExecutionCallback = (taskId: string, description: string, executionMode: 'deterministic' | 'stochastic' | 'hybrid', missionHandle: MissionHandle) => Promise<string>;
+/**
+ * §11, I-20: Budget decay factor for child mission delegation.
+ * Default: 0.3 per spec.
+ */
+export declare const DEFAULT_BUDGET_DECAY_FACTOR = 0.3;
+/**
+ * I-20: Default mission tree structural limits per spec.
+ */
+export declare const MISSION_TREE_DEFAULTS: {
+    readonly maxDepth: 5;
+    readonly maxChildren: 10;
+    readonly maxTasks: 50;
+    readonly maxTotalMissions: 50;
+};
+/**
+ * FM-17: Maximum plan revisions to prevent plan explosion.
+ * Agent-internal limit. Spec does not prescribe a specific number,
+ * but FM-17 requires bounded replanning.
+ *
+ * ASSUMPTION P5-FM17-1: We set this to 5, which allows reasonable
+ * adaptation without unbounded replanning. The spec says "plan_revision_limit"
+ * exists as an error code, implying the system enforces one. We track
+ * revisions internally and submit with current plan if limit reached.
+ */
+export declare const MAX_PLAN_REVISIONS = 5;
+/**
+ * §7: Default max retries for task execution per spec.
+ */
+export declare const DEFAULT_MAX_TASK_RETRIES = 2;
+/**
+ * FM-16: Confidence threshold below which the agent escalates.
+ * Derived from SDD §4 FM-16 defense: "Escalates when confidence drops below 0.5."
+ */
+export declare const ESCALATION_CONFIDENCE_THRESHOLD = 0.5;
+/**
+ * §22: Budget thresholds that trigger checkpoints.
+ * Per UC-12: checkpoints at 25%, 50%, 75%, 90% consumption.
+ */
+export declare const BUDGET_CHECKPOINT_THRESHOLDS: readonly [0.25, 0.5, 0.75, 0.9];
+//# sourceMappingURL=reference_agent.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference_agent.types.d.ts","sourceRoot":"","sources":["../../src/reference-agent/reference_agent.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EACtC,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAClD,cAAc,EAAE,eAAe,EAAE,QAAQ,EACzC,kBAAkB,EAAE,mBAAmB,EACvC,mBAAmB,EAAE,oBAAoB,EACzC,iBAAiB,EAAE,kBAAkB,EACrC,cAAc,EAAE,eAAe,EAC/B,sBAAsB,EAAE,uBAAuB,EAC/C,kBAAkB,EAAE,mBAAmB,EACvC,iBAAiB,EAAE,kBAAkB,EACrC,uBAAuB,EAAE,wBAAwB,EACjD,cAAc,EAAE,YAAY,EAC7B,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EACtC,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAClD,cAAc,EAAE,eAAe,EAAE,QAAQ,EACzC,kBAAkB,EAAE,mBAAmB,EACvC,mBAAmB,EAAE,oBAAoB,EACzC,iBAAiB,EAAE,kBAAkB,EACrC,cAAc,EAAE,eAAe,EAC/B,sBAAsB,EAAE,uBAAuB,EAC/C,kBAAkB,EAAE,mBAAmB,EACvC,iBAAiB,EAAE,kBAAkB,EACrC,uBAAuB,EAAE,wBAAwB,EACjD,cAAc,EAAE,YAAY,GAC7B,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,eAAe,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,eAAe,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mFAAmF;IACnF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAEvD,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC,4EAA4E;IAC5E,QAAQ,CAAC,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IAE7D,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,qDAAqD;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,oBAAoB,EAAE,UAAU,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACzD,QAAQ,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IAC/C,0FAA0F;IAC1F,QAAQ,CAAC,uBAAuB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,wCAAwC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,wCAAwC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IAEF,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;QACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IAEH,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAE3C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,KACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,eAAe,GAAG,YAAY,GAAG,QAAQ,EACxD,aAAa,EAAE,aAAa,KACzB,OAAO,CAAC,MAAM,CAAC,CAAC;AAMrB;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;CAKxB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,iCAAoC,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * Reference Agent internal type definitions.
+ * S ref: S6-S11, S14-S24 (types consumed from API surface),
+ *        SD-03 (single types file for DX simplicity)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: §6.1 of Synthesized SDD (Core Types)
+ *
+ * All API types are imported from src/api/. This file defines ONLY
+ * agent-internal types that are NOT part of the public API surface.
+ * The agent never creates its own branded ID types -- it uses the ones
+ * from the API surface exclusively.
+ *
+ * Invariants enforced: I-17 (governance boundary -- types import only from API)
+ * Failure modes defended: FM-14 (semantic drift -- types match spec exactly)
+ */
+// ============================================================================
+// Delegation Configuration (UC-10, I-20)
+// ============================================================================
+/**
+ * §11, I-20: Budget decay factor for child mission delegation.
+ * Default: 0.3 per spec.
+ */
+export const DEFAULT_BUDGET_DECAY_FACTOR = 0.3;
+/**
+ * I-20: Default mission tree structural limits per spec.
+ */
+export const MISSION_TREE_DEFAULTS = {
+    maxDepth: 5,
+    maxChildren: 10,
+    maxTasks: 50,
+    maxTotalMissions: 50, // I-20
+};
+/**
+ * FM-17: Maximum plan revisions to prevent plan explosion.
+ * Agent-internal limit. Spec does not prescribe a specific number,
+ * but FM-17 requires bounded replanning.
+ *
+ * ASSUMPTION P5-FM17-1: We set this to 5, which allows reasonable
+ * adaptation without unbounded replanning. The spec says "plan_revision_limit"
+ * exists as an error code, implying the system enforces one. We track
+ * revisions internally and submit with current plan if limit reached.
+ */
+export const MAX_PLAN_REVISIONS = 5;
+/**
+ * §7: Default max retries for task execution per spec.
+ */
+export const DEFAULT_MAX_TASK_RETRIES = 2;
+/**
+ * FM-16: Confidence threshold below which the agent escalates.
+ * Derived from SDD §4 FM-16 defense: "Escalates when confidence drops below 0.5."
+ */
+export const ESCALATION_CONFIDENCE_THRESHOLD = 0.5;
+/**
+ * §22: Budget thresholds that trigger checkpoints.
+ * Per UC-12: checkpoints at 25%, 50%, 75%, 90% consumption.
+ */
+export const BUDGET_CHECKPOINT_THRESHOLDS = [0.25, 0.50, 0.75, 0.90];
+//# sourceMappingURL=reference_agent.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference_agent.types.js","sourceRoot":"","sources":["../../src/reference-agent/reference_agent.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA+NH,+EAA+E;AAC/E,yCAAyC;AACzC,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,EAAE;IACZ,gBAAgB,EAAE,EAAE,EAAE,OAAO;CACrB,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC"}

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

@@ -0,0 +1,107 @@
+/**
+ * ResultAggregator -- mission completion and result synthesis.
+ * S ref: S23 (submit_result), SD-01 (lifecycle-phase grouping)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 5 (ResultAggregator)
+ *
+ * The ResultAggregator is responsible for:
+ *   1. Collecting results from completed tasks and child missions
+ *   2. Computing overall confidence from constituent results
+ *   3. Assembling deliverables (artifact references)
+ *   4. Producing unresolvedQuestions and followupRecommendations
+ *   5. Submitting the final result via SC-9 (submit_result)
+ *
+ * This is the final stage of the mission lifecycle. It synthesizes
+ * everything the agent has done into a coherent MissionResult.
+ *
+ * Invariants enforced: I-17 (governance boundary -- submit through SC-9),
+ *                      I-21 (bounded cognition -- uses only tracked artifacts)
+ * Failure modes defended: FM-14 (semantic drift -- result references objective)
+ */
+import type { ResultSubmitOutput, AgentExecutionState } from './reference_agent.types.js';
+import { SystemCallClient } from './system_call_client.js';
+/**
+ * §23: Compute aggregate confidence from execution state and child results.
+ *
+ * The aggregate confidence accounts for:
+ *   - Task completion ratio (primary factor)
+ *   - Child mission confidences (weighted by budget proportion)
+ *   - Artifact production (evidence of work)
+ *   - Checkpoint history trend (improving or declining)
+ *
+ * @param state - Agent execution state
+ * @returns Aggregate confidence in [0.0, 1.0]
+ */
+export declare function computeAggregateConfidence(state: AgentExecutionState): number;
+/**
+ * §23: Generate a result summary from execution state.
+ *
+ * The summary references the original objective (I-24 goal anchoring)
+ * and includes key metrics from the execution.
+ *
+ * @param state - Agent execution state
+ * @param confidence - Computed confidence
+ * @returns Human-readable summary string
+ */
+export declare function generateResultSummary(state: AgentExecutionState, confidence: number): string;
+/**
+ * §23: Collect unresolved questions from execution state.
+ *
+ * These are questions the agent could not answer within its budget
+ * and scope. They provide transparency about what was NOT achieved.
+ *
+ * @param state - Agent execution state
+ * @returns List of unresolved question strings
+ */
+export declare function collectUnresolvedQuestions(state: AgentExecutionState): string[];
+/**
+ * §23: Generate followup recommendations from execution state.
+ *
+ * @param state - Agent execution state
+ * @returns List of recommendation strings
+ */
+export declare function collectFollowupRecommendations(state: AgentExecutionState): string[];
+/**
+ * SD-01: ResultAggregator groups submit_result.
+ * It synthesizes everything the agent has done into a final MissionResult.
+ *
+ * The aggregator:
+ *   1. Collects all artifact IDs produced during execution
+ *   2. Incorporates child mission results
+ *   3. Computes aggregate confidence
+ *   4. Generates summary, unresolved questions, recommendations
+ *   5. Submits via SC-9 (submit_result)
+ */
+export declare class ResultAggregator {
+    private readonly client;
+    constructor(client: SystemCallClient);
+    /**
+     * §23, SC-9: Submit the mission result.
+     *
+     * This is the terminal call in the mission lifecycle. After this,
+     * the mission transitions to COMPLETED (or REVIEWING).
+     *
+     * I-21: Only artifacts tracked in completedArtifactIds are referenced.
+     * The agent does not reference artifacts it hasn't created or read.
+     *
+     * @param state - Final agent execution state
+     * @returns ResultSubmitOutput with resultId and final missionState
+     */
+    submitResult(state: AgentExecutionState): Promise<ResultSubmitOutput>;
+    /**
+     * §23: Submit a result with custom summary and confidence.
+     *
+     * Used when the agent has specific information to include in the result
+     * beyond what the automatic aggregation produces.
+     *
+     * @param state - Agent execution state
+     * @param summary - Custom summary string
+     * @param confidence - Custom confidence score
+     * @param unresolvedQuestions - Custom unresolved questions
+     * @param followupRecommendations - Custom recommendations
+     * @returns ResultSubmitOutput
+     */
+    submitCustomResult(state: AgentExecutionState, summary: string, confidence: number, unresolvedQuestions?: string[], followupRecommendations?: string[]): Promise<ResultSubmitOutput>;
+}
+//# sourceMappingURL=result_aggregator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result_aggregator.d.ts","sourceRoot":"","sources":["../../src/reference-agent/result_aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAES,kBAAkB,EACrC,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA6B7E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CAiBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAuB/E;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAyBnF;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,MAAM,EAAE,gBAAgB;IAIpC;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4B3E;;;;;;;;;;;;OAYG;IACG,kBAAkB,CACtB,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,mBAAmB,GAAE,MAAM,EAAO,EAClC,uBAAuB,GAAE,MAAM,EAAO,GACrC,OAAO,CAAC,kBAAkB,CAAC;CAY/B"}

package/dist/reference-agent/result_aggregator.js

@@ -0,0 +1,219 @@
+/**
+ * ResultAggregator -- mission completion and result synthesis.
+ * S ref: S23 (submit_result), SD-01 (lifecycle-phase grouping)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 5 (ResultAggregator)
+ *
+ * The ResultAggregator is responsible for:
+ *   1. Collecting results from completed tasks and child missions
+ *   2. Computing overall confidence from constituent results
+ *   3. Assembling deliverables (artifact references)
+ *   4. Producing unresolvedQuestions and followupRecommendations
+ *   5. Submitting the final result via SC-9 (submit_result)
+ *
+ * This is the final stage of the mission lifecycle. It synthesizes
+ * everything the agent has done into a coherent MissionResult.
+ *
+ * Invariants enforced: I-17 (governance boundary -- submit through SC-9),
+ *                      I-21 (bounded cognition -- uses only tracked artifacts)
+ * Failure modes defended: FM-14 (semantic drift -- result references objective)
+ */
+// ============================================================================
+// Confidence Aggregation
+// ============================================================================
+/**
+ * §23: Compute aggregate confidence from execution state and child results.
+ *
+ * The aggregate confidence accounts for:
+ *   - Task completion ratio (primary factor)
+ *   - Child mission confidences (weighted by budget proportion)
+ *   - Artifact production (evidence of work)
+ *   - Checkpoint history trend (improving or declining)
+ *
+ * @param state - Agent execution state
+ * @returns Aggregate confidence in [0.0, 1.0]
+ */
+export function computeAggregateConfidence(state) {
+    const totalTasks = state.activeTaskIds.size + state.completedTaskIds.size;
+    // Base confidence from task completion
+    let confidence;
+    if (totalTasks === 0) {
+        confidence = 0.5;
+    }
+    else {
+        confidence = state.completedTaskIds.size / totalTasks;
+    }
+    // Incorporate child mission confidences (if any)
+    if (state.childMissionResults.size > 0) {
+        let childConfidenceSum = 0;
+        for (const [, result] of state.childMissionResults) {
+            childConfidenceSum += result.confidence;
+        }
+        const avgChildConfidence = childConfidenceSum / state.childMissionResults.size;
+        // Weighted: 60% own completion, 40% child confidence
+        confidence = (confidence * 0.6) + (avgChildConfidence * 0.4);
+    }
+    // Artifact production bonus
+    if (state.completedArtifactIds.length > 0) {
+        confidence = Math.min(1, confidence + 0.05);
+    }
+    return Math.min(1, Math.max(0, confidence));
+}
+// ============================================================================
+// Result Summary Generation
+// ============================================================================
+/**
+ * §23: Generate a result summary from execution state.
+ *
+ * The summary references the original objective (I-24 goal anchoring)
+ * and includes key metrics from the execution.
+ *
+ * @param state - Agent execution state
+ * @param confidence - Computed confidence
+ * @returns Human-readable summary string
+ */
+export function generateResultSummary(state, confidence) {
+    const totalTasks = state.activeTaskIds.size + state.completedTaskIds.size;
+    const completedCount = state.completedTaskIds.size;
+    const artifactCount = state.completedArtifactIds.length;
+    const childCount = state.childMissionResults.size;
+    let summary = `Mission "${state.objective}" completed. `;
+    summary += `${completedCount}/${totalTasks} tasks executed, `;
+    summary += `${artifactCount} artifacts produced`;
+    if (childCount > 0) {
+        summary += `, ${childCount} child missions aggregated`;
+    }
+    summary += `. Confidence: ${(confidence * 100).toFixed(0)}%.`;
+    return summary;
+}
+/**
+ * §23: Collect unresolved questions from execution state.
+ *
+ * These are questions the agent could not answer within its budget
+ * and scope. They provide transparency about what was NOT achieved.
+ *
+ * @param state - Agent execution state
+ * @returns List of unresolved question strings
+ */
+export function collectUnresolvedQuestions(state) {
+    const questions = [];
+    // Tasks that remain active (not completed) represent unresolved work
+    if (state.activeTaskIds.size > 0) {
+        questions.push(`${state.activeTaskIds.size} task(s) were not completed within budget constraints.`);
+    }
+    // Child missions with low confidence
+    for (const [missionId, result] of state.childMissionResults) {
+        if (result.confidence < 0.7) {
+            questions.push(`Child mission ${missionId} completed with low confidence (${(result.confidence * 100).toFixed(0)}%).`);
+        }
+        for (const q of result.unresolvedQuestions) {
+            questions.push(q);
+        }
+    }
+    return questions;
+}
+/**
+ * §23: Generate followup recommendations from execution state.
+ *
+ * @param state - Agent execution state
+ * @returns List of recommendation strings
+ */
+export function collectFollowupRecommendations(state) {
+    const recommendations = [];
+    // Incomplete tasks -> recommend completing them
+    if (state.activeTaskIds.size > 0) {
+        recommendations.push(`Commission follow-up mission to complete ${state.activeTaskIds.size} remaining task(s).`);
+    }
+    // Aggregate child recommendations
+    for (const [, result] of state.childMissionResults) {
+        for (const rec of result.followupRecommendations) {
+            recommendations.push(rec);
+        }
+    }
+    // Budget exhaustion -> recommend additional budget
+    if (state.budgetAllocated > 0 && state.budgetConsumed >= state.budgetAllocated * 0.9) {
+        recommendations.push('Budget was nearly exhausted. Consider allocating additional budget for deeper analysis.');
+    }
+    return recommendations;
+}
+// ============================================================================
+// ResultAggregator Class
+// ============================================================================
+/**
+ * SD-01: ResultAggregator groups submit_result.
+ * It synthesizes everything the agent has done into a final MissionResult.
+ *
+ * The aggregator:
+ *   1. Collects all artifact IDs produced during execution
+ *   2. Incorporates child mission results
+ *   3. Computes aggregate confidence
+ *   4. Generates summary, unresolved questions, recommendations
+ *   5. Submits via SC-9 (submit_result)
+ */
+export class ResultAggregator {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * §23, SC-9: Submit the mission result.
+     *
+     * This is the terminal call in the mission lifecycle. After this,
+     * the mission transitions to COMPLETED (or REVIEWING).
+     *
+     * I-21: Only artifacts tracked in completedArtifactIds are referenced.
+     * The agent does not reference artifacts it hasn't created or read.
+     *
+     * @param state - Final agent execution state
+     * @returns ResultSubmitOutput with resultId and final missionState
+     */
+    async submitResult(state) {
+        const confidence = computeAggregateConfidence(state);
+        const summary = generateResultSummary(state, confidence);
+        const unresolvedQuestions = collectUnresolvedQuestions(state);
+        const followupRecommendations = collectFollowupRecommendations(state);
+        // Collect all artifact IDs (own + child mission artifacts)
+        const allArtifactIds = [...state.completedArtifactIds];
+        // Add artifacts from child mission results
+        for (const [, result] of state.childMissionResults) {
+            for (const artifact of result.artifacts) {
+                allArtifactIds.push(artifact.id);
+            }
+        }
+        const input = {
+            missionId: state.missionId,
+            summary,
+            confidence,
+            artifactIds: allArtifactIds,
+            unresolvedQuestions,
+            followupRecommendations,
+        };
+        return this.client.submitResult(input);
+    }
+    /**
+     * §23: Submit a result with custom summary and confidence.
+     *
+     * Used when the agent has specific information to include in the result
+     * beyond what the automatic aggregation produces.
+     *
+     * @param state - Agent execution state
+     * @param summary - Custom summary string
+     * @param confidence - Custom confidence score
+     * @param unresolvedQuestions - Custom unresolved questions
+     * @param followupRecommendations - Custom recommendations
+     * @returns ResultSubmitOutput
+     */
+    async submitCustomResult(state, summary, confidence, unresolvedQuestions = [], followupRecommendations = []) {
+        const input = {
+            missionId: state.missionId,
+            summary,
+            confidence,
+            artifactIds: state.completedArtifactIds,
+            unresolvedQuestions,
+            followupRecommendations,
+        };
+        return this.client.submitResult(input);
+    }
+}
+//# sourceMappingURL=result_aggregator.js.map

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

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