@crewx/cli 0.9.0-rc.94 → 0.9.0-rc.96

package/dist/bootstrap/crewx-cli.js

@@ -9,6 +9,7 @@ const plugins_1 = require("@crewx/sdk/plugins");
 const repository_1 = require("@crewx/sdk/repository");
 const register_builtin_tools_1 = require("../register-builtin-tools");
 const version_1 = require("../utils/version");
+const inherited_trace_1 = require("../utils/inherited-trace");
 const codex_writable_roots_1 = require("./codex-writable-roots");
 /**
  * Build a Crewx instance with CLI-standard plugins (FileLogger + SqliteTracing)
@@ -59,6 +60,9 @@ async function createCliCrewx(configPath = process.env.CREWX_CONFIG ?? 'crewx.ya
     (0, register_builtin_tools_1.registerBuiltinToolsIfNeeded)(crewx);
     await crewx.use(new plugins_1.ConversationPlugin());
     await crewx.use(new plugins_1.FileLoggerPlugin({ version: version_1.CLI_VERSION, workspaceRoot }));
-    await crewx.use(new plugins_1.SqliteTracingPlugin({ version: version_1.CLI_VERSION }));
+    await crewx.use(new plugins_1.SqliteTracingPlugin({
+        version: version_1.CLI_VERSION,
+        runnerIdentity: (0, inherited_trace_1.consumeInheritedRunnerIdentity)(),
+    }));
     return crewx;
 }

package/dist/commands/cal.d.ts

@@ -0,0 +1,15 @@
+import type { ActionContext } from '@crewx/knowledge-core';
+/** Suggested wait rungs in seconds. 540 is the safe caller-harness cap. */
+export declare const WAIT_LADDER_SECONDS: readonly [60, 300, 540];
+export interface SuggestWaitSecondsOptions {
+    startedAt?: string | number | Date | null;
+    lastWaitSeconds?: number;
+    now?: number;
+}
+/**
+ * Select the next safe result wait based on task runtime without stepping
+ * down from the wait value the caller just used.
+ */
+export declare function suggestWaitSeconds(options: SuggestWaitSecondsOptions): number;
+/** Write a human-only CAL footer without contaminating command stdout. */
+export declare function writeCalFooter(context: ActionContext): void;

package/dist/commands/cal.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAIT_LADDER_SECONDS = void 0;
+exports.suggestWaitSeconds = suggestWaitSeconds;
+exports.writeCalFooter = writeCalFooter;
+const knowledge_core_1 = require("@crewx/knowledge-core");
+/** Suggested wait rungs in seconds. 540 is the safe caller-harness cap. */
+exports.WAIT_LADDER_SECONDS = [60, 300, 540];
+function toTimestamp(value) {
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime()) ? value.getTime() : undefined;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const timestamp = Date.parse(value);
+        return Number.isFinite(timestamp) ? timestamp : undefined;
+    }
+    return undefined;
+}
+/**
+ * Select the next safe result wait based on task runtime without stepping
+ * down from the wait value the caller just used.
+ */
+function suggestWaitSeconds(options) {
+    const now = Number.isFinite(options.now) ? options.now : Date.now();
+    const startedAt = toTimestamp(options.startedAt);
+    const elapsedSeconds = startedAt === undefined
+        ? 0
+        : Math.max(0, (now - startedAt) / 1000);
+    const rung = exports.WAIT_LADDER_SECONDS.find(seconds => seconds > elapsedSeconds)
+        ?? exports.WAIT_LADDER_SECONDS[exports.WAIT_LADDER_SECONDS.length - 1];
+    const lastWaitSeconds = Number.isFinite(options.lastWaitSeconds)
+        ? Math.max(0, options.lastWaitSeconds)
+        : 0;
+    return Math.min(exports.WAIT_LADDER_SECONDS[exports.WAIT_LADDER_SECONDS.length - 1], Math.max(rung, lastWaitSeconds));
+}
+/** Write a human-only CAL footer without contaminating command stdout. */
+function writeCalFooter(context) {
+    const block = (0, knowledge_core_1.formatActions)((0, knowledge_core_1.generateNextActions)(context));
+    if (block)
+        process.stderr.write(`${block}\n`);
+}

package/dist/commands/db.d.ts

@@ -7,4 +7,5 @@
  *   crewx db push --dry-run      Show preview only, no changes
  */
 export declare const TASK_LOG_MIGRATION_HELP = "Usage:\n  crewx db migrate-task-logs --dry-run [--db PATH]\n  crewx db migrate-task-logs --apply [--db PATH] [--batch-tasks N]\n  crewx db migrate-task-logs --verify [--db PATH]\n\nModes:\n  --dry-run  Read and validate legacy blobs without writing or creating a backup.\n  --apply    Create a consistent SQLite backup, then migrate one task per transaction.\n  --verify   Check source invariants, event sequences, counts, and orphan rows.\n\nApply policy:\n  Only blob tasks with status success, failed, or completed are migrated.\n  pending, running, paused, and unknown statuses are deferred for a later run.\n  There is no --force or --include-active option. Apply requires the estimated\n  database/event growth plus a 10 GiB free-space reserve.\n\nExit codes:\n  0  Completed with no malformed rows or invariant failures.\n  1  Safe tasks completed but a row/invariant failed, or apply was blocked.\n  2  Invalid command-line arguments.\n\nThe command never runs automatically at server startup and never runs VACUUM.";
+export declare const USAGE_BACKFILL_HELP = "Usage:\n  crewx db backfill-usage [--dry-run|--apply|--verify] [--db PATH] [--backup PATH]\n  crewx db backfill-usage --restore SNAPSHOT [--db PATH]\n\nModes:\n  --dry-run  Show provider/reason recovery plans without changing the database (default).\n  --apply    Create a row-level undo snapshot, then account one task per transaction.\n  --verify   Recheck remaining targets and usageAccounting markers without changing the database.\n  --restore  Restore rows from SNAPSHOT when their current values still match the snapshot after-state.\n\nApply policy:\n  Only success, failed, and completed tasks with zero recorded usage are considered.\n  Workflow/MCP anchors and plugin/mock rows are excluded. Rows completed within 24 hours\n  are not marked unavailable when their logs do not contain usage.\n\nExit codes:\n  0  Completed successfully.\n  1  Apply was blocked or one or more task updates failed.\n  2  Invalid command-line arguments.";
 export declare function handleDb(args: string[]): Promise<void>;

package/dist/commands/db.js

@@ -11,7 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TASK_LOG_MIGRATION_HELP = void 0;
+exports.USAGE_BACKFILL_HELP = exports.TASK_LOG_MIGRATION_HELP = void 0;
 exports.handleDb = handleDb;
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -19,6 +19,7 @@ const readline_1 = __importDefault(require("readline"));
 const repository_1 = require("@crewx/sdk/repository");
 const repository_2 = require("@crewx/sdk/repository");
 const repository_3 = require("@crewx/sdk/repository");
+const repository_4 = require("@crewx/sdk/repository");
 exports.TASK_LOG_MIGRATION_HELP = `Usage:
   crewx db migrate-task-logs --dry-run [--db PATH]
   crewx db migrate-task-logs --apply [--db PATH] [--batch-tasks N]
@@ -41,6 +42,25 @@ Exit codes:
   2  Invalid command-line arguments.
 
 The command never runs automatically at server startup and never runs VACUUM.`;
+exports.USAGE_BACKFILL_HELP = `Usage:
+  crewx db backfill-usage [--dry-run|--apply|--verify] [--db PATH] [--backup PATH]
+  crewx db backfill-usage --restore SNAPSHOT [--db PATH]
+
+Modes:
+  --dry-run  Show provider/reason recovery plans without changing the database (default).
+  --apply    Create a row-level undo snapshot, then account one task per transaction.
+  --verify   Recheck remaining targets and usageAccounting markers without changing the database.
+  --restore  Restore rows from SNAPSHOT when their current values still match the snapshot after-state.
+
+Apply policy:
+  Only success, failed, and completed tasks with zero recorded usage are considered.
+  Workflow/MCP anchors and plugin/mock rows are excluded. Rows completed within 24 hours
+  are not marked unavailable when their logs do not contain usage.
+
+Exit codes:
+  0  Completed successfully.
+  1  Apply was blocked or one or more task updates failed.
+  2  Invalid command-line arguments.`;
 function defaultDbPath() {
     return path_1.default.join(os_1.default.homedir(), '.crewx', 'crewx.db');
 }
@@ -102,6 +122,10 @@ async function handleDb(args) {
         await handleTaskLogMigration(args.slice(1));
         return;
     }
+    if (subcommand === 'backfill-usage') {
+        await handleUsageBackfill(args.slice(1));
+        return;
+    }
     if (subcommand === '--help' || subcommand === '-h') {
         console.log('Usage: crewx db push [--force] [--dry-run]');
         console.log(exports.TASK_LOG_MIGRATION_HELP);
@@ -118,6 +142,8 @@ async function handleDb(args) {
 }
 class TaskLogMigrationUsageError extends Error {
 }
+class UsageBackfillUsageError extends Error {
+}
 function parseTaskLogMigrationArgs(args) {
     let mode;
     let dbPath;
@@ -266,6 +292,170 @@ async function handleTaskLogMigration(args) {
         process.exitCode = 1;
     }
 }
+function parseUsageBackfillArgs(args) {
+    let mode;
+    let dbPath;
+    let backupPath;
+    let restorePath;
+    const setMode = (next) => {
+        if (mode)
+            throw new UsageBackfillUsageError('Choose exactly one of --dry-run, --apply, --verify, or --restore.');
+        mode = next;
+    };
+    const requireValue = (index, flag) => {
+        const value = args[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new UsageBackfillUsageError(`${flag} requires a value.`);
+        return value;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h')
+            throw new UsageBackfillUsageError(exports.USAGE_BACKFILL_HELP);
+        if (arg === '--dry-run') {
+            setMode('dry-run');
+            continue;
+        }
+        if (arg === '--apply') {
+            setMode('apply');
+            continue;
+        }
+        if (arg === '--verify') {
+            setMode('verify');
+            continue;
+        }
+        if (arg === '--restore') {
+            setMode('restore');
+            restorePath = requireValue(index, '--restore');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--restore=')) {
+            setMode('restore');
+            restorePath = arg.slice('--restore='.length);
+            if (!restorePath)
+                throw new UsageBackfillUsageError('--restore requires a value.');
+            continue;
+        }
+        if (arg === '--db') {
+            dbPath = requireValue(index, '--db');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--db=')) {
+            dbPath = arg.slice('--db='.length);
+            if (!dbPath)
+                throw new UsageBackfillUsageError('--db requires a value.');
+            continue;
+        }
+        if (arg === '--backup') {
+            backupPath = requireValue(index, '--backup');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--backup=')) {
+            backupPath = arg.slice('--backup='.length);
+            if (!backupPath)
+                throw new UsageBackfillUsageError('--backup requires a value.');
+            continue;
+        }
+        throw new UsageBackfillUsageError(`Unknown option: ${arg}`);
+    }
+    const selectedMode = mode ?? 'dry-run';
+    if (backupPath && selectedMode !== 'apply') {
+        throw new UsageBackfillUsageError('--backup is only valid with --apply.');
+    }
+    if (restorePath && selectedMode !== 'restore') {
+        throw new UsageBackfillUsageError('--restore is only valid with restore mode.');
+    }
+    return { mode: selectedMode, dbPath, backupPath, restorePath };
+}
+function formatUsageBackfillReport(report) {
+    const modeLabel = report.mode === 'dry-run'
+        ? 'Dry-run'
+        : report.mode === 'apply'
+            ? 'Apply'
+            : report.mode === 'restore'
+                ? 'Restore'
+                : 'Verify';
+    const lines = [
+        `[crewx] Usage backfill — ${modeLabel}`,
+        `  Database: ${report.dbPath}`,
+        `  Tasks scanned: ${report.scannedTasks}`,
+        `  Terminal tasks: ${report.terminalTasks}`,
+        `  Raw target tasks: ${report.rawTargetTasks}`,
+        `  Candidate tasks: ${report.candidateTasks}`,
+        `  Recovered: ${report.recoveredTasks}`,
+        `  Unavailable: ${report.unavailableTasks}`,
+        `  Deferred (within 24h): ${report.deferredTasks}`,
+        `  Changed: ${report.changedTasks}`,
+        `  Would change: ${report.wouldChangeTasks}`,
+        `  Restored: ${report.restored}`,
+        `  Skipped conflicts: ${report.skippedConflict}`,
+        `  Remaining target tasks: ${report.remainingTargetTasks}`,
+        `  Tasks with usageAccounting: ${report.accountingTasks}`,
+        '  Provider distribution:',
+    ];
+    const providers = Object.entries(report.providerDistribution);
+    if (providers.length === 0) {
+        lines.push('    (none)');
+    }
+    else {
+        for (const [provider, stats] of providers) {
+            lines.push(`    ${provider}: candidates=${stats.candidates}, recovered=${stats.recovered}, unavailable=${stats.unavailable}, deferred=${stats.deferred}`);
+        }
+    }
+    lines.push('  Reason counts:');
+    for (const [reason, count] of Object.entries(report.reasonCounts))
+        lines.push(`    ${reason}: ${count}`);
+    lines.push(`  Estimated free-space need: ${report.estimatedFreeSpaceBytes}`);
+    lines.push(`  Required free space (with reserve): ${report.requiredFreeSpaceBytes}`);
+    lines.push(`  Available free space: ${report.availableFreeSpaceBytes}`);
+    lines.push(`  Free-space gate: ${report.freeSpaceGatePassed ? 'PASS' : 'FAIL'}`);
+    const snapshotPath = report.snapshotPath ?? report.backupPath;
+    if (snapshotPath) {
+        lines.push(`  Undo snapshot: ${snapshotPath}`);
+        if (report.backupMethod)
+            lines.push(`  Snapshot method: ${report.backupMethod}`);
+    }
+    if (report.blockedReason)
+        lines.push(`  Blocked: ${report.blockedReason}`);
+    for (const conflict of report.conflictSamples) {
+        lines.push(`  Conflict sample: ${conflict.taskId}: ${conflict.fields.join(', ')}`);
+    }
+    for (const failure of report.failures)
+        lines.push(`  Failure: ${failure.taskId}: ${failure.reason}`);
+    for (const warning of report.warnings)
+        lines.push(`  Warning: ${warning}`);
+    return lines.join('\n');
+}
+async function handleUsageBackfill(args) {
+    let parsed;
+    try {
+        parsed = parseUsageBackfillArgs(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === exports.USAGE_BACKFILL_HELP) {
+            console.log(message);
+        }
+        else {
+            console.error(message);
+            console.error(exports.USAGE_BACKFILL_HELP);
+            process.exitCode = 2;
+        }
+        return;
+    }
+    try {
+        const report = await (0, repository_4.runUsageBackfill)(parsed);
+        console.log(formatUsageBackfillReport(report));
+        process.exitCode = report.ok ? 0 : 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
 async function handleDbPush(args) {
     const force = args.includes('--force');
     const dryRun = args.includes('--dry-run');

package/dist/commands/detached.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared receipt-mode implementation for the query and execute commands.
+ *
+ * A receipt is persisted before a detached runner is started. The runner gets
+ * its own identity variables, while the trace variables remain the caller's
+ * trace context and are never repurposed as the runner assignment.
+ */
+import { TaskRepository } from '@crewx/sdk/repository';
+/**
+ * Remove receipt-selection flags, respecting the `--` literal-args sentinel.
+ */
+export declare function extractReceiptFlags(args: string[]): {
+    detach: boolean;
+    wait: boolean;
+    rest: string[];
+};
+export type ReceiptModeReason = 'explicit-detach' | 'agent-context' | 'detached-runner' | 'wait' | 'default';
+export interface ReceiptModeDecision {
+    receipt: boolean;
+    reason: ReceiptModeReason;
+}
+/** Resolve the receipt/synchronous mode contract shared by q and x. */
+export declare function resolveReceiptMode(options: {
+    detach: boolean;
+    wait: boolean;
+    detachedRunner: boolean;
+    agentContext: boolean;
+}): ReceiptModeDecision;
+export type AssignedTaskAdoption = {
+    kind: 'adopted';
+    taskId: string;
+} | {
+    kind: 'stale';
+} | {
+    kind: 'failed';
+};
+/**
+ * Claim a pre-issued receipt without overwriting an already-owned row.
+ * Assignment-only leakage is recoverable: discard the stale id and let the
+ * normal SDK path create a fresh task. A real detached runner must fail loud
+ * because its receipt would otherwise point at no execution row.
+ */
+export declare function adoptAssignedTask(taskRepo: Pick<TaskRepository, 'adoptPendingTask'>, taskId: string, detachedRunner: boolean): AssignedTaskAdoption;
+export interface DetachedMiddleHop {
+    taskId: string;
+    logPath: string;
+    runnerArgs: string[];
+}
+/**
+ * Read the private Windows middle-hop contract. Invalid direct invocations
+ * are left untouched and therefore fail through the normal unknown-option
+ * path instead of becoming an undocumented public command.
+ */
+export declare function readDetachedMiddleHop(args: string[]): DetachedMiddleHop | undefined;
+/**
+ * Windows middle hop: transfer a transient log handle to the final runner,
+ * close the middle process's copy, and exit immediately. The parent treats a
+ * successful middle-hop exit as normal and makes adoption a database decision.
+ */
+export declare function runDetachedMiddle(command: string, hop: DetachedMiddleHop): Promise<void>;
+/**
+ * Persist a receipt and launch its detached runner. Unix uses one hop. Windows
+ * uses a short-lived middle hop so the final runner has no live parent link.
+ */
+export declare function runDetached(command: string, filteredArgs: string[], reason: ReceiptModeReason): Promise<void>;