@wjarka/cezarion 0.14.8 → 0.14.9-dev.1009

package/dist/task-cli/discovery.js

@@ -0,0 +1,96 @@
+import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { healthResponseSchema, projectsResponseSchema } from '../contract/index.js';
+import { fetchJson, TaskCliError } from './http.js';
+/**
+ * Which cockpit serves this checkout (#504, spec 2026-09-24-cez-task-cli). Zero config: probe the
+ * range `pickPort` can land on and match the registry's project roots against this repo. Never
+ * starts a server and never writes anything — a missing cockpit is an answer, not a fallback.
+ */
+/** The ports `cez` can bind: 4321 plus the 49 `pickPort` tries after it. */
+export const COCKPIT_PORTS = Array.from({ length: 50 }, (_, index) => 4321 + index);
+const PROBE_TIMEOUT_MS = 1_500;
+function git(cwd, args) {
+    return new Promise((done) => {
+        execFile('git', ['-C', cwd, ...args], { timeout: 5_000 }, (error, stdout) => done(error ? undefined : stdout.trim()));
+    });
+}
+async function realpathOr(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/**
+ * The main checkout that owns `dir`. A task worktree's common git dir is the parent repo's
+ * `.git`, so this is what maps `.ai/cezar/worktrees/<id>` back to the project that ran it.
+ * Submodules instead keep their git dir under `.git/modules/` and record `core.worktree`.
+ */
+export async function checkoutRoot(dir) {
+    const common = await git(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (common && basename(common) === '.git')
+        return realpathOr(dirname(common));
+    if (common) {
+        // Read the main worktree's config, not a linked worktree override. Git resolves a relative
+        // core.worktree against this shared git dir, even when the caller is in a task worktree.
+        const main = await git(dir, ['--git-dir', common, 'config', '--path', '--get', 'core.worktree']);
+        if (main)
+            return realpathOr(resolve(common, main));
+    }
+    const top = await git(dir, ['rev-parse', '--show-toplevel']);
+    return realpathOr(top ?? dir);
+}
+/** Health first (cheap, and it proves this is a cezar), then the registry with its roots. */
+async function probe(origin, timeoutMs) {
+    try {
+        const health = await fetchJson(`${origin}/api/v1/health`, { timeoutMs });
+        if (health.status !== 200 || !healthResponseSchema.safeParse(health.data).success)
+            return undefined;
+        const registry = await fetchJson(`${origin}/api/v1/projects`, { timeoutMs });
+        const parsed = projectsResponseSchema.safeParse(registry.data);
+        if (registry.status !== 200 || !parsed.success)
+            return undefined;
+        const projects = await Promise.all(parsed.data.projects.map(async (entry) => ({ id: entry.id, root: await realpathOr(entry.root), hasWebhook: entry.webhook !== undefined })));
+        return { origin, projects, bootProject: parsed.data.bootProject };
+    }
+    catch {
+        return undefined;
+    }
+}
+function cockpitFor(origin, projectId, hasWebhook) {
+    return { origin, projectId, api: `${origin}/api/v1/p/${encodeURIComponent(projectId)}`, hasWebhook };
+}
+export async function discoverCockpit(options) {
+    const root = await checkoutRoot(options.repoDir);
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    const hint = `start the cockpit in ${root} with: cez`;
+    if (options.url) {
+        let origin;
+        try {
+            origin = new URL(options.url).origin;
+        }
+        catch {
+            throw new TaskCliError(64, { code: 'invalid_input', error: `invalid cockpit url: ${options.url}` });
+        }
+        const found = await probe(origin, Math.max(timeoutMs, 5_000));
+        if (!found)
+            throw new TaskCliError(2, { code: 'no-cockpit', error: `no cezar cockpit answered at ${origin}`, hint });
+        // A remote cockpit's roots are its own paths, so no match is the ordinary case there.
+        const match = found.projects.find((entry) => entry.root === root);
+        const id = match?.id ?? found.bootProject;
+        return cockpitFor(origin, id, found.projects.some((entry) => entry.id === id && entry.hasWebhook));
+    }
+    const ports = options.ports ?? COCKPIT_PORTS;
+    const candidates = await Promise.all(ports.map((port) => probe(`http://127.0.0.1:${port}`, timeoutMs)));
+    // `ports` is ascending, so the first match is the lowest port serving this checkout.
+    for (const candidate of candidates) {
+        const match = candidate?.projects.find((entry) => entry.root === root);
+        if (candidate && match)
+            return cockpitFor(candidate.origin, match.id, match.hasWebhook);
+    }
+    throw new TaskCliError(2, { code: 'no-cockpit', error: `no running cockpit serves ${root}`, hint });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/task-cli/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/task-cli/discovery.ts"],"names":[],"mappings":"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"}

package/dist/task-cli/http.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The loopback HTTP half of `cez task` (#504, spec 2026-09-24-cez-task-cli): plain `fetch`
+ * against the cockpit's own `/api/v1/p/:projectId` routes, with request deadlines.
+ *
+ * No credential is read, sent or printed: the cockpit's origin guard (#426) admits a loopback
+ * `Host` with no `Origin`, which is exactly what `fetch` sends.
+ */
+export declare const REQUEST_TIMEOUT_MS = 45000;
+/** Every failure carries its exit code and the JSON body the CLI prints. */
+export declare class TaskCliError extends Error {
+    readonly exitCode: number;
+    readonly body: Record<string, unknown>;
+    constructor(exitCode: number, body: Record<string, unknown>);
+}
+export interface Cockpit {
+    /** `http://127.0.0.1:<port>` — no trailing slash. */
+    origin: string;
+    projectId: string;
+    /** `${origin}/api/v1/p/${projectId}` */
+    api: string;
+    /** The project has a task webhook (#589), read from the registry discovery already fetched.
+     *  Absent = unknown, which `start` treats as "do not opt in". */
+    hasWebhook?: boolean;
+}
+export declare function threadUrl(cockpit: Cockpit, runId: string): string;
+export interface HttpResult {
+    status: number;
+    data: unknown;
+}
+/** One request to an absolute URL. JSON bodies are parsed; anything else comes back as text. */
+export declare function fetchJson(url: string, init?: {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+    responseLimitBytes?: number;
+}): Promise<HttpResult>;
+/** A project-scoped route: `path` starts with `/`, relative to `/api/v1/p/:projectId`. */
+export declare function request(cockpit: Cockpit, path: string, init?: {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+}): Promise<HttpResult>;
+/** The cockpit said no: pass its `{ error }` through verbatim, exit 2. */
+export declare function refuse(result: HttpResult): never;
+/** A response the contract does not describe is a cockpit problem, not a caller problem. */
+export declare function invalidResponse(what: string): never;

package/dist/task-cli/http.js

@@ -0,0 +1,101 @@
+/**
+ * The loopback HTTP half of `cez task` (#504, spec 2026-09-24-cez-task-cli): plain `fetch`
+ * against the cockpit's own `/api/v1/p/:projectId` routes, with request deadlines.
+ *
+ * No credential is read, sent or printed: the cockpit's origin guard (#426) admits a loopback
+ * `Host` with no `Origin`, which is exactly what `fetch` sends.
+ */
+const RESPONSE_BYTES = 3_145_728;
+export const REQUEST_TIMEOUT_MS = 45_000;
+/** Every failure carries its exit code and the JSON body the CLI prints. */
+export class TaskCliError extends Error {
+    exitCode;
+    body;
+    constructor(exitCode, body) {
+        super(typeof body.error === 'string' ? body.error : 'cez task failed');
+        this.exitCode = exitCode;
+        this.body = body;
+    }
+}
+export function threadUrl(cockpit, runId) {
+    return `${cockpit.origin}/p/${encodeURIComponent(cockpit.projectId)}/tasks/${encodeURIComponent(runId)}`;
+}
+/** Enforce a byte limit where the route has a bounded response, including error bodies. */
+async function boundedText(response, limit) {
+    if (Number(response.headers.get('content-length')) > limit) {
+        await response.body?.cancel();
+        throw new Error('Response too large');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return '';
+    let size = 0;
+    const chunks = [];
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.length;
+            if (size > limit) {
+                await reader.cancel();
+                throw new Error('Response too large');
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+/** One request to an absolute URL. JSON bodies are parsed; anything else comes back as text. */
+export async function fetchJson(url, init = {}) {
+    let response;
+    let text;
+    try {
+        response = await fetch(url, {
+            method: init.method ?? (init.body === undefined ? 'GET' : 'POST'),
+            redirect: 'error',
+            headers: init.body === undefined ? {} : { 'content-type': 'application/json' },
+            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            signal: AbortSignal.timeout(init.timeoutMs ?? REQUEST_TIMEOUT_MS),
+        });
+        text = await boundedText(response, response.ok ? (init.responseLimitBytes ?? RESPONSE_BYTES) : RESPONSE_BYTES);
+    }
+    catch (error) {
+        throw new TaskCliError(2, { code: 'unavailable', error: `cockpit request failed: ${error instanceof Error ? error.message : String(error)}` });
+    }
+    const json = (response.headers.get('content-type') ?? '').includes('application/json');
+    if (!json)
+        return { status: response.status, data: text };
+    try {
+        return { status: response.status, data: JSON.parse(text) };
+    }
+    catch {
+        throw new TaskCliError(2, { code: 'unavailable', error: 'cockpit returned invalid JSON' });
+    }
+}
+/** A project-scoped route: `path` starts with `/`, relative to `/api/v1/p/:projectId`. */
+export function request(cockpit, path, init = {}) {
+    // GET /runs is the existing unpaginated full history. Even 32 valid 100k-character tasks
+    // exceed the ordinary cap. Match the cockpit's full-list read rather than making list/wait
+    // fail as history grows; retain deadlines, error-body caps and every other route's cap.
+    const fullRunList = path === '/runs' && (init.method ?? (init.body === undefined ? 'GET' : 'POST')) === 'GET';
+    return fetchJson(`${cockpit.api}${path}`, {
+        ...init,
+        ...(fullRunList ? { responseLimitBytes: Infinity } : {}),
+    });
+}
+/** The cockpit said no: pass its `{ error }` through verbatim, exit 2. */
+export function refuse(result) {
+    const error = result.data && typeof result.data === 'object' && typeof result.data.error === 'string'
+        ? result.data.error
+        : `cockpit answered HTTP ${result.status}`;
+    throw new TaskCliError(2, { code: 'refused', status: result.status, error });
+}
+/** A response the contract does not describe is a cockpit problem, not a caller problem. */
+export function invalidResponse(what) {
+    throw new TaskCliError(2, { code: 'unavailable', error: `cockpit returned an unexpected ${what} response` });
+}
+//# sourceMappingURL=http.js.map

package/dist/task-cli/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/task-cli/http.ts"],"names":[],"mappings":"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"}

package/dist/task-cli/projections.d.ts

@@ -0,0 +1,40 @@
+import type { ApiRun, RunStatus } from '../contract/index.js';
+/**
+ * The slim shapes `cez task` prints (#504). A bot polls these every few seconds, so each one
+ * carries what a caller branches on and nothing it would have to pay tokens to skip: no
+ * `steps[]`, no `workflowDef`, no reference candidates. `--full` is the escape hatch.
+ */
+export declare const TERMINAL_STATUSES: readonly RunStatus[];
+export declare const SUCCESS_STATUSES: readonly RunStatus[];
+export declare function runTitle(run: Pick<ApiRun, 'title' | 'titleSummary'>): string;
+export declare function projectStatus(run: ApiRun, url: string, question?: unknown): Partial<{
+    id: string;
+    title: string;
+    status: "cancelled" | "done" | "failed" | "queued" | "review" | "running" | "waiting";
+    activity: "monitoring" | undefined;
+    currentStepId: string | undefined;
+    hasPendingHumanAsk: boolean;
+    question: unknown;
+    branch: string | undefined;
+    diffStat: {
+        adds: number;
+        dels: number;
+        files: number;
+        repointed?: boolean | undefined;
+    } | undefined;
+    pullRequestUrl: string | undefined;
+    error: string | undefined;
+    tokensUsed: number;
+    startedAt: string | undefined;
+    finishedAt: string | undefined;
+    url: string;
+}>;
+/** The record carries no `updatedAt`; the newest lifecycle stamp is the honest stand-in. */
+export declare function projectListRow(run: ApiRun): Partial<{
+    id: string;
+    title: string;
+    status: "cancelled" | "done" | "failed" | "queued" | "review" | "running" | "waiting";
+    activity: "monitoring" | undefined;
+    hasPendingHumanAsk: boolean;
+    updatedAt: string;
+}>;

package/dist/task-cli/projections.js

@@ -0,0 +1,45 @@
+/**
+ * The slim shapes `cez task` prints (#504). A bot polls these every few seconds, so each one
+ * carries what a caller branches on and nothing it would have to pay tokens to skip: no
+ * `steps[]`, no `workflowDef`, no reference candidates. `--full` is the escape hatch.
+ */
+export const TERMINAL_STATUSES = ['done', 'review', 'failed', 'cancelled'];
+export const SUCCESS_STATUSES = ['done', 'review'];
+/** Keys with an undefined value are left off, so the JSON stays as small as the run is. */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function runTitle(run) {
+    return run.titleSummary ?? run.title;
+}
+export function projectStatus(run, url, question) {
+    return defined({
+        id: run.id,
+        title: runTitle(run),
+        status: run.status,
+        activity: run.activity,
+        currentStepId: run.currentStepId,
+        hasPendingHumanAsk: run.hasPendingHumanAsk ?? false,
+        question,
+        branch: run.branch,
+        diffStat: run.diffStat,
+        pullRequestUrl: run.pullRequestUrl,
+        error: run.error,
+        tokensUsed: run.tokensUsed,
+        startedAt: run.startedAt,
+        finishedAt: run.finishedAt,
+        url,
+    });
+}
+/** The record carries no `updatedAt`; the newest lifecycle stamp is the honest stand-in. */
+export function projectListRow(run) {
+    return defined({
+        id: run.id,
+        title: runTitle(run),
+        status: run.status,
+        activity: run.activity,
+        hasPendingHumanAsk: run.hasPendingHumanAsk ?? false,
+        updatedAt: run.finishedAt ?? run.startedAt ?? run.createdAt,
+    });
+}
+//# sourceMappingURL=projections.js.map

package/dist/task-cli/projections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projections.js","sourceRoot":"","sources":["../../src/task-cli/projections.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAyB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzE,2FAA2F;AAC3F,SAAS,OAAO,CAAoC,KAAQ;IAC1D,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAe,CAAC;AAC5G,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAA2C;IAClE,OAAO,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,KAAK,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,GAAW,EAAE,QAAkB;IACxE,OAAO,OAAO,CAAC;QACb,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,kBAAkB,EAAE,GAAG,CAAC,kBAAkB,IAAI,KAAK;QACnD,QAAQ;QACR,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,GAAG;KACJ,CAAC,CAAC;AACL,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,OAAO,CAAC;QACb,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,kBAAkB,EAAE,GAAG,CAAC,kBAAkB,IAAI,KAAK;QACnD,SAAS,EAAE,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS;KAC5D,CAAC,CAAC;AACL,CAAC"}

package/dist/task-cli/watch.d.ts

@@ -0,0 +1,78 @@
+import { type RunHistoryEvent, type RunStatus } from '../contract/index.js';
+import { type Cockpit } from './http.ts';
+/**
+ * Watching a task from a terminal (#504, spec 2026-09-24-cez-task-cli). Every loop here ends —
+ * on a terminal status or at the caller's deadline — because a bot's tool call that never
+ * returns is the failure this command family exists to prevent.
+ */
+export declare const DEFAULT_POLL_MS = 1500;
+export type WaitMode = 'any' | 'all';
+export type WaitUntil = 'settled' | 'attention';
+export interface WaitEntry {
+    id: string;
+    /** `unknown`: the deadline passed before any poll answered. */
+    status: RunStatus | 'missing' | 'unknown';
+    activity?: string;
+    hasPendingHumanAsk?: boolean;
+}
+export interface WaitResult {
+    exitCode: number;
+    runs: WaitEntry[];
+    timedOut: boolean;
+}
+/**
+ * Grace for the millisecond race between a budget-bounded poll's abort and the
+ * deadline check (#538): `AbortSignal.timeout(budget)` can fire while
+ * `Date.now()` still reads just under the deadline, turning a timeout into an
+ * `unavailable` error (exit 2 instead of 3). A poll whose own abort consumed
+ * (almost) all of its budget failed *at* the deadline, so it answers "timed
+ * out". The grace never applies to other errors: a genuine failure stays
+ * `unavailable` even when it lands inside the grace window.
+ */
+export declare const TIMEOUT_GRACE_MS = 250;
+export declare function pollHitDeadline(startedAt: number, budgetMs: number, now?: number): boolean;
+/**
+ * True when the wrapped cockpit error came from the poll's own abort (its
+ * budget running out) rather than a fast failure such as a refused
+ * connection. `fetchJson` folds every fetch failure into `unavailable`, so the
+ * abort surfaces only through the original message it preserves (`TimeoutError:
+ * The operation was aborted due to timeout`).
+ */
+export declare function abortedPoll(error: unknown): boolean;
+/**
+ * Polls `GET /runs`: one call covers any number of runs and holds no socket open. Each poll is
+ * bounded by what is left of the deadline, so a slow cockpit answers "timed out" on time rather
+ * than holding the caller for a full request timeout.
+ */
+export declare function waitForRuns(cockpit: Cockpit, ids: string[], options: {
+    mode: WaitMode;
+    until: WaitUntil;
+    timeoutMs: number;
+    pollMs?: number;
+}): Promise<WaitResult>;
+/** One printable line per event the log keeps, or undefined for the rest. */
+export declare function logLine(event: RunHistoryEvent): Record<string, unknown> | undefined;
+/**
+ * `log`, read from the run's SSE stream, which replays every event after `afterSeq` and then
+ * streams live. The route subscribes to live `run` updates BEFORE it replays, so a `run` frame
+ * says nothing about where the replay is; the only reliable boundary is a `seq`. So:
+ *
+ * - the replay ends at `asOfSeq`, the event file's high-water mark read from `GET /history` just
+ *   before connecting — everything up to it is the tail, bounded to `maxChars`, and without
+ *   `follow` the command ends there;
+ * - with `follow`, a terminal status ends the command only once the stream has caught up with a
+ *   SECOND high-water read taken after that status arrived, so events the engine wrote just
+ *   before finishing are not dropped when the status frame overtakes them (exit 0/1, final line
+ *   is the status).
+ *
+ * One `deadline` bounds every request, the history reads included (exit 3). Deduped by `seq`.
+ * The stream rather than `GET /history` pages: a history page starts at its first transcript
+ * item, so it drops lifecycle events such as the opening `step-start`.
+ */
+export declare function readLog(cockpit: Cockpit, id: string, options: {
+    afterSeq: number;
+    maxChars: number;
+    follow: boolean;
+    deadline: number;
+    print: (line: string) => void;
+}): Promise<number>;