@cleocode/cleo 2026.4.161 → 2026.5.0

package/dist/dispatch/lib/background-jobs.js

@@ -0,0 +1,360 @@
+/**
+ * Background Job Manager for Long-Running Operations
+ *
+ * Operations that may take >30s support async execution. This module
+ * provides a job manager backed by a SQLite DurableJobStore so that job
+ * state survives process restart.  Any job recorded as `running` in the
+ * database at construction time is immediately transitioned to `orphaned`
+ * so that humans/agents can triage it — no silent retry.
+ *
+ * @task T641
+ */
+import { backgroundJobs, } from '@cleocode/core/store/tasks-schema';
+import { randomUUID } from 'crypto';
+import { eq, inArray } from 'drizzle-orm';
+// ---------------------------------------------------------------------------
+// Row ↔ domain model helpers
+// ---------------------------------------------------------------------------
+/** Convert a {@link BackgroundJobRow} (from DB) to the public {@link BackgroundJob}. */
+function rowToJob(row) {
+    const job = {
+        id: row.id,
+        operation: row.operation,
+        status: row.status,
+        startedAt: new Date(row.startedAt).toISOString(),
+    };
+    if (row.completedAt !== null && row.completedAt !== undefined) {
+        job.completedAt = new Date(row.completedAt).toISOString();
+    }
+    if (row.result !== null && row.result !== undefined) {
+        try {
+            job.result = JSON.parse(row.result);
+        }
+        catch {
+            job.result = row.result;
+        }
+    }
+    if (row.error !== null && row.error !== undefined) {
+        job.error = row.error;
+    }
+    if (row.progress !== null && row.progress !== undefined) {
+        job.progress = row.progress;
+    }
+    if (row.claimedBy !== null && row.claimedBy !== undefined) {
+        job.claimedBy = row.claimedBy;
+    }
+    return job;
+}
+/**
+ * Drizzle-backed persistence layer for background jobs.
+ *
+ * On construction the store scans for `running` rows left by a prior
+ * process and marks them `orphaned`.  All reads and writes go through
+ * Drizzle — no raw SQL strings.
+ *
+ * @task T641
+ */
+export class DurableJobStore {
+    #db;
+    constructor(db) {
+        this.#db = db;
+        this.#orphanStaleJobs();
+    }
+    /**
+     * Transition all `running` rows to `orphaned`.
+     *
+     * Called once at startup so abandoned jobs surface via {@link listJobs}
+     * rather than being silently retried.
+     */
+    #orphanStaleJobs() {
+        const now = Date.now();
+        this.#db
+            .update(backgroundJobs)
+            .set({
+            status: 'orphaned',
+            completedAt: now,
+            error: 'process-exited-before-completion',
+        })
+            .where(eq(backgroundJobs.status, 'running'))
+            .run();
+    }
+    /**
+     * Insert a new job row with `running` status.
+     *
+     * @param id        - UUID for the job
+     * @param operation - Operation name
+     * @param now       - Current timestamp in ms
+     */
+    insert(id, operation, now) {
+        const row = {
+            id,
+            operation,
+            status: 'running',
+            startedAt: now,
+            heartbeatAt: now,
+        };
+        this.#db.insert(backgroundJobs).values(row).run();
+    }
+    /**
+     * Retrieve a single job by ID.  Returns `undefined` if not found.
+     */
+    get(id) {
+        const rows = this.#db.select().from(backgroundJobs).where(eq(backgroundJobs.id, id)).all();
+        const row = rows[0];
+        return row === undefined ? undefined : rowToJob(row);
+    }
+    /**
+     * Retrieve all jobs, optionally filtered by status.
+     */
+    list(status) {
+        const rows = status
+            ? this.#db
+                .select()
+                .from(backgroundJobs)
+                .where(eq(backgroundJobs.status, status))
+                .all()
+            : this.#db.select().from(backgroundJobs).all();
+        return rows.map(rowToJob);
+    }
+    /**
+     * Mark a job as `complete` with an optional result payload.
+     */
+    complete(id, result, now) {
+        this.#db
+            .update(backgroundJobs)
+            .set({
+            status: 'complete',
+            completedAt: now,
+            result: result !== undefined ? JSON.stringify(result) : null,
+            progress: 100,
+            heartbeatAt: now,
+        })
+            .where(eq(backgroundJobs.id, id))
+            .run();
+    }
+    /**
+     * Mark a job as `failed` with an error message.
+     */
+    fail(id, error, now) {
+        this.#db
+            .update(backgroundJobs)
+            .set({
+            status: 'failed',
+            completedAt: now,
+            error,
+            heartbeatAt: now,
+        })
+            .where(eq(backgroundJobs.id, id))
+            .run();
+    }
+    /**
+     * Mark a job as `cancelled`.
+     */
+    cancel(id, now) {
+        this.#db
+            .update(backgroundJobs)
+            .set({
+            status: 'cancelled',
+            completedAt: now,
+            heartbeatAt: now,
+        })
+            .where(eq(backgroundJobs.id, id))
+            .run();
+    }
+    /**
+     * Update the progress (0-100) and heartbeat of a running job.
+     */
+    progress(id, progress, now) {
+        this.#db
+            .update(backgroundJobs)
+            .set({
+            progress: Math.max(0, Math.min(100, progress)),
+            heartbeatAt: now,
+        })
+            .where(eq(backgroundJobs.id, id))
+            .run();
+    }
+    /**
+     * Delete terminal (complete/failed/cancelled/orphaned) jobs whose
+     * `completedAt` is older than `cutoffMs`.
+     *
+     * @returns Number of rows deleted.
+     */
+    purgeOlderThan(cutoffMs) {
+        const terminalStatuses = ['complete', 'failed', 'cancelled', 'orphaned'];
+        const rows = this.#db
+            .select({ id: backgroundJobs.id, completedAt: backgroundJobs.completedAt })
+            .from(backgroundJobs)
+            .where(inArray(backgroundJobs.status, terminalStatuses))
+            .all();
+        const staleIds = rows
+            .filter((r) => r.completedAt !== null && r.completedAt !== undefined && r.completedAt < cutoffMs)
+            .map((r) => r.id);
+        if (staleIds.length === 0) {
+            return 0;
+        }
+        this.#db.delete(backgroundJobs).where(inArray(backgroundJobs.id, staleIds)).run();
+        return staleIds.length;
+    }
+}
+// ---------------------------------------------------------------------------
+// BackgroundJobManager — public façade (same interface as before T641)
+// ---------------------------------------------------------------------------
+/**
+ * Manages background jobs for long-running operations.
+ *
+ * Backed by a {@link DurableJobStore} so job state persists across process
+ * restarts.  The public interface is identical to the previous in-memory
+ * implementation so {@link job-manager-accessor} does not change.
+ *
+ * @task T641
+ */
+export class BackgroundJobManager {
+    #store;
+    #abortControllers;
+    #maxJobs;
+    #retentionMs;
+    #cleanupTimer;
+    constructor(db, config) {
+        this.#store = new DurableJobStore(db);
+        this.#abortControllers = new Map();
+        this.#maxJobs = config?.maxJobs ?? 10;
+        this.#retentionMs = config?.retentionMs ?? 3_600_000; // 1 hour default
+        this.#cleanupTimer = null;
+        // Start periodic cleanup every 5 minutes
+        this.#cleanupTimer = setInterval(() => this.cleanup(), 300_000);
+        // Don't prevent process exit
+        if (this.#cleanupTimer.unref) {
+            this.#cleanupTimer.unref();
+        }
+    }
+    /**
+     * Start a new background job.
+     *
+     * @param operation - The operation identifier (e.g. "nexus.analyze")
+     * @param executor  - Async function to execute in the background
+     * @returns The job ID
+     * @throws Error if the maximum number of concurrent running jobs is reached
+     */
+    async startJob(operation, executor) {
+        // Check concurrent job limit (only count running jobs)
+        const runningCount = this.listJobs('running').length;
+        if (runningCount >= this.#maxJobs) {
+            throw new Error(`Maximum concurrent jobs reached (${this.#maxJobs}). Cancel or wait for existing jobs to complete.`);
+        }
+        const jobId = randomUUID();
+        const abortController = new AbortController();
+        const now = Date.now();
+        this.#store.insert(jobId, operation, now);
+        this.#abortControllers.set(jobId, abortController);
+        // Execute async — do not await
+        void this.#executeJob(jobId, executor, abortController.signal);
+        return jobId;
+    }
+    /**
+     * Get a specific job by ID.
+     *
+     * @returns The job or `undefined` if not found.
+     */
+    getJob(jobId) {
+        return this.#store.get(jobId);
+    }
+    /**
+     * List all jobs, optionally filtered by status.
+     *
+     * @param status - Optional status filter string.
+     * @returns Array of matching jobs.
+     */
+    listJobs(status) {
+        return this.#store.list(status);
+    }
+    /**
+     * Cancel a running job.
+     *
+     * @returns `true` if the job was cancelled; `false` if not found or not running.
+     */
+    cancelJob(jobId) {
+        const job = this.#store.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        const controller = this.#abortControllers.get(jobId);
+        if (controller) {
+            controller.abort();
+            this.#abortControllers.delete(jobId);
+        }
+        this.#store.cancel(jobId, Date.now());
+        return true;
+    }
+    /**
+     * Update the progress of a running job (0-100).
+     *
+     * @returns `true` if updated; `false` if the job is not found or not running.
+     */
+    updateProgress(jobId, progress) {
+        const job = this.#store.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        this.#store.progress(jobId, progress, Date.now());
+        return true;
+    }
+    /**
+     * Delete completed/failed/cancelled/orphaned jobs past the retention window.
+     *
+     * @returns Number of jobs removed.
+     */
+    cleanup() {
+        const cutoff = Date.now() - this.#retentionMs;
+        return this.#store.purgeOlderThan(cutoff);
+    }
+    /**
+     * Destroy the manager: cancel all in-process running jobs and stop the
+     * cleanup timer.  Does NOT purge DB rows — orphaned jobs must be reviewed.
+     */
+    destroy() {
+        const now = Date.now();
+        for (const runningJob of this.listJobs('running')) {
+            const controller = this.#abortControllers.get(runningJob.id);
+            if (controller) {
+                controller.abort();
+            }
+            // Persist orphaned status for any jobs still running in this process
+            this.#store.fail(runningJob.id, 'manager-destroyed', now);
+        }
+        this.#abortControllers.clear();
+        if (this.#cleanupTimer) {
+            clearInterval(this.#cleanupTimer);
+            this.#cleanupTimer = null;
+        }
+    }
+    /**
+     * Execute a job's executor function and persist the outcome.
+     */
+    async #executeJob(jobId, executor, signal) {
+        const job = this.#store.get(jobId);
+        if (!job) {
+            return;
+        }
+        try {
+            const result = await executor();
+            // Check if cancelled during execution
+            if (signal.aborted) {
+                return;
+            }
+            this.#store.complete(jobId, result, Date.now());
+        }
+        catch (error) {
+            // Check if this was a cancellation
+            if (signal.aborted) {
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.#store.fail(jobId, message, Date.now());
+        }
+        finally {
+            this.#abortControllers.delete(jobId);
+        }
+    }
+}
+//# sourceMappingURL=background-jobs.js.map

package/dist/dispatch/lib/background-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-jobs.js","sourceRoot":"","sources":["../../../src/dispatch/lib/background-jobs.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/lib/budget.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LAFS token budget enforcement for dispatch responses.
+ *
+ * Wraps the LAFS protocol's applyBudgetEnforcement() to limit
+ * response sizes for context-constrained agents.
+ *
+ * @task T4701
+ * @task T338 — updated for canonical CLI envelope (meta, data)
+ * @epic T4663
+ */
+import type { BudgetEnforcementResult } from '@cleocode/lafs';
+/**
+ * Apply budget enforcement to a dispatch response envelope.
+ *
+ * Converts the DomainResponse into an LAFSEnvelope shape for budget checking,
+ * then applies truncation if the response exceeds the budget.
+ *
+ * @param response - The domain response object
+ * @param budget - Maximum allowed tokens (defaults to DEFAULT_BUDGET)
+ * @returns The response, potentially truncated, with budget metadata
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export declare function enforceBudget(response: Record<string, unknown>, budget?: number): {
+    response: Record<string, unknown>;
+    enforcement: BudgetEnforcementResult;
+};
+/**
+ * Quick check whether a response exceeds a token budget without modifying it.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export declare function isWithinBudget(response: Record<string, unknown>, budget?: number): boolean;
+//# sourceMappingURL=budget.d.ts.map

package/dist/dispatch/lib/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../src/dispatch/lib/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAY9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,WAAW,EAAE,uBAAuB,CAAA;CAAE,CAuD7E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAwB1F"}

package/dist/dispatch/lib/budget.js

@@ -0,0 +1,109 @@
+/**
+ * LAFS token budget enforcement for dispatch responses.
+ *
+ * Wraps the LAFS protocol's applyBudgetEnforcement() to limit
+ * response sizes for context-constrained agents.
+ *
+ * @task T4701
+ * @task T338 — updated for canonical CLI envelope (meta, data)
+ * @epic T4663
+ */
+import { applyBudgetEnforcement, checkBudget } from '@cleocode/lafs';
+/**
+ * Default token budget when no explicit budget is provided.
+ * Standard MVI level allows up to 4000 tokens per response.
+ *
+ * @task T4701
+ */
+const DEFAULT_BUDGET = 4000;
+/**
+ * Apply budget enforcement to a dispatch response envelope.
+ *
+ * Converts the DomainResponse into an LAFSEnvelope shape for budget checking,
+ * then applies truncation if the response exceeds the budget.
+ *
+ * @param response - The domain response object
+ * @param budget - Maximum allowed tokens (defaults to DEFAULT_BUDGET)
+ * @returns The response, potentially truncated, with budget metadata
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export function enforceBudget(response, budget) {
+    const effectiveBudget = budget ?? DEFAULT_BUDGET;
+    // Build a proto-envelope stub for the SDK budget checker.
+    // The SDK internally uses {_meta, result}, so we bridge from the canonical
+    // CLI shape {meta, data} here.
+    const protoMeta = (response['meta'] ?? {});
+    const envelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: Object.keys(protoMeta).length > 0
+            ? protoMeta
+            : {
+                specVersion: '1.2.3',
+                schemaVersion: '2026.2.1',
+                timestamp: new Date().toISOString(),
+                operation: 'dispatch.response',
+                requestId: 'budget-check',
+                transport: 'sdk',
+                strict: true,
+                mvi: 'standard',
+                contextVersion: 1,
+            },
+        success: response['success'] ?? true,
+        result: response['data'] ?? null,
+        ...(response['error'] ? { error: response['error'] } : {}),
+    };
+    const enforcement = applyBudgetEnforcement(envelope, effectiveBudget, { truncateOnExceed: true });
+    // Merge budget info back into the response meta
+    const meta = (response['meta'] ?? {});
+    meta['_budgetEnforcement'] = {
+        budget: effectiveBudget,
+        estimatedTokens: enforcement.estimatedTokens,
+        withinBudget: enforcement.withinBudget,
+        truncated: enforcement.truncated,
+    };
+    return {
+        response: {
+            ...response,
+            meta,
+            // Replace data with potentially truncated result
+            ...(enforcement.truncated &&
+                enforcement.envelope.result !== undefined && {
+                data: enforcement.envelope.result,
+            }),
+        },
+        enforcement,
+    };
+}
+/**
+ * Quick check whether a response exceeds a token budget without modifying it.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export function isWithinBudget(response, budget) {
+    const effectiveBudget = budget ?? DEFAULT_BUDGET;
+    const protoMeta = (response['meta'] ?? {});
+    const envelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: Object.keys(protoMeta).length > 0
+            ? protoMeta
+            : {
+                specVersion: '1.2.3',
+                schemaVersion: '2026.2.1',
+                timestamp: new Date().toISOString(),
+                operation: 'dispatch.response',
+                requestId: 'budget-check',
+                transport: 'sdk',
+                strict: true,
+                mvi: 'standard',
+                contextVersion: 1,
+            },
+        success: true,
+        result: response['data'] ?? null,
+    };
+    const { exceeded } = checkBudget(envelope, effectiveBudget);
+    return !exceeded;
+}
+//# sourceMappingURL=budget.js.map

package/dist/dispatch/lib/budget.js.map

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

package/dist/dispatch/lib/capability-matrix.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Capability Matrix (Backward-Compat Re-export)
+ *
+ * Thin wrapper that re-exports from the canonical location at
+ * src/core/routing/capability-matrix.ts.
+ *
+ * @task T5706
+ */
+export type { CapabilityReport, ExecutionMode, GatewayType, OperationCapability, PreferredChannel, } from '@cleocode/core/internal';
+export { canRunNatively, generateCapabilityReport, getCapabilityMatrix, getNativeOperations, getOperationMode, requiresCLI, } from '@cleocode/core/internal';
+//# sourceMappingURL=capability-matrix.d.ts.map

package/dist/dispatch/lib/capability-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-matrix.d.ts","sourceRoot":"","sources":["../../../src/dispatch/lib/capability-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,GACZ,MAAM,yBAAyB,CAAC"}

package/dist/dispatch/lib/capability-matrix.js

@@ -0,0 +1,10 @@
+/**
+ * Capability Matrix (Backward-Compat Re-export)
+ *
+ * Thin wrapper that re-exports from the canonical location at
+ * src/core/routing/capability-matrix.ts.
+ *
+ * @task T5706
+ */
+export { canRunNatively, generateCapabilityReport, getCapabilityMatrix, getNativeOperations, getOperationMode, requiresCLI, } from '@cleocode/core/internal';
+//# sourceMappingURL=capability-matrix.js.map

package/dist/dispatch/lib/capability-matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-matrix.js","sourceRoot":"","sources":["../../../src/dispatch/lib/capability-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,GACZ,MAAM,yBAAyB,CAAC"}

package/dist/dispatch/lib/config-loader.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Configuration loader for CLEO dispatch layer.
+ *
+ * Loads configuration from:
+ * 1. Environment variables (CLEO_*)
+ * 2. Config file (.cleo/config.json)
+ * 3. Defaults (fallback values)
+ *
+ * @task T2928
+ */
+import { type DispatchConfig } from './defaults.js';
+/**
+ * Configuration validation error
+ */
+export declare class ConfigValidationError extends Error {
+    field: string;
+    value: unknown;
+    constraint: string;
+    constructor(field: string, value: unknown, constraint: string);
+}
+/**
+ * Validate complete configuration
+ */
+export declare function validateConfig(config: DispatchConfig): void;
+/**
+ * Load configuration from all sources
+ *
+ * Priority order:
+ * 1. Environment variables (CLEO_*)
+ * 2. Config file (.cleo/config.json)
+ * 3. Defaults
+ */
+export declare function loadConfig(projectRoot?: string): DispatchConfig;
+/**
+ * Get global configuration (singleton)
+ */
+export declare function getConfig(): DispatchConfig;
+/**
+ * Reset global configuration (for testing)
+ */
+export declare function resetConfig(): void;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/dispatch/lib/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../../src/dispatch/lib/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAErC,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,OAAO;IACd,UAAU,EAAE,MAAM;gBAFlB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM;CAK5B;AAsHD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAa3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,cAAc,CAsD/D;AAQD;;GAEG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAK1C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}