@open-mercato/cezar 0.1.5-pr506.357

package/dist/runs/store.d.ts

@@ -0,0 +1,408 @@
+import { EventEmitter } from 'node:events';
+import { z } from 'zod';
+export type RunStatus = 'queued' | 'running' | 'waiting' | 'review' | 'done' | 'failed' | 'cancelled';
+/**
+ * A sub-state of `running` (spec 2026-07-18-subagent-monitoring-status, #490):
+ * the agent ended its turn still working on its own downstream work (a sub-agent
+ * or a monitored command) and declared it with the `CEZ:MONITORING` marker — so
+ * the cockpit shows a non-attention "monitoring" label instead of "needs you".
+ * Only ever set while `status === 'running'`; cleared on resume/terminal.
+ */
+export type RunActivity = 'monitoring';
+export type StepStatus = 'pending' | 'running' | 'waiting' | 'review' | 'done' | 'failed' | 'cancelled' | 'skipped';
+declare const stepStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<["agent", "check"]>;
+    status: z.ZodEnum<["pending", "running", "waiting", "review", "done", "failed", "cancelled", "skipped"]>;
+    iterations: z.ZodNumber;
+    tokensUsed: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    /** Latest claude session id — the user can `claude --resume <id>` with it. */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** Dollar cost reported by the claude CLI for this step's turns. */
+    costUsd: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+    name: string;
+    id: string;
+    kind: "agent" | "check";
+    iterations: number;
+    tokensUsed: number;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    error?: string | undefined;
+    sessionId?: string | undefined;
+    costUsd?: number | undefined;
+}, {
+    status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+    name: string;
+    id: string;
+    kind: "agent" | "check";
+    iterations: number;
+    tokensUsed: number;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    error?: string | undefined;
+    sessionId?: string | undefined;
+    costUsd?: number | undefined;
+}>;
+declare const runRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    /** Display title (#389): the auto-derived summary of the first agent turn,
+     *  or the user's inline edit (`PATCH /api/runs/:id` sets it together with
+     *  `title` so edits always win). The UI shows `titleSummary ?? title`. */
+    titleSummary: z.ZodOptional<z.ZodString>;
+    /** `git diff --shortstat` of the worktree vs its base, refreshed on every
+     *  turn-end (#389) — what the quick list / table shows without a git call. */
+    diffStat: z.ZodOptional<z.ZodObject<{
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        files: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        adds: number;
+        dels: number;
+        files: number;
+    }, {
+        adds: number;
+        dels: number;
+        files: number;
+    }>>;
+    workflow: z.ZodString;
+    task: z.ZodString;
+    /** URLs of images attached to the initial task prompt, for the thread's first bubble
+     *  (#image-display) — persisted like agent screenshots, served from `/images/`. */
+    taskImages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodString>;
+    /** Agent backend this run used — drives "open in CLI" resume command. */
+    runner: z.ZodOptional<z.ZodEnum<["claude", "codex", "opencode"]>>;
+    /** Echo of the extra system prompt this run actually used (R2): the
+     *  `POST /api/runs` override, or the `config.json` default it fell back to.
+     *  Deliberately NOT the full composed prompt — skill bodies and the handoff
+     *  contract are derivable from the persisted workflow and would bloat the
+     *  index. Resolved at execute time (a queued run picks up config edits). */
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    /** Per-task follow-up inbox contract (spec 007, #444). Missing on old runs
+     *  means enabled — the historical behavior. */
+    generateFollowups: z.ZodOptional<z.ZodBoolean>;
+    /** Autonomous mode (#489): the run was started with the "autonomous" checkbox,
+     *  so it never parks at `waiting` (auto-nudge) and — once persisted here —
+     *  never parks at the terminal `review` gate either (`settleSuccess` + the
+     *  group-pick winner-park read it). Additive-safe: absent = falsy = not
+     *  autonomous. Set at creation from `WorkflowInput.autonomous`. */
+    autonomous: z.ZodOptional<z.ZodBoolean>;
+    status: z.ZodEnum<["queued", "running", "waiting", "review", "done", "failed", "cancelled"]>;
+    /** Sub-state of `running` (spec 2026-07-18-subagent-monitoring-status, #490):
+     *  `monitoring` while the agent is still working on its own downstream work.
+     *  Optional/absent on old runs; cleared when the run resumes or ends. */
+    activity: z.ZodOptional<z.ZodEnum<["monitoring"]>>;
+    createdAt: z.ZodString;
+    startedAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    tokensUsed: z.ZodNumber;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+    /** First GitHub PR URL spotted in the transcript (the janitor trick). */
+    pullRequestUrl: z.ZodOptional<z.ZodString>;
+    /** The PR this task is ABOUT (#407, spec 2026-07-16-pr-autodiscovery):
+     *  auto-discovered from conversation references for tasks that work on an
+     *  existing PR (review/continue/merge). Display-only tier — `pullRequestUrl`
+     *  (the PR this task CREATED) always wins, and action gates ignore this. */
+    referencedPullRequestUrl: z.ZodOptional<z.ZodString>;
+    /** The PR/issue number this task is ABOUT (spec 2026-07-17-task-auto-naming):
+     *  regex-extracted from the task prompt, upgradable by the namer's
+     *  cross-checked output. Display tier — never gates actions. */
+    prNumber: z.ZodOptional<z.ZodNumber>;
+    issueNumber: z.ZodOptional<z.ZodNumber>;
+    /** Who owns the display title: `user` (PATCH rename — never auto-overwritten)
+     *  or `auto` (namer-owned — a later namer result may replace it). Missing on
+     *  old runs = legacy behavior (auto fills only an unset titleSummary). */
+    titleOrigin: z.ZodOptional<z.ZodEnum<["user", "auto"]>>;
+    /** Distinct PR URLs spotted so far — the referenced tier's working set,
+     *  persisted so a resumed run keeps disambiguating against the full history
+     *  instead of re-adopting the next URL as "the only one". Capped. */
+    referencedPrCandidates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Task worktree (spec 006) — absent when the run executed in the repo root. */
+    worktreePath: z.ZodOptional<z.ZodString>;
+    /** The task's own branch (`cez/<id8>`), created off `baseBranch`. */
+    branch: z.ZodOptional<z.ZodString>;
+    /** Branch (or commit, when HEAD was detached) the worktree was forked from. */
+    baseBranch: z.ZodOptional<z.ZodString>;
+    /** Set when count-based retention (#483) reclaimed this run's worktree
+     *  *directory* (the `cez/<id8>` branch is kept). Presence means "materialized
+     *  dir gone, recoverable via `git worktree add`"; it excludes the run from the
+     *  retention budget until the dir is re-materialized (resume clears it). */
+    worktreeReclaimedAt: z.ZodOptional<z.ZodString>;
+    /** Parallel variants (spec 010): tasks sharing a groupId are one group. */
+    groupId: z.ZodOptional<z.ZodString>;
+    /** Variant letter within the group — 'A' | 'B' | 'C' (kept as a string). */
+    variant: z.ZodOptional<z.ZodString>;
+    /** Peak resident memory (bytes) / process count observed across the run's
+     *  agent process trees (#348) — written when a session's telemetry ends.
+     *  Optional: old runs.json files and `ps`-less platforms have neither. */
+    peakRssBytes: z.ZodOptional<z.ZodNumber>;
+    peakProcCount: z.ZodOptional<z.ZodNumber>;
+    archived: z.ZodDefault<z.ZodBoolean>;
+    archivedAt: z.ZodOptional<z.ZodString>;
+    currentStepId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<["agent", "check"]>;
+        status: z.ZodEnum<["pending", "running", "waiting", "review", "done", "failed", "cancelled", "skipped"]>;
+        iterations: z.ZodNumber;
+        tokensUsed: z.ZodNumber;
+        startedAt: z.ZodOptional<z.ZodString>;
+        finishedAt: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        /** Latest claude session id — the user can `claude --resume <id>` with it. */
+        sessionId: z.ZodOptional<z.ZodString>;
+        /** Dollar cost reported by the claude CLI for this step's turns. */
+        costUsd: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+        name: string;
+        id: string;
+        kind: "agent" | "check";
+        iterations: number;
+        tokensUsed: number;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+        error?: string | undefined;
+        sessionId?: string | undefined;
+        costUsd?: number | undefined;
+    }, {
+        status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+        name: string;
+        id: string;
+        kind: "agent" | "check";
+        iterations: number;
+        tokensUsed: number;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+        error?: string | undefined;
+        sessionId?: string | undefined;
+        costUsd?: number | undefined;
+    }>, "many">;
+    /** Full workflow definition, persisted so a `queued` run can be re-enqueued
+     *  after a restart (#367) — including ad-hoc "(planned)" chains that exist
+     *  nowhere else. Kept loose here to avoid an upward import; the run manager
+     *  validates the shape before reviving it. */
+    workflowDef: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    status: "queued" | "running" | "waiting" | "review" | "done" | "failed" | "cancelled";
+    id: string;
+    tokensUsed: number;
+    title: string;
+    workflow: string;
+    task: string;
+    createdAt: string;
+    archived: boolean;
+    steps: {
+        status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+        name: string;
+        id: string;
+        kind: "agent" | "check";
+        iterations: number;
+        tokensUsed: number;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+        error?: string | undefined;
+        sessionId?: string | undefined;
+        costUsd?: number | undefined;
+    }[];
+    baseBranch?: string | undefined;
+    systemPrompt?: string | undefined;
+    branch?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    error?: string | undefined;
+    costUsd?: number | undefined;
+    titleSummary?: string | undefined;
+    diffStat?: {
+        adds: number;
+        dels: number;
+        files: number;
+    } | undefined;
+    taskImages?: string[] | undefined;
+    model?: string | undefined;
+    runner?: "claude" | "codex" | "opencode" | undefined;
+    generateFollowups?: boolean | undefined;
+    autonomous?: boolean | undefined;
+    activity?: "monitoring" | undefined;
+    pullRequestUrl?: string | undefined;
+    referencedPullRequestUrl?: string | undefined;
+    prNumber?: number | undefined;
+    issueNumber?: number | undefined;
+    titleOrigin?: "user" | "auto" | undefined;
+    referencedPrCandidates?: string[] | undefined;
+    worktreePath?: string | undefined;
+    worktreeReclaimedAt?: string | undefined;
+    groupId?: string | undefined;
+    variant?: string | undefined;
+    peakRssBytes?: number | undefined;
+    peakProcCount?: number | undefined;
+    archivedAt?: string | undefined;
+    currentStepId?: string | undefined;
+    workflowDef?: Record<string, unknown> | undefined;
+}, {
+    status: "queued" | "running" | "waiting" | "review" | "done" | "failed" | "cancelled";
+    id: string;
+    tokensUsed: number;
+    title: string;
+    workflow: string;
+    task: string;
+    createdAt: string;
+    steps: {
+        status: "running" | "waiting" | "review" | "done" | "failed" | "cancelled" | "pending" | "skipped";
+        name: string;
+        id: string;
+        kind: "agent" | "check";
+        iterations: number;
+        tokensUsed: number;
+        startedAt?: string | undefined;
+        finishedAt?: string | undefined;
+        error?: string | undefined;
+        sessionId?: string | undefined;
+        costUsd?: number | undefined;
+    }[];
+    baseBranch?: string | undefined;
+    systemPrompt?: string | undefined;
+    branch?: string | undefined;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    error?: string | undefined;
+    costUsd?: number | undefined;
+    titleSummary?: string | undefined;
+    diffStat?: {
+        adds: number;
+        dels: number;
+        files: number;
+    } | undefined;
+    taskImages?: string[] | undefined;
+    model?: string | undefined;
+    runner?: "claude" | "codex" | "opencode" | undefined;
+    generateFollowups?: boolean | undefined;
+    autonomous?: boolean | undefined;
+    activity?: "monitoring" | undefined;
+    pullRequestUrl?: string | undefined;
+    referencedPullRequestUrl?: string | undefined;
+    prNumber?: number | undefined;
+    issueNumber?: number | undefined;
+    titleOrigin?: "user" | "auto" | undefined;
+    referencedPrCandidates?: string[] | undefined;
+    worktreePath?: string | undefined;
+    worktreeReclaimedAt?: string | undefined;
+    groupId?: string | undefined;
+    variant?: string | undefined;
+    peakRssBytes?: number | undefined;
+    peakProcCount?: number | undefined;
+    archived?: boolean | undefined;
+    archivedAt?: string | undefined;
+    currentStepId?: string | undefined;
+    workflowDef?: Record<string, unknown> | undefined;
+}>;
+export type StepState = z.infer<typeof stepStateSchema>;
+export type RunRecord = z.infer<typeof runRecordSchema>;
+/** One persisted event line; `type` mirrors AgentEvent plus engine lifecycle. */
+export interface RunEvent {
+    seq: number;
+    ts: string;
+    stepId?: string;
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * File-backed run store: `runs.json` index (atomic tmp+rename writes, the
+ * pattern from @cezar/core's IssueStore) plus one append-only NDJSON event
+ * file per run. Also the in-process event bus the SSE endpoints subscribe to:
+ * emits `('run', RunRecord)` and `('event', { runId, event: RunEvent })`.
+ */
+export declare class RunStore extends EventEmitter {
+    private readonly dataDir;
+    private runs;
+    private saveTimer;
+    private constructor();
+    /**
+     * `keepLive` (#367): leave `queued`/`running`/`waiting` statuses untouched
+     * so the caller can recover them (RunManager.recover re-queues queued runs,
+     * resumes interrupted ones). Without it — one-shot CLI paths that never
+     * recover — live-looking runs are marked failed so no ghost stays behind.
+     */
+    static open(dataDir: string, opts?: {
+        keepLive?: boolean;
+    }): RunStore;
+    listRuns(): RunRecord[];
+    getRun(id: string): RunRecord | undefined;
+    createRun(input: {
+        title: string;
+        workflow: string;
+        task: string;
+        model?: string;
+        runner?: 'claude' | 'codex' | 'opencode';
+        generateFollowups?: boolean;
+        autonomous?: boolean;
+        groupId?: string;
+        variant?: string;
+        steps: Array<Pick<StepState, 'id' | 'name' | 'kind'>>;
+    }): RunRecord;
+    updateRun(id: string, patch: Partial<Omit<RunRecord, 'id' | 'steps'>>): RunRecord | undefined;
+    /** Append a step to an existing run (used by "Continue" — spec 003). */
+    addStep(runId: string, step: Pick<StepState, 'id' | 'name' | 'kind'>): void;
+    updateStep(runId: string, stepId: string, patch: Partial<Omit<StepState, 'id'>>): void;
+    setArchived(id: string, archived: boolean): RunRecord | undefined;
+    /** Bulk-archive every finished run; returns how many were archived. */
+    archiveFinished(): number;
+    appendEvent(runId: string, event: {
+        type: string;
+        stepId?: string;
+        [key: string]: unknown;
+    }): RunEvent;
+    /**
+     * Fold every PR URL in `haystack` into the run's referenced-tier working
+     * set and re-resolve `referencedPullRequestUrl` (spec
+     * 2026-07-16-pr-autodiscovery). Mutates the record in place — the caller
+     * owns persistence/fan-out — and reports whether anything changed.
+     */
+    private trackReferencedPrs;
+    /**
+     * Fan an event out to live subscribers WITHOUT writing it to the NDJSON
+     * file — the channel for coalesced `item.delta` flushes (protocol-v2
+     * performance guardrail: raw deltas never hit disk; replay = the persisted
+     * snapshots). Stamped with `seq`/`ts` like persisted lines so the live
+     * wire keeps one ordering axis; the seq simply never appears in a replay
+     * (gaps are fine — dedup compares with `>`).
+     */
+    emitEphemeral(runId: string, event: {
+        type: string;
+        stepId?: string;
+        [key: string]: unknown;
+    }): RunEvent;
+    readEvents(runId: string): RunEvent[];
+    deleteRun(id: string): boolean;
+    /** Write the index out now (used on shutdown). */
+    flush(): void;
+    private seqs;
+    private nextSeq;
+    /** After a restart the in-memory counter is empty while the run's NDJSON file
+     *  keeps the history. Restarting from 1 would collide with the seqs a client
+     *  already replayed — its `seq > maxSeq` dedup then silently drops every
+     *  resumed event, even across a reload (the frozen-transcript symptom class
+     *  of #424). One file read on the first post-restart append per run. */
+    private rehydrateSeq;
+    private eventsPath;
+    /** Same location `handoffPath()` in handoff.ts produces — inlined to keep
+     *  the store free of upward imports. */
+    private handoffPath;
+    /** Agent screenshots persisted by the run manager (see persistImage). */
+    private imagesDir;
+    private touch;
+    private pruneOldRuns;
+    /** Debounced so token-usage updates don't rewrite the index per event. */
+    private scheduleSave;
+    private saveNow;
+}
+export {};