@cleocode/core 2026.3.74 → 2026.3.76

package/README.md

@@ -565,7 +565,7 @@ async function buildKnowledge() {
 
 - `@cleocode/contracts` - Type definitions
 - `@cleocode/caamp` - Context-aware agent memory protocol
-- `@cleocode/lafs-protocol` - Language-agnostic feedback schema
+- `@cleocode/lafs` - Language-agnostic feedback schema
 - `drizzle-orm` - Database ORM
 - `zod` - Schema validation
 - `pino` - Logging

package/dist/cant/approval.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Approval gate manager for CANT workflow execution.
+ *
+ * Manages the lifecycle of approval tokens: generation, validation,
+ * approval, rejection, and expiration. Tokens follow the state machine
+ * defined in CANT-DSL-SPEC.md Section 8.2.
+ *
+ * State transitions are atomic (CAS): only `pending -> approved`,
+ * `pending -> rejected`, and `pending -> expired` are permitted.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 8 (Approval Token Protocol)
+ */
+import type { ApprovalToken, TokenValidation } from './types.js';
+/**
+ * Manages approval tokens for CANT workflow gates.
+ *
+ * Tokens are stored in-memory per instance. In production, these are
+ * persisted via the session's `approvalTokensJson` column in tasks.db.
+ */
+export declare class ApprovalManager {
+    /** In-memory token store keyed by token UUID. */
+    private tokens;
+    /**
+     * Generates a new approval token for a workflow gate.
+     *
+     * @param sessionId - The session that owns this token.
+     * @param workflowName - The workflow containing the approval gate.
+     * @param gateName - The label of the specific approval gate.
+     * @param message - The message to display to the approver.
+     * @param workflowHash - SHA-256 hash of the workflow definition.
+     * @param requestedBy - The agent/workflow requesting approval.
+     * @param expiresInMs - Token lifetime in milliseconds (default: 24h).
+     * @returns The generated approval token.
+     */
+    generateToken(sessionId: string, workflowName: string, gateName: string, message: string, workflowHash: string, requestedBy: string, expiresInMs?: number): ApprovalToken;
+    /**
+     * Validates an approval token against the current execution context.
+     *
+     * Checks: (a) token exists, (b) sessionId matches, (c) status is pending,
+     * (d) not expired, (e) workflowHash matches current workflow.
+     *
+     * @param tokenId - The token UUID to validate.
+     * @param currentSessionId - The current session to validate against.
+     * @param currentWorkflowHash - The current workflow hash for TOCTOU check.
+     * @returns Validation result with reason if invalid.
+     */
+    validateToken(tokenId: string, currentSessionId: string, currentWorkflowHash: string): TokenValidation;
+    /**
+     * Approves a pending token.
+     *
+     * Performs an atomic CAS transition: `pending -> approved`. If the token
+     * is not in `pending` state, the operation is a no-op and returns false.
+     *
+     * @param tokenId - The token UUID to approve.
+     * @param approvedBy - The identifier of the approving actor.
+     * @returns `true` if the transition succeeded, `false` if CAS failed.
+     */
+    approveToken(tokenId: string, approvedBy: string): boolean;
+    /**
+     * Rejects a pending token.
+     *
+     * Performs an atomic CAS transition: `pending -> rejected`.
+     *
+     * @param tokenId - The token UUID to reject.
+     * @returns `true` if the transition succeeded, `false` if CAS failed.
+     */
+    rejectToken(tokenId: string): boolean;
+    /**
+     * Expires a pending token.
+     *
+     * Performs an atomic CAS transition: `pending -> expired`.
+     *
+     * @param tokenId - The token UUID to expire.
+     * @returns `true` if the transition succeeded, `false` if CAS failed.
+     */
+    expireToken(tokenId: string): boolean;
+    /**
+     * Retrieves a token by its UUID.
+     *
+     * @param tokenId - The token UUID to look up.
+     * @returns The token if found, otherwise undefined.
+     */
+    getToken(tokenId: string): ApprovalToken | undefined;
+    /**
+     * Lists all tokens for a given session.
+     *
+     * @param sessionId - The session to filter by.
+     * @returns Array of tokens belonging to the session.
+     */
+    getTokensForSession(sessionId: string): ApprovalToken[];
+    /**
+     * Computes a SHA-256 hash of a workflow definition string.
+     *
+     * Used for TOCTOU protection: the hash at token creation time is compared
+     * against the hash at approval time.
+     *
+     * @param workflowText - The raw workflow definition text.
+     * @returns Hex-encoded SHA-256 hash.
+     */
+    static computeWorkflowHash(workflowText: string): string;
+    /**
+     * Atomically transitions a token from `pending` to the target status.
+     *
+     * @param tokenId - The token UUID.
+     * @param targetStatus - The desired new status.
+     * @returns `true` if the CAS transition succeeded.
+     */
+    private transitionStatus;
+}
+//# sourceMappingURL=approval.d.ts.map

package/dist/cant/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/cant/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAuB,eAAe,EAAE,MAAM,YAAY,CAAC;AAKtF;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,iDAAiD;IACjD,OAAO,CAAC,MAAM,CAAyC;IAEvD;;;;;;;;;;;OAWG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAA0B,GACtC,aAAa;IAmBhB;;;;;;;;;;OAUG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,EAAE,MAAM,GAC1B,eAAe;IA8BlB;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAc1D;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAWrC;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIpD;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAIvD;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAIxD;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;CASzB"}

package/dist/cant/context-builder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Execution context builder for CANT workflows.
+ *
+ * Resolves variable references and manages the scope chain for workflow
+ * execution. Variables from workflow parameters, step outputs, and
+ * intermediate bindings are tracked in a hierarchical scope.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7.2 (Workflow Execution)
+ */
+import type { ExecutionScope } from './types.js';
+/**
+ * Creates a new root execution scope with initial variable bindings.
+ *
+ * @param initialBindings - Initial variable values (typically workflow parameters).
+ * @returns A new root scope.
+ */
+export declare function createScope(initialBindings?: Record<string, unknown>): ExecutionScope;
+/**
+ * Creates a child scope that inherits from a parent.
+ *
+ * Lookups in the child scope fall through to the parent if not found locally.
+ * This is used for parallel arms, loop iterations, and nested blocks.
+ *
+ * @param parent - The parent scope.
+ * @param localBindings - Local variable overrides for this child scope.
+ * @returns A new child scope.
+ */
+export declare function createChildScope(parent: ExecutionScope, localBindings?: Record<string, unknown>): ExecutionScope;
+/**
+ * Resolves a variable name in the scope chain.
+ *
+ * Searches the current scope first, then walks up the parent chain.
+ *
+ * @param scope - The scope to search in.
+ * @param name - The variable name to resolve.
+ * @returns The variable value, or `undefined` if not found in any scope.
+ */
+export declare function resolveVariable(scope: ExecutionScope, name: string): unknown;
+/**
+ * Sets a variable in the current scope (does not affect parent scopes).
+ *
+ * @param scope - The scope to modify.
+ * @param name - The variable name to set.
+ * @param value - The value to assign.
+ */
+export declare function setVariable(scope: ExecutionScope, name: string, value: unknown): void;
+/**
+ * Resolves `{variable}` placeholders in a template string against the scope.
+ *
+ * Performs single-pass replacement per the T07 security rule: nested
+ * interpolation within resolved values is treated as literal text.
+ *
+ * @param template - The string containing `{variable}` placeholders.
+ * @param scope - The execution scope for variable resolution.
+ * @returns The string with all placeholders resolved.
+ * @throws {Error} If a referenced variable is not found in any scope.
+ */
+export declare function resolveTemplate(template: string, scope: ExecutionScope): string;
+/**
+ * Merges step output into the current scope.
+ *
+ * Binds `<stepName>.stdout`, `<stepName>.stderr`, and `<stepName>.exitCode`
+ * for use in subsequent step variable resolution.
+ *
+ * @param scope - The scope to add bindings to.
+ * @param stepName - The name of the completed step.
+ * @param output - The step output to merge.
+ */
+export declare function mergeStepOutput(scope: ExecutionScope, stepName: string, output: Record<string, unknown>): void;
+/**
+ * Collects all variable bindings visible from the given scope (including parents).
+ *
+ * Parent bindings are overridden by child bindings of the same name.
+ *
+ * @param scope - The scope to flatten.
+ * @returns A flat record of all visible variable bindings.
+ */
+export declare function flattenScope(scope: ExecutionScope): Record<string, unknown>;
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/cant/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../src/cant/context-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,cAAc,CAIzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAC1C,cAAc,CAKhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAY5E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAErF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAQ/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAQN;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG3E"}

package/dist/cant/discretion.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Discretion evaluation for CANT workflow conditionals.
+ *
+ * Discretion conditions (`**prose text**`) are AI-evaluated logic gates
+ * in CANT workflows. The evaluation is pluggable: the default evaluator
+ * stubs `true` (real LLM integration is a separate task), while custom
+ * evaluators can be injected for testing, rule-based shortcuts, or
+ * alternative model backends.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7.3 (Discretion Evaluation)
+ */
+import type { DiscretionContext } from './types.js';
+/** Evaluates a discretion condition and returns a boolean judgment. */
+export interface DiscretionEvaluator {
+    /**
+     * Evaluate whether a discretion condition is met.
+     *
+     * @param condition - The prose text between `**` delimiters.
+     * @param context - Execution context including session, variables, and prior results.
+     * @returns `true` if the condition is judged to be met.
+     */
+    evaluate(condition: string, context: DiscretionContext): Promise<boolean>;
+}
+/**
+ * Default discretion evaluator that always returns `true`.
+ *
+ * This is a stub implementation. The real LLM-backed evaluator will be
+ * implemented as a separate task. In production, this should be replaced
+ * with an evaluator that:
+ * - Calls the LLM API with the condition in a structured field
+ * - Uses structured prompting (tool use / JSON mode)
+ * - Returns a boolean judgment
+ */
+export declare class DefaultDiscretionEvaluator implements DiscretionEvaluator {
+    /** Always returns `true` (stub). */
+    evaluate(_condition: string, _context: DiscretionContext): Promise<boolean>;
+}
+/**
+ * Mock discretion evaluator with configurable responses for testing.
+ *
+ * Responses can be set per condition text or as a blanket default.
+ */
+export declare class MockDiscretionEvaluator implements DiscretionEvaluator {
+    private responses;
+    private defaultResponse;
+    private evaluationLog;
+    /**
+     * Creates a mock evaluator.
+     *
+     * @param defaultResponse - The response for conditions without a specific mapping.
+     */
+    constructor(defaultResponse?: boolean);
+    /** Set the response for a specific condition text. */
+    setResponse(condition: string, result: boolean): void;
+    /** Evaluate using the configured response map. */
+    evaluate(condition: string, context: DiscretionContext): Promise<boolean>;
+    /** Get the log of all evaluations performed. */
+    getLog(): ReadonlyArray<{
+        condition: string;
+        context: DiscretionContext;
+        result: boolean;
+    }>;
+    /** Reset the evaluation log. */
+    clearLog(): void;
+}
+/**
+ * Wraps a discretion evaluator with rate limiting.
+ *
+ * Enforces a configurable maximum number of discretion evaluations per
+ * workflow execution. Default limit is 100 per the spec. This prevents
+ * runaway costs from loops containing discretion conditions.
+ */
+export declare class RateLimitedDiscretionEvaluator implements DiscretionEvaluator {
+    private readonly inner;
+    private readonly maxEvaluations;
+    private evaluationCount;
+    /**
+     * Creates a rate-limited evaluator wrapper.
+     *
+     * @param inner - The underlying evaluator to delegate to.
+     * @param maxEvaluations - Maximum evaluations allowed (default: 100).
+     */
+    constructor(inner: DiscretionEvaluator, maxEvaluations?: number);
+    /**
+     * Evaluate with rate limiting.
+     *
+     * @throws {Error} If the evaluation count exceeds the configured maximum.
+     */
+    evaluate(condition: string, context: DiscretionContext): Promise<boolean>;
+    /** Get the current evaluation count. */
+    getEvaluationCount(): number;
+    /** Reset the evaluation counter (for reuse across workflow runs). */
+    resetCount(): void;
+}
+//# sourceMappingURL=discretion.d.ts.map

package/dist/cant/discretion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discretion.d.ts","sourceRoot":"","sources":["../../src/cant/discretion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMpD,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAMD;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE,oCAAoC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;CAGlF;AAMD;;;;GAIG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB;IACjE,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,aAAa,CAChB;IAEL;;;;OAIG;gBACS,eAAe,UAAO;IAIlC,sDAAsD;IACtD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAIrD,kDAAkD;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAM/E,gDAAgD;IAChD,MAAM,IAAI,aAAa,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAI3F,gCAAgC;IAChC,QAAQ,IAAI,IAAI;CAGjB;AAMD;;;;;;GAMG;AACH,qBAAa,8BAA+B,YAAW,mBAAmB;IAUtE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAVjC,OAAO,CAAC,eAAe,CAAK;IAE5B;;;;;OAKG;gBAEgB,KAAK,EAAE,mBAAmB,EAC1B,cAAc,GAAE,MAAY;IAG/C;;;;OAIG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/E,wCAAwC;IACxC,kBAAkB,IAAI,MAAM;IAI5B,qEAAqE;IACrE,UAAU,IAAI,IAAI;CAGnB"}

package/dist/cant/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CANT DSL runtime — TypeScript workflow executor.
+ *
+ * This module provides the TypeScript side of the CANT hybrid runtime:
+ * - Workflow execution (sessions, parallel, conditionals, loops, try/catch)
+ * - Discretion evaluation (pluggable AI-judged conditions)
+ * - Approval gate management (token generation, validation, state machine)
+ * - Parallel arm execution (all/race/settle strategies)
+ * - Execution context and scope management
+ *
+ * Pipeline execution is handled by the Rust `cant-runtime` crate and
+ * bridged via napi-rs.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7 (Runtime) and Section 8 (Approval Tokens)
+ */
+export { ApprovalManager } from './approval.js';
+export { createChildScope, createScope, flattenScope, mergeStepOutput, resolveTemplate, resolveVariable, setVariable, } from './context-builder.js';
+export type { DiscretionEvaluator } from './discretion.js';
+export { DefaultDiscretionEvaluator, MockDiscretionEvaluator, RateLimitedDiscretionEvaluator, } from './discretion.js';
+export type { ParallelArm, ParallelResult } from './parallel-runner.js';
+export { executeParallel } from './parallel-runner.js';
+export type { ApprovalToken, ApprovalTokenStatus, DiscretionContext, ExecutionResult, ExecutionScope, JoinStrategy, SettleResult, StepResult, TokenValidation, } from './types.js';
+export type { WorkflowExecutorConfig } from './workflow-executor.js';
+export { WorkflowExecutor } from './workflow-executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cant/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cant/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/cant/parallel-runner.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Parallel arm execution for CANT workflow parallel blocks.
+ *
+ * Supports three join strategies:
+ * - `all` (default): Wait for ALL arms. Fail if any arm fails.
+ * - `race`: Return when the FIRST arm completes. Cancel remaining.
+ * - `settle`: Wait for ALL arms. Collect successes and failures.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7.5 (Parallel Execution)
+ */
+import type { JoinStrategy, SettleResult, StepResult } from './types.js';
+/** A single parallel arm to execute. */
+export interface ParallelArm {
+    /** The arm name (used for binding results to scope). */
+    name: string;
+    /** The async function that executes the arm's body. */
+    execute: () => Promise<unknown>;
+}
+/** Result of a parallel block execution. */
+export interface ParallelResult {
+    /** Whether the parallel block succeeded according to its join strategy. */
+    success: boolean;
+    /** Per-arm results mapped by arm name. */
+    results: Record<string, unknown>;
+    /** Step results for audit/logging. */
+    steps: StepResult[];
+    /** Settle-mode detailed breakdown (only for `settle` strategy). */
+    settleResult?: SettleResult;
+}
+/**
+ * Executes parallel arms according to the specified join strategy.
+ *
+ * @param arms - The arms to execute concurrently.
+ * @param strategy - The join strategy (default: 'all').
+ * @returns Parallel execution result.
+ */
+export declare function executeParallel(arms: ParallelArm[], strategy?: JoinStrategy): Promise<ParallelResult>;
+//# sourceMappingURL=parallel-runner.d.ts.map

package/dist/cant/parallel-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-runner.d.ts","sourceRoot":"","sources":["../../src/cant/parallel-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzE,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sCAAsC;IACtC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,mEAAmE;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,EAAE,EACnB,QAAQ,GAAE,YAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/cant/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Runtime types for the CANT DSL workflow executor.
+ *
+ * These types are used by the TypeScript workflow execution layer to
+ * represent execution results, step outcomes, discretion evaluation
+ * contexts, and approval tokens.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7 (Runtime) and Section 8 (Approval Tokens)
+ */
+/** The aggregate result of executing a CANT workflow. */
+export interface ExecutionResult {
+    /** Whether the workflow completed without errors. */
+    success: boolean;
+    /** Output bindings from `output name = expr` statements. */
+    outputs: Record<string, unknown>;
+    /** Results for each executed step in order. */
+    steps: StepResult[];
+    /** Total wall-clock execution duration in milliseconds. */
+    duration: number;
+}
+/** The result of a single workflow statement execution. */
+export interface StepResult {
+    /** The step or statement name. */
+    name: string;
+    /** The type of statement that was executed. */
+    type: 'session' | 'pipeline' | 'parallel' | 'conditional' | 'loop' | 'approval' | 'binding' | 'directive' | 'output';
+    /** Whether this step completed successfully. */
+    success: boolean;
+    /** The output value produced by this step, if any. */
+    output?: unknown;
+    /** Error message if the step failed. */
+    error?: string;
+    /** Wall-clock execution duration in milliseconds. */
+    duration: number;
+}
+/** Context provided to a discretion evaluator for AI-judged conditions. */
+export interface DiscretionContext {
+    /** The current session identifier. */
+    sessionId: string;
+    /** Task references currently in scope. */
+    taskRefs: string[];
+    /** The agent performing the evaluation. */
+    agentId: string;
+    /** All variables in the current workflow scope. */
+    variables: Record<string, unknown>;
+    /** The raw discretion condition text (between `**` delimiters). */
+    condition: string;
+    /** Output from preceding pipeline steps or session results. */
+    precedingResults: Record<string, unknown>;
+}
+/** Valid states for an approval token. */
+export type ApprovalTokenStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+/**
+ * An approval token for human-in-the-loop workflow gates.
+ *
+ * Tokens are bound to a specific session and workflow. The `workflowHash`
+ * provides TOCTOU protection: if the workflow is modified between token
+ * creation and approval, the token is invalidated.
+ *
+ * Security invariants:
+ * - Token values MUST NOT appear in audit logs, summaries, or error messages.
+ * - `approvalTokensJson` is NEVER included in handoff/debrief serialization.
+ * - Status transitions use atomic CAS (pending -> approved|rejected|expired only).
+ */
+export interface ApprovalToken {
+    /** UUID v4 generated via CSPRNG (crypto.randomUUID). */
+    token: string;
+    /** The session that generated this token. Token is bound to this session. */
+    sessionId: string;
+    /** The workflow that contains the approval gate. */
+    workflowName: string;
+    /** The name label of the specific approval gate. */
+    gateName: string;
+    /**
+     * SHA-256 hash of the workflow definition text at the time the token was
+     * created. Used for TOCTOU protection.
+     */
+    workflowHash: string;
+    /** The message displayed to the approver. */
+    message: string;
+    /** ISO 8601 timestamp of token creation. */
+    createdAt: string;
+    /** ISO 8601 timestamp of token expiration. REQUIRED. Default 24h. */
+    expiresAt: string;
+    /** Current token state. */
+    status: ApprovalTokenStatus;
+    /** Identifier of the actor who approved/rejected (informational). */
+    approvedBy?: string;
+    /** ISO 8601 timestamp of the approval/rejection action. */
+    approvedAt?: string;
+    /** ISO 8601 timestamp of when the token was consumed by the runtime. */
+    usedAt?: string;
+    /** Identifier of the agent/workflow that requested approval. */
+    requestedBy: string;
+}
+/** Result of validating an approval token. */
+export interface TokenValidation {
+    /** Whether the token is valid and can be consumed. */
+    valid: boolean;
+    /** If invalid, the reason for rejection. */
+    reason?: 'not_found' | 'wrong_session' | 'not_pending' | 'expired' | 'hash_mismatch';
+    /** The token object if found. */
+    token?: ApprovalToken;
+}
+/** Join strategy for parallel block execution. */
+export type JoinStrategy = 'all' | 'race' | 'settle';
+/** Result of a parallel block execution with the settle strategy. */
+export interface SettleResult {
+    /** Arms that completed successfully. */
+    successes: Array<{
+        name: string;
+        result: unknown;
+    }>;
+    /** Arms that failed. */
+    failures: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** Variable scope for workflow execution. */
+export interface ExecutionScope {
+    /** Variable bindings in the current scope. */
+    variables: Record<string, unknown>;
+    /** Parent scope for nested blocks (parallel arms, loops, etc.). */
+    parent?: ExecutionScope;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cant/types.d.ts.map

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

package/dist/cant/workflow-executor.d.ts

@@ -0,0 +1,105 @@
+/**
+ * CANT workflow executor — orchestrates workflow statement execution.
+ *
+ * Walks the statement list of a `WorkflowDef` AST node, dispatching to
+ * appropriate handlers for each statement type: sessions, pipelines,
+ * parallel blocks, conditionals, loops, try/catch, approval gates,
+ * bindings, directives, and output statements.
+ *
+ * Pipelines are delegated to the Rust executor via napi-rs bridge.
+ * Sessions invoke the CLEO session machinery. Discretion conditions
+ * are evaluated by a pluggable evaluator.
+ *
+ * @see docs/specs/CANT-DSL-SPEC.md Section 7.2 (Workflow Execution)
+ */
+import { ApprovalManager } from './approval.js';
+import type { DiscretionEvaluator } from './discretion.js';
+import type { ExecutionResult } from './types.js';
+/** Configuration options for the workflow executor. */
+export interface WorkflowExecutorConfig {
+    /** Maximum number of discretion evaluations per workflow run (default: 100). */
+    maxDiscretionEvaluations?: number;
+    /** The session ID for this execution. */
+    sessionId?: string;
+    /** The agent ID performing the execution. */
+    agentId?: string;
+}
+/** Loose AST statement shape — mirrors cant-core Statement variants. */
+interface AstStatement {
+    type?: string;
+    [key: string]: unknown;
+}
+/** A workflow definition with a name, params, and body statements. */
+interface WorkflowDef {
+    name: {
+        value: string;
+    };
+    params: Array<{
+        name: {
+            value: string;
+        };
+    }>;
+    body: AstStatement[];
+}
+/**
+ * Executes CANT workflow definitions.
+ *
+ * The executor processes each statement in the workflow body sequentially,
+ * maintaining an execution scope for variable bindings and dispatching to
+ * the appropriate handler based on statement type.
+ */
+export declare class WorkflowExecutor {
+    private readonly discretionEvaluator;
+    private readonly approvalManager;
+    private readonly config;
+    /**
+     * Creates a new workflow executor.
+     *
+     * @param discretionEvaluator - Custom discretion evaluator (default: stub that returns true).
+     * @param approvalManager - Approval token manager (default: new instance).
+     * @param config - Executor configuration.
+     */
+    constructor(discretionEvaluator?: DiscretionEvaluator, approvalManager?: ApprovalManager, config?: WorkflowExecutorConfig);
+    /**
+     * Executes a workflow definition with the given parameter values.
+     *
+     * @param workflow - The parsed workflow AST node.
+     * @param context - Parameter values and initial context.
+     * @returns Execution result with outputs and step results.
+     */
+    execute(workflow: WorkflowDef, context?: Record<string, unknown>): Promise<ExecutionResult>;
+    /**
+     * Dispatches a single statement to the appropriate handler.
+     */
+    private executeStatement;
+    /** Execute a let binding statement. */
+    private executeBinding;
+    /** Execute an output binding statement. */
+    private executeOutput;
+    /** Execute an if/elif/else conditional. */
+    private executeConditional;
+    /** Execute a parallel block with arms. */
+    private executeParallelBlock;
+    /** Execute a session invocation (stub — real session dispatch is a separate integration). */
+    private executeSession;
+    /** Execute a pipeline definition (stub — real pipeline calls Rust via napi-rs). */
+    private executePipeline;
+    /** Execute an approval gate. */
+    private executeApprovalGate;
+    /** Execute a repeat N loop. */
+    private executeRepeat;
+    /** Execute a for-in loop. */
+    private executeForLoop;
+    /** Execute a loop-until block. */
+    private executeLoopUntil;
+    /** Execute a try/catch/finally block. */
+    private executeTryCatch;
+    /** Execute a CANT directive statement. */
+    private executeDirective;
+    /**
+     * Evaluate a condition (regular expression or discretion).
+     */
+    private evaluateCondition;
+}
+export {};
+//# sourceMappingURL=workflow-executor.d.ts.map

package/dist/cant/workflow-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-executor.d.ts","sourceRoot":"","sources":["../../src/cant/workflow-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3D,OAAO,KAAK,EAEV,eAAe,EAIhB,MAAM,YAAY,CAAC;AAMpB,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAUD,wEAAwE;AACxE,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,UAAU,WAAW;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD;;;;;;OAMG;gBAED,mBAAmB,GAAE,mBAAsD,EAC3E,eAAe,GAAE,eAAuC,EACxD,MAAM,GAAE,sBAA2B;IAQrC;;;;;;OAMG;IACG,OAAO,CACX,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,OAAO,CAAC,eAAe,CAAC;IAkD3B;;OAEG;YACW,gBAAgB;IA4C9B,uCAAuC;YACzB,cAAc;IAU5B,2CAA2C;YAC7B,aAAa;IAY3B,2CAA2C;YAC7B,kBAAkB;IA8ChC,0CAA0C;YAC5B,oBAAoB;IAuClC,6FAA6F;YAC/E,cAAc;IAkB5B,mFAAmF;YACrE,eAAe;IAgB7B,gCAAgC;YAClB,mBAAmB;IAiCjC,+BAA+B;YACjB,aAAa;IAkB3B,6BAA6B;YACf,cAAc;IA+B5B,kCAAkC;YACpB,gBAAgB;IAgC9B,yCAAyC;YAC3B,eAAe;IA0C7B,0CAA0C;YAC5B,gBAAgB;IAwB9B;;OAEG;YACW,iBAAiB;CAwBhC"}

package/dist/conduit/conduit-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ConduitClient — High-level agent messaging that wraps a Transport adapter.
+ *
+ * This is the WHAT layer: send messages, subscribe to events, manage presence.
+ * The Transport adapter (HttpTransport, LocalTransport, etc.) handles the HOW.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.3
+ * @task T177
+ */
+import type { AgentCredential, Conduit, ConduitMessage, ConduitSendOptions, ConduitSendResult, ConduitState, ConduitUnsubscribe, Transport } from '@cleocode/contracts';
+/** ConduitClient wraps a Transport, adding high-level messaging semantics. */
+export declare class ConduitClient implements Conduit {
+    private transport;
+    private credential;
+    private state;
+    constructor(transport: Transport, credential: AgentCredential);
+    get agentId(): string;
+    getState(): ConduitState;
+    connect(): Promise<void>;
+    send(to: string, content: string, options?: ConduitSendOptions): Promise<ConduitSendResult>;
+    onMessage(handler: (message: ConduitMessage) => void): ConduitUnsubscribe;
+    heartbeat(): Promise<void>;
+    isOnline(agentId: string): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=conduit-client.d.ts.map

package/dist/conduit/conduit-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conduit-client.d.ts","sourceRoot":"","sources":["../../src/conduit/conduit-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,SAAS,EACV,MAAM,qBAAqB,CAAC;AAE7B,8EAA8E;AAC9E,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,KAAK,CAAgC;gBAEjC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe;IAK7D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,QAAQ,IAAI,YAAY;IAIlB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBxB,IAAI,CACR,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAU7B,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,kBAAkB;IAgBnE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAIlC"}