@open-mercato/cezar 0.1.5-pr506.357

package/dist/core/ui-events.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Normalized agent-event protocol v2 — the shared vocabulary every runner
+ * emits ALONGSIDE the v1 `AgentEvent` stream (never replacing it; mixed
+ * NDJSON files stay valid — old recordings must keep replaying).
+ *
+ * Contract sources (authoritative, in this order):
+ *  - `.ai/analysis/cockpit-ui-redesign/agent-event-protocols.md` §7 (schema)
+ *    and §7.1 (per-backend mapping tables);
+ *  - the spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`
+ *    §"Normalized agent-event protocol v2".
+ *
+ * Design rules baked in:
+ *  1. Item-lifecycle model (Codex/ACP style): one stable `id` per item with
+ *     started/delta/updated/completed phases — two of the three backends are
+ *     natively item-shaped and claude maps trivially.
+ *  2. ACP vocabulary wherever a choice is arbitrary (tool status/kind, plan
+ *     entries, diff shape, stop reasons) for ecosystem alignment.
+ *  3. Every v1 `AgentEvent` stays derivable from this stream, so consumers
+ *     can migrate one panel at a time.
+ *
+ * This module is pure vocabulary: no runtime imports, no runner coupling.
+ * Step 2.4 mirrors it into `web/app/src/protocol/`.
+ */
+/** The backend that produced a session — mirrors `RunnerId` in
+ *  `agent-runner.ts` (kept structurally identical; a type-level test
+ *  guards against drift so this module stays dependency-free). */
+export type UiBackend = 'claude' | 'codex' | 'opencode';
+/**
+ * Tool lifecycle status (ACP: pending/in_progress/completed/failed).
+ * `running` ≡ ACP `in_progress` (opencode's word — reads better in code);
+ * `declined` covers codex approval declines and claude `permission_denials`.
+ *
+ * Per backend: claude has no pending phase (`tool_use` arrives already
+ * running); codex maps `inProgress→running`, `completed/failed/declined`
+ * verbatim; opencode maps `pending/running` verbatim and `error→failed`.
+ */
+export type ToolStatus = 'pending' | 'running' | 'completed' | 'failed' | 'declined';
+/**
+ * Icon/verb hint for a tool item — a superset of ACP's ToolKind.
+ * `task` = subagent spawn (claude Task / opencode subtask / codex review).
+ */
+export type ToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'task' | 'plan' | 'other';
+/**
+ * Why a turn (or the session) stopped.
+ *
+ * Per backend: claude `result` subtype success→`end_turn`,
+ * error_max_turns→`max_tokens`, error_during_execution→`error`; codex
+ * turn/completed→`end_turn`, turn/failed→`error`, interrupt→`cancelled`;
+ * opencode `session.idle`→`end_turn` (or `error` when a session.error
+ * preceded it).
+ */
+export type StopReason = 'end_turn' | 'max_tokens' | 'refusal' | 'cancelled' | 'timeout' | 'error';
+/**
+ * Status of one plan/todo entry. claude TodoWrite/TaskUpdate use the first
+ * three words verbatim; codex `turn/plan/updated` sends camelCase
+ * (`inProgress`) and is normalized here; opencode `todowrite` adds
+ * `cancelled` ("no longer needed") — its status field is a free-form string
+ * whose documented vocabulary is pending|in_progress|completed|cancelled.
+ *
+ * `cancelled` is opencode-only today. It is a first-class status rather than a
+ * dropped row: an abandoned todo must stay visible (struck through) instead of
+ * silently vanishing from the dock mid-run.
+ */
+export type PlanStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+/** One entry of the session plan — full-replacement semantics (ACP style). */
+export interface PlanEntry {
+    content: string;
+    status: PlanStatus;
+    priority?: 'high' | 'medium' | 'low';
+    /** Present-continuous label shown while the entry is in progress
+     *  (claude TodoWrite's `activeForm`). */
+    activeForm?: string;
+}
+/**
+ * Raw token counts — never pre-weighted (cost weighting is a presentation
+ * concern, not a wire concern).
+ *
+ * Per backend: claude `result.usage` (+ `total_cost_usd` as `costUsd` on the
+ * carrying event); codex `thread/tokenUsage/updated` (no USD); opencode
+ * `message.updated` info.tokens/cost and `step-finish` parts.
+ */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+    /** The backend's own total when given, else the sum of the parts. */
+    total: number;
+    /** Model context-window size when known — feeds the fill gauge. */
+    contextWindow?: number;
+}
+/**
+ * One file change carried by an edit-tool item.
+ * claude `Edit`/`Write` input → `oldText`/`newText`; codex
+ * `fileChange.changes[]` → `unified`; opencode `patch` parts → `unified`.
+ * `oldText: null` means the file is newly created.
+ */
+export interface FileDiff {
+    path: string;
+    oldText: string | null;
+    newText?: string;
+    unified?: string;
+}
+/** A file location a tool touched (feeds "jump to file" affordances). */
+export interface ToolLocation {
+    path: string;
+    line?: number;
+}
+/** A choice offered by a permission request (ACP option kinds). */
+export type PermissionOptionKind = 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always';
+export interface PermissionOption {
+    id: string;
+    label: string;
+    kind: PermissionOptionKind;
+}
+/**
+ * A chat message.
+ * claude: `assistant` `text` blocks (whole-block, or true deltas via
+ * `--include-partial-messages`); codex: `agentMessage` items (`phase` from
+ * the item's own phase field); opencode: text parts of a message.
+ */
+export interface UiMessageItem {
+    kind: 'message';
+    id: string;
+    role: 'assistant' | 'user';
+    text: string;
+    phase?: 'commentary' | 'final';
+    parentItemId?: string;
+}
+/**
+ * Extended thinking / reasoning summary.
+ * claude: `thinking` blocks; codex: `reasoning` items (+ textDelta);
+ * opencode: `reasoning` parts.
+ */
+export interface UiReasoningItem {
+    kind: 'reasoning';
+    id: string;
+    text: string;
+    parentItemId?: string;
+}
+/**
+ * One tool invocation with its full lifecycle.
+ * claude: `tool_use` (started, status `running`) + `tool_result`
+ * (completed/failed; `permission_denials` → `declined`); codex: typed items
+ * (`commandExecution`→execute with `exitCode`, `fileChange`→edit with
+ * `diffs`, `mcpToolCall`→other, `webSearch`→fetch); opencode: tool parts
+ * (state pending/running/completed/error, `patch` parts → `diffs`).
+ *
+ * `parentItemId` nests subagent work under its spawning task item —
+ * claude `parent_tool_use_id`, opencode `subtask` parts, codex review items.
+ */
+export interface UiToolItem {
+    kind: 'tool';
+    id: string;
+    /** The backend's tool name / item type (e.g. `Bash`, `commandExecution`). */
+    name: string;
+    /** ACP-style icon/verb hint — see `toolDisplay()` in `tool-display.ts`. */
+    toolKind: ToolKind;
+    /** Human line, computed once in the protocol layer: "Ran npm test". */
+    title: string;
+    status: ToolStatus;
+    /** Raw input — may arrive incrementally. */
+    input?: unknown;
+    output?: string;
+    error?: string;
+    diffs?: FileDiff[];
+    locations?: ToolLocation[];
+    /** commandExecution / bash exit code, when the backend reports one. */
+    exitCode?: number;
+    parentItemId?: string;
+}
+export type UiItem = UiMessageItem | UiReasoningItem | UiToolItem;
+/**
+ * Session opened.
+ * claude: `system/init` (model, tools, cwd); codex: `thread/started` or the
+ * `thread/start` result; opencode: `POST /session` response.
+ */
+export interface UiSessionStartedEvent {
+    type: 'session.started';
+    sessionId: string;
+    backend: UiBackend;
+    model?: string;
+    cwd?: string;
+    tools?: string[];
+}
+/** Session over (replaces v1 `done` / fatal `error`). */
+export interface UiSessionEndedEvent {
+    type: 'session.ended';
+    reason: StopReason;
+    message?: string;
+}
+/** v1 `note` + `error` unified — severity explicit instead of implied. */
+export interface UiSessionErrorEvent {
+    type: 'session.error';
+    message: string;
+    fatal: boolean;
+}
+/**
+ * A turn began.
+ * claude: on each stdin user message; codex: `turn/started`;
+ * opencode: on each prompt POST.
+ */
+export interface UiTurnStartedEvent {
+    type: 'turn.started';
+    turnId: string;
+}
+/**
+ * A turn finished.
+ * claude: `result` (usage + `total_cost_usd`); codex: `turn/completed` /
+ * `turn/failed`; opencode: `session.idle`.
+ */
+export interface UiTurnCompletedEvent {
+    type: 'turn.completed';
+    turnId: string;
+    stopReason: StopReason;
+    usage?: TokenUsage;
+    costUsd?: number;
+}
+/** An item entered the stream (tools usually with status pending/running). */
+export interface UiItemStartedEvent {
+    type: 'item.started';
+    item: UiItem;
+}
+/**
+ * Streaming append to one field of a live item.
+ * claude: partial-message text deltas; codex: `item/agentMessage/delta`
+ * (`text`), `item/reasoning/textDelta` (`reasoning`),
+ * `item/commandExecution/outputDelta` (`output` — live terminal); opencode:
+ * text/reasoning part cursor deltas, running-state metadata for `output`.
+ * claude has no live command output — the tool card fills on completion
+ * (per-capability degradation, never per-backend).
+ */
+export interface UiItemDeltaEvent {
+    type: 'item.delta';
+    itemId: string;
+    field: 'text' | 'reasoning' | 'output';
+    delta: string;
+}
+/** Status flips and streamed-content snapshots (codex `item/updated`,
+ *  opencode part-state flips such as pending→running). */
+export interface UiItemUpdatedEvent {
+    type: 'item.updated';
+    item: UiItem;
+}
+/** Final snapshot of an item — safe to persist (snapshots, not deltas). */
+export interface UiItemCompletedEvent {
+    type: 'item.completed';
+    item: UiItem;
+}
+/**
+ * Full-replacement plan snapshot (ACP semantics).
+ * claude: `TodoWrite` tool input, or a snapshot folded from the incremental
+ * `TaskCreate`/`TaskUpdate`/`TaskList` calls (keyed by the task id the harness
+ * reports in each tool's RESULT — see `claude-ui-mapper`); codex: the
+ * `turn/plan/updated` notification carrying the whole `update_plan` list (it is
+ * a turn-level notification, NOT an item — the app-server `ThreadItem` union has
+ * no todo variant); opencode: `todowrite` tool input — identical
+ * full-replacement semantics across all three.
+ */
+export interface UiPlanUpdatedEvent {
+    type: 'plan.updated';
+    entries: PlanEntry[];
+}
+/**
+ * RESERVED — wired when auto-approve becomes optional. Types only for now.
+ * claude: `control_request can_use_tool`; codex: the per-item
+ * `requestApproval` JSON-RPC requests; opencode: `permission.updated`.
+ */
+export interface UiPermissionRequestedEvent {
+    type: 'permission.requested';
+    requestId: string;
+    itemId?: string;
+    title: string;
+    options: PermissionOption[];
+}
+/** RESERVED — the counterpart resolution (see `permission.requested`). */
+export interface UiPermissionResolvedEvent {
+    type: 'permission.resolved';
+    requestId: string;
+    optionId: string;
+}
+/**
+ * Cumulative-for-session raw telemetry.
+ * claude: `result.usage` + `total_cost_usd`; codex:
+ * `thread/tokenUsage/updated` (cost stays absent); opencode:
+ * `message.updated` tokens/cost + `step-finish` increments.
+ */
+export interface UiUsageUpdatedEvent {
+    type: 'usage.updated';
+    usage: TokenUsage;
+    costUsd?: number;
+}
+/**
+ * An image emitted mid-stream (kept from v1) — raw base64 on the wire here;
+ * the run manager persists it and re-emits a URL. claude: image blocks in
+ * `tool_result` (with `itemId` linking back to the tool item).
+ */
+export interface UiImageEvent {
+    type: 'image';
+    itemId?: string;
+    mediaType: string;
+    data: string;
+}
+export type UiEvent = UiSessionStartedEvent | UiSessionEndedEvent | UiSessionErrorEvent | UiTurnStartedEvent | UiTurnCompletedEvent | UiItemStartedEvent | UiItemDeltaEvent | UiItemUpdatedEvent | UiItemCompletedEvent | UiPlanUpdatedEvent | UiPermissionRequestedEvent | UiPermissionResolvedEvent | UiUsageUpdatedEvent | UiImageEvent;
+/** Every v2 event discriminator — `satisfies Record<UiEventType, …>` maps
+ *  downstream keep new event types honest at compile time. */
+export type UiEventType = UiEvent['type'];

package/dist/core/ui-events.js

@@ -0,0 +1,25 @@
+/**
+ * Normalized agent-event protocol v2 — the shared vocabulary every runner
+ * emits ALONGSIDE the v1 `AgentEvent` stream (never replacing it; mixed
+ * NDJSON files stay valid — old recordings must keep replaying).
+ *
+ * Contract sources (authoritative, in this order):
+ *  - `.ai/analysis/cockpit-ui-redesign/agent-event-protocols.md` §7 (schema)
+ *    and §7.1 (per-backend mapping tables);
+ *  - the spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`
+ *    §"Normalized agent-event protocol v2".
+ *
+ * Design rules baked in:
+ *  1. Item-lifecycle model (Codex/ACP style): one stable `id` per item with
+ *     started/delta/updated/completed phases — two of the three backends are
+ *     natively item-shaped and claude maps trivially.
+ *  2. ACP vocabulary wherever a choice is arbitrary (tool status/kind, plan
+ *     entries, diff shape, stop reasons) for ecosystem alignment.
+ *  3. Every v1 `AgentEvent` stays derivable from this stream, so consumers
+ *     can migrate one panel at a time.
+ *
+ * This module is pure vocabulary: no runtime imports, no runner coupling.
+ * Step 2.4 mirrors it into `web/app/src/protocol/`.
+ */
+export {};
+//# sourceMappingURL=ui-events.js.map

package/dist/core/ui-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-events.js","sourceRoot":"","sources":["../../src/core/ui-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/core/usage.d.ts

@@ -0,0 +1,11 @@
+export declare const CACHE_READ_WEIGHT = 0.1;
+export declare const CACHE_CREATION_WEIGHT = 1.25;
+/** A loosely-typed usage record as emitted by the claude CLI stream. */
+export interface RawUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/** Collapse a raw usage record into a single cost-weighted token count. */
+export declare function costWeightedTokens(usage: RawUsage | undefined | null): number;

package/dist/core/usage.js

@@ -0,0 +1,15 @@
+// Anthropic bills cache-read input at ~10% of standard input cost and cache
+// creation at ~125%. Weighting raw counts by these keeps the token number
+// shown in the cockpit roughly proportional to dollar cost.
+export const CACHE_READ_WEIGHT = 0.1;
+export const CACHE_CREATION_WEIGHT = 1.25;
+/** Collapse a raw usage record into a single cost-weighted token count. */
+export function costWeightedTokens(usage) {
+    if (!usage)
+        return 0;
+    return Math.round((usage.input_tokens ?? 0) +
+        (usage.output_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0) * CACHE_CREATION_WEIGHT +
+        (usage.cache_read_input_tokens ?? 0) * CACHE_READ_WEIGHT);
+}
+//# sourceMappingURL=usage.js.map

package/dist/core/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAU1C,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,KAAkC;IACnE,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC,KAAK,CACf,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;QACvB,CAAC,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;QAC1B,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,CAAC,GAAG,qBAAqB;QAChE,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,CAAC,GAAG,iBAAiB,CAC3D,CAAC;AACJ,CAAC"}

package/dist/git-worktree.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Git worktree per task (spec 006). Each run gets its own branch
+ * `cez/<id8>` checked out into `.ai/cezar/worktrees/<runId>` so agents never
+ * touch the user's working tree. Pattern ported from github-janitor's
+ * `git.ts` (createWorktree / autosaveCommit), minus the bare clone — we're
+ * already inside a working copy. Everything degrades: helpers never throw
+ * except `createWorktree`, whose failure the caller turns into a note.
+ */
+/** Repo-relative home of all task worktrees (gitignored via .ai/cezar/.gitignore). */
+export declare const WORKTREES_DIR = ".ai/cezar/worktrees";
+export declare function branchFor(runId: string): string;
+/**
+ * Resolve the configured base branch to something `git worktree add` can
+ * fork from: the branch itself, else its remote-tracking ref (base exists
+ * only on origin), else null — the caller falls back to the current branch
+ * with a note. Never throws.
+ */
+export declare function resolveBaseRef(repoRoot: string, base: string): Promise<string | null>;
+export declare function worktreePathFor(repoRoot: string, runId: string): string;
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    /** Branch name the worktree was forked from (commit sha when HEAD was detached). */
+    baseBranch: string;
+}
+/**
+ * Establish the task worktree idempotently. Besides the fresh
+ * `git worktree add -b` path, recover the two normal restart/deletion cases:
+ * reuse an already-registered task worktree, or reattach a surviving task
+ * branch after its directory/registration was removed. Existing non-empty
+ * unregistered paths are never deleted because they may hold recoverable
+ * uncommitted work.
+ */
+export declare function createWorktree(repoRoot: string, runId: string, baseBranch: string): Promise<WorktreeInfo>;
+/**
+ * Best-effort on-disk size of a worktree directory in bytes, via POSIX
+ * `du -sk` (kibibytes → bytes). Returns `null` when `du` is unavailable —
+ * including all of Windows, where `du` is not a command — or on any error.
+ * Never throws and never blocks: worktree retention is count-based, so a null
+ * size only blanks the panel's size column, it does not affect reclamation.
+ */
+export declare function worktreeSizeBytes(path: string): Promise<number | null>;
+/** Remove a task worktree and its branch. Best effort — never throws. */
+export declare function removeWorktree(repoRoot: string, worktreePath: string, branch?: string): Promise<void>;
+/**
+ * Stage and commit everything in the worktree as a "cezar autosave" commit
+ * (janitor pattern) — the agent's progress is always recoverable from the
+ * `cez/<id8>` branch history. Quietly a no-op when nothing changed.
+ */
+export declare function autosaveCommit(dir: string): Promise<boolean>;
+/**
+ * "What did this task change": diff of the worktree (committed + uncommitted
+ * + untracked, via `add -N`) against the merge-base with its base branch —
+ * so the diff stays *this task's* changes even after the base moves on.
+ */
+export declare function worktreeDiff(worktreePath: string, baseBranch: string, cap?: number): Promise<string>;
+/**
+ * `git diff --stat` version of `worktreeDiff` (spec 010 — the variant
+ * comparison columns). Same merge-base anchoring; returns '' on any failure.
+ */
+export declare function worktreeDiffStat(worktreePath: string, baseBranch: string): Promise<string>;
+/** Aggregate diff numbers (#389) — the shape stored on `RunRecord.diffStat`. */
+export interface DiffStat {
+    adds: number;
+    dels: number;
+    files: number;
+}
+/**
+ * Parse `git diff --shortstat` output — " 3 files changed, 10 insertions(+),
+ * 2 deletions(-)". Every part is optional: insertions-only and deletions-only
+ * diffs omit the other counter, and an empty diff prints nothing at all
+ * (→ all zeros). The wording is stable porcelain English — git does not
+ * localize `--shortstat` — so matching the words is safe.
+ */
+export declare function parseShortstat(s: string): DiffStat;
+/**
+ * `git diff --shortstat` of the worktree vs its base (#389) — same
+ * merge-base anchoring and intent-to-add as `worktreeDiff`, parsed into
+ * numbers. Null on git failure (the caller notes it, never fails the run);
+ * an empty diff is a valid all-zero stat.
+ */
+export declare function worktreeShortstat(worktreePath: string, baseBranch: string): Promise<DiffStat | null>;
+/**
+ * Startup reconcile: `git worktree prune` + remove every directory under
+ * `.ai/cezar/worktrees/` whose run id is no longer in the store (and its
+ * branch). Returns the removed run ids for the boot log. Never throws.
+ */
+export declare function pruneOrphans(repoRoot: string, validIds: ReadonlySet<string>): Promise<string[]>;