limen-ai 1.0.0

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

@@ -0,0 +1,106 @@
+/**
+ * SystemCallClient -- thin wrapper over MissionHandle system call methods.
+ * S ref: S14 (interface design principles), SD-07 (thin wrapper rationale),
+ *        SD-05 (error taxonomy)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §6.2 (System Call Client Interface), §6.3 (Error Code Classification)
+ *
+ * This wrapper provides:
+ *   - Structured error classification (every error code categorized per SD-05)
+ *   - Transient-error retry with exponential backoff (WORKER_UNAVAILABLE, RATE_LIMITED)
+ *   - Consistent logging pattern for debugging
+ *
+ * This wrapper does NOT:
+ *   - Cache state (would violate I-17 by creating shadow authority)
+ *   - Validate beyond spec (orchestrator validates; agent does not second-guess)
+ *   - Extend capabilities (pure passthrough to MissionHandle methods)
+ *
+ * Invariants enforced: I-17 (governance boundary -- pure passthrough)
+ * Failure modes defended: FM-02 (cost explosion -- retry limits prevent waste)
+ */
+import type { MissionHandle, MissionCreateOptions, TaskGraphInput, TaskGraphOutput, TaskExecutionInput, TaskExecutionOutput, ArtifactCreateInput, ArtifactCreateOutput, ArtifactReadInput, ArtifactReadOutput, EventEmitInput, EventEmitOutput, CapabilityRequestInput, CapabilityRequestOutput, BudgetRequestInput, BudgetRequestOutput, ResultSubmitInput, ResultSubmitOutput, CheckpointResponseInput, CheckpointResponseOutput, LimenErrorCode } from './reference_agent.types.js';
+import type { ClassifiedError, ErrorCategory } from './reference_agent.types.js';
+/**
+ * SD-05: Classify an error code into the three-category taxonomy.
+ * Unknown codes default to 'terminal' for safety.
+ *
+ * @param code - The LimenErrorCode to classify
+ * @returns The error category
+ */
+export declare function classifyError(code: LimenErrorCode): ErrorCategory;
+/**
+ * SD-05: Create a ClassifiedError from a caught error.
+ *
+ * @param error - The caught error (from system call rejection)
+ * @returns Structured ClassifiedError with category
+ */
+export declare function toClassifiedError(error: unknown): ClassifiedError;
+/**
+ * SD-07: Retry a system call with exponential backoff for transient errors.
+ *
+ * Only retries errors classified as 'retryable' (WORKER_UNAVAILABLE, RATE_LIMITED).
+ * Recoverable and terminal errors are NOT retried -- they require agent restructuring
+ * or escalation, respectively.
+ *
+ * @param fn - The async operation to retry
+ * @param maxRetries - Maximum retry attempts (default 3)
+ * @returns The result of the operation
+ * @throws ClassifiedError if all retries exhausted or non-retryable error
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number): Promise<T>;
+/**
+ * SD-07, S14: System call client wrapping MissionHandle methods.
+ *
+ * Pure passthrough convenience wrapper. Does NOT add state caching,
+ * validation beyond spec, or capability extension.
+ *
+ * Each method:
+ *   1. Delegates to the corresponding MissionHandle method
+ *   2. Applies retry logic for retryable errors
+ *   3. Classifies errors for the caller
+ *
+ * I-17: This wrapper is a pure convenience layer. It adds no capabilities
+ * beyond what MissionHandle provides. It does not create shadow authority.
+ */
+export declare class SystemCallClient {
+    private readonly handle;
+    private readonly maxRetries;
+    constructor(handle: MissionHandle, maxRetries?: number);
+    /**
+     * §15, SC-1, DR-P5-003: Propose (create) a mission via limen.missions.create().
+     *
+     * Static method because SC-1 executes BEFORE a MissionHandle exists.
+     * The returned handle is then used to construct a SystemCallClient instance
+     * for SC-2 through SC-10.
+     *
+     * @param missions - The limen.missions API object
+     * @param options - Mission creation options
+     * @param maxRetries - Maximum retry attempts for transient errors
+     * @returns MissionHandle for the created mission
+     */
+    static proposeMission(missions: {
+        create(options: MissionCreateOptions): Promise<MissionHandle>;
+    }, options: MissionCreateOptions, maxRetries?: number): Promise<MissionHandle>;
+    /** §15: Get the mission handle for direct access when needed. */
+    getHandle(): MissionHandle;
+    /** §16, SC-2: Propose a task graph with retry for transient errors. */
+    proposeTaskGraph(input: TaskGraphInput): Promise<TaskGraphOutput>;
+    /** §17, SC-3: Propose task execution with retry for transient errors. */
+    proposeTaskExecution(input: TaskExecutionInput): Promise<TaskExecutionOutput>;
+    /** §18, SC-4: Create an artifact with retry for transient errors. */
+    createArtifact(input: ArtifactCreateInput): Promise<ArtifactCreateOutput>;
+    /** §19, SC-5: Read an artifact with retry for transient errors. */
+    readArtifact(input: ArtifactReadInput): Promise<ArtifactReadOutput>;
+    /** §20, SC-6: Emit an event with retry for transient errors. */
+    emitEvent(input: EventEmitInput): Promise<EventEmitOutput>;
+    /** §21, SC-7: Request a capability with retry for transient errors. */
+    requestCapability(input: CapabilityRequestInput): Promise<CapabilityRequestOutput>;
+    /** §22, SC-8: Request additional budget with retry for transient errors. */
+    requestBudget(input: BudgetRequestInput): Promise<BudgetRequestOutput>;
+    /** §23, SC-9: Submit mission result with retry for transient errors. */
+    submitResult(input: ResultSubmitInput): Promise<ResultSubmitOutput>;
+    /** §24, SC-10: Respond to a checkpoint with retry for transient errors. */
+    respondCheckpoint(input: CheckpointResponseInput): Promise<CheckpointResponseOutput>;
+}
+//# sourceMappingURL=system_call_client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system_call_client.d.ts","sourceRoot":"","sources":["../../src/reference-agent/system_call_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EAAE,eAAe,EAC/B,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,EACf,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAgEjF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAoBjE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,GAAE,MAAU,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,aAAa,EAAE,UAAU,GAAE,MAAU;IAKzD;;;;;;;;;;;OAWG;WACU,cAAc,CACzB,QAAQ,EAAE;QAAE,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;KAAE,EAC3E,OAAO,EAAE,oBAAoB,EAC7B,UAAU,GAAE,MAAU,GACrB,OAAO,CAAC,aAAa,CAAC;IAIzB,iEAAiE;IACjE,SAAS,IAAI,aAAa;IAI1B,uEAAuE;IACjE,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAIvE,yEAAyE;IACnE,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAInF,qEAAqE;IAC/D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI/E,mEAAmE;IAC7D,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIzE,gEAAgE;IAC1D,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAIhE,uEAAuE;IACjE,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAIxF,4EAA4E;IACtE,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI5E,wEAAwE;IAClE,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIzE,2EAA2E;IACrE,iBAAiB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAG3F"}

package/dist/reference-agent/system_call_client.js

@@ -0,0 +1,231 @@
+/**
+ * SystemCallClient -- thin wrapper over MissionHandle system call methods.
+ * S ref: S14 (interface design principles), SD-07 (thin wrapper rationale),
+ *        SD-05 (error taxonomy)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §6.2 (System Call Client Interface), §6.3 (Error Code Classification)
+ *
+ * This wrapper provides:
+ *   - Structured error classification (every error code categorized per SD-05)
+ *   - Transient-error retry with exponential backoff (WORKER_UNAVAILABLE, RATE_LIMITED)
+ *   - Consistent logging pattern for debugging
+ *
+ * This wrapper does NOT:
+ *   - Cache state (would violate I-17 by creating shadow authority)
+ *   - Validate beyond spec (orchestrator validates; agent does not second-guess)
+ *   - Extend capabilities (pure passthrough to MissionHandle methods)
+ *
+ * Invariants enforced: I-17 (governance boundary -- pure passthrough)
+ * Failure modes defended: FM-02 (cost explosion -- retry limits prevent waste)
+ */
+// ============================================================================
+// Error Classification (SD-05)
+// ============================================================================
+/**
+ * SD-05: Exhaustive error code classification.
+ * Every error code from S15-S24 is mapped to exactly one category.
+ *
+ * Retryable: transient infrastructure failures -- retry with backoff.
+ * Recoverable: agent can restructure and retry with a different approach.
+ * Terminal: cannot recover -- abort or escalate.
+ */
+const ERROR_CLASSIFICATION = new Map([
+    // Retryable (transient infrastructure)
+    ['WORKER_UNAVAILABLE', 'retryable'],
+    ['RATE_LIMITED', 'retryable'],
+    // Recoverable (agent can adapt)
+    ['BUDGET_EXCEEDED', 'recoverable'],
+    ['TASK_LIMIT_EXCEEDED', 'recoverable'],
+    ['PLAN_REVISION_LIMIT', 'recoverable'],
+    ['CAPABILITY_DENIED', 'recoverable'],
+    ['STORAGE_EXCEEDED', 'recoverable'],
+    ['ARTIFACT_LIMIT_EXCEEDED', 'recoverable'],
+    ['CHECKPOINT_EXPIRED', 'recoverable'],
+    ['INVALID_PLAN', 'recoverable'],
+    ['PARENT_INSUFFICIENT', 'recoverable'],
+    ['HUMAN_APPROVAL_REQUIRED', 'recoverable'],
+    ['DEPENDENCIES_UNMET', 'recoverable'],
+    ['ARCHIVED', 'recoverable'],
+    ['JUSTIFICATION_REQUIRED', 'recoverable'],
+    // Terminal (cannot recover)
+    ['CYCLE_DETECTED', 'terminal'],
+    ['CAPABILITY_VIOLATION', 'terminal'],
+    ['DEPTH_EXCEEDED', 'terminal'],
+    ['CHILDREN_EXCEEDED', 'terminal'],
+    ['TREE_SIZE_EXCEEDED', 'terminal'],
+    ['AGENT_NOT_FOUND', 'terminal'],
+    ['UNAUTHORIZED', 'terminal'],
+    ['DEADLINE_EXCEEDED', 'terminal'],
+    ['MISSION_NOT_ACTIVE', 'terminal'],
+    ['INVALID_DEPENDENCY', 'terminal'],
+    ['TASKS_INCOMPLETE', 'terminal'],
+    ['NO_ARTIFACTS', 'terminal'],
+    ['NOT_FOUND', 'terminal'],
+    ['INVALID_TYPE', 'terminal'],
+    ['MISSION_NOT_FOUND', 'terminal'],
+    ['TASK_NOT_PENDING', 'terminal'],
+    ['TIMEOUT', 'terminal'],
+    ['SANDBOX_VIOLATION', 'terminal'],
+    ['DELEGATION_CYCLE', 'terminal'],
+    // API surface errors (pass-through, classified as terminal)
+    ['CANCELLED', 'terminal'],
+    ['PROVIDER_UNAVAILABLE', 'recoverable'],
+    ['SCHEMA_VALIDATION_FAILED', 'terminal'],
+    ['ENGINE_UNHEALTHY', 'terminal'],
+    ['SESSION_NOT_FOUND', 'terminal'],
+    ['INVALID_CONFIG', 'terminal'],
+]);
+/**
+ * SD-05: Classify an error code into the three-category taxonomy.
+ * Unknown codes default to 'terminal' for safety.
+ *
+ * @param code - The LimenErrorCode to classify
+ * @returns The error category
+ */
+export function classifyError(code) {
+    return ERROR_CLASSIFICATION.get(code) ?? 'terminal';
+}
+/**
+ * SD-05: Create a ClassifiedError from a caught error.
+ *
+ * @param error - The caught error (from system call rejection)
+ * @returns Structured ClassifiedError with category
+ */
+export function toClassifiedError(error) {
+    if (error && typeof error === 'object' && 'code' in error && 'message' in error) {
+        const e = error;
+        const category = classifyError(e.code);
+        return {
+            code: e.code,
+            message: e.message,
+            category,
+            retryable: category === 'retryable',
+        };
+    }
+    // Unknown error shape -- treat as terminal
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: 'ENGINE_UNHEALTHY',
+        message,
+        category: 'terminal',
+        retryable: false,
+    };
+}
+// ============================================================================
+// Retry Logic (SD-07)
+// ============================================================================
+/**
+ * SD-07: Retry a system call with exponential backoff for transient errors.
+ *
+ * Only retries errors classified as 'retryable' (WORKER_UNAVAILABLE, RATE_LIMITED).
+ * Recoverable and terminal errors are NOT retried -- they require agent restructuring
+ * or escalation, respectively.
+ *
+ * @param fn - The async operation to retry
+ * @param maxRetries - Maximum retry attempts (default 3)
+ * @returns The result of the operation
+ * @throws ClassifiedError if all retries exhausted or non-retryable error
+ */
+export async function withRetry(fn, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = toClassifiedError(error);
+            if (lastError.category !== 'retryable') {
+                throw lastError;
+            }
+            if (attempt < maxRetries) {
+                // Exponential backoff: 100ms, 200ms, 400ms, ...
+                const delayMs = 100 * Math.pow(2, attempt);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+        }
+    }
+    // All retries exhausted
+    throw lastError;
+}
+// ============================================================================
+// System Call Client (SD-07)
+// ============================================================================
+/**
+ * SD-07, S14: System call client wrapping MissionHandle methods.
+ *
+ * Pure passthrough convenience wrapper. Does NOT add state caching,
+ * validation beyond spec, or capability extension.
+ *
+ * Each method:
+ *   1. Delegates to the corresponding MissionHandle method
+ *   2. Applies retry logic for retryable errors
+ *   3. Classifies errors for the caller
+ *
+ * I-17: This wrapper is a pure convenience layer. It adds no capabilities
+ * beyond what MissionHandle provides. It does not create shadow authority.
+ */
+export class SystemCallClient {
+    handle;
+    maxRetries;
+    constructor(handle, maxRetries = 3) {
+        this.handle = handle;
+        this.maxRetries = maxRetries;
+    }
+    /**
+     * §15, SC-1, DR-P5-003: Propose (create) a mission via limen.missions.create().
+     *
+     * Static method because SC-1 executes BEFORE a MissionHandle exists.
+     * The returned handle is then used to construct a SystemCallClient instance
+     * for SC-2 through SC-10.
+     *
+     * @param missions - The limen.missions API object
+     * @param options - Mission creation options
+     * @param maxRetries - Maximum retry attempts for transient errors
+     * @returns MissionHandle for the created mission
+     */
+    static async proposeMission(missions, options, maxRetries = 3) {
+        return withRetry(() => missions.create(options), maxRetries);
+    }
+    /** §15: Get the mission handle for direct access when needed. */
+    getHandle() {
+        return this.handle;
+    }
+    /** §16, SC-2: Propose a task graph with retry for transient errors. */
+    async proposeTaskGraph(input) {
+        return withRetry(() => this.handle.proposeTaskGraph(input), this.maxRetries);
+    }
+    /** §17, SC-3: Propose task execution with retry for transient errors. */
+    async proposeTaskExecution(input) {
+        return withRetry(() => this.handle.proposeTaskExecution(input), this.maxRetries);
+    }
+    /** §18, SC-4: Create an artifact with retry for transient errors. */
+    async createArtifact(input) {
+        return withRetry(() => this.handle.createArtifact(input), this.maxRetries);
+    }
+    /** §19, SC-5: Read an artifact with retry for transient errors. */
+    async readArtifact(input) {
+        return withRetry(() => this.handle.readArtifact(input), this.maxRetries);
+    }
+    /** §20, SC-6: Emit an event with retry for transient errors. */
+    async emitEvent(input) {
+        return withRetry(() => this.handle.emitEvent(input), this.maxRetries);
+    }
+    /** §21, SC-7: Request a capability with retry for transient errors. */
+    async requestCapability(input) {
+        return withRetry(() => this.handle.requestCapability(input), this.maxRetries);
+    }
+    /** §22, SC-8: Request additional budget with retry for transient errors. */
+    async requestBudget(input) {
+        return withRetry(() => this.handle.requestBudget(input), this.maxRetries);
+    }
+    /** §23, SC-9: Submit mission result with retry for transient errors. */
+    async submitResult(input) {
+        return withRetry(() => this.handle.submitResult(input), this.maxRetries);
+    }
+    /** §24, SC-10: Respond to a checkpoint with retry for transient errors. */
+    async respondCheckpoint(input) {
+        return withRetry(() => this.handle.respondCheckpoint(input), this.maxRetries);
+    }
+}
+//# sourceMappingURL=system_call_client.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system_call_client.js","sourceRoot":"","sources":["../../src/reference-agent/system_call_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAmBH,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAA+C,IAAI,GAAG,CAAgC;IAC9G,uCAAuC;IACvC,CAAC,oBAAoB,EAAE,WAAW,CAAC;IACnC,CAAC,cAAc,EAAE,WAAW,CAAC;IAE7B,gCAAgC;IAChC,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAClC,CAAC,qBAAqB,EAAE,aAAa,CAAC;IACtC,CAAC,qBAAqB,EAAE,aAAa,CAAC;IACtC,CAAC,mBAAmB,EAAE,aAAa,CAAC;IACpC,CAAC,kBAAkB,EAAE,aAAa,CAAC;IACnC,CAAC,yBAAyB,EAAE,aAAa,CAAC;IAC1C,CAAC,oBAAoB,EAAE,aAAa,CAAC;IACrC,CAAC,cAAc,EAAE,aAAa,CAAC;IAC/B,CAAC,qBAAqB,EAAE,aAAa,CAAC;IACtC,CAAC,yBAAyB,EAAE,aAAa,CAAC;IAC1C,CAAC,oBAAoB,EAAE,aAAa,CAAC;IACrC,CAAC,UAAU,EAAE,aAAa,CAAC;IAC3B,CAAC,wBAAwB,EAAE,aAAa,CAAC;IAEzC,4BAA4B;IAC5B,CAAC,gBAAgB,EAAE,UAAU,CAAC;IAC9B,CAAC,sBAAsB,EAAE,UAAU,CAAC;IACpC,CAAC,gBAAgB,EAAE,UAAU,CAAC;IAC9B,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACjC,CAAC,oBAAoB,EAAE,UAAU,CAAC;IAClC,CAAC,iBAAiB,EAAE,UAAU,CAAC;IAC/B,CAAC,cAAc,EAAE,UAAU,CAAC;IAC5B,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACjC,CAAC,oBAAoB,EAAE,UAAU,CAAC;IAClC,CAAC,oBAAoB,EAAE,UAAU,CAAC;IAClC,CAAC,kBAAkB,EAAE,UAAU,CAAC;IAChC,CAAC,cAAc,EAAE,UAAU,CAAC;IAC5B,CAAC,WAAW,EAAE,UAAU,CAAC;IACzB,CAAC,cAAc,EAAE,UAAU,CAAC;IAC5B,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACjC,CAAC,kBAAkB,EAAE,UAAU,CAAC;IAChC,CAAC,SAAS,EAAE,UAAU,CAAC;IACvB,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACjC,CAAC,kBAAkB,EAAE,UAAU,CAAC;IAEhC,4DAA4D;IAC5D,CAAC,WAAW,EAAE,UAAU,CAAC;IACzB,CAAC,sBAAsB,EAAE,aAAa,CAAC;IACvC,CAAC,0BAA0B,EAAE,UAAU,CAAC;IACxC,CAAC,kBAAkB,EAAE,UAAU,CAAC;IAChC,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACjC,CAAC,gBAAgB,EAAE,UAAU,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAoB;IAChD,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAChF,MAAM,CAAC,GAAG,KAAuE,CAAC;QAClF,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,QAAQ;YACR,SAAS,EAAE,QAAQ,KAAK,WAAW;SACpC,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO;QACL,IAAI,EAAE,kBAAoC;QAC1C,OAAO;QACP,QAAQ,EAAE,UAAU;QACpB,SAAS,EAAE,KAAK;KACjB,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,aAAqB,CAAC;IAEtB,IAAI,SAAsC,CAAC;IAE3C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAErC,IAAI,SAAS,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;gBACvC,MAAM,SAAS,CAAC;YAClB,CAAC;YAED,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBACzB,gDAAgD;gBAChD,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBAC3C,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,MAAM,SAAU,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAgB;IACtB,UAAU,CAAS;IAEpC,YAAY,MAAqB,EAAE,aAAqB,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,QAA2E,EAC3E,OAA6B,EAC7B,aAAqB,CAAC;QAEtB,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/D,CAAC;IAED,iEAAiE;IACjE,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,gBAAgB,CAAC,KAAqB;QAC1C,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/E,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,oBAAoB,CAAC,KAAyB;QAClD,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACnF,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,cAAc,CAAC,KAA0B;QAC7C,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7E,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3E,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,SAAS,CAAC,KAAqB;QACnC,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACxE,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,iBAAiB,CAAC,KAA6B;QACnD,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChF,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,aAAa,CAAC,KAAyB;QAC3C,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3E,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,iBAAiB,CAAC,KAA8B;QACpD,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChF,CAAC;CACF"}

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

@@ -0,0 +1,108 @@
+/**
+ * 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 type { MissionId, TaskExecutionOutput, CapabilityRequestOutput, AgentExecutionState, TaskExecutionCallback, CheckpointCallback } from './reference_agent.types.js';
+import { SystemCallClient } from './system_call_client.js';
+import type { CheckpointHandler } from './checkpoint_handler.js';
+import type { TimeProvider } from '../kernel/interfaces/time.js';
+/**
+ * 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 declare class TaskExecutor {
+    private readonly client;
+    private readonly onExecution;
+    private readonly clock;
+    constructor(client: SystemCallClient, onExecution?: TaskExecutionCallback, time?: TimeProvider);
+    /**
+     * §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
+     */
+    executeTask(taskId: string, description: string, executionMode: 'deterministic' | 'stochastic' | 'hybrid', capabilities: readonly string[], timeout: number, _state: AgentExecutionState): Promise<TaskExecutionOutput>;
+    /**
+     * §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
+     */
+    executeTaskGraph(tasks: readonly {
+        readonly id: string;
+        readonly description: string;
+        readonly executionMode: 'deterministic' | 'stochastic' | 'hybrid';
+        readonly capabilitiesRequired?: readonly string[];
+    }[], dependencies: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[], state: AgentExecutionState, taskDescriptions: ReadonlyMap<string, string>, checkpointHandler?: CheckpointHandler, onCheckpoint?: CheckpointCallback): Promise<readonly string[]>;
+    /**
+     * §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
+     */
+    requestCapability(capabilityType: string, parameters: Record<string, unknown>, missionId: MissionId, taskId: string, state: AgentExecutionState): Promise<CapabilityRequestOutput>;
+    /**
+     * Find all tasks that transitively depend on a given task.
+     * Used to propagate failure cancellation.
+     */
+    private findDependents;
+}
+//# sourceMappingURL=task_executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task_executor.d.ts","sourceRoot":"","sources":["../../src/reference-agent/task_executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACF,SAAS,EACG,mBAAmB,EACf,uBAAuB,EAC/C,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAqB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAMjE;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGnC,MAAM,EAAE,gBAAgB,EACxB,WAAW,CAAC,EAAE,qBAAqB,EACnC,IAAI,CAAC,EAAE,YAAY;IAOrB;;;;;;;;;;;;;;;;OAgBG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,eAAe,GAAG,YAAY,GAAG,QAAQ,EACxD,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,CAAC;IAsB/B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,CACpB,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,aAAa,EAAE,eAAe,GAAG,YAAY,GAAG,QAAQ,CAAC;QAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,EAC7L,YAAY,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,EACvE,KAAK,EAAE,mBAAmB,EAC1B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7C,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,YAAY,CAAC,EAAE,kBAAkB,GAChC,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IA6H7B;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,uBAAuB,CAAC;IAkBnC;;;OAGG;IACH,OAAO,CAAC,cAAc;CAmBvB"}