@open-mercato/cezar 0.1.5-pr506.357

package/dist/workflows/load.js

@@ -0,0 +1,56 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { QUICK_TASK_WORKFLOW, normalizeWorkflowDoc, stepsIssue, workflowFileSchema, } from './types.js';
+export const WORKFLOWS_DIR = '.ai/cezar/workflows';
+/**
+ * Load the workflow catalog: the built-in `quick-task` plus every
+ * `.ai/cezar/workflows/*.{yaml,yml}` in the repo. File workflows win name
+ * collisions with built-ins. Invalid files are reported, never fatal.
+ */
+export async function loadWorkflows(repoRoot) {
+    const dir = resolve(repoRoot, WORKFLOWS_DIR);
+    const issues = [];
+    const fromFiles = [];
+    let entries = [];
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        // no workflows dir — built-ins only
+    }
+    for (const entry of entries) {
+        const ext = extname(entry).toLowerCase();
+        if (ext !== '.yaml' && ext !== '.yml')
+            continue;
+        const path = join(dir, entry);
+        try {
+            const raw = await readFile(path, 'utf8');
+            const parsed = workflowFileSchema.safeParse(parseYaml(raw));
+            if (!parsed.success) {
+                issues.push({ path, message: parsed.error.issues.map((i) => i.message).join('; ') });
+                continue;
+            }
+            // `skills:` shorthand files become plain agent steps here (spec 012).
+            const normalized = normalizeWorkflowDoc(parsed.data);
+            // Steps referenced by onFail.retry must exist and come earlier; ids unique.
+            const issue = stepsIssue(normalized.steps);
+            if (issue) {
+                issues.push({ path, message: issue });
+                continue;
+            }
+            fromFiles.push({ ...normalized, source: 'file', path });
+        }
+        catch (err) {
+            issues.push({ path, message: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    const fileNames = new Set(fromFiles.map((w) => w.name));
+    const workflows = [
+        ...fromFiles,
+        ...[QUICK_TASK_WORKFLOW].filter((w) => !fileNames.has(w.name)),
+    ];
+    workflows.sort((a, b) => a.name.localeCompare(b.name));
+    return { workflows, issues };
+}
+//# sourceMappingURL=load.js.map

package/dist/workflows/load.js.map

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

package/dist/workflows/run.d.ts

@@ -0,0 +1,281 @@
+import type { RunnerId } from '../core/agent-runner.js';
+import type { ContentBlock } from '../core/agent-runner.js';
+import { type Skill } from '../skills.js';
+import type { RunRecord, RunStore } from '../runs/store.js';
+import { type WorkflowDef } from './types.js';
+/** An interactive session that hears nothing from the user closes itself. */
+export declare const IDLE_TIMEOUT_MS: number;
+/** Periodic "cezar autosave" commit in the task worktree (spec 006). */
+export declare const AUTOSAVE_INTERVAL_MS = 90000;
+/** The periodic autosave timer is opt-in (#471): off, a task branch carries only the
+ *  agent's own commits plus the turn-end/pre-PR flushes — no mid-run "cezar autosave"
+ *  noise interleaving PR history. The flushes (`autosaveCommit` at turn end and before
+ *  a draft PR) are NOT gated: the branch must still end holding the finished state. */
+export declare function periodicAutosaveEnabled(env?: NodeJS.ProcessEnv): boolean;
+export interface StartRunInput {
+    task: string;
+    model?: string;
+    /** Agent backend chosen for this task (GUI). Unset = the config default. */
+    runner?: RunnerId;
+    /** Screenshots pasted into the new-task form — delivered once, with the
+     *  first agent step's opening message. */
+    images?: ContentBlock[];
+    /** Per-run system-prompt override (`POST /api/runs`, programmatic callers).
+     *  Replaces the `config.json` default for this run — see
+     *  `resolveExtraSystemPrompt` for the precedence contract. */
+    systemPrompt?: string;
+    /** Composer opt-out (#worktree-toggle): `false` runs the task in the repo
+     *  working tree instead of an isolated worktree — for read-only skills that
+     *  don't need a branch. Undefined/`true` keeps the default per-task worktree.
+     *  Ignored for variants (they always isolate). */
+    worktree?: boolean;
+    /** Autonomous mode (#autonomous): the run never parks at `waiting` for the
+     *  user — turn-ends auto-continue until the agent signals done or the safety
+     *  cap is hit. No "needs you" is ever raised. */
+    autonomous?: boolean;
+    /** Follow-up inbox generation (spec 007, #444). Omitted means enabled for
+     *  compatibility; the handoff journal runs either way. */
+    generateFollowups?: boolean;
+}
+/**
+ * The effective "extra" system prompt for a run (spec §protocol v2, R2 2.3):
+ * the per-run override (`POST /api/runs` `systemPrompt`) REPLACES the
+ * `config.json` default — they are the same knob at two scopes, so the more
+ * specific one wins outright; they never concatenate. Whichever wins is
+ * ADDITIVE to the skill body and the handoff contract, which always ride
+ * along (see `composeSystemPrompt`). Blank strings count as unset.
+ */
+export declare function resolveExtraSystemPrompt(override: string | undefined, configDefault: string | undefined): string | undefined;
+/**
+ * Joins the parts of one agent step's system prompt in fixed order — skill
+ * body (most task-specific), then the run's extra prompt (user guidance, can
+ * amend the skill), then the handoff contract (always last, never optional in
+ * practice). Blank parts drop out; survivors join with the same `\n\n---\n\n`
+ * divider the skill+handoff composition has always used.
+ */
+export declare function composeSystemPrompt(...parts: Array<string | undefined>): string;
+/** Variant letters + the fixed diversification hints (spec 010). A runs the
+ *  task verbatim; B/C get one constant sentence each — zero configuration. */
+export declare const VARIANT_LETTERS: readonly ["A", "B", "C"];
+/**
+ * The mini workflow engine: executes a `WorkflowDef` against a repo, one step
+ * at a time, persisting every event to the RunStore (which the SSE endpoints
+ * relay live to the GUI). No GitHub choreography — agent steps and shell
+ * checks with bounded retry loops, plus live sessions: the last agent step
+ * stays open for follow-ups (`waiting`) until "finish", idle timeout, or
+ * cancel. Runs queue behind `maxParallel` slots and each run executes in its
+ * own git worktree on a `cez/<id8>` branch (spec 006), autosave-committed at
+ * turn end and before a draft PR — plus every 90 s when opted in via
+ * CEZ_AUTOSAVE=1 (#471). The user's working tree is never touched.
+ */
+export declare class RunManager {
+    private readonly store;
+    private readonly repoRoot;
+    private readonly active;
+    private readonly queue;
+    private readonly starting;
+    private readonly waiting;
+    private readonly pendingJobs;
+    private pumping;
+    /**
+     * Runs normally isolate in worktrees and may execute in parallel. When that
+     * isolation is unavailable (or explicitly disabled), serialize access to
+     * `repoRoot` so two agents can never edit/revert the same files (#438).
+     */
+    private repoRootTail;
+    /** `.ai/cezar` — where the per-task handoff files and todos.json live. */
+    private readonly dataDir;
+    /** Runs currently being paused by the memory guard — dedupes the ~2 s samples so one breach
+     *  triggers one pause, not a burst. Cleared in dropActive when the run leaves the registry. */
+    private readonly memoryPausing;
+    constructor(store: RunStore, repoRoot: string);
+    /**
+     * Pause any active run whose whole process tree exceeds `config.memoryLimitMb`, freeing its
+     * slot so the queue advances (#memory-guard). "Pause" closes the session — freeing the tree's
+     * memory — and leaves the run resumable via Continue; a loud warning explains why. No-op when
+     * no limit is set or the sampler has no data (e.g. `ps`/PowerShell unavailable).
+     */
+    private enforceMemoryLimit;
+    /** Env the spawned claude gets so the agent can find its handoff file and
+     *  the global inbox (spec 007; the inbox only when the run opted in).
+     *
+     *  `CEZ_TODOS_FILE` is set to `''` rather than omitted when follow-ups are
+     *  off: runners spawn with `{ ...process.env, ...spec.env }`, so omitting the
+     *  key would let a value inherited from *this* process through — a nested
+     *  cezar (an agent running `cez serve`/`cez run`/the test suite) would then
+     *  write follow-ups into the parent's inbox despite the opt-out. Empty is the
+     *  established "absent" spelling — consumers guard with `if (todosFile)`. */
+    private agentEnv;
+    startRun(workflow: WorkflowDef, input: StartRunInput, group?: {
+        groupId: string;
+        variant: string;
+    }): RunRecord;
+    /**
+     * Parallel variants (spec 010): N runs of the same workflow on the same
+     * task, sharing a groupId. Variant A gets the task verbatim; B and C get a
+     * fixed one-line approach hint appended to the *task input* (not the step
+     * template), so diversification works with any workflow. The normal queue
+     * applies — with maxParallel=2 a third variant simply waits.
+     */
+    startVariants(workflow: WorkflowDef, input: StartRunInput, count: number): RunRecord[];
+    /**
+     * Start queued runs while parallel slots are free. `maxParallel` comes from
+     * `.ai/cezar/config.json` (default 2); a non-git directory degrades to 1
+     * sequential run in the repo root (spec 006 degradation rule).
+     */
+    private pump;
+    /**
+     * Startup recovery (#367) — re-adopt runs that were live when the previous
+     * cezar process exited (requires the store opened with `keepLive`):
+     *  - `queued`  → back into the queue (FIFO by createdAt), from the persisted
+     *    workflowDef (or the catalog by name for older records);
+     *  - `waiting` → the turn was over and the ball was in the user's court —
+     *    settle exactly like a closed session (review/done, Continue still works);
+     *  - `running` → mark interrupted, then immediately resume the last agent
+     *    session via the Continue path, pointing the agent at its handoff file.
+     * Call once, before the server starts taking requests.
+     */
+    recover(): Promise<void>;
+    /** The persisted definition when it looks sane, else the catalog by name. */
+    private reviveWorkflow;
+    /** Remove a run from the live registries — keeps `waiting ⊆ active`. */
+    private dropActive;
+    /** Reclaim finished worktrees beyond the keep-limit (#483) — directory only,
+     *  `cez/<id8>` branch kept. Best-effort; a failure never affects run
+     *  lifecycle. `review`/live runs are excluded by the selector. */
+    private enforceRetention;
+    /** Last live-refresh namer inputs per run — unchanged inputs skip the call. */
+    private lastNamerKey;
+    /**
+     * Acquire the one-at-a-time lease for runs executing in `repoRoot`.
+     *
+     * A lease waiter is idle, so it parks in `waiting` and gives its
+     * `maxParallel` slot back (the #347 rule): isolated worktrees keep using
+     * every configured slot while root runs line up. The store status stays
+     * `running` — only the queue's busy count changes, so the GUI never shows a
+     * lease-blocked run as awaiting user input.
+     *
+     * The lease is held for the run's whole lifetime, including the idle
+     * `waiting` parks between agent turns. A parked session is still live and
+     * writes to the working tree the moment it resumes, so handing the tree to
+     * another run there would reintroduce the concurrent-edit bug (#438) this
+     * lease exists to prevent.
+     *
+     * Returns false when the run was cancelled while waiting: the lease was
+     * never granted and the caller must not touch the working tree.
+     */
+    private acquireRepoRoot;
+    cancel(runId: string): boolean;
+    isActive(runId: string): boolean;
+    /**
+     * Deliver a user message into the run's live claude session (mid-turn or
+     * while `waiting`). Returns false when there is no open session — the GUI
+     * then offers "Continue" instead.
+     */
+    sendMessage(runId: string, content: ContentBlock[]): boolean;
+    /** Close the open session gracefully — the run then completes as `done`
+     *  (or rests at `review` when the worktree holds changes, spec 009).
+     *  On a run already resting at `review` (no session — the engine loop is
+     *  over), "Finish" is the third review exit: accept the changes without a
+     *  PR and flip straight to `done`. */
+    finish(runId: string): boolean;
+    /**
+     * "Continue" (spec 003): reopen a finished run's claude session in-process
+     * (`claude --resume <sessionId>`) as a new synthetic step. The session then
+     * behaves exactly like an interactive step: `waiting` after each turn,
+     * messages via sendMessage, closed by finish/idle/cancel.
+     */
+    continueRun(runId: string, text?: string): {
+        ok: boolean;
+        error?: string;
+    };
+    private runContinuation;
+    private execute;
+    /** Returns an error message, or null on success. */
+    private runAgentStep;
+    /**
+     * Protocol-v2 sink for one agent session (R2 step 2.1): the runner's
+     * `onUiEvent` stream flows through here. Persisted snapshots ride the same
+     * NDJSON file as v1 (the store stamps `seq`/`ts`, `appendEvent` fans them
+     * out live too); coalesced `item.delta` flushes go out live-only via
+     * `emitEphemeral` — raw deltas never hit disk (spec §performance
+     * guardrails). One sink per session: cumulative usage dedup and the
+     * item-shape cache are session-scoped, like the mapper state feeding them.
+     */
+    private makeUiSink;
+    /**
+     * Turn-end bookkeeping (#389), shared by `runAgentStep` and
+     * `runContinuation` — called (fire-and-forget) from every `turn-end` event:
+     *
+     *  - `titleSummary`: derived from the turn's text, set ONCE — only while the
+     *    record has none. A user's inline edit also lands in `titleSummary`
+     *    (see `PATCH /api/runs/:id`), so an edit is never overwritten either.
+     *  - `diffStat`: cheap `git diff --shortstat` vs the base, refreshed every
+     *    turn. Async and best-effort — a git failure becomes at most a `note`
+     *    event, NEVER a run failure. `updateRun` fans the record out over SSE,
+     *    so the list views pick both up with no extra wiring.
+     *
+     * Not `private` so the integration tests can drive a turn-end directly —
+     * a real agent session is the only other way to reach this path.
+     */
+    /**
+     * The namer's apply path (task auto-naming spec). Fire-and-forget: called
+     * without await from `startRun` (creation) and `recordTurnEnd` (live
+     * refresh). A user-owned title (`titleOrigin: 'user'`) is never overwritten;
+     * namer-owned titles may be replaced by fresher namer results.
+     */
+    private autoNameRun;
+    recordTurnEnd(runId: string, turnText: string): Promise<void>;
+    /**
+     * Live title refresh (task auto-naming spec, step 3): re-run the namer with
+     * the turn's context. Skips: toggle off (`liveTitleUpdates` config over
+     * `CEZ_TITLE_UPDATES` env, default ON), user-owned title, dry-run mocks
+     * (canned answers add nothing), empty turn text, unchanged namer inputs.
+     */
+    private maybeRefreshTitle;
+    /**
+     * End-of-session telemetry (#348): stop sampling the run's process tree and
+     * fold the session's peaks into the run record. `max` with existing values —
+     * a run can hold several sessions (multiple agent steps, Continue) and the
+     * record keeps the highest water mark across all of them.
+     */
+    private recordUsagePeaks;
+    /**
+     * Diff-first review gate (spec 009), shared by `execute` and
+     * `runContinuation`: a *successful* run whose worktree holds changes rests
+     * at `review` instead of `done` — the user inspects the diff first, then
+     * sends feedback back, opens a draft PR, or just finishes. Failed/cancelled
+     * runs never enter review; no worktree or an empty diff means plain `done`.
+     *
+     * The gate is opt-in (#489): the review park happens only when it is enabled
+     * (`reviewGateEnabled` — config toggle over the `CEZ_REVIEW_GATE` env, default
+     * OFF) AND the run is not autonomous. Autonomous runs — and runs with the gate
+     * off — settle straight to `done`, leaving the diff in the worktree untouched.
+     */
+    private settleSuccess;
+    /**
+     * Agent screenshot (an image block inside a tool result): the base64 data
+     * never enters the NDJSON event log — it lands as a file under
+     * `.ai/cezar/runs/<id>-images/` and the transcript event carries only the
+     * name + serving URL. Best effort: on failure the screenshot is dropped,
+     * the transcript still shows the tool result's `[screenshot]` placeholder.
+     */
+    private persistImage;
+    private armIdleTimer;
+    private clearIdleTimer;
+    /** Autosave-commit the worktree every 90 s while the run lives (spec 006).
+     *  Opt-in via CEZ_AUTOSAVE=1 (#471) — see periodicAutosaveEnabled. */
+    private armAutosave;
+    private clearAutosaveTimer;
+    private runCheckStep;
+    private finishStep;
+}
+/**
+ * Immediate title shown while a run is queued. The namer's `titleSummary`
+ * replaces it once the model answers; this is the honest, permanent fallback
+ * when no model is available (#432, spec 2026-07-17-task-auto-naming). When
+ * the task references a PR/issue, the number leads: `469: /om-auto-review-pr`.
+ */
+export declare function makeRunTitle(task: string, workflow: WorkflowDef): string;
+/** Skill identity is context, while the Markdown body remains instructions. */
+export declare function skillSystemPrompt(skill: Pick<Skill, 'name' | 'description' | 'body'>): string;