limen-ai 1.0.0

package/dist/reference-agent/task_executor.js

@@ -0,0 +1,249 @@
+/**
+ * TaskExecutor -- drives tasks through their lifecycle.
+ * S ref: S17 (propose_task_execution), S21 (request_capability),
+ *        SD-01 (lifecycle-phase grouping)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 3 (TaskExecutor)
+ *
+ * The TaskExecutor is responsible for:
+ *   1. Proposing task execution via SC-3 (propose_task_execution)
+ *   2. Requesting capabilities via SC-7 (request_capability)
+ *   3. Driving tasks through PENDING -> SCHEDULED -> RUNNING -> terminal
+ *   4. Respecting dependency order (agent-side dependency awareness)
+ *
+ * The executor does NOT validate dependencies -- that is the orchestrator's job.
+ * It does NOT manage artifacts -- that is ArtifactManager's job.
+ *
+ * Invariants enforced: I-17 (all execution through system calls),
+ *                      I-22 (capability immutability -- uses only mission-scoped caps)
+ * Failure modes defended: FM-02 (budget tracking per execution)
+ */
+import { toClassifiedError } from './system_call_client.js';
+// ============================================================================
+// TaskExecutor Class
+// ============================================================================
+/**
+ * SD-01: TaskExecutor groups propose_task_execution + request_capability.
+ * These are the "execution" calls that perform WORK on individual tasks.
+ *
+ * The executor:
+ *   1. Drives tasks in dependency order (topological sort awareness)
+ *   2. Proposes execution via system call
+ *   3. Uses capabilities within mission scope (I-22)
+ *   4. Tracks budget consumption from execution responses
+ */
+export class TaskExecutor {
+    client;
+    onExecution;
+    clock;
+    constructor(client, onExecution, time) {
+        this.client = client;
+        this.onExecution = onExecution;
+        this.clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    }
+    /**
+     * §17, SC-3: Execute a single task.
+     *
+     * Proposes task execution to the orchestrator. The orchestrator validates
+     * dependencies, budget, and task state before scheduling.
+     *
+     * DR-P5-011: Now accepts description parameter so the callback receives
+     * a meaningful task description instead of an empty string.
+     *
+     * @param taskId - The task to execute
+     * @param description - Human-readable description of the task
+     * @param executionMode - How the task should be executed
+     * @param capabilities - Capabilities required for this task
+     * @param timeout - Execution timeout in milliseconds
+     * @param state - Current agent execution state (for budget tracking)
+     * @returns TaskExecutionOutput with scheduling info
+     */
+    async executeTask(taskId, description, executionMode, capabilities, timeout, _state) {
+        const input = {
+            taskId: taskId,
+            executionMode,
+            environmentRequest: {
+                capabilities: capabilities,
+                timeout,
+            },
+        };
+        const result = await this.client.proposeTaskExecution(input);
+        // If we have a custom execution callback, invoke it
+        // DR-P5-011: Thread the actual task description through to the callback.
+        if (this.onExecution) {
+            const handle = this.client.getHandle();
+            await this.onExecution(taskId, description, executionMode, handle);
+        }
+        return result;
+    }
+    /**
+     * §17: Execute all tasks in a graph respecting dependency order.
+     *
+     * This is a simplified topological execution: tasks with no unresolved
+     * dependencies execute first, then their dependents, and so on.
+     *
+     * SEC-P5-006: Added retry counter per task for DEPENDENCIES_UNMET and
+     * max iteration count for outer while loop to prevent infinite loops.
+     *
+     * DR-P5-004: Polls checkBudgetThreshold() between task executions.
+     * When a threshold is crossed, invokes the checkpoint handler.
+     *
+     * @param tasks - Task definitions from the task graph
+     * @param dependencies - Dependency edges (from -> to means "from must complete before to")
+     * @param state - Agent execution state for tracking
+     * @param taskDescriptions - Map of taskId to description for the executor callback
+     * @param checkpointHandler - Optional checkpoint handler for budget threshold polling (DR-P5-004)
+     * @param onCheckpoint - Optional checkpoint callback from MissionRunOptions
+     * @returns List of completed task IDs in execution order
+     */
+    async executeTaskGraph(tasks, dependencies, state, taskDescriptions, checkpointHandler, onCheckpoint) {
+        const completedTasks = [];
+        const remainingTasks = new Set(tasks.map(t => t.id));
+        const taskMap = new Map(tasks.map(t => [t.id, t]));
+        // SEC-P5-006: Per-task retry counter for DEPENDENCIES_UNMET errors.
+        const depUnmetRetries = new Map();
+        const MAX_DEP_UNMET_RETRIES = 3;
+        // SEC-P5-006: Max iterations for outer loop to prevent infinite loops.
+        // Worst case: each iteration resolves one task. tasks.length * (MAX_DEP_UNMET_RETRIES + 1)
+        // gives a generous upper bound.
+        const MAX_ITERATIONS = tasks.length * (MAX_DEP_UNMET_RETRIES + 2);
+        let iterations = 0;
+        // Build adjacency: for each task, which tasks must complete before it
+        const incomingDeps = new Map();
+        for (const task of tasks) {
+            incomingDeps.set(task.id, new Set());
+        }
+        for (const dep of dependencies) {
+            incomingDeps.get(dep.to)?.add(dep.from);
+        }
+        // Topological execution loop
+        while (remainingTasks.size > 0) {
+            // SEC-P5-006: Guard against infinite loop.
+            iterations++;
+            if (iterations > MAX_ITERATIONS) {
+                break;
+            }
+            // Find tasks with all dependencies satisfied
+            const readyTasks = [];
+            for (const taskId of remainingTasks) {
+                const deps = incomingDeps.get(taskId);
+                if (!deps || deps.size === 0) {
+                    readyTasks.push(taskId);
+                }
+            }
+            if (readyTasks.length === 0) {
+                // All remaining tasks have unresolved dependencies.
+                // This should not happen if the DAG was validated, but we handle it.
+                break;
+            }
+            // Execute ready tasks (sequentially for determinism in heuristic mode)
+            for (const taskId of readyTasks) {
+                const task = taskMap.get(taskId);
+                if (!task)
+                    continue;
+                // DR-P5-011: Get actual task description for the callback
+                const description = taskDescriptions.get(taskId) ?? task.description ?? taskId;
+                try {
+                    await this.executeTask(taskId, description, task.executionMode, task.capabilitiesRequired ?? [], 60000, // Default timeout
+                    state);
+                    completedTasks.push(taskId);
+                    remainingTasks.delete(taskId);
+                    state.activeTaskIds.delete(taskId);
+                    state.completedTaskIds.add(taskId);
+                    // Remove this task from all dependents' incoming deps
+                    for (const [, deps] of incomingDeps) {
+                        deps.delete(taskId);
+                    }
+                    // DR-P5-004: Poll budget threshold after each task execution.
+                    if (checkpointHandler) {
+                        const threshold = checkpointHandler.checkBudgetThreshold(state);
+                        if (threshold !== null) {
+                            // Budget threshold crossed -- handle checkpoint
+                            const checkpointId = `budget-${threshold}-${this.clock.nowMs()}`;
+                            if (onCheckpoint) {
+                                // Use consumer-provided callback
+                                const response = await onCheckpoint(checkpointId, 'BUDGET_THRESHOLD', state);
+                                await this.client.respondCheckpoint(response);
+                            }
+                            else {
+                                // Use internal heuristic handler
+                                await checkpointHandler.handleCheckpoint(checkpointId, 'BUDGET_THRESHOLD', state);
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    const classified = toClassifiedError(error);
+                    if (classified.code === 'DEPENDENCIES_UNMET') {
+                        // SEC-P5-006: Track retries per task, don't retry forever
+                        const retryCount = (depUnmetRetries.get(taskId) ?? 0) + 1;
+                        depUnmetRetries.set(taskId, retryCount);
+                        if (retryCount < MAX_DEP_UNMET_RETRIES) {
+                            // Task not ready yet -- skip and retry next iteration
+                            continue;
+                        }
+                        // Exhausted retries -- fall through to failure handling
+                    }
+                    // For other errors (or exhausted DEPENDENCIES_UNMET retries),
+                    // mark task as failed and continue
+                    remainingTasks.delete(taskId);
+                    state.activeTaskIds.delete(taskId);
+                    // Propagate failure: remove all tasks that depend on this one
+                    const toCancel = this.findDependents(taskId, dependencies);
+                    for (const cancelId of toCancel) {
+                        remainingTasks.delete(cancelId);
+                        state.activeTaskIds.delete(cancelId);
+                    }
+                }
+            }
+        }
+        return completedTasks;
+    }
+    /**
+     * §21, SC-7: Request a capability execution within a task.
+     *
+     * I-22: The capability must be within the mission's capability set.
+     * The system validates this -- the agent does not second-guess.
+     *
+     * @param capabilityType - The capability to invoke
+     * @param parameters - Capability-specific parameters
+     * @param missionId - The mission context
+     * @param taskId - The task context
+     * @param state - Agent execution state (for budget tracking)
+     * @returns CapabilityRequestOutput with result and resources consumed
+     */
+    async requestCapability(capabilityType, parameters, missionId, taskId, state) {
+        const input = {
+            capabilityType,
+            parameters,
+            missionId,
+            taskId: taskId,
+        };
+        const result = await this.client.requestCapability(input);
+        // FM-02: Track budget consumption from capability execution
+        if (result.resourcesConsumed.tokens) {
+            state.budgetConsumed += result.resourcesConsumed.tokens;
+        }
+        return result;
+    }
+    /**
+     * Find all tasks that transitively depend on a given task.
+     * Used to propagate failure cancellation.
+     */
+    findDependents(taskId, dependencies) {
+        const dependents = new Set();
+        const queue = [taskId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dep of dependencies) {
+                if (dep.from === current && !dependents.has(dep.to)) {
+                    dependents.add(dep.to);
+                    queue.push(dep.to);
+                }
+            }
+        }
+        return dependents;
+    }
+}
+//# sourceMappingURL=task_executor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task_executor.js","sourceRoot":"","sources":["../../src/reference-agent/task_executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH,OAAO,EAAoB,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI9E,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAmB;IACzB,WAAW,CAAoC;IAC/C,KAAK,CAAe;IAErC,YACE,MAAwB,EACxB,WAAmC,EACnC,IAAmB;QAEnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC3F,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,WAAW,CACf,MAAc,EACd,WAAmB,EACnB,aAAwD,EACxD,YAA+B,EAC/B,OAAe,EACf,MAA2B;QAE3B,MAAM,KAAK,GAAuB;YAChC,MAAM,EAAE,MAAgB;YACxB,aAAa;YACb,kBAAkB,EAAE;gBAClB,YAAY,EAAE,YAAwB;gBACtC,OAAO;aACR;SACF,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE7D,oDAAoD;QACpD,yEAAyE;QACzE,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACrE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,gBAAgB,CACpB,KAA6L,EAC7L,YAAuE,EACvE,KAA0B,EAC1B,gBAA6C,EAC7C,iBAAqC,EACrC,YAAiC;QAEjC,MAAM,cAAc,GAAa,EAAE,CAAC;QACpC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAEnD,oEAAoE;QACpE,MAAM,eAAe,GAAG,IAAI,GAAG,EAAkB,CAAC;QAClD,MAAM,qBAAqB,GAAG,CAAC,CAAC;QAEhC,uEAAuE;QACvE,2FAA2F;QAC3F,gCAAgC;QAChC,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,qBAAqB,GAAG,CAAC,CAAC,CAAC;QAClE,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,sEAAsE;QACtE,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;QACpD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,6BAA6B;QAC7B,OAAO,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC/B,2CAA2C;YAC3C,UAAU,EAAE,CAAC;YACb,IAAI,UAAU,GAAG,cAAc,EAAE,CAAC;gBAChC,MAAM;YACR,CAAC;YAED,6CAA6C;YAC7C,MAAM,UAAU,GAAa,EAAE,CAAC;YAChC,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;gBACpC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBAC7B,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;YAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,oDAAoD;gBACpD,qEAAqE;gBACrE,MAAM;YACR,CAAC;YAED,uEAAuE;YACvE,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;gBAChC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjC,IAAI,CAAC,IAAI;oBAAE,SAAS;gBAEpB,0DAA0D;gBAC1D,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC;gBAE/E,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,WAAW,CACpB,MAAM,EACN,WAAW,EACX,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,oBAAoB,IAAI,EAAE,EAC/B,KAAK,EAAE,kBAAkB;oBACzB,KAAK,CACN,CAAC;oBAEF,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAC5B,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC9B,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBACnC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAEnC,sDAAsD;oBACtD,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,YAAY,EAAE,CAAC;wBACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBACtB,CAAC;oBAED,8DAA8D;oBAC9D,IAAI,iBAAiB,EAAE,CAAC;wBACtB,MAAM,SAAS,GAAG,iBAAiB,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;wBAChE,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;4BACvB,gDAAgD;4BAChD,MAAM,YAAY,GAAG,UAAU,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;4BACjE,IAAI,YAAY,EAAE,CAAC;gCACjB,iCAAiC;gCACjC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC;gCAC7E,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;4BAChD,CAAC;iCAAM,CAAC;gCACN,iCAAiC;gCACjC,MAAM,iBAAiB,CAAC,gBAAgB,CACtC,YAAY,EAAE,kBAAkB,EAAE,KAAK,CACxC,CAAC;4BACJ,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAc,EAAE,CAAC;oBACxB,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;oBAE5C,IAAI,UAAU,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;wBAC7C,0DAA0D;wBAC1D,MAAM,UAAU,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;wBAC1D,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;wBACxC,IAAI,UAAU,GAAG,qBAAqB,EAAE,CAAC;4BACvC,sDAAsD;4BACtD,SAAS;wBACX,CAAC;wBACD,wDAAwD;oBAC1D,CAAC;oBAED,8DAA8D;oBAC9D,mCAAmC;oBACnC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC9B,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAEnC,8DAA8D;oBAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;oBAC3D,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;wBAChC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;wBAChC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBACvC,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,cAAc,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,iBAAiB,CACrB,cAAsB,EACtB,UAAmC,EACnC,SAAoB,EACpB,MAAc,EACd,KAA0B;QAE1B,MAAM,KAAK,GAA2B;YACpC,cAAc;YACd,UAAU;YACV,SAAS;YACT,MAAM,EAAE,MAAgB;SACzB,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAE1D,4DAA4D;QAC5D,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC;YACpC,KAAK,CAAC,cAAc,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC;QAC1D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,cAAc,CACpB,MAAc,EACd,YAAuE;QAEvE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC;QAEvB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAC/B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;gBAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;oBACpD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBACvB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}

package/dist/substrate/accounting/resource_accounting.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Resource Accounting implementation.
+ * S ref: §25.6 (Resource Accounting), §11 (Resource Model), FM-02 (Cost Explosion)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: Per-task token/time/compute/artifact tracking via meter_interaction_accounting.
+ *             Budget enforcement with max(engine, provider) effective token counting per §11.
+ *
+ * Invariants enforced: I-03 (audit in same transaction), I-05 (transactional)
+ * Failure modes defended: FM-02 (cost explosion), FM-11 (observability overhead < 2%)
+ *
+ * SYNC interface. All methods return Result<T>.
+ */
+import type { DatabaseConnection } from '../../kernel/interfaces/index.js';
+import type { Result, AuditCreateInput } from '../../kernel/interfaces/index.js';
+/**
+ * Minimal audit dependency. Uses only the append method to keep coupling lightweight.
+ * S ref: I-03 (every state mutation and its audit entry in same transaction)
+ */
+interface AuditDep {
+    append(conn: DatabaseConnection, input: AuditCreateInput): Result<unknown>;
+}
+import type { ResourceAccounting } from '../interfaces/substrate.js';
+/**
+ * §25.6 default budget limit (tokens). Configurable per mission via orchestration.
+ * This is the fallback if no mission-specific budget is set.
+ */
+export declare const DEFAULT_BUDGET_LIMIT = 1000000;
+/**
+ * Create a ResourceAccounting implementation.
+ * S ref: §25.6, C-07 (Object.freeze)
+ *
+ * Token counting follows §11: effective = max(engine_counted, provider_reported).
+ * Budget enforcement prevents cost explosion (FM-02).
+ */
+export declare function createResourceAccounting(audit?: AuditDep): ResourceAccounting;
+/**
+ * Phase 5A: Supplementary deliberation recording for resource accounting.
+ * Called by the LLM gateway after a successful transport execution.
+ * This is a standalone function (not on the frozen ResourceAccounting interface)
+ * because deliberation data comes from the transport layer, not from the
+ * AccountingRecord input.
+ *
+ * S ref: §25.6, I-03 (same transaction as accounting record)
+ */
+export declare function recordAccountingDeliberation(conn: DatabaseConnection, accountingId: string, deliberation: {
+    deliberationTokens: number;
+    accountingMode: 'provider_authoritative' | 'estimated';
+    providerReportedThinkingTokens: number | null;
+}): void;
+export {};
+//# sourceMappingURL=resource_accounting.d.ts.map

package/dist/substrate/accounting/resource_accounting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource_accounting.d.ts","sourceRoot":"","sources":["../../../src/substrate/accounting/resource_accounting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EACV,MAAM,EAIN,gBAAgB,EACjB,MAAM,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;CAC5E;AACD,OAAO,KAAK,EACV,kBAAkB,EAKnB,MAAM,4BAA4B,CAAC;AAUpC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,kBAAkB,CAkL7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,kBAAkB,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE;IACZ,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,wBAAwB,GAAG,WAAW,CAAC;IACvD,8BAA8B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,GACA,IAAI,CAyBN"}

package/dist/substrate/accounting/resource_accounting.js

@@ -0,0 +1,200 @@
+/**
+ * Resource Accounting implementation.
+ * S ref: §25.6 (Resource Accounting), §11 (Resource Model), FM-02 (Cost Explosion)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: Per-task token/time/compute/artifact tracking via meter_interaction_accounting.
+ *             Budget enforcement with max(engine, provider) effective token counting per §11.
+ *
+ * Invariants enforced: I-03 (audit in same transaction), I-05 (transactional)
+ * Failure modes defended: FM-02 (cost explosion), FM-11 (observability overhead < 2%)
+ *
+ * SYNC interface. All methods return Result<T>.
+ */
+import { randomUUID } from 'node:crypto';
+// ─── Error Constructors ───
+function ok(value) {
+    return { ok: true, value };
+}
+// ─── Resource Accounting Factory ───
+/**
+ * §25.6 default budget limit (tokens). Configurable per mission via orchestration.
+ * This is the fallback if no mission-specific budget is set.
+ */
+export const DEFAULT_BUDGET_LIMIT = 1_000_000;
+/**
+ * Create a ResourceAccounting implementation.
+ * S ref: §25.6, C-07 (Object.freeze)
+ *
+ * Token counting follows §11: effective = max(engine_counted, provider_reported).
+ * Budget enforcement prevents cost explosion (FM-02).
+ */
+export function createResourceAccounting(audit) {
+    /** §25.6: Record a task interaction's resource consumption */
+    function record(conn, _ctx, rec) {
+        // §11: effective = max(engine, provider)
+        const providerIn = rec.providerInputTokens ?? 0;
+        const providerOut = rec.providerOutputTokens ?? 0;
+        const effectiveIn = Math.max(rec.inputTokens, providerIn);
+        const effectiveOut = Math.max(rec.outputTokens, providerOut);
+        const id = randomUUID();
+        // I-03: mutation + audit in same transaction
+        conn.transaction(() => {
+            conn.run(`INSERT INTO meter_interaction_accounting
+          (id, task_id, mission_id, tenant_id, agent_id, model_id,
+           interaction_type, input_tokens, output_tokens,
+           provider_input_tokens, provider_output_tokens,
+           effective_input_tokens, effective_output_tokens,
+           wall_clock_ms, artifacts_bytes, capabilities_used, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`, [
+                id,
+                rec.taskId,
+                rec.missionId,
+                rec.tenantId,
+                rec.agentId,
+                rec.modelId,
+                rec.interactionType,
+                rec.inputTokens,
+                rec.outputTokens,
+                rec.providerInputTokens ?? null,
+                rec.providerOutputTokens ?? null,
+                effectiveIn,
+                effectiveOut,
+                rec.wallClockMs,
+                rec.artifactsBytes,
+                JSON.stringify(rec.capabilitiesUsed),
+            ]);
+            audit?.append(conn, {
+                tenantId: rec.tenantId,
+                actorType: 'system',
+                actorId: 'substrate.accounting',
+                operation: 'accounting.record',
+                resourceType: 'accounting',
+                resourceId: id,
+                detail: {
+                    taskId: rec.taskId,
+                    missionId: rec.missionId,
+                    interactionType: rec.interactionType,
+                    effectiveInputTokens: effectiveIn,
+                    effectiveOutputTokens: effectiveOut,
+                },
+            });
+        });
+        return ok(undefined);
+    }
+    /** §11, FM-02: Check if estimated tokens would exceed mission budget */
+    function checkBudget(conn, missionId, estimatedTokens) {
+        // Sum effective tokens for this mission
+        const row = conn.get(`SELECT COALESCE(SUM(effective_input_tokens + effective_output_tokens), 0) as total_effective
+       FROM meter_interaction_accounting
+       WHERE mission_id = ?`, [missionId]);
+        const consumed = row?.total_effective ?? 0;
+        const budgetLimit = DEFAULT_BUDGET_LIMIT;
+        const remaining = budgetLimit - consumed;
+        if (estimatedTokens > remaining) {
+            return ok({
+                allowed: false,
+                remainingTokens: remaining,
+                consumedTokens: consumed,
+                budgetLimit,
+                reason: `Estimated ${estimatedTokens} tokens exceeds remaining budget of ${remaining}`,
+            });
+        }
+        return ok({
+            allowed: true,
+            remainingTokens: remaining,
+            consumedTokens: consumed,
+            budgetLimit,
+        });
+    }
+    /** §25.6: Get total consumption for a mission */
+    function getMissionConsumption(conn, missionId) {
+        const row = conn.get(`SELECT
+        COALESCE(SUM(effective_input_tokens), 0) as total_effective_in,
+        COALESCE(SUM(effective_output_tokens), 0) as total_effective_out,
+        COALESCE(SUM(wall_clock_ms), 0) as total_wall_clock,
+        COALESCE(SUM(artifacts_bytes), 0) as total_artifacts_bytes,
+        COUNT(*) as interaction_count
+       FROM meter_interaction_accounting
+       WHERE mission_id = ?`, [missionId]);
+        if (!row) {
+            return ok({
+                missionId,
+                totalEffectiveInputTokens: 0,
+                totalEffectiveOutputTokens: 0,
+                totalWallClockMs: 0,
+                totalArtifactsBytes: 0,
+                interactionCount: 0,
+            });
+        }
+        return ok({
+            missionId,
+            totalEffectiveInputTokens: row.total_effective_in,
+            totalEffectiveOutputTokens: row.total_effective_out,
+            totalWallClockMs: row.total_wall_clock,
+            totalArtifactsBytes: row.total_artifacts_bytes,
+            interactionCount: row.interaction_count,
+        });
+    }
+    /** §25.6: Get total consumption for a tenant */
+    function getTenantConsumption(conn, tenantId) {
+        const row = conn.get(`SELECT
+        COALESCE(SUM(effective_input_tokens), 0) as total_effective_in,
+        COALESCE(SUM(effective_output_tokens), 0) as total_effective_out,
+        COUNT(*) as total_interactions
+       FROM meter_interaction_accounting
+       WHERE tenant_id = ?`, [tenantId]);
+        if (!row) {
+            return ok({
+                tenantId,
+                totalEffectiveInputTokens: 0,
+                totalEffectiveOutputTokens: 0,
+                totalInteractions: 0,
+            });
+        }
+        return ok({
+            tenantId,
+            totalEffectiveInputTokens: row.total_effective_in,
+            totalEffectiveOutputTokens: row.total_effective_out,
+            totalInteractions: row.total_interactions,
+        });
+    }
+    const accounting = {
+        record,
+        checkBudget,
+        getMissionConsumption,
+        getTenantConsumption,
+    };
+    // Expose deliberation recording as a separate function on the module
+    // (not on the frozen interface — this is an internal substrate path)
+    return Object.freeze(accounting);
+}
+/**
+ * Phase 5A: Supplementary deliberation recording for resource accounting.
+ * Called by the LLM gateway after a successful transport execution.
+ * This is a standalone function (not on the frozen ResourceAccounting interface)
+ * because deliberation data comes from the transport layer, not from the
+ * AccountingRecord input.
+ *
+ * S ref: §25.6, I-03 (same transaction as accounting record)
+ */
+export function recordAccountingDeliberation(conn, accountingId, deliberation) {
+    const effectiveDeliberationTokens = Math.max(deliberation.deliberationTokens, deliberation.providerReportedThinkingTokens ?? 0);
+    conn.run(`UPDATE meter_interaction_accounting
+     SET deliberation_tokens = ?,
+         deliberation_accounting_mode = ?,
+         provider_deliberation_tokens = ?,
+         effective_deliberation_tokens = ?,
+         estimator_id = ?,
+         estimator_version = ?
+     WHERE id = ?`, [
+        deliberation.deliberationTokens,
+        deliberation.accountingMode,
+        deliberation.providerReportedThinkingTokens,
+        effectiveDeliberationTokens,
+        null,
+        null,
+        accountingId,
+    ]);
+}
+//# sourceMappingURL=resource_accounting.js.map

package/dist/substrate/accounting/resource_accounting.js.map

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

package/dist/substrate/adapters/capability_registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Capability Adapter Registry implementation.
+ * S ref: §25.3 (Capability Adapters), I-12 (Tool Sandboxing), I-22 (Capability Immutability)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: Registry of 7 capability types with per-adapter sandbox configuration,
+ *             validation, and sandboxed execution. Capabilities are immutable once
+ *             registered for a mission (I-22).
+ *
+ * Seven capability types per specification:
+ *   web_search, web_fetch, code_execute, data_query, file_read, file_write, api_call
+ *
+ * Invariants enforced: I-12 (sandbox), I-22 (immutable capabilities)
+ * Failure modes defended: FM-09 (unauthorized tool execution)
+ *
+ * SYNC interface. All methods return Result<T>.
+ */
+import type { CapabilityAdapterRegistry } from '../interfaces/substrate.js';
+/**
+ * Create a CapabilityAdapterRegistry implementation.
+ * S ref: §25.3, C-07 (Object.freeze)
+ *
+ * Adapters are registered with sandbox configurations.
+ * Execution validates the requested capability, applies sandbox rules,
+ * and dispatches to the adapter implementation.
+ */
+export declare function createCapabilityAdapterRegistry(): CapabilityAdapterRegistry;
+//# sourceMappingURL=capability_registry.d.ts.map

package/dist/substrate/adapters/capability_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability_registry.d.ts","sourceRoot":"","sources":["../../../src/substrate/adapters/capability_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EACV,yBAAyB,EAO1B,MAAM,4BAA4B,CAAC;AAgGpC;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,IAAI,yBAAyB,CAkI3E"}