@cleocode/cant 2026.4.11 → 2026.4.13

package/dist/mental-model.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Mental Model Manager -- per-agent persistent observations.
+ *
+ * Implements ULTRAPLAN section 12: mental models are per-project, async-updated
+ * after each spawn, and validated on every load.
+ *
+ * Mental models compound intelligence over time by recording patterns,
+ * decisions, and outcomes from agent sessions. They decay naturally and
+ * are token-bounded to fit within tier caps.
+ *
+ * @packageDocumentation
+ */
+/** Trigger events that cause an observation to be recorded. */
+export type ObservationTrigger = 'task_completed' | 'bug_fixed' | 'pattern_observed' | 'decision_made';
+/** A single observation in the mental model. */
+export interface MentalModelObservation {
+    /** Unique observation ID. */
+    id: string;
+    /** The agent that made this observation. */
+    agentName: string;
+    /** Project hash scoping this observation. */
+    projectHash: string;
+    /** When this observation was recorded (ISO 8601). */
+    timestamp: string;
+    /** The observation content. */
+    content: string;
+    /** Estimated tokens for this content. */
+    tokens: number;
+    /** What triggered this observation. */
+    trigger: ObservationTrigger;
+    /** Number of times this observation has been reinforced. */
+    reinforceCount: number;
+}
+/** Scope for a mental model: project-specific or global. */
+export type MentalModelScope = 'project' | 'global';
+/** The consolidated mental model for an agent+project. */
+export interface MentalModel {
+    /** Agent this model belongs to. */
+    agentName: string;
+    /** Project hash scoping this model. */
+    projectHash: string;
+    /** Scope: project or global (per ULTRAPLAN L5). */
+    scope: MentalModelScope;
+    /** Consolidated observations (token-bounded). */
+    observations: MentalModelObservation[];
+    /** Total tokens across all observations. */
+    totalTokens: number;
+    /** Max allowed tokens (from tier cap). */
+    maxTokens: number;
+    /** When this model was last consolidated (ISO 8601), or null if never. */
+    lastConsolidated: string | null;
+    /** When this model was last validated by an agent (ISO 8601), or null if never. */
+    lastValidated: string | null;
+}
+/** Storage interface for mental model persistence (mockable). */
+export interface MentalModelStore {
+    /** Load the mental model for an agent+project. */
+    load(agentName: string, projectHash: string): Promise<MentalModel | null>;
+    /** Save the mental model. */
+    save(model: MentalModel): Promise<void>;
+    /** Append a raw observation (async, non-blocking per ULTRAPLAN L5). */
+    appendObservation(obs: MentalModelObservation): Promise<void>;
+    /** List pending (unconsolidated) observations. */
+    listPending(agentName: string, projectHash: string): Promise<MentalModelObservation[]>;
+    /** Clear pending observations after consolidation. */
+    clearPending(agentName: string, projectHash: string): Promise<void>;
+}
+/** Options for the {@link consolidate} function. */
+export interface ConsolidateOptions {
+    /** Maximum total tokens for all observations. */
+    maxTokens: number;
+    /** Number of days after which unreinforced observations decay. */
+    decayAfterDays: number;
+    /** Scope for the resulting model. */
+    scope: MentalModelScope;
+}
+/**
+ * Create an empty mental model for an agent+project.
+ *
+ * @param agentName - The agent this model belongs to.
+ * @param projectHash - The project hash scoping this model.
+ * @param scope - Whether this is a project or global model.
+ * @param maxTokens - Maximum token budget for observations.
+ * @returns A fresh, empty mental model.
+ */
+export declare function createEmptyModel(agentName: string, projectHash: string, scope: MentalModelScope, maxTokens: number): MentalModel;
+/**
+ * Consolidate pending observations into the mental model.
+ *
+ * Implements the consolidation from ULTRAPLAN section 12.2:
+ * 1. Load pending observations from the store
+ * 2. Merge into existing model (deduplicate by content, reinforce matches)
+ * 3. Decay entries older than decayAfterDays
+ * 4. Enforce maxTokens cap (drop oldest first)
+ * 5. Save consolidated model and clear pending queue
+ *
+ * @param store - The persistence layer for mental models.
+ * @param agentName - The agent whose model to consolidate.
+ * @param projectHash - The project hash scoping the model.
+ * @param options - Consolidation configuration.
+ * @returns The consolidated mental model.
+ */
+export declare function consolidate(store: MentalModelStore, agentName: string, projectHash: string, options: ConsolidateOptions): Promise<MentalModel>;
+/**
+ * Render a mental model for system prompt injection.
+ *
+ * Includes the ULTRAPLAN section 12.3 validation prefix:
+ * "VALIDATE THIS MENTAL MODEL. Re-evaluate each claim against
+ * current code state. Mental models are dynamic per project;
+ * assume drift."
+ *
+ * @param model - The mental model to render.
+ * @returns Rendered text for injection into system prompts, or empty string if no observations.
+ */
+export declare function renderMentalModel(model: MentalModel): string;
+/**
+ * Session output data used by {@link harvestObservations} to extract
+ * mental model observations from a completed agent session.
+ */
+export interface SessionOutput {
+    /** Patterns the agent applied during the session. */
+    patternsUsed: string[];
+    /** Decisions the agent made during the session. */
+    decisionsMade: string[];
+    /** File paths the agent touched during the session. */
+    filesTouched: string[];
+    /** Overall outcome of the session. */
+    outcome: 'success' | 'failure' | 'partial';
+}
+/**
+ * Extract observations from a completed agent session.
+ *
+ * Implements ULTRAPLAN section 12.2 post-spawn harvesting:
+ * parses session output for patterns, decisions, and files touched.
+ * Only records task completion observations on successful outcomes.
+ *
+ * @param agentName - The agent that ran the session.
+ * @param projectHash - The project hash for scoping observations.
+ * @param sessionOutput - Structured output from the completed session.
+ * @returns Array of observations ready for {@link MentalModelStore.appendObservation}.
+ */
+export declare function harvestObservations(agentName: string, projectHash: string, sessionOutput: SessionOutput): MentalModelObservation[];

package/dist/mental-model.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Mental Model Manager -- per-agent persistent observations.
+ *
+ * Implements ULTRAPLAN section 12: mental models are per-project, async-updated
+ * after each spawn, and validated on every load.
+ *
+ * Mental models compound intelligence over time by recording patterns,
+ * decisions, and outcomes from agent sessions. They decay naturally and
+ * are token-bounded to fit within tier caps.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyModel = createEmptyModel;
+exports.consolidate = consolidate;
+exports.renderMentalModel = renderMentalModel;
+exports.harvestObservations = harvestObservations;
+// ---------------------------------------------------------------------------
+// Validation prefix (ULTRAPLAN section 12.3)
+// ---------------------------------------------------------------------------
+/**
+ * Validation prefix injected before mental model content.
+ *
+ * Per ULTRAPLAN section 12.3, every load must instruct the agent to
+ * re-evaluate the mental model against current project state.
+ */
+const VALIDATION_PREFIX = 'VALIDATE THIS MENTAL MODEL. Re-evaluate each claim against current ' +
+    'code state. Mental models are dynamic per project; assume drift.';
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Create an empty mental model for an agent+project.
+ *
+ * @param agentName - The agent this model belongs to.
+ * @param projectHash - The project hash scoping this model.
+ * @param scope - Whether this is a project or global model.
+ * @param maxTokens - Maximum token budget for observations.
+ * @returns A fresh, empty mental model.
+ */
+function createEmptyModel(agentName, projectHash, scope, maxTokens) {
+    return {
+        agentName,
+        projectHash,
+        scope,
+        observations: [],
+        totalTokens: 0,
+        maxTokens,
+        lastConsolidated: null,
+        lastValidated: null,
+    };
+}
+/**
+ * Consolidate pending observations into the mental model.
+ *
+ * Implements the consolidation from ULTRAPLAN section 12.2:
+ * 1. Load pending observations from the store
+ * 2. Merge into existing model (deduplicate by content, reinforce matches)
+ * 3. Decay entries older than decayAfterDays
+ * 4. Enforce maxTokens cap (drop oldest first)
+ * 5. Save consolidated model and clear pending queue
+ *
+ * @param store - The persistence layer for mental models.
+ * @param agentName - The agent whose model to consolidate.
+ * @param projectHash - The project hash scoping the model.
+ * @param options - Consolidation configuration.
+ * @returns The consolidated mental model.
+ */
+async function consolidate(store, agentName, projectHash, options) {
+    // Load existing model or create fresh
+    let model = await store.load(agentName, projectHash);
+    if (!model) {
+        model = createEmptyModel(agentName, projectHash, options.scope, options.maxTokens);
+    }
+    // Load pending observations
+    const pending = await store.listPending(agentName, projectHash);
+    // Merge: add pending, increment reinforceCount for duplicates
+    for (const obs of pending) {
+        const existing = model.observations.find((o) => o.content === obs.content);
+        if (existing) {
+            existing.reinforceCount += 1;
+            existing.timestamp = obs.timestamp; // refresh timestamp on reinforce
+        }
+        else {
+            model.observations.push(obs);
+        }
+    }
+    // Decay: remove observations older than decayAfterDays
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - options.decayAfterDays);
+    const cutoffIso = cutoff.toISOString();
+    model.observations = model.observations.filter((o) => o.timestamp >= cutoffIso);
+    // Enforce token cap: sort newest first, keep within budget
+    model.observations.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    let tokenSum = 0;
+    const kept = [];
+    for (const obs of model.observations) {
+        if (tokenSum + obs.tokens > options.maxTokens)
+            break;
+        kept.push(obs);
+        tokenSum += obs.tokens;
+    }
+    model.observations = kept;
+    model.totalTokens = tokenSum;
+    model.maxTokens = options.maxTokens;
+    model.lastConsolidated = new Date().toISOString();
+    // Persist consolidated model and clear pending queue
+    await store.save(model);
+    await store.clearPending(agentName, projectHash);
+    return model;
+}
+/**
+ * Render a mental model for system prompt injection.
+ *
+ * Includes the ULTRAPLAN section 12.3 validation prefix:
+ * "VALIDATE THIS MENTAL MODEL. Re-evaluate each claim against
+ * current code state. Mental models are dynamic per project;
+ * assume drift."
+ *
+ * @param model - The mental model to render.
+ * @returns Rendered text for injection into system prompts, or empty string if no observations.
+ */
+function renderMentalModel(model) {
+    if (model.observations.length === 0)
+        return '';
+    const entries = model.observations
+        .map((o) => `- [${o.trigger}] ${o.content} (reinforced ${o.reinforceCount}x)`)
+        .join('\n');
+    return `${VALIDATION_PREFIX}\n\n${entries}`;
+}
+/**
+ * Generate a unique observation ID.
+ *
+ * @returns A prefixed unique ID string.
+ */
+function generateObservationId() {
+    return `mm-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Extract observations from a completed agent session.
+ *
+ * Implements ULTRAPLAN section 12.2 post-spawn harvesting:
+ * parses session output for patterns, decisions, and files touched.
+ * Only records task completion observations on successful outcomes.
+ *
+ * @param agentName - The agent that ran the session.
+ * @param projectHash - The project hash for scoping observations.
+ * @param sessionOutput - Structured output from the completed session.
+ * @returns Array of observations ready for {@link MentalModelStore.appendObservation}.
+ */
+function harvestObservations(agentName, projectHash, sessionOutput) {
+    const now = new Date().toISOString();
+    const observations = [];
+    for (const pattern of sessionOutput.patternsUsed) {
+        observations.push({
+            id: generateObservationId(),
+            agentName,
+            projectHash,
+            timestamp: now,
+            content: `Pattern applied: ${pattern}`,
+            tokens: Math.ceil(`Pattern applied: ${pattern}`.length / 4),
+            trigger: 'pattern_observed',
+            reinforceCount: 0,
+        });
+    }
+    for (const decision of sessionOutput.decisionsMade) {
+        observations.push({
+            id: generateObservationId(),
+            agentName,
+            projectHash,
+            timestamp: now,
+            content: `Decision: ${decision}`,
+            tokens: Math.ceil(`Decision: ${decision}`.length / 4),
+            trigger: 'decision_made',
+            reinforceCount: 0,
+        });
+    }
+    if (sessionOutput.outcome === 'success') {
+        const fileList = sessionOutput.filesTouched.join(', ');
+        const content = `Task completed successfully. Files: ${fileList}`;
+        observations.push({
+            id: generateObservationId(),
+            agentName,
+            projectHash,
+            timestamp: now,
+            content,
+            tokens: Math.ceil(content.length / 4),
+            trigger: 'task_completed',
+            reinforceCount: 0,
+        });
+    }
+    return observations;
+}

package/dist/worktree.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Git worktree manager for multi-agent isolation.
+ *
+ * Implements ULTRAPLAN §14: each spawned agent gets its own git
+ * worktree so parallel workers cannot conflict. The orchestrator
+ * stays on its current branch.
+ *
+ * @packageDocumentation
+ */
+/** Request payload for creating a new git worktree. */
+export interface WorktreeRequest {
+    /** The base ref to branch from (e.g. "main", "develop", a SHA). */
+    baseRef: string;
+    /** Branch name for the worktree. If absent, derived from taskId. */
+    branchName?: string;
+    /** Task ID driving this worktree. */
+    taskId: string;
+    /** Why this worktree is being created. */
+    reason: 'subagent' | 'experiment' | 'parallel-wave';
+}
+/** Handle returned after worktree creation; used for merge and cleanup. */
+export interface WorktreeHandle {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch name created for this worktree. */
+    branch: string;
+    /** The base ref it was branched from. */
+    baseRef: string;
+    /** Task ID. */
+    taskId: string;
+    /** Clean up: remove the worktree and optionally delete the branch. */
+    cleanup(deleteBranch?: boolean): void;
+}
+/** Configuration for worktree path resolution and git operations. */
+export interface WorktreeConfig {
+    /** Root directory for worktrees. Defaults to $XDG_DATA_HOME/cleo/worktrees/<projectHash>/ */
+    worktreeRoot?: string;
+    /** Project hash for path scoping. */
+    projectHash: string;
+    /** The project's git root directory. */
+    gitRoot: string;
+}
+/** Result of a merge operation. */
+export interface MergeResult {
+    /** Whether the merge succeeded. */
+    success: boolean;
+    /** Error message if the merge failed. */
+    error?: string;
+}
+/** Entry in the list of active worktrees. */
+export interface WorktreeEntry {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch checked out in this worktree. */
+    branch: string;
+}
+/**
+ * Resolve the worktree root directory.
+ *
+ * Uses `$XDG_DATA_HOME/cleo/worktrees/<projectHash>/` per ULTRAPLAN §14.3.
+ * Falls back to `~/.local/share/cleo/worktrees/<projectHash>/` when
+ * `XDG_DATA_HOME` is not set.
+ *
+ * @param config - Worktree configuration containing optional override and project hash.
+ * @returns Absolute path to the worktree root directory.
+ */
+export declare function resolveWorktreeRoot(config: WorktreeConfig): string;
+/**
+ * Create a git worktree for an agent.
+ *
+ * Runs `git worktree add <path> -b <branch> <baseRef>` from the
+ * project's git root. Branch naming convention: `cleo/<taskId>-<shortId>`.
+ *
+ * If a worktree already exists at the target path (stale from a prior run),
+ * it is removed before creating the new one.
+ *
+ * @param request - The worktree request specifying task, base ref, and optional branch name.
+ * @param config - Project-level worktree configuration.
+ * @returns A handle for the created worktree with cleanup capability.
+ * @throws Error if the git worktree add command fails.
+ */
+export declare function createWorktree(request: WorktreeRequest, config: WorktreeConfig): WorktreeHandle;
+/**
+ * Merge a worktree's branch back into the current branch.
+ *
+ * On success the worktree is cleaned up (directory removed, branch deleted).
+ * On failure the worktree is retained for forensic inspection.
+ *
+ * @param handle - The worktree handle returned from {@link createWorktree}.
+ * @param config - Project-level worktree configuration.
+ * @param options - Merge strategy options (defaults to fast-forward only).
+ * @returns A result object indicating success or failure with an error message.
+ */
+export declare function mergeWorktree(handle: WorktreeHandle, config: WorktreeConfig, options?: {
+    strategy?: 'ff-only' | 'no-ff';
+}): MergeResult;
+/**
+ * List active worktrees scoped to the current project.
+ *
+ * Parses `git worktree list --porcelain` and filters entries whose path
+ * falls under the project's worktree root directory.
+ *
+ * @param config - Project-level worktree configuration.
+ * @returns Array of worktree entries with their paths and branch names.
+ */
+export declare function listWorktrees(config: WorktreeConfig): WorktreeEntry[];

package/dist/worktree.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Git worktree manager for multi-agent isolation.
+ *
+ * Implements ULTRAPLAN §14: each spawned agent gets its own git
+ * worktree so parallel workers cannot conflict. The orchestrator
+ * stays on its current branch.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorktreeRoot = resolveWorktreeRoot;
+exports.createWorktree = createWorktree;
+exports.mergeWorktree = mergeWorktree;
+exports.listWorktrees = listWorktrees;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+/**
+ * Resolve the worktree root directory.
+ *
+ * Uses `$XDG_DATA_HOME/cleo/worktrees/<projectHash>/` per ULTRAPLAN §14.3.
+ * Falls back to `~/.local/share/cleo/worktrees/<projectHash>/` when
+ * `XDG_DATA_HOME` is not set.
+ *
+ * @param config - Worktree configuration containing optional override and project hash.
+ * @returns Absolute path to the worktree root directory.
+ */
+function resolveWorktreeRoot(config) {
+    if (config.worktreeRoot)
+        return config.worktreeRoot;
+    const xdgData = process.env['XDG_DATA_HOME'] ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.local', 'share');
+    return (0, node_path_1.join)(xdgData, 'cleo', 'worktrees', config.projectHash);
+}
+/**
+ * Create a git worktree for an agent.
+ *
+ * Runs `git worktree add <path> -b <branch> <baseRef>` from the
+ * project's git root. Branch naming convention: `cleo/<taskId>-<shortId>`.
+ *
+ * If a worktree already exists at the target path (stale from a prior run),
+ * it is removed before creating the new one.
+ *
+ * @param request - The worktree request specifying task, base ref, and optional branch name.
+ * @param config - Project-level worktree configuration.
+ * @returns A handle for the created worktree with cleanup capability.
+ * @throws Error if the git worktree add command fails.
+ */
+function createWorktree(request, config) {
+    const root = resolveWorktreeRoot(config);
+    (0, node_fs_1.mkdirSync)(root, { recursive: true });
+    const shortId = Math.random().toString(36).slice(2, 8);
+    const branch = request.branchName ?? `cleo/${request.taskId}-${shortId}`;
+    const worktreePath = (0, node_path_1.join)(root, request.taskId);
+    // Remove existing worktree at this path if it exists (stale from prior run)
+    if ((0, node_fs_1.existsSync)(worktreePath)) {
+        try {
+            (0, node_child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {
+                cwd: config.gitRoot,
+                stdio: 'pipe',
+            });
+        }
+        catch {
+            // Best-effort cleanup — directory may not be a valid worktree
+            (0, node_fs_1.rmSync)(worktreePath, { recursive: true, force: true });
+        }
+    }
+    // Create the worktree
+    (0, node_child_process_1.execSync)(`git worktree add "${worktreePath}" -b "${branch}" "${request.baseRef}"`, { cwd: config.gitRoot, stdio: 'pipe' });
+    return buildHandle(worktreePath, branch, request.baseRef, request.taskId, config.gitRoot);
+}
+/**
+ * Merge a worktree's branch back into the current branch.
+ *
+ * On success the worktree is cleaned up (directory removed, branch deleted).
+ * On failure the worktree is retained for forensic inspection.
+ *
+ * @param handle - The worktree handle returned from {@link createWorktree}.
+ * @param config - Project-level worktree configuration.
+ * @param options - Merge strategy options (defaults to fast-forward only).
+ * @returns A result object indicating success or failure with an error message.
+ */
+function mergeWorktree(handle, config, options = {}) {
+    const strategy = options.strategy ?? 'ff-only';
+    const mergeFlag = strategy === 'ff-only' ? '--ff-only' : '--no-ff';
+    try {
+        (0, node_child_process_1.execSync)(`git merge ${mergeFlag} "${handle.branch}"`, {
+            cwd: config.gitRoot,
+            stdio: 'pipe',
+        });
+        // Success: clean up worktree
+        handle.cleanup(true);
+        return { success: true };
+    }
+    catch (err) {
+        // Failure: retain worktree for forensics
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            error: `Merge failed: ${message}. Worktree retained at ${handle.path} for forensics.`,
+        };
+    }
+}
+/**
+ * List active worktrees scoped to the current project.
+ *
+ * Parses `git worktree list --porcelain` and filters entries whose path
+ * falls under the project's worktree root directory.
+ *
+ * @param config - Project-level worktree configuration.
+ * @returns Array of worktree entries with their paths and branch names.
+ */
+function listWorktrees(config) {
+    try {
+        const output = (0, node_child_process_1.execSync)('git worktree list --porcelain', {
+            cwd: config.gitRoot,
+            encoding: 'utf-8',
+        });
+        const entries = [];
+        const root = resolveWorktreeRoot(config);
+        let currentPath = '';
+        let currentBranch = '';
+        for (const line of output.split('\n')) {
+            if (line.startsWith('worktree ')) {
+                currentPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                currentBranch = line.slice('branch refs/heads/'.length);
+            }
+            else if (line === '') {
+                if (currentPath.startsWith(root)) {
+                    entries.push({ path: currentPath, branch: currentBranch });
+                }
+                currentPath = '';
+                currentBranch = '';
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build a WorktreeHandle with a cleanup closure.
+ *
+ * @internal
+ */
+function buildHandle(worktreePath, branch, baseRef, taskId, gitRoot) {
+    return {
+        path: worktreePath,
+        branch,
+        baseRef,
+        taskId,
+        cleanup(deleteBranch = false) {
+            try {
+                (0, node_child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {
+                    cwd: gitRoot,
+                    stdio: 'pipe',
+                });
+            }
+            catch {
+                (0, node_fs_1.rmSync)(worktreePath, { recursive: true, force: true });
+            }
+            if (deleteBranch) {
+                try {
+                    (0, node_child_process_1.execSync)(`git branch -D "${branch}"`, {
+                        cwd: gitRoot,
+                        stdio: 'pipe',
+                    });
+                }
+                catch {
+                    // Branch may already be deleted
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.4.11",
+  "version": "2026.4.13",
   "description": "CANT protocol parser and runtime for CLEO — wraps cant-core via napi-rs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,8 +9,8 @@
     "napi/"
   ],
   "dependencies": {
-    "@cleocode/contracts": "2026.4.11",
-    "@cleocode/lafs": "2026.4.11"
+    "@cleocode/contracts": "2026.4.13",
+    "@cleocode/lafs": "2026.4.13"
   },
   "devDependencies": {
     "typescript": "^5.0.0",