ultracode-for-codex 0.2.2 → 0.2.4

package/README.md

@@ -26,7 +26,7 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.2.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.4.tgz
 ```
 
 Run a workflow:
@@ -60,10 +60,15 @@ plugin workflow folders, and built-ins:
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
   --cwd /path/to/target-repo \
-  --name code-review \
-  --args '{"prompt":"review correctness risks"}'
+  --name task \
+  --args '{"prompt":"review correctness risks and propose fixes"}'
 ```
 
+The built-in `task` and `code-review` workflows use an LLM planner first, then
+run work phase by phase. Within each phase, multiple focused Codex subagents run
+in parallel by default, followed by phase and final synthesis. The planner may
+choose a single-agent path only when parallel execution would add risk or waste.
+
 ## Settings
 
 Package defaults live in `settings.json`:
@@ -98,6 +103,8 @@ Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
   agent records also include stable agent identity and label fields.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
+- `--timeout-ms` is the workflow timeout and the default per-agent silence
+  budget; it is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
   permission reviews.
 - Use `--progress plain` for human-readable log lines.
@@ -120,8 +127,9 @@ want Codex to auto-load the package boundaries and verification routine.
   environment.
 - Codex subagents run against the requested workflow cwd and receive bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` injects deterministic workspace context before calling
-  its subagent so file-specific prompts carry local evidence into the review.
+- Built-in `task` and `code-review` inject deterministic workspace context into
+  planner-selected phase-wise parallel subagents, then synthesize each phase and
+  the final result.
 - Workflow execution is local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.

package/ULTRACODE_INSTALL.md

@@ -31,7 +31,7 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.2.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.4.tgz
 ```
 
 Optional Codex companion skill:
@@ -58,6 +58,12 @@ npm exec -- ultracode-for-codex run \
 The default run prints a background launch record to stdout. Use
 `--execution attached` when Codex should read progress until completion.
 
+Use built-in `task` for general work and `code-review` for review-specific work.
+Both start with an LLM planner, execute phase by phase, run multiple focused
+Codex subagents in parallel within each phase by default, and synthesize phase
+and final results. The planner chooses a single-agent path only when parallel
+execution would add risk or waste.
+
 Settings defaults:
 
 ```json
@@ -87,6 +93,8 @@ Useful controls:
   agent records also include stable agent identity and label fields.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
+- `--timeout-ms` is the workflow timeout and the default per-agent silence
+  budget; it is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath
   workflow permission reviews.
 - Use `--progress plain` for human-readable log lines.
@@ -106,8 +114,9 @@ Useful controls:
 - Strip direct provider credentials from child CLI environments.
 - Run Codex subagents against the requested workflow cwd and provide bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` adds deterministic workspace context before the agent
-  call, prioritizing files explicitly mentioned in the prompt.
+- Built-in `task` and `code-review` add deterministic workspace context to
+  planner-selected phase-wise parallel subagents, then synthesize each phase and
+  the final result.
 - Install consumers from a packaged artifact.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned

package/dist/runtime/workflow-runtime.js

@@ -10,7 +10,6 @@ import { WORKFLOW_JOURNAL_GENESIS_AGENT_CALL_KEY, WORKFLOW_JOURNAL_WRITE_FAILED_
 const MAX_SCRIPT_BYTES = 64 * 1024;
 const MAX_AGENT_CALLS = 1000;
 const MAX_PARALLELISM = 16;
-const DEFAULT_AGENT_STALL_TIMEOUT_MS = 180_000;
 const DEFAULT_AGENT_STALL_RETRY_LIMIT = 5;
 const DEFAULT_WORKSPACE_CONTEXT_MAX_FILES = 24;
 const DEFAULT_WORKSPACE_CONTEXT_MAX_FILE_BYTES = 12_000;
@@ -100,39 +99,209 @@ const WORKSPACE_CONTEXT_PRIORITY_FILES = new Set([
     'tsconfig.json',
 ]);
 const DEFAULT_BUILTIN_WORKFLOWS = [
+    {
+        name: 'task',
+        script: phaseWiseBuiltinWorkflowScript({
+            name: 'task',
+            description: 'Run an LLM-planned phase-wise parallel task workflow',
+            defaultPrompt: 'Complete the requested repository task.',
+            plannerKind: 'general task',
+            plannerGuidance: 'Plan phases that make the work faster and more accurate through parallel agents. Default to phase_parallel. Choose single only for tiny changes, strictly sequential investigations, or one indivisible failure mode.',
+            agentGuidance: 'Complete the assigned phase work. Prefer concrete evidence, file paths, commands, and risks over broad narration.',
+            finalGuidance: 'Return the completed task result, key evidence, decisions made, verification status, and residual risk.',
+        }),
+    },
     {
         name: 'code-review',
-        script: `export const meta = {
-  name: "code-review",
-  description: "Run a code review workflow"
-};
-const input = args && typeof args === "object" ? args : {};
-const prompt = typeof input.prompt === "string" && input.prompt.trim()
-  ? input.prompt
-  : "Review the current repository for correctness risks.";
-const context = await workspaceContext({ query: prompt });
-return await agent([
-  prompt,
-  "",
-  "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
-  "",
-  context
-].join("\\n"), { label: "code-review" });`,
+        script: phaseWiseBuiltinWorkflowScript({
+            name: 'code-review',
+            description: 'Run an LLM-planned phase-wise parallel code review workflow',
+            defaultPrompt: 'Review the current repository for correctness risks.',
+            plannerKind: 'code review',
+            plannerGuidance: 'Plan an effective code review. Default to phase_parallel with multiple focused reviewers per phase. Commonly useful lenses include runtime correctness, security/capability boundaries, API/CLI contracts, persistence/retry/cancel behavior, and test coverage. Choose single only for a tiny scoped diff or one indivisible failure mode.',
+            agentGuidance: 'Return material findings only. Prioritize root cause, severity, exact file/line evidence, reproduction or impact, and residual risk.',
+            finalGuidance: 'Return findings ordered by severity with exact file/line references. Deduplicate overlaps, preserve dissent or uncertainty, and say clearly if there are no material findings.',
+        }),
     },
     {
         name: 'batch',
         script: `export const meta = {
   name: "batch",
-  description: "Run multiple prompts in parallel"
+  description: "Run explicitly supplied prompts in one parallel phase"
 };
 const input = args && typeof args === "object" ? args : {};
 const prompts = Array.isArray(input.prompts) ? input.prompts : [];
+phase("Batch");
 return await parallel(prompts.map((prompt, index) => () => agent(
   prompt == null ? "" : "" + prompt,
   { label: "batch-" + (index + 1) }
 )));`,
     },
 ];
+function phaseWiseBuiltinWorkflowScript(input) {
+    return `export const meta = {
+  name: ${JSON.stringify(input.name)},
+  description: ${JSON.stringify(input.description)}
+};
+const workflowInput = args && typeof args === "object" ? args : {};
+const prompt = typeof workflowInput.prompt === "string" && workflowInput.prompt.trim()
+  ? workflowInput.prompt
+  : ${JSON.stringify(input.defaultPrompt)};
+const context = await workspaceContext({ query: prompt });
+const plan = await agent([
+  ${JSON.stringify(`Plan the phase-wise execution strategy for ${input.plannerKind}.`)},
+  "",
+  ${JSON.stringify(input.plannerGuidance)},
+  "A phase runs after previous phase summaries are available. Within each phase, use parallel agents by default.",
+  "Return 1 to 4 phases. For ordinary work, prefer 2 phases with 2 to 4 parallel agents each. Use concise stable ids.",
+  "",
+  "User request:",
+  prompt,
+  "",
+  context
+].join("\\n"), {
+  label: ${JSON.stringify(`${input.name}-planner`)},
+  schema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      mode: { type: "string", enum: ["phase_parallel", "single"] },
+      rationale: { type: "string", minLength: 1 },
+      phases: {
+        type: "array",
+        minItems: 1,
+        maxItems: 4,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            id: { type: "string", minLength: 1, maxLength: 32 },
+            title: { type: "string", minLength: 1, maxLength: 80 },
+            goal: { type: "string", minLength: 1, maxLength: 800 },
+            agents: {
+              type: "array",
+              minItems: 1,
+              maxItems: 4,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1, maxLength: 32 },
+                  title: { type: "string", minLength: 1, maxLength: 80 },
+                  focus: { type: "string", minLength: 1, maxLength: 800 }
+                },
+                required: ["id", "title", "focus"]
+              }
+            }
+          },
+          required: ["id", "title", "goal", "agents"]
+        }
+      }
+    },
+    required: ["mode", "rationale", "phases"]
+  }
+});
+const selectedPhases = plan.mode === "single" ? [plan.phases[0]] : plan.phases;
+if (plan.mode === "single") {
+  const singlePhase = selectedPhases[0];
+  const singleAgent = singlePhase.agents[0];
+  phase(singlePhase.title);
+  return await agent([
+    "Single-agent execution selected by the LLM planner.",
+    "Planner rationale: " + plan.rationale,
+    "Phase goal: " + singlePhase.goal,
+    "Agent focus: " + singleAgent.title + " - " + singleAgent.focus,
+    "",
+    "Original request:",
+    prompt,
+    "",
+    ${JSON.stringify(input.agentGuidance)},
+    "",
+    "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+    "",
+    context
+  ].join("\\n"), { label: ${JSON.stringify(`${input.name}-single`)}, phase: singlePhase.title });
+}
+const phaseOutputs = [];
+const priorSummaries = [];
+for (const phasePlan of selectedPhases) {
+  phase(phasePlan.title);
+  const agents = phasePlan.agents;
+  const agentOutputs = agents.length < 2
+    ? [await agent([
+        "Parallel phase agent: " + agents[0].title,
+        "Phase: " + phasePlan.title,
+        "Phase goal: " + phasePlan.goal,
+        "Agent focus: " + agents[0].focus,
+        "",
+        "Previous phase summaries:",
+        JSON.stringify(priorSummaries, null, 2),
+        "",
+        "Original request:",
+        prompt,
+        "",
+        ${JSON.stringify(input.agentGuidance)},
+        "",
+        "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+        "",
+        context
+      ].join("\\n"), { label: ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + agents[0].id, phase: phasePlan.title })]
+    : await parallel(agents.map((phaseAgent) => () => agent([
+        "Parallel phase agent: " + phaseAgent.title,
+        "Phase: " + phasePlan.title,
+        "Phase goal: " + phasePlan.goal,
+        "Agent focus: " + phaseAgent.focus,
+        "",
+        "Previous phase summaries:",
+        JSON.stringify(priorSummaries, null, 2),
+        "",
+        "Original request:",
+        prompt,
+        "",
+        ${JSON.stringify(input.agentGuidance)},
+        "",
+        "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+        "",
+        context
+      ].join("\\n"), { label: ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + phaseAgent.id, phase: phasePlan.title })));
+  const phaseSummary = await agent([
+    "Synthesize this phase.",
+    "Phase: " + phasePlan.title,
+    "Phase goal: " + phasePlan.goal,
+    "",
+    "Original request:",
+    prompt,
+    "",
+    "Agent outputs:",
+    JSON.stringify(agentOutputs, null, 2),
+    "",
+    "Return a concise phase summary with material findings, completed work, open questions, and what the next phase should know."
+  ].join("\\n"), { label: ${JSON.stringify(`${input.name}-phase-`)} + phasePlan.id + "-synthesis", phase: phasePlan.title });
+  const phaseRecord = {
+    id: phasePlan.id,
+    title: phasePlan.title,
+    goal: phasePlan.goal,
+    results: agentOutputs,
+    summary: phaseSummary
+  };
+  phaseOutputs.push(phaseRecord);
+  priorSummaries.push({ id: phaseRecord.id, title: phaseRecord.title, summary: phaseRecord.summary });
+}
+return await agent([
+  ${JSON.stringify(`Synthesize the phase-wise ${input.plannerKind} workflow into the final result.`)},
+  "",
+  "Original request:",
+  prompt,
+  "",
+  "Planner rationale:",
+  plan.rationale,
+  "",
+  "Phase outputs:",
+  JSON.stringify(phaseOutputs, null, 2),
+  "",
+  ${JSON.stringify(input.finalGuidance)}
+].join("\\n"), { label: ${JSON.stringify(`${input.name}-final-synthesis`)} });`;
+}
 export class WorkflowTaskRegistry {
     options;
     tasks = new Map();
@@ -146,7 +315,7 @@ export class WorkflowTaskRegistry {
         this.options = options;
         this.stateDir = options.stateDir ?? join(options.cwd ?? process.cwd(), '.ultracode-for-codex');
         this.agentStallRetryLimit = normalizeAgentStallRetryLimit(options.agentStallRetryLimit);
-        this.agentStallTimeoutMs = normalizeAgentStallTimeoutMs(options.agentStallTimeoutMs, options.requestTimeoutMs, this.agentStallRetryLimit);
+        this.agentStallTimeoutMs = normalizeAgentStallTimeoutMs(options.agentStallTimeoutMs, options.requestTimeoutMs);
     }
     async launch(input) {
         if (this.closed)
@@ -2469,12 +2638,11 @@ function normalizeAgentStallRetryLimit(value) {
         return DEFAULT_AGENT_STALL_RETRY_LIMIT;
     return Math.max(0, Math.floor(value));
 }
-function normalizeAgentStallTimeoutMs(configured, requestTimeoutMs, retryLimit) {
+function normalizeAgentStallTimeoutMs(configured, requestTimeoutMs) {
     if (configured !== undefined && Number.isFinite(configured) && configured > 0) {
         return Math.max(1, Math.floor(configured));
     }
-    const retryAwareTimeout = Math.floor(requestTimeoutMs / Math.max(1, retryLimit + 2));
-    return Math.max(1, Math.min(DEFAULT_AGENT_STALL_TIMEOUT_MS, retryAwareTimeout));
+    return Math.max(1, Math.floor(requestTimeoutMs));
 }
 function workflowTaskSnapshot(task) {
     return {

package/docs/provenance-audit.md

@@ -7,7 +7,7 @@ Date: 2026-06-22
 This audit checked:
 
 - tracked repository files;
-- generated npm package contents for `ultracode-for-codex@0.2.2`;
+- generated npm package contents for `ultracode-for-codex@0.2.3`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,7 +23,7 @@ License transition completed:
 
 - Apache-2.0 `LICENSE` file is present;
 - `package.json` and `package-lock.json` declare `Apache-2.0`;
-- package version is prepared as `0.2.2` for the license-bearing patch release.
+- package version is prepared as `0.2.3` for the license-bearing patch release.
 
 ## Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",

package/skills/ultracode-for-codex/SKILL.md

@@ -17,6 +17,12 @@ command process. `settings.json` defaults runs to OS background execution.
 Attached runs stream stderr JSONL for Codex-readable status, while stdout
 remains the final workflow result JSON.
 
+The default Ultracode work shape is phase-wise parallel execution: built-in
+`task` and `code-review` first call a planner agent, then execute each planned
+phase with parallel focused subagents by default, followed by phase and final
+synthesis. A single-agent path is reserved for cases where the planner judges
+parallel execution risky or wasteful.
+
 ## Install And Run
 
 Use the npm package for consumer installs.
@@ -35,7 +41,7 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.2.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-0.2.4.tgz
 ```
 
 CLI behavior:
@@ -49,6 +55,8 @@ CLI behavior:
   with agent identity and label fields on agent records;
 - `Ctrl-C` cancels the active attached workflow;
 - `--retry-limit <n>` retries failed workflows inside the same process;
+- `--timeout-ms` is the workflow timeout and the default per-agent silence
+  budget; it is not divided by the retry budget.
 - `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
 - `--progress plain` switches to human-readable progress lines.
 - background file locations are controlled by `workflow.background` in
@@ -60,8 +68,8 @@ CLI behavior:
 - Keep direct provider credentials out of Codex child process environments.
 - Codex subagents run against the requested workflow cwd and have bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` injects deterministic workspace context and prioritizes
-  files explicitly mentioned in the prompt.
+- Built-in `task` and `code-review` inject deterministic workspace context into
+  planner-selected phase-wise parallel subagents.
 - Keep workflow execution local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.