@wjarka/cezarion 0.14.8 → 0.14.9-dev.842

package/dist/delegation/transport.d.ts

@@ -41,7 +41,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     requestIds?: string[] | undefined;
                     requestOutcomes?: {
                         requestId: string;
-                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                         observedAt: string;
                         replyId?: string | undefined;
                     }[] | undefined;
@@ -89,7 +89,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     requestIds?: string[] | undefined;
                     requestOutcomes?: {
                         requestId: string;
-                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                         observedAt: string;
                         replyId?: string | undefined;
                     }[] | undefined;
@@ -137,11 +137,23 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     state: "accepted" | "continuation-required" | "destroyed" | "late";
                     resumed?: true | undefined;
                     instruction?: string | undefined;
+                    question?: {
+                        questions: {
+                            id?: string | undefined;
+                            header: string;
+                            question: string;
+                            options: {
+                                label: string;
+                                description?: string | undefined;
+                            }[];
+                            multiSelect?: boolean | undefined;
+                        }[];
+                    } | undefined;
                 };
-                delivery: "delivered" | "not-delivered" | "queued";
+                delivery: "consumed" | "delivered" | "not-delivered" | "queued";
                 outcome?: {
                     requestId: string;
-                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                     observedAt: string;
                     replyId?: string | undefined;
                 } | undefined;
@@ -178,11 +190,23 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     state: "accepted" | "continuation-required" | "destroyed" | "late";
                     resumed?: true | undefined;
                     instruction?: string | undefined;
+                    question?: {
+                        questions: {
+                            id?: string | undefined;
+                            header: string;
+                            question: string;
+                            options: {
+                                label: string;
+                                description?: string | undefined;
+                            }[];
+                            multiSelect?: boolean | undefined;
+                        }[];
+                    } | undefined;
                 };
-                delivery: "delivered" | "not-delivered" | "queued";
+                delivery: "consumed" | "delivered" | "not-delivered" | "queued";
                 outcome?: {
                     requestId: string;
-                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                     observedAt: string;
                     replyId?: string | undefined;
                 } | undefined;
@@ -219,11 +243,23 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     state: "accepted" | "continuation-required" | "destroyed" | "late";
                     resumed?: true | undefined;
                     instruction?: string | undefined;
+                    question?: {
+                        questions: {
+                            id?: string | undefined;
+                            header: string;
+                            question: string;
+                            options: {
+                                label: string;
+                                description?: string | undefined;
+                            }[];
+                            multiSelect?: boolean | undefined;
+                        }[];
+                    } | undefined;
                 };
-                delivery: "delivered" | "not-delivered" | "queued";
+                delivery: "consumed" | "delivered" | "not-delivered" | "queued";
                 outcome?: {
                     requestId: string;
-                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                     observedAt: string;
                     replyId?: string | undefined;
                 } | undefined;
@@ -260,13 +296,26 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     state: "accepted" | "continuation-required" | "destroyed" | "late";
                     resumed?: true | undefined;
                     instruction?: string | undefined;
+                    question?: {
+                        questions: {
+                            id?: string | undefined;
+                            header: string;
+                            question: string;
+                            options: {
+                                label: string;
+                                description?: string | undefined;
+                            }[];
+                            multiSelect?: boolean | undefined;
+                        }[];
+                    } | undefined;
                 }[];
                 outcomes: {
                     requestId: string;
-                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                     observedAt: string;
                     replyId?: string | undefined;
                 }[];
+                hint?: string | undefined;
             };
             outputFormat: "json";
             status: 200;
@@ -277,12 +326,90 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             };
         };
     };
+} & {
+    "/inbox": {
+        $post: {
+            output: {
+                messages: {
+                    senderRunId: string;
+                    recipientRunId: string;
+                    kind: "follow-up" | "progress" | "reply" | "request";
+                    requestId?: string | undefined;
+                    id: string;
+                    text: string;
+                    createdAt: string;
+                    deadline?: string | undefined;
+                    requestHash: string;
+                    state: "accepted" | "continuation-required" | "destroyed" | "late";
+                    resumed?: true | undefined;
+                    instruction?: string | undefined;
+                    question?: {
+                        questions: {
+                            id?: string | undefined;
+                            header: string;
+                            question: string;
+                            options: {
+                                label: string;
+                                description?: string | undefined;
+                            }[];
+                            multiSelect?: boolean | undefined;
+                        }[];
+                    } | undefined;
+                }[];
+                outcomes: {
+                    requestId: string;
+                    status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
+                    observedAt: string;
+                    replyId?: string | undefined;
+                }[];
+                receiptId?: string | undefined;
+                expiresAt?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                json: Record<string, never>;
+            };
+        };
+    };
+} & {
+    "/inbox/ack": {
+        $post: {
+            output: {
+                receiptId: string;
+                status: "acknowledged" | "already-acknowledged" | "released";
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                json: {
+                    receiptId: string;
+                };
+            };
+        };
+    };
+} & {
+    "/inbox/release": {
+        $post: {
+            output: {
+                receiptId: string;
+                status: "acknowledged" | "already-acknowledged" | "released";
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                json: {
+                    receiptId: string;
+                };
+            };
+        };
+    };
 } & {
     "/cancel-request": {
         $post: {
             output: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             };
@@ -298,18 +425,6 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
 } & {
     "/:workerId": {
         $get: {
-            output: {
-                error: string;
-                code?: "invalid_input" | undefined;
-            };
-            outputFormat: "json";
-            status: 400;
-            input: {
-                param: {
-                    workerId: string;
-                };
-            };
-        } | {
             output: {
                 workerId: string;
                 parentRunId: string;
@@ -344,7 +459,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     requestIds?: string[] | undefined;
                     requestOutcomes?: {
                         requestId: string;
-                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                        status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                         observedAt: string;
                         replyId?: string | undefined;
                     }[] | undefined;
@@ -386,11 +501,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     workerId: string;
                 };
             };
-        };
-    };
-} & {
-    "/:workerId/collect": {
-        $post: {
+        } | {
             output: {
                 error: string;
                 code?: "invalid_input" | undefined;
@@ -401,10 +512,12 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                 param: {
                     workerId: string;
                 };
-            } & {
-                json: Record<string, never>;
             };
-        } | {
+        };
+    };
+} & {
+    "/:workerId/collect": {
+        $post: {
             output: {
                 workerId: string;
                 parentRunId: string;
@@ -506,11 +619,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             } & {
                 json: Record<string, never>;
             };
-        };
-    };
-} & {
-    "/:workerId/steer": {
-        $post: {
+        } | {
             output: {
                 error: string;
                 code?: "invalid_input" | undefined;
@@ -522,11 +631,13 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     workerId: string;
                 };
             } & {
-                json: {
-                    text: string;
-                };
+                json: Record<string, never>;
             };
-        } | {
+        };
+    };
+} & {
+    "/:workerId/steer": {
+        $post: {
             output: {
                 workerId: string;
                 state: "delivered" | "queued";
@@ -542,11 +653,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     text: string;
                 };
             };
-        };
-    };
-} & {
-    "/:workerId/stop": {
-        $post: {
+        } | {
             output: {
                 error: string;
                 code?: "invalid_input" | undefined;
@@ -558,9 +665,15 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
                     workerId: string;
                 };
             } & {
-                json: Record<string, never>;
+                json: {
+                    text: string;
+                };
             };
-        } | {
+        };
+    };
+} & {
+    "/:workerId/stop": {
+        $post: {
             output: {
                 workerId: string;
                 state: "stopping" | "terminated";
@@ -574,11 +687,7 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             } & {
                 json: Record<string, never>;
             };
-        };
-    };
-} & {
-    "/:workerId/destroy": {
-        $post: {
+        } | {
             output: {
                 error: string;
                 code?: "invalid_input" | undefined;
@@ -592,7 +701,11 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             } & {
                 json: Record<string, never>;
             };
-        } | {
+        };
+    };
+} & {
+    "/:workerId/destroy": {
+        $post: {
             output: {
                 workerId: string;
                 state: "complete" | "incomplete";
@@ -615,6 +728,20 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             } & {
                 json: Record<string, never>;
             };
+        } | {
+            output: {
+                error: string;
+                code?: "invalid_input" | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                param: {
+                    workerId: string;
+                };
+            } & {
+                json: Record<string, never>;
+            };
         } | {
             output: {
                 workerId: string;
@@ -644,11 +771,13 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
     "/:workerId/diff": {
         $get: {
             output: {
-                error: string;
-                code?: "invalid_input" | undefined;
+                workerId: string;
+                baselineSha: string;
+                diff: string;
+                truncated: boolean;
             };
             outputFormat: "json";
-            status: 400;
+            status: 200;
             input: {
                 param: {
                     workerId: string;
@@ -656,13 +785,11 @@ export declare function createDelegationApp(routes: DelegationRoutes): import("h
             };
         } | {
             output: {
-                workerId: string;
-                baselineSha: string;
-                diff: string;
-                truncated: boolean;
+                error: string;
+                code?: "invalid_input" | undefined;
             };
             outputFormat: "json";
-            status: 200;
+            status: 400;
             input: {
                 param: {
                     workerId: string;

package/dist/index.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { DelegationController } from './delegation/provision.js';
 import { parseArgs } from 'node:util';
-import { spawn, execFileSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { createServer } from 'node:net';
+import { once } from 'node:events';
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -27,6 +28,12 @@ import { runMigrations } from './workspace/migrations.js';
 import { registerProject, shouldRegisterProject } from './workspace/projects.js';
 import { runProjectsCommand } from './workspace/projects-cli.js';
 import { WorkspaceSemaphore } from './workspace/semaphore.js';
+import { ApplicationUpdateService } from './application-update/service.js';
+import { armRestartHelper } from './application-update/launcher.js';
+import { restartEndpoint } from './application-update/helper.js';
+import { readNpmConfiguration } from './application-update/npm-process.js';
+import { cezarHomeDir } from './paths.js';
+import { openUrl } from './open-url.js';
 const HELP = `cezar — local cockpit for AI agent tasks in your repo
 
 Usage:
@@ -34,8 +41,11 @@ Usage:
   cez run "<task>"          run a task headless in the terminal
   cez init                  scaffold .ai/cezar/ (example workflow + skill)
   cez projects              list the projects this cockpit serves
-                            (also: projects add [<dir>] · projects remove <id>)
+                            (also: projects add [<dir>] · projects remove|rm <id> ·
+                             projects tag <id> [<tag>…])
   cez worker                manage owned workers (see: worker --help)
+  cez task                  start/watch/steer cockpit tasks from the terminal (see: task --help)
+  cez artifact publish <path> publish a local task artifact (see: artifact --help)
   cez server-install        interactive wizard to host cezar on a server
   cez server-deploy         redeploy a new version (reload the service) + verify
   cez server-uninstall      reverse a server-install
@@ -69,6 +79,17 @@ Skills live in .ai/skills/, .ai/cezar/skills/ and your team skills repo
 (default open-mercato/skills; override via .ai/cezar/config.json);
 workflows in .ai/cezar/workflows/.`;
 async function main() {
+    if (process.argv[2] === 'artifact') {
+        const { runArtifactCommand } = await import('./artifacts/cli.js');
+        process.exitCode = await runArtifactCommand(process.argv.slice(3), process.env);
+        return;
+    }
+    if (process.argv[2] === 'task') {
+        // Before the global parseArgs, like `worker`: task flags are not cockpit flags (#504).
+        const { runTaskCommand } = await import('./task-cli/cli.js');
+        process.exitCode = await runTaskCommand(process.argv.slice(3), process.env);
+        return;
+    }
     if (process.argv[2] === 'worker') {
         const { runWorkerCommand } = await import('./delegation/cli.js');
         process.exitCode = await runWorkerCommand(process.argv.slice(3), process.env);
@@ -89,6 +110,7 @@ async function main() {
             reconfigure: { type: 'string' },
             reinstall: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h', default: false },
+            'restart-exact': { type: 'boolean', default: false },
         },
         allowPositionals: true,
     });
@@ -109,7 +131,7 @@ async function main() {
     const repoRoot = repoInfo?.root ?? cwd;
     switch (command) {
         case 'serve':
-            await serveCommand(repoRoot, Number(values.port), !values['no-open'], values['bind-host']);
+            await serveCommand(repoRoot, Number(values.port), !values['no-open'], values['bind-host'], Boolean(values['restart-exact']));
             return;
         case 'run':
             await runCommand(repoRoot, positionals.slice(1).join(' ').trim(), values.workflow, values.model);
@@ -187,7 +209,7 @@ async function initWorkspace(repoRoot) {
     return undefined;
 }
 // ---- serve -----------------------------------------------------------------
-async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost) {
+async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost, restartExact = false) {
     const bootProjectId = await initWorkspace(repoRoot);
     // ONE workspace semaphore for the whole process (spec 2026-07-20, step 2.5):
     // the boot manager and every lazily-built project context count their runs
@@ -240,7 +262,7 @@ async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost) {
         update.latest = latest;
         console.log(`\n  ⬆ cezar ${latest} is available (running ${version}) — restart with: npx ${pkgName}@latest\n`);
     });
-    const port = await pickPort(preferredPort);
+    const port = restartExact ? preferredPort : await pickPort(preferredPort);
     // SECURITY: cezar executes agents. A non-loopback bind exposes that box to
     // whatever can reach the interface, and cezar itself has NO auth — it is only
     // for a deliberate hosted setup where a reverse proxy in front provides TLS +
@@ -250,13 +272,29 @@ async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost) {
             `    Only do this behind a reverse proxy that enforces authentication,\n` +
             `    and make sure this interface is not reachable from the internet.\n`);
     }
-    const server = startServer({
+    // Discovery reads npm metadata only; a missing npm or source checkout degrades to manual update.
+    const npm = readNpmConfiguration();
+    const npmPrefix = npm?.prefix;
+    const npmCache = npm?.cache;
+    let server;
+    const applicationUpdate = (npmPrefix && npmCache) || process.env.CEZ_DRY_RUN === '1'
+        ? new ApplicationUpdateService({
+            packageRoot: join(dirname(fileURLToPath(import.meta.url)), '..'),
+            launchEntry: resolve(process.argv[1] ?? ''),
+            npmPrefix: npmPrefix ?? join(cezarHomeDir(), 'dry-prefix'),
+            npmCache: npmCache ?? join(cezarHomeDir(), 'dry-cache'), npmBin: npm?.npmBin, home: cezarHomeDir(), targetVersion: () => update.latest,
+            dryRun: process.env.CEZ_DRY_RUN === '1',
+            armRestart: (plan) => armRestartHelper(plan, { repoRoot, ...restartEndpoint(server.address()), npmBin: npm?.npmBin ?? 'npm' }),
+            handoff: () => { void server.shutdownForRestart().then(() => process.exit(0)); },
+        }) : undefined;
+    server = startServer({
         delegation,
         repoRoot,
         store,
         manager,
         version,
         update,
+        applicationUpdate,
         bootProjectId,
         semaphore,
         bindHost,
@@ -264,7 +302,17 @@ async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost) {
         providerRuntimeAuth,
         workspaceEvents,
     }, port);
-    const url = `http://localhost:${port}`;
+    if (!server.listening)
+        await once(server, 'listening');
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('cockpit TCP listener is unavailable');
+    const boundPort = address.port;
+    const boundHost = address.address;
+    if (restartExact && process.send) {
+        process.send({ type: 'application-update-listening', host: boundHost, port: boundPort, repoRoot, version }, () => process.disconnect?.());
+    }
+    const url = `http://${boundHost.includes(':') ? `[${boundHost}]` : boundHost}:${boundPort}`;
     console.log(`\n  cezar v${version} — ${repoRoot}`);
     console.log(`  ${repo ? `branch ${repo.branch}` : 'not a git repository (tasks run in place, one at a time; repo view is empty)'}`);
     for (const check of checks) {
@@ -272,8 +320,8 @@ async function serveCommand(repoRoot, preferredPort, openBrowser, bindHost) {
         const detail = check.available ? (check.version ?? 'ok') : (check.hint ?? 'missing');
         console.log(`  ${mark} ${check.name.padEnd(6)} ${detail}`);
     }
-    if (port !== preferredPort)
-        console.log(`  (port ${preferredPort} was busy — using ${port})`);
+    if (preferredPort !== 0 && boundPort !== preferredPort)
+        console.log(`  (port ${preferredPort} was busy — using ${boundPort})`);
     console.log(`\n  cockpit → ${url}\n`);
     // Silenced by CEZ_NO_BANNER=1 or by dismissing the cockpit's banner (#391).
     await printSkillsBanner(repoRoot);
@@ -326,12 +374,27 @@ async function waitForHealth(healthUrl, timeoutMs) {
     return false;
 }
 // ---- run (headless) ----------------------------------------------------------
+/**
+ * Headless `run` stays headless (#504), but a cockpit already serving this repo will never see
+ * the run until it restarts — say so once, on stderr. Capped so it never delays the run, and
+ * silent on any failure.
+ */
+async function hintRunningCockpit(repoRoot) {
+    const { discoverCockpit } = await import('./task-cli/discovery.js');
+    const found = await Promise.race([
+        discoverCockpit({ repoDir: repoRoot, timeoutMs: 300 }).catch(() => undefined),
+        new Promise((done) => setTimeout(() => done(undefined), 600).unref()),
+    ]);
+    if (found)
+        console.error(`a cockpit is running at ${found.origin}; use "cez task start" to run this task there instead`);
+}
 async function runCommand(repoRoot, task, workflowName, model) {
     if (!task) {
         console.error('usage: cez run "<task>" [--workflow name] [--model model]');
         process.exitCode = 1;
         return;
     }
+    await hintRunningCockpit(repoRoot);
     await initWorkspace(repoRoot);
     const { workflows, issues } = await loadWorkflows(repoRoot);
     for (const issue of issues)
@@ -671,23 +734,6 @@ function readOwnVersion() {
         return '0.0.0';
     }
 }
-function openUrl(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    try {
-        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
-        // A missing opener (e.g. no `xdg-open` on a headless Linux VPS) surfaces
-        // asynchronously as an 'error' event, NOT a synchronous throw — without a
-        // listener Node promotes it to an unhandled error and hard-crashes the whole
-        // process, even though the cockpit is already serving. Swallow it: the URL is
-        // printed above, so a browser-less host just doesn't auto-open.
-        child.on('error', () => { });
-        child.unref();
-    }
-    catch {
-        // the printed URL is enough
-    }
-}
 function previewJson(input) {
     try {
         const s = JSON.stringify(input);