@crewx/sdk 0.9.0-rc.94 → 0.9.0-rc.95

package/dist/repository/task-status.d.ts

@@ -0,0 +1,14 @@
+export type TaskStatus = 'pending' | 'running' | 'paused' | 'success' | 'failed' | 'stopped' | 'runner_lost';
+export declare const TASK_TERMINAL_STATUSES: readonly ["success", "failed", "stopped", "runner_lost"];
+export type TaskTerminalStatus = (typeof TASK_TERMINAL_STATUSES)[number];
+export type TaskTerminalReason = 'user_stop' | 'runner_lost' | 'launch_failed';
+export declare const LEGACY_TASK_TERMINAL_ERROR_PATTERNS: {
+    readonly stopped: RegExp;
+    readonly runnerLost: RegExp;
+};
+export interface TaskStatusInput {
+    status: string;
+    error?: string | null;
+    metadata?: string | null;
+}
+export declare function normalizeTaskStatus(row: TaskStatusInput): TaskStatus;

package/dist/repository/task.repository.d.ts

@@ -1,8 +1,37 @@
 import { BaseSqliteRepository } from './base-sqlite-repository.js';
 import { tasks } from '../schema/index.js';
 import type { TaskLogEntry, TaskLogReadResult, TaskLogState } from './task-log.repository.js';
-export type TaskRow = typeof tasks.$inferSelect;
+import { type TaskStatus, type TaskTerminalReason } from './task-status.js';
+import { type StopTaskOptions, type StopTaskResult } from '../lifecycle/task-stop.js';
+export { TASK_HEARTBEAT_HARD_STALE_MS, TASK_HEARTBEAT_INTERVAL_MS, TASK_HEARTBEAT_STALE_MS, resolveTaskHeartbeatHardStaleMs, resolveTaskHeartbeatIntervalMs, resolveTaskHeartbeatStaleMs, } from '../lifecycle/task-heartbeat.js';
+type RawTaskRow = typeof tasks.$inferSelect;
+export type TaskRow = Omit<RawTaskRow, 'status'> & {
+    status: TaskStatus;
+};
 export type NewTask = typeof tasks.$inferInsert;
+export type TaskKillStatus = 'terminated' | 'not_found' | 'failed' | 'not_running';
+export interface TaskKillResult {
+    status: TaskKillStatus;
+    killed: boolean;
+    pid?: number;
+    error?: string;
+}
+export interface TaskStopRequestResult {
+    accepted: boolean;
+    status: string | null;
+    runEpoch: number;
+    alreadyRequestedAt?: string;
+}
+export type TaskStopMethod = 'cooperative' | 'forced';
+export interface FinalizeTaskStopOptions {
+    id: string;
+    runEpoch: number;
+    completedAt?: string;
+    method: TaskStopMethod;
+    error?: string;
+    terminalReason?: TaskTerminalReason;
+    durationMs?: number | null;
+}
 export type TaskListRow = Pick<TaskRow, 'id' | 'thread_id' | 'agent_id' | 'status' | 'parent_task_id' | 'started_at' | 'completed_at' | 'duration_ms' | 'input_tokens' | 'output_tokens' | 'cost_usd' | 'error'>;
 export type TaskActivityLogRow = Pick<TaskRow, 'id' | 'thread_id' | 'agent_id' | 'parent_task_id' | 'started_at' | 'completed_at'>;
 export type FindTasksByThreadOptions = {
@@ -36,6 +65,7 @@ export interface AgentUsageRow {
     agentId: string;
     workspaceId: string | null;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -45,6 +75,7 @@ export interface AgentUsageRow {
 export interface TrendRow {
     date: string;
     agentId: string;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -54,6 +85,7 @@ export interface TrendRow {
 export interface ProviderUsageRow {
     provider: string;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -66,6 +98,7 @@ export interface ModelUsageRow {
     model: string;
     provider: string;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -107,17 +140,38 @@ export interface ThreadChain {
     targetAgentTurnCount: number;
     turns: ThreadChainTurn[];
 }
+type TaskUsageColumns = Pick<TaskRow, 'input_tokens' | 'output_tokens' | 'cached_input_tokens' | 'cost_usd'>;
+export declare function mergeTerminalReason(metadataJson: string | null | undefined, reason: TaskTerminalReason): string;
+export declare function hasRecordedUsage(task: TaskUsageColumns): boolean;
 export declare const PID_NULL_REAP_GRACE_MS: number;
+export declare const PENDING_ADOPT_GRACE_MS: number;
+export declare const DEFAULT_TASK_REAPER_TICK_INTERVAL_MS: number;
+export interface ReapOrphanedTasksOptions {
+    tickIntervalMs?: number;
+}
 export declare class TaskRepository extends BaseSqliteRepository {
     private readonly dbPath?;
+    private readonly clock;
     private readonly taskLogRepository;
+    private lastReaperTickAt?;
     private readonly pidNullObservedSince;
     constructor(opts?: {
         dbPath?: string;
         dbRoot?: string;
+        clock?: () => number;
     });
     resolveDbPath(): string;
     private openHandle;
+    heartbeatTask(opts: {
+        id: string;
+        runEpoch: number;
+    }): boolean;
+    requestTaskStop(opts: {
+        id: string;
+        requestedAt: string;
+    }): TaskStopRequestResult;
+    finalizeTaskStop(opts: FinalizeTaskStopOptions): boolean;
+    stopTask(id: string, options?: StopTaskOptions): Promise<StopTaskResult>;
     startTask(opts: {
         id: string;
         agentId: string;
@@ -140,6 +194,14 @@ export declare class TaskRepository extends BaseSqliteRepository {
         renderedPrompt?: string | null;
         codingAgentCommand?: string | null;
     }): void;
+    updateTaskOwnership(opts: {
+        id: string;
+        runEpoch: number;
+        ownership: 'runner' | 'caller';
+        providerPid?: number | null;
+    }): boolean;
+    adoptPendingTask(id: string): boolean;
+    failPendingTask(id: string, error: string, completedAt?: string): boolean;
     listTasksByProjectId(projectId: string): TaskRow[];
     finishTask(opts: {
         id: string;
@@ -159,11 +221,12 @@ export declare class TaskRepository extends BaseSqliteRepository {
     }): void;
     updateTaskLifecycle(opts: {
         id: string;
-        status: string;
+        status: TaskStatus;
         error: string | null;
         completedAt: string | null;
         durationMs: number | null;
         workspaceId: string;
+        terminalReason?: TaskTerminalReason;
     }): void;
     appendLog(taskId: string, entry: {
         timestamp: string;
@@ -175,13 +238,11 @@ export declare class TaskRepository extends BaseSqliteRepository {
     readLogsTail(taskId: string, limit: number): TaskLogReadResult | undefined;
     getLogState(taskId: string): TaskLogState | undefined;
     getRunningTasks(): TaskRow[];
+    getActiveTasks(): TaskRow[];
     getAllTasks(): TaskRow[];
     getTask(id: string): TaskRow | undefined;
-    killTask(id: string): {
-        killed: boolean;
-        pid?: number;
-    };
-    reapOrphanedTasks(): number;
+    killTask(id: string): Promise<TaskKillResult>;
+    reapOrphanedTasks(options?: ReapOrphanedTasksOptions): number;
     reapRunningWorkflowTasks(graceMs?: number): number;
     findTaskStatus(taskId: string, workspaceId?: string): TaskRow | undefined;
     findChildTasks(parentTaskId: string, workspaceId?: string): TaskRow[];
@@ -239,7 +300,7 @@ export declare class TaskRepository extends BaseSqliteRepository {
         completed_at: string | null;
         metadata: string | null;
     } | null;
-    markTaskFailed(taskId: string, error: string, workspaceId?: string): void;
+    markTaskFailed(taskId: string, error: string, workspaceId?: string, status?: TaskStatus, terminalReason?: TaskTerminalReason): void;
     findTasksByPromptHint(hint: string, workspaceId?: string): TaskRow[];
     getProviderUsage(from: string, to: string, workspace?: string): ProviderUsageRow[];
     getModelUsage(from: string, to: string, workspace?: string): ModelUsageRow[];

package/dist/repository/usage-backfill.d.ts

@@ -0,0 +1,62 @@
+export type UsageBackfillMode = 'dry-run' | 'apply' | 'verify' | 'restore';
+export declare const USAGE_BACKFILL_TERMINAL_STATUSES: readonly ["success", "failed", "completed"];
+export declare const USAGE_BACKFILL_MAX_LATE_USAGE_AGE_MS: number;
+export declare const USAGE_BACKFILL_UNDO_SCHEMA_VERSION = 1;
+export declare const USAGE_BACKFILL_SNAPSHOT_ROW_BYTES = 2048;
+export declare const USAGE_BACKFILL_MIN_FREE_SPACE_RESERVE_BYTES: number;
+export type UsageAccountingReason = 'pre-instrumentation' | 'provider-no-usage' | 'suppressed-by-adapter' | 'not-captured';
+export interface UsageBackfillOptions {
+    mode: UsageBackfillMode;
+    dbPath?: string;
+    backupPath?: string;
+    restorePath?: string;
+    now?: Date | string | number;
+}
+export interface UsageBackfillProviderStats {
+    candidates: number;
+    recovered: number;
+    unavailable: number;
+    deferred: number;
+}
+export interface UsageBackfillFailure {
+    taskId: string;
+    reason: string;
+}
+export interface UsageBackfillReport {
+    mode: UsageBackfillMode;
+    ok: boolean;
+    dbPath: string;
+    scannedTasks: number;
+    terminalTasks: number;
+    rawTargetTasks: number;
+    candidateTasks: number;
+    recoveredTasks: number;
+    unavailableTasks: number;
+    deferredTasks: number;
+    changedTasks: number;
+    wouldChangeTasks: number;
+    accountingTasks: number;
+    remainingTargetTasks: number;
+    providerDistribution: Record<string, UsageBackfillProviderStats>;
+    reasonCounts: Record<UsageAccountingReason, number>;
+    estimatedFreeSpaceBytes: number;
+    requiredFreeSpaceBytes: number;
+    availableFreeSpaceBytes: number;
+    minimumFreeSpaceReserveBytes: number;
+    freeSpaceGatePassed: boolean;
+    backupPath?: string;
+    snapshotPath?: string;
+    backupMethod?: 'row-undo-snapshot';
+    restored: number;
+    skippedConflict: number;
+    conflictSamples: UsageBackfillConflict[];
+    blockedReason?: string;
+    failures: UsageBackfillFailure[];
+    warnings: string[];
+}
+export interface UsageBackfillConflict {
+    taskId: string;
+    fields: string[];
+}
+export declare function classifyUsageAccountingReason(provider: string | undefined): UsageAccountingReason;
+export declare function runUsageBackfill(options: UsageBackfillOptions): Promise<UsageBackfillReport>;

package/dist/repository/usage-from-logs.d.ts

@@ -0,0 +1,21 @@
+import type { CliProviderAdapter } from '../provider/cli/adapter.types.js';
+import type { TaskLogRepositoryContract } from './task-log.repository.js';
+export interface RecoveredTaskUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    costUsd: number;
+    model: string | null;
+}
+export interface TaskLogUsageRecovery {
+    stdout: string;
+    adapter: CliProviderAdapter;
+    usage?: RecoveredTaskUsage;
+}
+export interface RecoverUsageFromTaskLogsOptions {
+    taskLogRepository: Pick<TaskLogRepositoryContract, 'readLogs'>;
+    taskId: string;
+    provider?: string | null;
+    model?: string | null;
+}
+export declare function recoverUsageFromTaskLogs(options: RecoverUsageFromTaskLogsOptions): TaskLogUsageRecovery | undefined;

package/dist/schema/tasks.d.ts

@@ -429,6 +429,61 @@ export declare const tasks: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        heartbeat_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "heartbeat_at";
+            tableName: "tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stop_requested_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "stop_requested_at";
+            tableName: "tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stop_requested_epoch: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "stop_requested_epoch";
+            tableName: "tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         rendered_prompt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "rendered_prompt";
             tableName: "tasks";

package/dist/utils/runner-env.d.ts

@@ -0,0 +1,3 @@
+export declare const CREWX_RUNNER_IDENTITY_ENV: readonly ["CREWX_ASSIGNED_TASK_ID", "CREWX_DETACHED_RUNNER"];
+export declare function withoutCrewxRunnerIdentity(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function withoutCrewxRootContext(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/sdk",
-  "version": "0.9.0-rc.94",
+  "version": "0.9.0-rc.95",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=20.19.0"
@@ -55,6 +55,11 @@
       "import": "./dist/desktop/index.js",
       "require": "./dist/desktop/index.js"
     },
+    "./process": {
+      "types": "./dist/process/index.d.ts",
+      "import": "./dist/process/index.js",
+      "require": "./dist/process/index.js"
+    },
     "./publish": {
       "types": "./dist/publish/index.d.ts",
       "import": "./dist/publish/index.js",
@@ -78,6 +83,8 @@
     "./dist/esm/repository/index.js": false,
     "./dist/desktop/index.js": false,
     "./dist/esm/desktop/index.js": false,
+    "./dist/process/index.js": false,
+    "./dist/esm/process/index.js": false,
     "./dist/publish/index.js": false,
     "./dist/esm/publish/index.js": false,
     "./dist/account/index.js": false,

package/templates/agents/default.yaml

@@ -140,16 +140,21 @@ layouts:
             when it completes" are NOT true in this mode. That notification will never
             arrive; trusting it silently kills the delegated work.
 
-          Rules for delegation and long-running commands:
-          - Run delegations (crewx q / crewx x) in the FOREGROUND and wait for
-            the result within the same turn. Never use run_in_background, `&`, or nohup
-            for a CrewX delegation.
-          - If the harness force-moves a long command to the background (e.g. on
-            timeout), do NOT end your turn. Keep checking completion with short
-            foreground status checks until it actually finishes.
-          - A PID, a "running" status, a partially created file, or a --thread link is
-            NOT evidence of completion. Report success only after the command has
-            exited and returned its final result.
+          Delegation procedure:
+          1. Inside an agent process, `crewx q` and `crewx x` immediately return a
+             receipt (task ID). A receipt means accepted, not completed.
+          2. Recover the result by repeatedly calling `crewx result <id> --wait=N`
+             with N ≤ 300 from the foreground. Exit 124 means the work is still in
+             progress, so call it again. Read the terminal status before judging the
+             outcome.
+          3. Do not use `&`, `nohup`, or another background execution method. The
+             runner owns the work, so it continues after your turn ends.
+          4. Add `--wait` when a short call should run synchronously and is expected
+             to finish within the harness time limit.
+          5. Accepted does not mean successful. Read both the status and body from
+             `crewx result` before reporting completion.
+          6. The harness warning that background commands may be killed still
+             applies to commands it owns; this runner is outside that process tree.
         </delegation_lifecycle>
         </agent_profile>
         {{/if}}