ultracode-for-codex 0.3.2 → 0.3.4

package/dist/cli.js

@@ -10,10 +10,12 @@ import { CodexSubagentBackend } from './codex/subagent-backend.js';
 import { WorkflowTaskRegistry } from './runtime/workflow-runtime.js';
 import { UltracodeRequestError } from './runtime/types.js';
 import { ultracodePackageVersion } from './runtime/package-info.js';
+import { defaultUltracodeStateRoot, resolveUltracodeStatePath } from './runtime/state-root.js';
 import { renderUltracodeInstallGuideNotice } from './ultracode-install-guide.js';
 import { codexDefaultReasoningEffort, codexDefaultVerbosity, isReasoningEffort, isVerbosity, isWorkflowExecutionMode, isWorkflowPermissionPolicy, isWorkflowProgressMode, workflowBackgroundDefaults, workflowDefaultExecutionMode, workflowDefaultPermissionPolicy, workflowDefaultProgressMode, workflowDefaultRetryLimit, workflowDefaultTimeoutMs, } from './settings.js';
 const ULTRACODE_INSTALL_GUIDE_ACCEPT_VERSION = 'v1';
 const PROGRESS_KIND = 'ultracode.workflow.progress';
+const WORKFLOW_RUN_ID_RE = /^run_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 async function main(argv) {
     const [command = 'help', ...args] = argv;
     if (command === 'help' || command === '--help' || command === '-h') {
@@ -56,13 +58,18 @@ async function runWorkflow(args) {
     }
     const cwd = options.cwd ?? process.cwd();
     const executionMode = parseExecutionMode(options.execution);
-    if (executionMode === 'background')
+    const inputPromise = workflowLaunchInputFromOptions(options);
+    if (executionMode === 'background') {
+        const input = await inputPromise;
+        if (input.resumeFromRunId)
+            await assertBackgroundResumeSource(cwd, input.resumeFromRunId);
         return launchBackgroundWorkflow(args, cwd);
+    }
     const timeoutMs = parseIntOption(options.timeoutMs, workflowDefaultTimeoutMs());
     const retryLimit = parseRetryLimit(options.retryLimit);
     const permissionPolicy = parsePermissionPolicy(options.permission);
     const progressMode = parseProgressMode(options.progress);
-    const input = await workflowLaunchInputFromOptions(options);
+    const input = await inputPromise;
     const backend = new CodexSubagentBackend({
         command: options.command,
         cwd,
@@ -107,6 +114,27 @@ async function runWorkflow(args) {
         await runtime.close();
     }
 }
+async function assertBackgroundResumeSource(cwd, runId) {
+    const runtime = new WorkflowTaskRegistry({
+        backend: RESUME_PREFLIGHT_BACKEND,
+        cwd,
+        requestTimeoutMs: 0,
+    });
+    try {
+        await runtime.validateResumeSource(runId);
+    }
+    finally {
+        await runtime.close();
+    }
+}
+const RESUME_PREFLIGHT_BACKEND = {
+    name: 'resume-preflight',
+    model: 'resume-preflight',
+    async generate() {
+        throw new Error('Resume preflight must not run subagents.');
+    },
+    async close() { },
+};
 export function parseOptions(args) {
     const out = { _: [] };
     for (let i = 0; i < args.length; i += 1) {
@@ -619,10 +647,9 @@ function backgroundProcessIdentityMatches(metadata, commandLine) {
 async function backgroundArchivePath(options, jobId) {
     if (options.outputPath)
         return resolve(options.outputPath);
-    const cwd = options.cwd ?? process.cwd();
     const archiveDir = options.outDir
         ? resolve(options.outDir)
-        : resolve(cwd, '.ultracode-for-codex', 'archive');
+        : join(defaultUltracodeStateRoot(), 'archive');
     return join(archiveDir, `${jobId}.json`);
 }
 async function readBackgroundProgress(progressPath) {
@@ -813,6 +840,9 @@ function delay(ms) {
 }
 function resolveBackgroundRunDir(cwd, template, jobId) {
     const expanded = template.replaceAll('{jobId}', jobId);
+    if (expanded.includes('{stateRoot}') || expanded === '~' || expanded.startsWith('~/')) {
+        return resolveUltracodeStatePath(expanded);
+    }
     return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
 }
 function assertDistinctBackgroundPaths(paths) {
@@ -832,9 +862,7 @@ async function workflowLaunchInputFromOptions(options) {
     if (options._.length > 1)
         throw new Error('run accepts at most one positional workflow script file.');
     const scriptFile = options.scriptFile ?? positionalScriptFile;
-    if (options.resumeFromRunId) {
-        throw new Error('CLI resume is not available yet; use --retry-limit for same-run retry or rerun the workflow command.');
-    }
+    const hasResumeFromRunId = options.resumeFromRunId !== undefined;
     const sourceSelectors = [
         options.script !== undefined ? '--script' : '',
         scriptFile ? '--script-file' : '',
@@ -844,17 +872,33 @@ async function workflowLaunchInputFromOptions(options) {
     if (sourceSelectors.length > 1) {
         throw new Error(`Choose only one workflow source selector: ${sourceSelectors.join(', ')}.`);
     }
-    if (sourceSelectors.length === 0) {
-        throw new Error('run requires --script, --script-file, --script-path, --name, or a positional script file.');
+    if (hasResumeFromRunId)
+        validateCliResumeFromRunId(options.resumeFromRunId);
+    if (hasResumeFromRunId && sourceSelectors.length > 0) {
+        throw new Error('--resume-from-run-id cannot be combined with --script, --script-file, --script-path, --name, or a positional script file.');
+    }
+    if (sourceSelectors.length === 0 && !hasResumeFromRunId) {
+        throw new Error('run requires --script, --script-file, --script-path, --name, --resume-from-run-id, or a positional script file.');
     }
+    const parsedArgs = await parseArgsPayload(options);
+    const shouldIncludeArgs = options.args !== undefined || options.argsFile !== undefined || !hasResumeFromRunId;
     return {
         ...(options.script !== undefined ? { script: options.script } : {}),
         ...(scriptFile ? { script: await readFile(scriptFile, 'utf8') } : {}),
         ...(options.scriptPath ? { scriptPath: options.scriptPath } : {}),
         ...(options.name ? { name: options.name } : {}),
-        args: await parseArgsPayload(options),
+        ...(hasResumeFromRunId ? { resumeFromRunId: options.resumeFromRunId } : {}),
+        ...(shouldIncludeArgs ? { args: parsedArgs } : {}),
     };
 }
+function validateCliResumeFromRunId(value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error('resumeFromRunId must be a non-empty workflow runId string.');
+    }
+    if (!WORKFLOW_RUN_ID_RE.test(value.trim())) {
+        throw new Error('resumeFromRunId must be a workflow runId in run_<uuid> format.');
+    }
+}
 async function parseArgsPayload(options) {
     if (options.args !== undefined && options.argsFile) {
         throw new Error('Use either --args or --args-file, not both.');
@@ -1116,31 +1160,27 @@ function workflowPhaseExecutionSummary(events) {
     for (const event of events) {
         if (event.type !== 'workflow.agent.started' || !event.phase)
             continue;
+        const startedAgent = {
+            title: event.label,
+            label: event.label,
+            angle: event.promptPreview,
+        };
         const existing = phases.get(event.phase);
         if (!existing) {
             phases.set(event.phase, {
                 title: event.phase,
                 agentCount: 1,
-                agents: [{
-                        title: event.label,
-                        label: event.label,
-                        angle: event.promptPreview,
-                    }],
+                agents: [startedAgent],
             });
             continue;
         }
-        if (phaseTitlesWithPlannedAgents.has(event.phase))
+        if (phaseTitlesWithPlannedAgents.has(event.phase)
+            && existing.agents.length > 0
+            && !phaseSummaryAllowsDynamicStartedAgents(existing))
             continue;
         if (existing.agents.some((agent) => agent.label === event.label || agent.title === event.label))
             continue;
-        const agents = [
-            ...existing.agents,
-            {
-                title: event.label,
-                label: event.label,
-                angle: event.promptPreview,
-            },
-        ];
+        const agents = [...existing.agents, startedAgent];
         phases.set(event.phase, {
             ...existing,
             agentCount: agents.length,
@@ -1149,6 +1189,14 @@ function workflowPhaseExecutionSummary(events) {
     }
     return [...phases.values()];
 }
+function phaseSummaryAllowsDynamicStartedAgents(phase) {
+    return phase.agents.some((agent) => {
+        const label = agent.label ?? '';
+        const title = agent.title ?? '';
+        const angle = agent.angle ?? '';
+        return /\bdynamic\b/i.test(`${label} ${title} ${angle}`);
+    });
+}
 function criticalReviewRecommendation() {
     return 'Session LLM should critically re-check the final result before acting: verify whether the conclusion is justified, internally consistent, supported by the observed workflow evidence, and missing material counterarguments.';
 }
@@ -1422,7 +1470,8 @@ Options:
   --script-file <path>               Workflow script file. A positional file path is also accepted.
   --script-path <path>               Runtime-owned persisted workflow script path.
   --name <name>                      Named workflow from .codex/workflows or built-ins.
-  --args <json>                      Workflow args JSON. Default: {}.
+  --resume-from-run-id <runId>        Resume a completed local workflow run from preserved runtime state.
+  --args <json>                      Workflow args JSON. Default: {}; resume runs inherit prior args when omitted.
   --args-file <path>                 Read workflow args JSON from a file.
   --permission <ask|allow|deny>      Permission review behavior. Default: settings.json (${workflowDefaultPermissionPolicy()}).
   --retry-limit <number>             Retry failed workflows in the same process. Default: settings.json (${workflowDefaultRetryLimit()}).

package/dist/runtime/state-root.d.ts

@@ -0,0 +1,3 @@
+export declare function defaultUltracodeStateRoot(): string;
+export declare function defaultWorkflowStateDir(cwd?: string): string;
+export declare function resolveUltracodeStatePath(value: string): string;

package/dist/runtime/state-root.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+const ULTRACODE_HOME_ENV = 'ULTRACODE_FOR_CODEX_HOME';
+export function defaultUltracodeStateRoot() {
+    const configured = process.env[ULTRACODE_HOME_ENV]?.trim();
+    if (configured)
+        return resolveHomePath(configured);
+    return join(homedir(), '.ultracode-for-codex');
+}
+export function defaultWorkflowStateDir(cwd = process.cwd()) {
+    const root = resolve(cwd);
+    const digest = createHash('sha256').update(root).digest('hex').slice(0, 16);
+    const label = safeWorkspaceLabel(basename(root) || 'workspace');
+    return join(defaultUltracodeStateRoot(), 'workspaces', `${label}-${digest}`);
+}
+export function resolveUltracodeStatePath(value) {
+    return resolveHomePath(value.replaceAll('{stateRoot}', defaultUltracodeStateRoot()));
+}
+function resolveHomePath(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/'))
+        return join(homedir(), value.slice(2));
+    return resolve(value);
+}
+function safeWorkspaceLabel(value) {
+    return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'workspace';
+}

package/dist/runtime/workflow-journal.d.ts

@@ -12,6 +12,7 @@ export interface WorkflowAgentSemanticOpts {
     readonly effort?: string;
     readonly isolation?: string;
     readonly agentType?: string;
+    readonly logicalKey?: string;
 }
 export type WorkflowJournalEntry = WorkflowRunStartedEntry | WorkflowAgentStartedEntry | WorkflowAgentCompletedEntry | WorkflowAgentFailedEntry | WorkflowRunCompletedEntry | WorkflowRunFailedEntry;
 interface WorkflowJournalEntryEnvelope {

package/dist/runtime/workflow-journal.js

@@ -219,6 +219,9 @@ export function computeWorkflowAgentCallKey(input) {
     if (!HASH_RE.test(input.previousAgentCallKey)) {
         throw new WorkflowJournalValidationError('previousAgentCallKey must be a 64-character sha256 hex digest.');
     }
+    if (input.semanticOpts.logicalKey) {
+        return sha256(`logical\0${input.semanticOpts.logicalKey}\0${input.prompt}\0${stableJson(input.semanticOpts)}`);
+    }
     return sha256(`${input.previousAgentCallKey}\0${input.prompt}\0${stableJson(input.semanticOpts)}`);
 }
 export function workflowJournalHash(entryWithoutEntryHash) {
@@ -473,10 +476,10 @@ function assertWorkflowAgentSemanticOpts(value) {
     const opts = asRecord(value);
     if (!opts)
         throw new WorkflowJournalValidationError('semanticOpts must be an object.');
-    rejectUnknownKeys(opts, ['schema', 'model', 'effort', 'isolation', 'agentType'], 'semanticOpts');
+    rejectUnknownKeys(opts, ['schema', 'model', 'effort', 'isolation', 'agentType', 'logicalKey'], 'semanticOpts');
     if (typeof opts.model !== 'string' || !opts.model)
         throw new WorkflowJournalValidationError('semanticOpts.model must be a string.');
-    for (const key of ['effort', 'isolation', 'agentType']) {
+    for (const key of ['effort', 'isolation', 'agentType', 'logicalKey']) {
         if (opts[key] !== undefined && typeof opts[key] !== 'string') {
             throw new WorkflowJournalValidationError(`semanticOpts.${key} must be a string.`);
         }

package/dist/runtime/workflow-runtime.d.ts

@@ -241,9 +241,12 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private readonly agentStallRetryLimit;
     constructor(options: WorkflowTaskRegistryOptions);
     launch(input: WorkflowLaunchInput): Promise<WorkflowLaunchResult>;
+    validateResumeSource(resumeFromRunId: string): Promise<void>;
     private prepareResumePlan;
     private workflowTaskByRunId;
+    private durableWorkflowResumeSource;
     private createResumeCache;
+    private readCompletedResumeJournal;
     private resolveLaunchInput;
     private workflowPermissionRequired;
     private resolveTrustedScriptPathMetadata;