crewx 0.9.0-rc.2 → 0.9.0-rc.21

package/dist-server/domain/usage-report/usage-report.controller.js

@@ -0,0 +1,72 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageReportController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const usage_report_service_js_1 = require("./usage-report.service.js");
+const workspace_decorator_js_1 = require("../../common/decorators/workspace.decorator.js");
+let UsageReportController = class UsageReportController {
+    usageReportService;
+    constructor(usageReportService) {
+        this.usageReportService = usageReportService;
+    }
+    // USR.PUBLISH: Publish (or re-publish/upsert) a usage report snapshot for the given month.
+    publish(month, ws) {
+        const data = this.usageReportService.publish(month, ws.id);
+        return { success: true, data };
+    }
+    // USR.GET: Fetch a previously published report. 404 if the month was never published.
+    get(month, ws) {
+        const data = this.usageReportService.get(month, ws.id);
+        return { success: true, data };
+    }
+    // USR.LIST: List publish history for the workspace.
+    list(ws) {
+        const data = this.usageReportService.list(ws.id);
+        return { success: true, data };
+    }
+};
+exports.UsageReportController = UsageReportController;
+__decorate([
+    (0, swagger_1.ApiOperation)({ operationId: 'USR.PUBLISH', summary: 'Publish a usage report snapshot for a month' }),
+    (0, common_1.Post)(':month/publish'),
+    __param(0, (0, common_1.Param)('month')),
+    __param(1, (0, workspace_decorator_js_1.Workspace)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", void 0)
+], UsageReportController.prototype, "publish", null);
+__decorate([
+    (0, swagger_1.ApiOperation)({ operationId: 'USR.GET', summary: 'Get the published usage report for a month' }),
+    (0, common_1.Get)(':month'),
+    __param(0, (0, common_1.Param)('month')),
+    __param(1, (0, workspace_decorator_js_1.Workspace)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", void 0)
+], UsageReportController.prototype, "get", null);
+__decorate([
+    (0, swagger_1.ApiOperation)({ operationId: 'USR.LIST', summary: 'List published usage report history' }),
+    (0, common_1.Get)(),
+    __param(0, (0, workspace_decorator_js_1.Workspace)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], UsageReportController.prototype, "list", null);
+exports.UsageReportController = UsageReportController = __decorate([
+    (0, swagger_1.ApiTags)('usage-report'),
+    (0, common_1.Controller)('ws/:slug/usage-reports'),
+    __metadata("design:paramtypes", [usage_report_service_js_1.UsageReportService])
+], UsageReportController);

package/dist-server/domain/usage-report/usage-report.module.js

@@ -0,0 +1,23 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageReportModule = void 0;
+const common_1 = require("@nestjs/common");
+const usage_module_js_1 = require("../usage/usage.module.js");
+const usage_report_controller_js_1 = require("./usage-report.controller.js");
+const usage_report_service_js_1 = require("./usage-report.service.js");
+let UsageReportModule = class UsageReportModule {
+};
+exports.UsageReportModule = UsageReportModule;
+exports.UsageReportModule = UsageReportModule = __decorate([
+    (0, common_1.Module)({
+        imports: [usage_module_js_1.UsageModule],
+        controllers: [usage_report_controller_js_1.UsageReportController],
+        providers: [usage_report_service_js_1.UsageReportService],
+    })
+], UsageReportModule);

package/dist-server/domain/usage-report/usage-report.service.js

@@ -0,0 +1,135 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageReportService = void 0;
+const common_1 = require("@nestjs/common");
+const nanoid_1 = require("nanoid");
+const usage_service_js_1 = require("../usage/usage.service.js");
+const usage_report_repository_js_1 = require("../../repository/usage-report.repository.js");
+const nanoidBase62 = (0, nanoid_1.customAlphabet)('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789', 12);
+const MONTH_RE = /^\d{4}-\d{2}$/;
+// Tier thresholds — duplicated from src/ui/lib/tier.ts (server code cannot import from src/ui;
+// tsconfig.server.json explicitly excludes it). Only the tier *name* is needed here; keep the
+// `min` thresholds in sync with tier.ts's TIERS array if that ever changes.
+const TIER_THRESHOLDS = [
+    { name: 'Iron', min: 0 },
+    { name: 'Bronze', min: 5_000_000 },
+    { name: 'Silver', min: 10_000_000 },
+    { name: 'Gold', min: 30_000_000 },
+    { name: 'Platinum', min: 50_000_000 },
+    { name: 'Emerald', min: 100_000_000 },
+    { name: 'Diamond', min: 300_000_000 },
+    { name: 'Master', min: 500_000_000 },
+    { name: 'Grandmaster', min: 1_000_000_000 },
+    { name: 'Challenger', min: 1_500_000_000 },
+];
+function getTierName(totalTokens) {
+    let name = TIER_THRESHOLDS[0].name;
+    for (const t of TIER_THRESHOLDS) {
+        if (totalTokens >= t.min)
+            name = t.name;
+    }
+    return name;
+}
+let UsageReportService = class UsageReportService {
+    usageService;
+    usageReportRepository;
+    constructor(usageService, usageReportRepository) {
+        this.usageService = usageService;
+        this.usageReportRepository = usageReportRepository;
+    }
+    // USR.PUBLISH: Aggregate the given month and store (or re-publish/upsert) a snapshot.
+    publish(month, workspaceId) {
+        this.validateMonth(month);
+        const { from, to } = this.monthRange(month);
+        const agentUsage = this.usageService.getAgentUsage(from, to, workspaceId);
+        const providerUsage = this.usageService.getProviderUsage(from, to, workspaceId);
+        const modelUsage = this.usageService.getModelUsage(from, to, workspaceId);
+        const reworkRate = this.usageService.getReworkRate(from, to, workspaceId);
+        const hourlyUsage = this.usageService.getHourlyUsage(from, to, workspaceId);
+        const failureBreakdown = this.usageService.getFailureBreakdown(from, to, workspaceId);
+        const agentSuccess = this.usageService.getAgentSuccess(from, to, workspaceId);
+        const totalTokens = agentUsage.totals.totalTokens;
+        const totalCostUsd = agentUsage.totals.totalCost;
+        const tier = getTierName(totalTokens);
+        const generatedAt = new Date().toISOString();
+        const sourceRange = `${from}/${to}`;
+        const payload = {
+            agentUsage,
+            providerUsage,
+            modelUsage,
+            reworkRate,
+            hourlyUsage,
+            failureBreakdown,
+            agentSuccess,
+        };
+        this.usageReportRepository.publish({
+            id: `usr_${nanoidBase62()}`,
+            workspaceId,
+            month,
+            generatedAt,
+            sourceRange,
+            tier,
+            totalTokens,
+            totalCostUsd,
+            payload: JSON.stringify(payload),
+        });
+        return { month, generatedAt, sourceRange, tier, totalTokens, totalCostUsd, payload };
+    }
+    // USR.GET: Fetch a previously published report. 404 if the month was never published.
+    get(month, workspaceId) {
+        this.validateMonth(month);
+        const row = this.usageReportRepository.findByMonth(workspaceId, month);
+        if (!row) {
+            throw new common_1.NotFoundException(`Usage report not found for month: ${month}`);
+        }
+        return {
+            month: row.month,
+            generatedAt: row.generated_at,
+            sourceRange: row.source_range,
+            tier: row.tier,
+            totalTokens: row.total_tokens,
+            totalCostUsd: row.total_cost_usd,
+            payload: JSON.parse(row.payload),
+        };
+    }
+    // USR.LIST: List publish history (summary columns only, no payload).
+    list(workspaceId) {
+        const rows = this.usageReportRepository.listByWorkspace(workspaceId);
+        const reports = rows.map((row) => ({
+            month: row.month,
+            generatedAt: row.generated_at,
+            tier: row.tier,
+            totalTokens: row.total_tokens,
+            totalCostUsd: row.total_cost_usd,
+        }));
+        return { reports };
+    }
+    validateMonth(month) {
+        if (!MONTH_RE.test(month)) {
+            throw new common_1.BadRequestException(`Invalid month format: ${month}. Expected YYYY-MM.`);
+        }
+    }
+    monthRange(month) {
+        const [year, mon] = month.split('-').map(Number);
+        const from = `${month}-01T00:00:00.000Z`;
+        const nextMonth = mon === 12 ? 1 : mon + 1;
+        const nextYear = mon === 12 ? year + 1 : year;
+        const to = `${nextYear}-${String(nextMonth).padStart(2, '0')}-01T00:00:00.000Z`;
+        return { from, to };
+    }
+};
+exports.UsageReportService = UsageReportService;
+exports.UsageReportService = UsageReportService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [usage_service_js_1.UsageService,
+        usage_report_repository_js_1.UsageReportRepository])
+], UsageReportService);

package/dist-server/domain/wi/wi.service.js

@@ -15,6 +15,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const js_yaml_1 = require("js-yaml");
 const thread_repository_js_1 = require("../../repository/thread.repository.js");
+const task_repository_js_1 = require("../../repository/task.repository.js");
 const WI_ID_RE = /^WI-\d{8}-\d+$/;
 const VALID_STATUSES = new Set(['draft', 'approved', 'in-progress', 'done', 'cancelled']);
 function toArray(v) {
@@ -36,8 +37,10 @@ function normalizeStatus(v) {
 }
 let WiService = class WiService {
     threadRepo;
-    constructor(threadRepo) {
+    taskRepo;
+    constructor(threadRepo, taskRepo) {
         this.threadRepo = threadRepo;
+        this.taskRepo = taskRepo;
     }
     validatePathBoundary(dir, fullPath) {
         const dirCmp = dir.replace(/\\/g, '/').toLowerCase();
@@ -91,9 +94,44 @@ let WiService = class WiService {
         const match = entries.find((f) => f === `${wiId}.md` || (f.startsWith(`${wiId}-`) && f.endsWith('.md')));
         return match ?? null;
     }
+    parseTaskMetadata(raw) {
+        if (!raw)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Find the workflow_card task for a thread, if any.
+     * Reuses TaskRepository.findTasksByThread (not batchFetchTasks, which is
+     * scoped to top-level tasks only and would miss workflow-nested tasks).
+     * No new proof API — proof stays embedded in the task result raw string;
+     * the caller (frontend) re-derives it from `raw` as needed.
+     */
+    findWorkflowCard(threadId) {
+        const tasks = this.taskRepo.findTasksByThread(threadId);
+        const cardTasks = tasks.filter((t) => this.parseTaskMetadata(t.metadata).kind === 'workflow_card');
+        if (cardTasks.length === 0)
+            return undefined;
+        // findTasksByThread orders by started_at ASC — take the most recent card
+        const latest = cardTasks[cardTasks.length - 1];
+        const metadata = this.parseTaskMetadata(latest.metadata);
+        return {
+            taskId: latest.id,
+            workflowRunId: typeof metadata['workflowRunId'] === 'string' ? metadata['workflowRunId'] : undefined,
+            raw: latest.result ?? undefined,
+        };
+    }
     /**
      * Build a map from WI ID → runtime task info by loading all threads + their
-     * latest tasks in two bulk queries (no N+1).
+     * latest tasks in two bulk queries (no N+1), plus a per-thread
+     * workflow_card lookup (documented N+1, thread task volume is small).
      *
      * Matching rule: thread.id === wiId  OR  thread.title === wiId
      */
@@ -126,6 +164,7 @@ let WiService = class WiService {
                 current_task_id: latest?.id,
                 task_status: latest?.status,
                 task_agent: latest?.agent_id || undefined,
+                workflowCard: this.findWorkflowCard(thread.id),
             });
         }
         return result;
@@ -154,6 +193,7 @@ let WiService = class WiService {
             summary.current_task_id = runtime.current_task_id;
             summary.task_status = runtime.task_status;
             summary.task_agent = runtime.task_agent;
+            summary.workflowCard = runtime.workflowCard;
         }
         return { summary, frontmatter: data, body };
     }
@@ -226,6 +266,7 @@ let WiService = class WiService {
                 summary.current_task_id = runtime.current_task_id;
                 summary.task_status = runtime.task_status;
                 summary.task_agent = runtime.task_agent;
+                summary.workflowCard = runtime.workflowCard;
             }
         }
         return out.sort((a, b) => b.mtime - a.mtime);
@@ -234,5 +275,6 @@ let WiService = class WiService {
 exports.WiService = WiService;
 exports.WiService = WiService = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [thread_repository_js_1.ThreadRepository])
+    __metadata("design:paramtypes", [thread_repository_js_1.ThreadRepository,
+        task_repository_js_1.TaskRepository])
 ], WiService);

package/dist-server/main.js

@@ -59,6 +59,7 @@ async function bootstrap() {
     // Adapter routes (/adapters/*) need raw Buffer body for signature verification.
     const app = await core_1.NestFactory.create(app_module_js_1.AppModule, {
         bodyParser: false,
+        forceCloseConnections: true,
         ...(httpsOptions ? { httpsOptions } : {}),
     });
     // trust proxy — set before other middleware so req.ip is correct behind nginx/Caddy

package/dist-server/repository/repository.module.js

@@ -15,6 +15,7 @@ const box_repository_js_1 = require("./box.repository.js");
 const project_repository_js_1 = require("./project.repository.js");
 const request_log_repository_js_1 = require("./request-log.repository.js");
 const usage_limit_snapshot_repository_js_1 = require("./usage-limit-snapshot.repository.js");
+const usage_report_repository_js_1 = require("./usage-report.repository.js");
 const repositories = [
     thread_repository_js_1.ThreadRepository,
     task_repository_js_1.TaskRepository,
@@ -23,6 +24,7 @@ const repositories = [
     project_repository_js_1.ProjectRepository,
     request_log_repository_js_1.RequestLogRepository,
     usage_limit_snapshot_repository_js_1.UsageLimitSnapshotRepository,
+    usage_report_repository_js_1.UsageReportRepository,
 ];
 let RepositoryModule = class RepositoryModule {
 };

package/dist-server/repository/task.repository.js

@@ -158,6 +158,14 @@ let TaskRepository = class TaskRepository extends base_sqlite_repository_js_1.Ba
     getProviderUsage(from, to, workspace) {
         return this.sdk.getProviderUsage(from, to, workspace);
     }
+    /** USG.MODEL: Aggregate per-model (canonical) usage within a date range. */
+    getModelUsage(from, to, workspace) {
+        return this.sdk.getModelUsage(from, to, workspace);
+    }
+    /** USR: Generic raw task rows for usage-report aggregation (rework/hourly/failure). */
+    getTasksForReport(from, to, workspace) {
+        return this.sdk.getTasksForReport(from, to, workspace);
+    }
     /** Find a task by id with workspace isolation for stop operation. */
     findTaskForStop(taskId, workspaceId) {
         const row = this.sdk.findTaskForStop(taskId, workspaceId);
@@ -279,6 +287,54 @@ let TaskRepository = class TaskRepository extends base_sqlite_repository_js_1.Ba
             handle.close();
         }
     }
+    /**
+     * Resume-failure safety net for `instructTask`. If the resume `crewx.execute()`
+     * rejects before the new process ever reports its pid (task:start), the row
+     * is stuck at status='running', pid=NULL forever. This transitions it to
+     * `failed`, but ONLY when the row is still exactly in that pending-resume
+     * state:
+     *   - status = 'running'
+     *   - run_epoch = the epoch bumped by this resume (markTaskResumedForInstruction)
+     *   - pid IS NULL
+     *
+     * If a new process already reported its pid (task:start beat the catch), or
+     * a later instruction bumped run_epoch again, this is a no-op — we must
+     * never clobber a task that already recovered.
+     *
+     * @returns true if the row was updated.
+     */
+    markTaskFailedIfResumePending(taskId, runEpoch, error, workspaceId) {
+        const handle = (0, repository_1.openDrizzleDb)(this.resolveDbPath());
+        try {
+            const condition = workspaceId
+                ? (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(repository_1.tasks.id, taskId), (0, drizzle_orm_1.eq)(repository_1.tasks.workspace_id, workspaceId), (0, drizzle_orm_1.eq)(repository_1.tasks.status, 'running'), (0, drizzle_orm_1.eq)(repository_1.tasks.run_epoch, runEpoch), (0, drizzle_orm_1.isNull)(repository_1.tasks.pid))
+                : (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(repository_1.tasks.id, taskId), (0, drizzle_orm_1.eq)(repository_1.tasks.status, 'running'), (0, drizzle_orm_1.eq)(repository_1.tasks.run_epoch, runEpoch), (0, drizzle_orm_1.isNull)(repository_1.tasks.pid));
+            const row = handle.db
+                .select({ id: repository_1.tasks.id })
+                .from(repository_1.tasks)
+                .where(condition)
+                .limit(1)
+                .get();
+            if (!row)
+                return false;
+            const params = workspaceId
+                ? ['failed', error, new Date().toISOString(), taskId, runEpoch, workspaceId]
+                : ['failed', error, new Date().toISOString(), taskId, runEpoch];
+            const where = workspaceId
+                ? `WHERE id = ? AND run_epoch = ? AND pid IS NULL AND status = 'running' AND workspace_id = ?`
+                : `WHERE id = ? AND run_epoch = ? AND pid IS NULL AND status = 'running'`;
+            handle.runRaw(`UPDATE tasks SET status = ?, error = ?, completed_at = ? ${where}`, params);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof repository_1.RepositoryError)
+                throw e;
+            throw new repository_1.RepositoryError('DB_ERROR', 'Failed to mark task failed for pending resume', e);
+        }
+        finally {
+            handle.close();
+        }
+    }
     appendLog(taskId, entry) {
         this.sdk.appendLog(taskId, entry);
     }

package/dist-server/repository/thread.repository.js

@@ -149,6 +149,19 @@ let ThreadRepository = class ThreadRepository extends base_sqlite_repository_js_
             throw e;
         }
     }
+    /** Atomically resolve overdrive state for an incoming request.
+     *  See SdkThreadRepository.resolveOverdriveForRequest for the state model.
+     *  Returns null when the thread is not found. */
+    resolveOverdriveForRequest(threadId, workspaceId, action, opts) {
+        try {
+            return this.sdkThread.resolveOverdriveForRequest(threadId, workspaceId, action, opts);
+        }
+        catch (e) {
+            if (e instanceof repository_1.RepositoryError)
+                return null;
+            throw e;
+        }
+    }
     /** Reorder pinned threads by writing pinOrder to each thread's metadata. */
     reorderPins(threadIds, workspaceId) {
         try {

package/dist-server/repository/usage-report.repository.js

@@ -0,0 +1,27 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageReportRepository = void 0;
+const common_1 = require("@nestjs/common");
+const repository_1 = require("@crewx/sdk/repository");
+let UsageReportRepository = class UsageReportRepository {
+    sdk = new repository_1.UsageReportRepository();
+    publish(input) {
+        return this.sdk.publish(input);
+    }
+    findByMonth(workspaceId, month) {
+        return this.sdk.findByMonth(workspaceId, month);
+    }
+    listByWorkspace(workspaceId) {
+        return this.sdk.listByWorkspace(workspaceId);
+    }
+};
+exports.UsageReportRepository = UsageReportRepository;
+exports.UsageReportRepository = UsageReportRepository = __decorate([
+    (0, common_1.Injectable)()
+], UsageReportRepository);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewx",
-  "version": "0.9.0-rc.2",
+  "version": "0.9.0-rc.21",
   "description": "CrewX — AI agent team dashboard with Electron UI and CLI (Web + Electron + Global CLI)",
   "main": "server.js",
   "bin": {
@@ -81,19 +81,19 @@
     "yargs": "17.7.0",
     "zod": "3.25.76",
     "@crewx/chromex": "0.1.0",
-    "@crewx/cli": "0.9.0-rc.2",
-    "@crewx/cron": "0.1.10",
+    "@crewx/cli": "0.9.0-rc.21",
     "@crewx/doc": "0.1.9",
+    "@crewx/cron": "0.1.10",
     "@crewx/dreaming": "0.1.0",
-    "@crewx/knowledge-core": "0.1.17",
     "@crewx/memory": "0.1.23",
-    "@crewx/sdk": "0.9.0-rc.2",
+    "@crewx/knowledge-core": "0.1.17-rc.30",
     "@crewx/search": "0.1.10",
-    "@crewx/shared": "0.0.6",
-    "@crewx/wbs": "0.1.10",
-    "@crewx/wi": "0.1.10",
+    "@crewx/sdk": "0.9.0-rc.21",
     "@crewx/skill": "0.1.20",
-    "@crewx/workflow": "0.3.22"
+    "@crewx/shared": "0.0.6",
+    "@crewx/workflow": "0.3.22-rc.67",
+    "@crewx/wi": "0.1.10-rc.41",
+    "@crewx/wbs": "0.1.10"
   },
   "devDependencies": {
     "@ccusage/codex": "0.0.1",

package/packages/cli/dist/bootstrap/codex-writable-roots.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CLI-layer policy: inject CrewX home as an extra writable root for Codex
+ * `workspace-write` sandbox invocations.
+ *
+ * Why this lives in packages/cli (not packages/sdk):
+ * CrewX home (`~/.crewx` by default) is a product-specific path. The SDK's
+ * `additionalArgsProvider` extension point (WI-20260703-001) exists precisely
+ * so that product layers like this CLI can inject such paths without the SDK
+ * knowing about them.
+ *
+ * Why `-c sandbox_workspace_write.writable_roots=[...]` instead of `--add-dir`:
+ * Verified against codex-cli 0.139.0 (`codex exec --help` / `codex exec resume --help`):
+ *   - `codex exec` supports `--add-dir <DIR>`.
+ *   - `codex exec resume` does NOT support `--add-dir` (only `-c/--config`).
+ * Using the `-c` config-override form works identically for both `exec` and
+ * `exec resume`, avoiding a resume-incompatible flag.
+ */
+import type { AdditionalArgsProvider } from '@crewx/sdk';
+/**
+ * Resolve CrewX home directory.
+ * Priority: `CREWX_HOME` env var → `~/.crewx`.
+ */
+export declare function resolveCrewxHome(): string;
+/**
+ * Escape a string for embedding inside a TOML basic string (`"..."`).
+ * Sufficient for filesystem paths: handles backslash (Windows paths),
+ * double-quote, and control characters that could otherwise break TOML
+ * parsing of the `-c key="value"` override.
+ */
+export declare function escapeTomlBasicString(value: string): string;
+/**
+ * Build the `-c sandbox_workspace_write.writable_roots=["<path>"]` arg pair.
+ * Works for both `codex exec` and `codex exec resume` (config-override form).
+ */
+export declare function buildCodexWritableRootArgs(crewxHome: string): string[];
+/**
+ * Create an `AdditionalArgsProvider` (SDK extension point, WI-20260703-001)
+ * that injects CrewX home as a Codex writable root for `workspace-write`
+ * equivalent modes (`agent`, `auto`, `undefined`).
+ *
+ * No-ops for:
+ *   - Non-codex providers.
+ *   - Modes in {@link NO_INJECT_MODES} (read-only/plan/agent-full-access/yolo/danger-full-access).
+ */
+export declare function createCodexWritableRootsProvider(crewxHome?: string): AdditionalArgsProvider;

package/packages/cli/dist/bootstrap/codex-writable-roots.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * CLI-layer policy: inject CrewX home as an extra writable root for Codex
+ * `workspace-write` sandbox invocations.
+ *
+ * Why this lives in packages/cli (not packages/sdk):
+ * CrewX home (`~/.crewx` by default) is a product-specific path. The SDK's
+ * `additionalArgsProvider` extension point (WI-20260703-001) exists precisely
+ * so that product layers like this CLI can inject such paths without the SDK
+ * knowing about them.
+ *
+ * Why `-c sandbox_workspace_write.writable_roots=[...]` instead of `--add-dir`:
+ * Verified against codex-cli 0.139.0 (`codex exec --help` / `codex exec resume --help`):
+ *   - `codex exec` supports `--add-dir <DIR>`.
+ *   - `codex exec resume` does NOT support `--add-dir` (only `-c/--config`).
+ * Using the `-c` config-override form works identically for both `exec` and
+ * `exec resume`, avoiding a resume-incompatible flag.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCrewxHome = resolveCrewxHome;
+exports.escapeTomlBasicString = escapeTomlBasicString;
+exports.buildCodexWritableRootArgs = buildCodexWritableRootArgs;
+exports.createCodexWritableRootsProvider = createCodexWritableRootsProvider;
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * crewx.yaml / query-option `mode` values for which Codex is NOT running in
+ * (or being pushed into) a `workspace-write`-equivalent sandbox. Injecting an
+ * extra writable root is meaningless (read-only/plan) or redundant
+ * (full-access variants already allow writes everywhere) in these modes.
+ */
+const NO_INJECT_MODES = new Set([
+    'read-only',
+    'plan',
+    'agent-full-access',
+    'yolo',
+    'danger-full-access',
+]);
+/**
+ * Resolve CrewX home directory.
+ * Priority: `CREWX_HOME` env var → `~/.crewx`.
+ */
+function resolveCrewxHome() {
+    return process.env.CREWX_HOME ?? (0, path_1.join)((0, os_1.homedir)(), '.crewx');
+}
+/**
+ * Escape a string for embedding inside a TOML basic string (`"..."`).
+ * Sufficient for filesystem paths: handles backslash (Windows paths),
+ * double-quote, and control characters that could otherwise break TOML
+ * parsing of the `-c key="value"` override.
+ */
+function escapeTomlBasicString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+/**
+ * Build the `-c sandbox_workspace_write.writable_roots=["<path>"]` arg pair.
+ * Works for both `codex exec` and `codex exec resume` (config-override form).
+ */
+function buildCodexWritableRootArgs(crewxHome) {
+    const escaped = escapeTomlBasicString(crewxHome);
+    return ['-c', `sandbox_workspace_write.writable_roots=["${escaped}"]`];
+}
+function isCodexProvider(ctx) {
+    return ctx.providerId === 'codex' || ctx.providerStr === 'cli/codex';
+}
+/**
+ * Create an `AdditionalArgsProvider` (SDK extension point, WI-20260703-001)
+ * that injects CrewX home as a Codex writable root for `workspace-write`
+ * equivalent modes (`agent`, `auto`, `undefined`).
+ *
+ * No-ops for:
+ *   - Non-codex providers.
+ *   - Modes in {@link NO_INJECT_MODES} (read-only/plan/agent-full-access/yolo/danger-full-access).
+ */
+function createCodexWritableRootsProvider(crewxHome = resolveCrewxHome()) {
+    return (ctx) => {
+        if (!isCodexProvider(ctx))
+            return [];
+        if (ctx.mode !== undefined && NO_INJECT_MODES.has(ctx.mode))
+            return [];
+        return buildCodexWritableRootArgs(crewxHome);
+    };
+}

package/packages/cli/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 codex_writable_roots_1 = require("./codex-writable-roots");
 /**
  * Build a Crewx instance with CLI-standard plugins (FileLogger + SqliteTracing)
  * and built-in tools registered. Use this from any CLI command that needs a
@@ -52,6 +53,7 @@ async function createCliCrewx(configPath = process.env.CREWX_CONFIG ?? 'crewx.ya
     }
     const crewx = await sdk_1.Crewx.loadYaml(yamlPath, {
         remoteFactory: createCliCrewx,
+        additionalArgsProvider: (0, codex_writable_roots_1.createCodexWritableRootsProvider)(),
     });
     (0, register_builtin_tools_1.registerBuiltinToolsIfNeeded)(crewx);
     await crewx.use(new plugins_1.ConversationPlugin());