@cleocode/core 2026.3.74 → 2026.4.0

package/src/cant/approval.ts

@@ -0,0 +1,218 @@
+/**
+ * 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 { createHash, randomUUID } from 'node:crypto';
+import type { ApprovalToken, ApprovalTokenStatus, TokenValidation } from './types.js';
+
+/** Default token expiration duration: 24 hours in milliseconds. */
+const DEFAULT_EXPIRY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 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 class ApprovalManager {
+  /** In-memory token store keyed by token UUID. */
+  private tokens: Map<string, ApprovalToken> = new Map();
+
+  /**
+   * 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 = DEFAULT_EXPIRY_MS,
+  ): ApprovalToken {
+    const now = new Date();
+    const token: ApprovalToken = {
+      token: randomUUID(),
+      sessionId,
+      workflowName,
+      gateName,
+      workflowHash,
+      message,
+      createdAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + expiresInMs).toISOString(),
+      status: 'pending',
+      requestedBy,
+    };
+
+    this.tokens.set(token.token, token);
+    return token;
+  }
+
+  /**
+   * 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 {
+    const token = this.tokens.get(tokenId);
+
+    if (!token) {
+      return { valid: false, reason: 'not_found' };
+    }
+
+    if (token.sessionId !== currentSessionId) {
+      return { valid: false, reason: 'wrong_session', token };
+    }
+
+    if (token.status !== 'pending') {
+      return { valid: false, reason: 'not_pending', token };
+    }
+
+    // Check expiration
+    if (new Date(token.expiresAt).getTime() < Date.now()) {
+      // Atomically transition to expired
+      this.transitionStatus(tokenId, 'expired');
+      return { valid: false, reason: 'expired', token: { ...token, status: 'expired' } };
+    }
+
+    // TOCTOU: verify workflow has not been modified
+    if (token.workflowHash !== currentWorkflowHash) {
+      return { valid: false, reason: 'hash_mismatch', token };
+    }
+
+    return { valid: true, token };
+  }
+
+  /**
+   * 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 {
+    const token = this.tokens.get(tokenId);
+    if (!token || token.status !== 'pending') {
+      return false;
+    }
+
+    const now = new Date().toISOString();
+    token.status = 'approved';
+    token.approvedBy = approvedBy;
+    token.approvedAt = now;
+    token.usedAt = now;
+    return true;
+  }
+
+  /**
+   * 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 {
+    const token = this.tokens.get(tokenId);
+    if (!token || token.status !== 'pending') {
+      return false;
+    }
+
+    token.status = 'rejected';
+    token.usedAt = new Date().toISOString();
+    return true;
+  }
+
+  /**
+   * 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 {
+    return this.transitionStatus(tokenId, 'expired');
+  }
+
+  /**
+   * 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 {
+    return this.tokens.get(tokenId);
+  }
+
+  /**
+   * 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[] {
+    return Array.from(this.tokens.values()).filter((t) => t.sessionId === sessionId);
+  }
+
+  /**
+   * 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 {
+    return createHash('sha256').update(workflowText).digest('hex');
+  }
+
+  /**
+   * 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(tokenId: string, targetStatus: ApprovalTokenStatus): boolean {
+    const token = this.tokens.get(tokenId);
+    if (!token || token.status !== 'pending') {
+      return false;
+    }
+    token.status = targetStatus;
+    token.usedAt = new Date().toISOString();
+    return true;
+  }
+}

package/src/cant/context-builder.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 function createScope(initialBindings: Record<string, unknown> = {}): ExecutionScope {
+  return {
+    variables: { ...initialBindings },
+  };
+}
+
+/**
+ * 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 function createChildScope(
+  parent: ExecutionScope,
+  localBindings: Record<string, unknown> = {},
+): ExecutionScope {
+  return {
+    variables: { ...localBindings },
+    parent,
+  };
+}
+
+/**
+ * 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 function resolveVariable(scope: ExecutionScope, name: string): unknown {
+  // Check current scope
+  if (name in scope.variables) {
+    return scope.variables[name];
+  }
+
+  // Check parent chain
+  if (scope.parent) {
+    return resolveVariable(scope.parent, name);
+  }
+
+  return undefined;
+}
+
+/**
+ * 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 function setVariable(scope: ExecutionScope, name: string, value: unknown): void {
+  scope.variables[name] = value;
+}
+
+/**
+ * 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 function resolveTemplate(template: string, scope: ExecutionScope): string {
+  return template.replace(/\{([^}]+)\}/g, (_match, varName: string) => {
+    const value = resolveVariable(scope, varName);
+    if (value === undefined) {
+      throw new Error(`Variable '${varName}' not found in execution scope`);
+    }
+    return String(value);
+  });
+}
+
+/**
+ * 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 function mergeStepOutput(
+  scope: ExecutionScope,
+  stepName: string,
+  output: Record<string, unknown>,
+): void {
+  // Bind the full output object under the step name
+  scope.variables[stepName] = output;
+
+  // Also bind dotted access for convenience
+  for (const [key, value] of Object.entries(output)) {
+    scope.variables[`${stepName}.${key}`] = value;
+  }
+}
+
+/**
+ * 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 function flattenScope(scope: ExecutionScope): Record<string, unknown> {
+  const parentVars = scope.parent ? flattenScope(scope.parent) : {};
+  return { ...parentVars, ...scope.variables };
+}

package/src/cant/discretion.ts

@@ -0,0 +1,149 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Evaluator Interface
+// ---------------------------------------------------------------------------
+
+/** 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 Evaluator (Stub)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 class DefaultDiscretionEvaluator implements DiscretionEvaluator {
+  /** Always returns `true` (stub). */
+  async evaluate(_condition: string, _context: DiscretionContext): Promise<boolean> {
+    return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mock Evaluator (Testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mock discretion evaluator with configurable responses for testing.
+ *
+ * Responses can be set per condition text or as a blanket default.
+ */
+export class MockDiscretionEvaluator implements DiscretionEvaluator {
+  private responses: Map<string, boolean> = new Map();
+  private defaultResponse: boolean;
+  private evaluationLog: Array<{ condition: string; context: DiscretionContext; result: boolean }> =
+    [];
+
+  /**
+   * Creates a mock evaluator.
+   *
+   * @param defaultResponse - The response for conditions without a specific mapping.
+   */
+  constructor(defaultResponse = true) {
+    this.defaultResponse = defaultResponse;
+  }
+
+  /** Set the response for a specific condition text. */
+  setResponse(condition: string, result: boolean): void {
+    this.responses.set(condition, result);
+  }
+
+  /** Evaluate using the configured response map. */
+  async evaluate(condition: string, context: DiscretionContext): Promise<boolean> {
+    const result = this.responses.get(condition) ?? this.defaultResponse;
+    this.evaluationLog.push({ condition, context, result });
+    return result;
+  }
+
+  /** Get the log of all evaluations performed. */
+  getLog(): ReadonlyArray<{ condition: string; context: DiscretionContext; result: boolean }> {
+    return this.evaluationLog;
+  }
+
+  /** Reset the evaluation log. */
+  clearLog(): void {
+    this.evaluationLog = [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rate-Limited Evaluator (Decorator)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 class RateLimitedDiscretionEvaluator implements DiscretionEvaluator {
+  private evaluationCount = 0;
+
+  /**
+   * Creates a rate-limited evaluator wrapper.
+   *
+   * @param inner - The underlying evaluator to delegate to.
+   * @param maxEvaluations - Maximum evaluations allowed (default: 100).
+   */
+  constructor(
+    private readonly inner: DiscretionEvaluator,
+    private readonly maxEvaluations: number = 100,
+  ) {}
+
+  /**
+   * Evaluate with rate limiting.
+   *
+   * @throws {Error} If the evaluation count exceeds the configured maximum.
+   */
+  async evaluate(condition: string, context: DiscretionContext): Promise<boolean> {
+    this.evaluationCount++;
+    if (this.evaluationCount > this.maxEvaluations) {
+      throw new Error(
+        `Discretion evaluation limit exceeded: ${this.evaluationCount} > ${this.maxEvaluations}. ` +
+          'This prevents runaway costs from loops containing discretion conditions.',
+      );
+    }
+    return this.inner.evaluate(condition, context);
+  }
+
+  /** Get the current evaluation count. */
+  getEvaluationCount(): number {
+    return this.evaluationCount;
+  }
+
+  /** Reset the evaluation counter (for reuse across workflow runs). */
+  resetCount(): void {
+    this.evaluationCount = 0;
+  }
+}

package/src/cant/index.ts

@@ -0,0 +1,58 @@
+/**
+ * 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)
+ */
+
+// Approval gate management
+export { ApprovalManager } from './approval.js';
+
+// Execution context and scope
+export {
+  createChildScope,
+  createScope,
+  flattenScope,
+  mergeStepOutput,
+  resolveTemplate,
+  resolveVariable,
+  setVariable,
+} from './context-builder.js';
+
+// Discretion evaluation
+export type { DiscretionEvaluator } from './discretion.js';
+export {
+  DefaultDiscretionEvaluator,
+  MockDiscretionEvaluator,
+  RateLimitedDiscretionEvaluator,
+} from './discretion.js';
+
+// Parallel execution
+export type { ParallelArm, ParallelResult } from './parallel-runner.js';
+export { executeParallel } from './parallel-runner.js';
+
+// Runtime types
+export type {
+  ApprovalToken,
+  ApprovalTokenStatus,
+  DiscretionContext,
+  ExecutionResult,
+  ExecutionScope,
+  JoinStrategy,
+  SettleResult,
+  StepResult,
+  TokenValidation,
+} from './types.js';
+
+// Workflow executor
+export type { WorkflowExecutorConfig } from './workflow-executor.js';
+export { WorkflowExecutor } from './workflow-executor.js';