@kbediako/codex-orchestrator 0.1.24 → 0.1.25

package/README.md

@@ -173,6 +173,14 @@ Usage snapshot (scans local `.runs/`):
 codex-orchestrator doctor --usage
 ```
 
+## Downstream usage cheatsheet (agent-first)
+
+- Bootstrap + wire everything: `codex-orchestrator setup --yes`
+- Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
+- Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
+- Collab (symbolic RLM subagents): `codex-orchestrator rlm "<goal>" --collab auto` (requires collab feature enabled in Codex)
+- Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
+
 Print DevTools MCP setup guidance:
 ```bash
 codex-orchestrator devtools setup

package/dist/orchestrator/src/cli/doctorUsage.js

@@ -14,14 +14,25 @@ export async function runDoctorUsage(options = {}) {
     const seenRunIds = new Set();
     const pipelines = new Map();
     const cloudByStatus = {};
+    const cloudByDiffStatus = {};
+    const cloudByApplyStatus = {};
+    const cloudEnvIds = new Map();
+    const cloudTasks = new Set();
     const statusCounts = { total: 0, succeeded: 0, failed: 0, cancelled: 0, other: 0 };
     let cloudRuns = 0;
     let rlmRuns = 0;
+    const rlmTasks = new Set();
     let collabRunsWithToolCalls = 0;
     let collabTotalToolCalls = 0;
+    const collabTasks = new Set();
+    const collabByStatus = {};
+    const collabByEventType = {};
+    const collabTools = new Map();
     const collabCaptureDisabled = String(process.env.CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS ?? '').trim() === '0';
     const activeIndexTasks = new Set();
     const taskKeys = readTaskIndexKeys(env.repoRoot);
+    const tasksWithChildRuns = new Set();
+    let totalChildRuns = 0;
     for (const manifestPath of manifestPaths) {
         const runIdFromPath = extractRunIdFromManifestPath(manifestPath);
         if (!runIdFromPath) {
@@ -68,19 +79,54 @@ export async function runDoctorUsage(options = {}) {
         pipelines.set(pipelineId, (pipelines.get(pipelineId) ?? 0) + 1);
         if (pipelineId === 'rlm') {
             rlmRuns += 1;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                rlmTasks.add(manifest.task_id);
+            }
         }
         if (manifest.cloud_execution) {
             cloudRuns += 1;
-            const status = (manifest.cloud_execution.status ?? 'unknown').trim() || 'unknown';
+            const cloudStatusRaw = manifest.cloud_execution.status;
+            const status = typeof cloudStatusRaw === 'string' ? cloudStatusRaw.trim() || 'unknown' : 'unknown';
             cloudByStatus[status] = (cloudByStatus[status] ?? 0) + 1;
+            const cloudDiffRaw = manifest.cloud_execution.diff_status;
+            const diffStatus = typeof cloudDiffRaw === 'string' ? cloudDiffRaw.trim() || 'unknown' : 'unknown';
+            cloudByDiffStatus[diffStatus] = (cloudByDiffStatus[diffStatus] ?? 0) + 1;
+            const cloudApplyRaw = manifest.cloud_execution.apply_status;
+            const applyStatus = typeof cloudApplyRaw === 'string' ? cloudApplyRaw.trim() || 'unknown' : 'unknown';
+            cloudByApplyStatus[applyStatus] = (cloudByApplyStatus[applyStatus] ?? 0) + 1;
+            const cloudEnvIdRaw = manifest.cloud_execution.environment_id;
+            const envId = typeof cloudEnvIdRaw === 'string' ? cloudEnvIdRaw.trim() : '';
+            if (envId) {
+                cloudEnvIds.set(envId, (cloudEnvIds.get(envId) ?? 0) + 1);
+            }
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                cloudTasks.add(manifest.task_id);
+            }
         }
         if (Array.isArray(manifest.collab_tool_calls) && manifest.collab_tool_calls.length > 0) {
             collabRunsWithToolCalls += 1;
             collabTotalToolCalls += manifest.collab_tool_calls.length;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                collabTasks.add(manifest.task_id);
+            }
+            for (const entry of manifest.collab_tool_calls) {
+                const tool = typeof entry?.tool === 'string' && entry.tool ? entry.tool : 'unknown';
+                const status = typeof entry?.status === 'string' && entry.status ? entry.status : 'unknown';
+                const eventType = typeof entry?.event_type === 'string' && entry.event_type ? entry.event_type : 'unknown';
+                collabByStatus[status] = (collabByStatus[status] ?? 0) + 1;
+                collabByEventType[eventType] = (collabByEventType[eventType] ?? 0) + 1;
+                collabTools.set(tool, (collabTools.get(tool) ?? 0) + 1);
+            }
         }
-        if (taskKeys.has(manifest.task_id)) {
+        if (typeof manifest.task_id === 'string' && manifest.task_id && taskKeys.has(manifest.task_id)) {
             activeIndexTasks.add(manifest.task_id);
         }
+        if (Array.isArray(manifest.child_runs) && manifest.child_runs.length > 0) {
+            totalChildRuns += manifest.child_runs.length;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                tasksWithChildRuns.add(manifest.task_id);
+            }
+        }
     }
     const pipelineTop = [...pipelines.entries()]
         .sort((a, b) => b[1] - a[1])
@@ -103,26 +149,45 @@ export async function runDoctorUsage(options = {}) {
             activeWithSubagents += 1;
         }
     }
+    const cloudTopEnvIds = [...cloudEnvIds.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([id, runs]) => ({ id, runs }));
+    const collabTopTools = [...collabTools.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([tool, calls]) => ({ tool, calls }));
     return {
         window_days: windowDays,
         cutoff_iso: cutoffIso,
         runs: statusCounts,
         cloud: {
             runs: cloudRuns,
-            by_status: cloudByStatus
+            unique_tasks: cloudTasks.size,
+            by_status: cloudByStatus,
+            by_diff_status: cloudByDiffStatus,
+            by_apply_status: cloudByApplyStatus,
+            top_environment_ids: cloudTopEnvIds
         },
         rlm: {
-            runs: rlmRuns
+            runs: rlmRuns,
+            unique_tasks: rlmTasks.size
         },
         collab: {
             runs_with_tool_calls: collabRunsWithToolCalls,
             total_tool_calls: collabTotalToolCalls,
+            unique_tasks: collabTasks.size,
+            by_status: collabByStatus,
+            by_event_type: collabByEventType,
+            top_tools: collabTopTools,
             capture_disabled: collabCaptureDisabled
         },
         delegation: {
             active_top_level_tasks: activeTasks.length,
             active_with_subagents: activeWithSubagents,
             total_subagent_manifests: totalSubagentManifests,
+            tasks_with_child_runs: tasksWithChildRuns.size,
+            total_child_runs: totalChildRuns,
             errors: delegationErrors
         },
         pipelines: {
@@ -135,12 +200,31 @@ export function formatDoctorUsageSummary(result) {
     const lines = [];
     lines.push(`Usage (last ${result.window_days}d, cutoff ${result.cutoff_iso})`);
     lines.push(`  - runs: ${result.runs.total} (ok=${result.runs.succeeded}, failed=${result.runs.failed}, cancelled=${result.runs.cancelled}, other=${result.runs.other})`);
-    lines.push(`  - cloud: ${result.cloud.runs} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}`);
-    lines.push(`  - rlm: ${result.rlm.runs} (${formatPercent(result.rlm.runs, result.runs.total)})`);
+    const cloudSuffix = result.cloud.unique_tasks > 0
+        ? ` over ${result.cloud.unique_tasks} task${result.cloud.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    const cloudDiff = formatTopCounts(result.cloud.by_diff_status, 2, 'diff');
+    const cloudApply = formatTopCounts(result.cloud.by_apply_status, 2, 'apply');
+    const cloudEnv = formatTopList(result.cloud.top_environment_ids.map((entry) => ({ key: entry.id, value: entry.runs })), 2, 'env');
+    lines.push(`  - cloud: ${result.cloud.runs}${cloudSuffix} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}${cloudDiff}${cloudApply}${cloudEnv}`);
+    const rlmSuffix = result.rlm.unique_tasks > 0
+        ? ` over ${result.rlm.unique_tasks} task${result.rlm.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    lines.push(`  - rlm: ${result.rlm.runs}${rlmSuffix} (${formatPercent(result.rlm.runs, result.runs.total)})`);
     const collabSuffix = result.collab.capture_disabled ? ' (capture disabled)' : '';
-    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`);
+    const collabTaskSuffix = result.collab.unique_tasks > 0
+        ? ` over ${result.collab.unique_tasks} task${result.collab.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    const collabAvg = result.collab.runs_with_tool_calls > 0
+        ? ` (avg ${Math.round((result.collab.total_tool_calls / result.collab.runs_with_tool_calls) * 10) / 10}/run)`
+        : '';
+    const collabOk = result.collab.by_status.completed ?? 0;
+    const collabFailed = result.collab.by_status.failed ?? 0;
+    const collabToolList = formatTopList(result.collab.top_tools.map((entry) => ({ key: entry.tool, value: entry.calls })), 3, 'tools');
+    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`
+        + `${collabTaskSuffix}, events=${result.collab.total_tool_calls}${collabAvg} (ok=${collabOk}, failed=${collabFailed})${collabToolList}`);
     if (result.delegation.active_top_level_tasks > 0) {
-        lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests`);
+        lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests (${result.delegation.total_subagent_manifests} total); child_runs=${result.delegation.total_child_runs} over ${result.delegation.tasks_with_child_runs} tasks`);
     }
     else {
         lines.push('  - delegation: no top-level tasks detected in tasks/index.json for this window');
@@ -193,6 +277,30 @@ function formatCloudStatuses(byStatus) {
         .join(', ');
     return ` [${top}]`;
 }
+function formatTopCounts(byKey, limit, label) {
+    const entries = Object.entries(byKey);
+    if (entries.length === 0) {
+        return '';
+    }
+    entries.sort((a, b) => b[1] - a[1]);
+    const top = entries
+        .slice(0, limit)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(', ');
+    return ` ${label}[${top}]`;
+}
+function formatTopList(entries, limit, label) {
+    const filtered = entries.filter((entry) => entry.key && Number.isFinite(entry.value) && entry.value > 0);
+    if (filtered.length === 0) {
+        return '';
+    }
+    const top = filtered
+        .sort((a, b) => b.value - a.value || a.key.localeCompare(b.key))
+        .slice(0, limit)
+        .map((entry) => `${entry.key}=${entry.value}`)
+        .join(', ');
+    return ` ${label}[${top}]`;
+}
 function readTaskIndexKeys(repoRoot) {
     const indexPath = join(repoRoot, 'tasks', 'index.json');
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "license": "MIT",
   "repository": {
     "type": "git",