@cleocode/core 2026.4.6 → 2026.4.9

package/src/cant/discretion.ts

@@ -1,149 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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';

package/src/cant/parallel-runner.ts

@@ -1,205 +0,0 @@
-/**
- * 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 async function executeParallel(
-  arms: ParallelArm[],
-  strategy: JoinStrategy = 'all',
-): Promise<ParallelResult> {
-  switch (strategy) {
-    case 'race':
-      return executeRace(arms);
-    case 'settle':
-      return executeSettle(arms);
-    default: // 'all' or any other value
-      return executeAll(arms);
-  }
-}
-
-/**
- * Execute all arms concurrently. Fail if any arm fails.
- */
-async function executeAll(arms: ParallelArm[]): Promise<ParallelResult> {
-  const startTimes = new Map<string, number>();
-  const promises = arms.map(async (arm) => {
-    const start = Date.now();
-    startTimes.set(arm.name, start);
-    const result = await arm.execute();
-    return { name: arm.name, result, duration: Date.now() - start };
-  });
-
-  try {
-    const outcomes = await Promise.all(promises);
-    const results: Record<string, unknown> = {};
-    const steps: StepResult[] = [];
-
-    for (const outcome of outcomes) {
-      results[outcome.name] = outcome.result;
-      steps.push({
-        name: outcome.name,
-        type: 'parallel',
-        success: true,
-        output: outcome.result,
-        duration: outcome.duration,
-      });
-    }
-
-    return { success: true, results, steps };
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    return {
-      success: false,
-      results: {},
-      steps: [
-        {
-          name: 'parallel:all',
-          type: 'parallel',
-          success: false,
-          error,
-          duration: 0,
-        },
-      ],
-    };
-  }
-}
-
-/**
- * Execute all arms concurrently. Return on first completion.
- */
-async function executeRace(arms: ParallelArm[]): Promise<ParallelResult> {
-  const promises = arms.map(async (arm) => {
-    const start = Date.now();
-    const result = await arm.execute();
-    return { name: arm.name, result, duration: Date.now() - start };
-  });
-
-  try {
-    const winner = await Promise.race(promises);
-    return {
-      success: true,
-      results: { [winner.name]: winner.result },
-      steps: [
-        {
-          name: winner.name,
-          type: 'parallel',
-          success: true,
-          output: winner.result,
-          duration: winner.duration,
-        },
-      ],
-    };
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    return {
-      success: false,
-      results: {},
-      steps: [
-        {
-          name: 'parallel:race',
-          type: 'parallel',
-          success: false,
-          error,
-          duration: 0,
-        },
-      ],
-    };
-  }
-}
-
-/**
- * Execute all arms concurrently. Collect all successes and failures.
- */
-async function executeSettle(arms: ParallelArm[]): Promise<ParallelResult> {
-  const promises = arms.map(async (arm) => {
-    const start = Date.now();
-    try {
-      const result = await arm.execute();
-      return {
-        name: arm.name,
-        status: 'fulfilled' as const,
-        result,
-        duration: Date.now() - start,
-      };
-    } catch (err) {
-      return {
-        name: arm.name,
-        status: 'rejected' as const,
-        error: err instanceof Error ? err.message : String(err),
-        duration: Date.now() - start,
-      };
-    }
-  });
-
-  const outcomes = await Promise.all(promises);
-
-  const successes: SettleResult['successes'] = [];
-  const failures: SettleResult['failures'] = [];
-  const results: Record<string, unknown> = {};
-  const steps: StepResult[] = [];
-
-  for (const outcome of outcomes) {
-    if (outcome.status === 'fulfilled') {
-      successes.push({ name: outcome.name, result: outcome.result });
-      results[outcome.name] = outcome.result;
-      steps.push({
-        name: outcome.name,
-        type: 'parallel',
-        success: true,
-        output: outcome.result,
-        duration: outcome.duration,
-      });
-    } else {
-      failures.push({ name: outcome.name, error: outcome.error });
-      steps.push({
-        name: outcome.name,
-        type: 'parallel',
-        success: false,
-        error: outcome.error,
-        duration: outcome.duration,
-      });
-    }
-  }
-
-  return {
-    success: failures.length === 0,
-    results,
-    steps,
-    settleResult: { successes, failures },
-  };
-}

package/src/cant/types.ts

@@ -1,158 +0,0 @@
-/**
- * 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)
- */
-
-// ---------------------------------------------------------------------------
-// Execution Results
-// ---------------------------------------------------------------------------
-
-/** 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;
-}
-
-// ---------------------------------------------------------------------------
-// Discretion Evaluation
-// ---------------------------------------------------------------------------
-
-/** 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>;
-}
-
-// ---------------------------------------------------------------------------
-// Approval Tokens (Section 8 of CANT-DSL-SPEC.md)
-// ---------------------------------------------------------------------------
-
-/** 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;
-}
-
-// ---------------------------------------------------------------------------
-// Parallel Execution
-// ---------------------------------------------------------------------------
-
-/** 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 }>;
-}
-
-// ---------------------------------------------------------------------------
-// Execution Scope
-// ---------------------------------------------------------------------------
-
-/** 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;
-}