@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/workflows/run/types.d.ts

@@ -0,0 +1,293 @@
+import type { Home } from '../../home/home.ts';
+import type { TrackedWork } from './tracked-work.ts';
+import type { HumanWaitEntry } from '../../contract/index.js';
+import type { AskRequest } from '../../core/ask.ts';
+import type { UiEventSink } from '../../runs/ui-event-sink.ts';
+import type { ScheduleTaskAnswer, ScheduleTaskRequest, ScheduledTasksAnswer, ScheduledTasksRequest } from '../../contract/index.js';
+import type { ContentBlock, RunnerId, ToolGrant } from '../../core/agent-runner.ts';
+import type { CiToolSession } from '../../ci-wait/controller.ts';
+import type { LaunchConfig, LaunchSource } from './launch-read-resolver.ts';
+import type { WorkerAccountBinding } from '../../delegation/execution-identity.ts';
+import type { DelegationSession } from '../../delegation/provision.ts';
+import type { RunRecord } from '../../runs/store.ts';
+import type { ActiveRun } from '../active-run.ts';
+import type { PastedContent, PersistedAttachment } from '../pasted-content.ts';
+import type { WorkflowDef, WorkflowStepDef } from '../types.ts';
+import type { QuestionAnswerSource } from './worker-questions.ts';
+export type { FileBlock, PastedContent, PersistedAttachment } from '../pasted-content.ts';
+export type TurnTail = 'none' | 'visible' | 'silent';
+type ReadonlyValue<T> = T extends object ? {
+    readonly [K in keyof T]: ReadonlyValue<T[K]>;
+} : T;
+export type DelegationExecutionSettings = ReadonlyValue<{
+    cwd: string;
+    runner: RunnerId;
+    model?: string | undefined;
+    modelIdentity?: string | undefined;
+    effort?: string | undefined;
+    agentProfile: string;
+    accountBinding?: WorkerAccountBinding | undefined;
+    systemPrompt?: string | undefined;
+    allowedTools?: string[] | undefined;
+    bashAllowlist?: string[] | undefined;
+}>;
+export interface StartRunInput {
+    task: string;
+    model?: string | undefined;
+    /** Reasoning-effort pin (#45). Canonical `low`/`medium`/`high`/`xhigh`/`max`.
+     *  Unset = harness default. Same class of override as `model`. */
+    effort?: string | undefined;
+    /** Agent backend chosen for this task (GUI). Unset = the config default. */
+    runner?: RunnerId | undefined;
+    /** Agent account for this task (spec 2026-07-29-agent-profiles), applying to steps that run
+     *  on `runner`. Unset = the project's own selection. Persisted on the record so the choice
+     *  survives into resume and Continue, and so the thread can say which account did the work. */
+    agentProfile?: string | undefined;
+    /** Attachments pasted into the new-task form — persisted when the run is created and
+     *  delivered once, with the first agent step's opening message. Images ride along as blocks the
+     *  model can view; a file (#950) only ever reaches the agent as the path it was written to. */
+    images?: PastedContent[] | undefined;
+    /** 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 | undefined;
+    /** Composer opt-out (#worktree-toggle): `false` runs the task in the repo
+     *  working tree instead of an isolated worktree. Undefined/`true` keeps the
+     *  default per-task worktree. */
+    worktree?: boolean | undefined;
+    /** Autonomous mode (#autonomous): eligible turn ends auto-continue until done
+     *  or the safety cap. Native asks, input delivery and lifecycle waits still apply. */
+    autonomous?: boolean | undefined;
+    archiveWhenDone?: boolean | undefined;
+    autoMergePr?: boolean | undefined;
+    /** Task access (hearsay-tools/cezarion#2784). Omitted = on; the record stores the explicit value. */
+    allowWorkers?: boolean | undefined;
+    allowMessaging?: boolean | undefined;
+    /** Task webhook opt-in (#589). Persisted on the record at creation; read from there after. */
+    notify?: boolean | undefined;
+    /** Attachments from the queued prompt stack (#472), re-encoded from disk by
+     *  `hydrateQueuedInput` at dequeue. Kept separate from `images` because those
+     *  are persisted into `taskImages` by `startRun()` — folding
+     *  the stack's (already-persisted) files in there would write duplicate files
+     *  and make the task bubble render the stack's images as its own. In-memory
+     *  only: rebuilt from the record on every hydration, never persisted. */
+    stackedImages?: ContentBlock[] | undefined;
+    /** Automation provenance (hearsay-tools/cezarion#1465). Written by `createRun` in the row that
+     *  creates the run, so a receipt never points at nothing after a crash. */
+    automation?: RunRecord['automation'];
+    automationTrigger?: RunRecord['automationTrigger'];
+}
+export interface PendingContinuation {
+    stepId: string;
+    sessionId: string | undefined;
+    backend: RunnerId;
+    prompt: string;
+    /** Attachments the user pasted into the follow-up composer — images to view, files (#950) to
+     *  be given the path of. Persisted when the continuation actually opens, not here. */
+    images: PastedContent[];
+    /** When this continuation joined the line (epoch ms). A queued continuation is a wake of a run
+     *  already in progress, so it goes ahead of unstarted runs, oldest first (`nextLineEntry`). */
+    lineJoinedAt: number;
+}
+/** What `execute` writes to its run's event stream. */
+export type ExecutionEmit = (event: {
+    type: string;
+    stepId?: string;
+    [k: string]: unknown;
+}) => void;
+/** One `execute` call: what its phases share. */
+export type Execution = {
+    runId: string;
+    workflow: WorkflowDef;
+    input: LaunchSource;
+    startAt: number;
+    state: ActiveRun;
+    emit: ExecutionEmit;
+};
+/** What `startExecution` resolved before the first step. */
+export type ExecutionLaunch = {
+    config: LaunchConfig;
+    taskBackend: RunnerId;
+    extraSystemPrompt: string | undefined;
+    /** The run record as it was before `startExecution` recorded the start. */
+    ownedRun: RunRecord | undefined;
+    /** An owned worker's workspace. */
+    owned: Extract<NonNullable<RunRecord['delegation']>, {
+        role: 'worker';
+    }>['workspace'] | undefined;
+};
+/** The state of `execute`'s step loop, which `settleExecution` reads once the loop ended. */
+export type StepLoop = {
+    /** A failed check's output, handed to the agent step its retry loops back to. */
+    checkFailure: string | null;
+    runError: string | null;
+    deliveryCapped: boolean;
+    /** An earlier step whose session closed without a done (hearsay-tools/cezarion#1620). */
+    incompleteStepId?: string;
+};
+/** What a launched session's callbacks share (hearsay-tools/cezarion#1632): the turn in progress
+ *  and the session's first fault. */
+export type SessionTurn = {
+    /** The turn's v1 assistant text, read for its task-reference markers at the turn end. */
+    text: string;
+    tail: TurnTail;
+    /** The delay a Claude ScheduleWakeup call asked for in this turn. */
+    scheduleWakeup: number | null | undefined;
+    /** The fault that ended the session; an agent input error recorded before it wins. */
+    sessionError: string | undefined;
+};
+/** The delegation capability and the CI tools one launch provisioned. */
+export type LaunchDelegation = DelegationSession | undefined;
+export type LaunchCiTools = CiToolSession | undefined;
+/** A launch's opening message, and whether its session-start context carries the handoff. */
+export type LaunchOpening = {
+    userPrompt: string;
+    handoffInjected: boolean;
+};
+/** The account a step's session runs under: its profile, environment and account binding. */
+export type StepProfile = {
+    env: Record<string, string>;
+    profileId: string;
+    accountBinding?: WorkerAccountBinding | undefined;
+};
+/** The model and effort a fresh step's session runs with. */
+export type StepModel = {
+    backendModel: string | undefined;
+    effectiveEffort: string | undefined;
+};
+/** What `runAgentStep` resolved before it starts the step's session. */
+export type StepSessionLaunch = {
+    step: WorkflowStepDef;
+    sessionId: string;
+    images: ContentBlock[] | undefined;
+    opening: LaunchOpening;
+    skillPrompt: string | undefined;
+    extraSystemPrompt: string | undefined;
+    toolGrant: ToolGrant;
+    profile: StepProfile;
+    model: StepModel;
+    delegation: LaunchDelegation;
+    webhooksPart: string | undefined;
+    ciTools: LaunchCiTools;
+};
+/** An owned worker's delegation record. */
+export type WorkerDelegationRecord = Extract<NonNullable<RunRecord['delegation']>, {
+    role: 'worker';
+}>;
+/** A Continue's opening message and what it carries: the checkpoint it replays, who sent it when it
+ *  answers a worker's pending question (hearsay-tools/cezarion#505, hearsay-tools/cezarion#2410), and the images and
+ *  attachments it hands over. */
+export type ContinuationOpening = {
+    prompt: string;
+    checkpoint: RunRecord['continuationMessage'];
+    answerSource?: QuestionAnswerSource;
+    openingImages: ContentBlock[];
+    attachments: PersistedAttachment[];
+};
+/** The human ask a Continue's opening message answers, and the human waits that answer settles
+ *  when the opening turn ends. The turn end clears `askSeq`. */
+export type OpeningAnswer = {
+    askSeq: number | undefined;
+    waits: string[];
+    answerSource?: QuestionAnswerSource;
+};
+/** What a Continue resolved before its pre-spawn checks: the step that owns its session, the
+ *  workflow step it extends, and its tool grant, model, effort and account. */
+export type ContinuationSettings = {
+    owningStep: RunRecord['steps'][number] | undefined;
+    toolsStep: WorkflowStepDef | undefined;
+    toolGrant: ToolGrant;
+    backendModel: string | undefined;
+    effort: string | undefined;
+    profile: StepProfile;
+    /** The run's extra system prompt, which workers inherit. */
+    extraSystemPrompt: string | undefined;
+};
+/** The continued step's skill playbook, for the system prompt or for the fallback system prompt of
+ *  an in-thread resume, and the skill files the opening message names. */
+export type ContinuationSkills = {
+    skillPrompt: string | undefined;
+    fallbackSkillPrompt: string | undefined;
+    files: Map<string, string>;
+};
+/** What `runContinuation` resolved before it starts the Continue's session. */
+export type ContinuationSessionLaunch = {
+    stepId: string;
+    sessionId: string | undefined;
+    prompt: string;
+    setupNote: string | undefined;
+    opening: ContinuationOpening;
+    skills: ContinuationSkills;
+    skipSkillOnResume: boolean;
+    settings: ContinuationSettings;
+    delegation: LaunchDelegation;
+    webhooksPart: string | undefined;
+    ciTools: LaunchCiTools;
+};
+/** The workflow remainder a successful Continue queues once its session is released. */
+export type ContinuationClose = {
+    resumeWorkflow?: {
+        workflow: WorkflowDef;
+        input: StartRunInput;
+        startAt: number;
+    } | undefined;
+};
+/** #469: why destroy could not prove a crashed generation's termination. */
+export type WorkerTerminationBlocker = {
+    kind: 'unreadable';
+} | {
+    kind: 'controller';
+    pid: number;
+} | {
+    kind: 'processes';
+    pids: number[];
+};
+/** hearsay-tools/cezarion#1465: what `startServer` hands a manager for the schedule tools. */
+export type AutomationToolService = {
+    scheduleTask(request: ScheduleTaskRequest): Promise<ScheduleTaskAnswer>;
+    scheduledTasks(request: ScheduledTasksRequest): Promise<ScheduledTasksAnswer>;
+};
+/** Shared dependencies for state-owning run modules. */
+export interface RunModuleContext {
+    home: Home;
+    readonly work: TrackedWork;
+    store: import('../../runs/store.ts').RunStore;
+    repoRoot: string;
+    dataDir: string;
+    semaphore: import('../../workspace/semaphore.ts').WorkspaceSemaphore;
+    /** Builds every runner this manager starts: the entry point's choice (hearsay-tools/cezarion#2939). */
+    createRunner: import('../../core/agent-runner.ts').RunnerFactory;
+    disposed(): boolean;
+    /** Sweeps the project's merged branches after a retention pass (hearsay-tools/cezarion#2268).
+     *  `serve` supplies it; `cez run` and tests leave it out. */
+    sweepBranches?: ((keep: number) => void) | undefined;
+    /** The process's tool activity tracker (spec 2026-11-05-live-activity-view): every run's UI
+     *  event sink feeds it. `serve` supplies it; `cez run` and tests leave it out. */
+    toolActivity?: import('../../activity/tool-activity.ts').ToolActivityFeed | undefined;
+}
+/** What a turn end said, as the entry that settles it reads it (hearsay-tools/cezarion#1525). The
+ *  turn end reads it from the turn; a later entry from what `parkAfterAck` kept (`boundaryTurn`). */
+export type SettledTurn = {
+    stepId: string | undefined;
+    monitoring: boolean;
+    humanGate: boolean;
+    /** This turn's ask, which the turn end surfaces as a card; a later entry has none. */
+    ask: AskRequest | null;
+    humanWait?: HumanWaitEntry | undefined;
+    sink?: UiEventSink;
+    done: boolean;
+    doneRequest?: ActiveRun['boundary']['doneRequested'];
+    /** The turn answered the no-wait nudge. The completion cause's flag is `completionNudgeAnswered`. */
+    nudgedLastTurn: boolean;
+    scheduleWakeup?: number | null | undefined;
+};
+/** What re-reading a message's persisted attachments yields: viewable blocks for the images, and
+ *  a path for every attachment including the files that have no block. */
+export interface PersistedAttachments {
+    blocks: ContentBlock[];
+    attachments: PersistedAttachment[];
+}
+/** Only the synchronous delivery of a human answer uses the budget its reset replaced. */
+export type HumanAnswerBudget = {
+    spent: number;
+};

package/dist/workflows/run/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workflows/run/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/workflows/run/types.ts"],"names":[],"mappings":""}

package/dist/workflows/run/usage-accounting.d.ts

@@ -0,0 +1,49 @@
+import type { RunnerId } from '../../core/agent-runner.ts';
+import type { UiEvent } from '../../core/ui-events.ts';
+import type { RunStore, StepState } from '../../runs/store.ts';
+import type { ActiveRun } from '../active-run.ts';
+export interface UsageAccountingHost {
+    isDisposedDelegatedRun(runId: string): boolean;
+}
+/** Durable directional-usage accounting state for the current runner
+ * invocation. Provider-local turn ids are unique only within this epoch. */
+export declare class UsageInvocation {
+    #private;
+    constructor(stepId: string, epoch: number);
+    get stepId(): string;
+    get epoch(): number;
+    get observed(): boolean;
+    get startedTurns(): ReadonlySet<string>;
+    get recordedTurns(): ReadonlySet<string>;
+}
+/** Accounting state has one writer; every public property is a live read view. */
+export declare class UsageGroup {
+    #private;
+    constructor();
+    /** Last cumulative Claude report per provider session during this process. */
+    get reportedClaudeCost(): ReadonlyMap<string, number> | undefined;
+    get usageInvocation(): UsageInvocation | undefined;
+}
+export declare function createUsageGroup(): UsageGroup;
+/** Persist the invocation checkpoint before launching a runner. A throw or
+ * process exit before `turn.started` therefore leaves a durable mismatch. */
+export declare function beginUsageInvocation(store: RunStore, runId: string, state: ActiveRun, stepId: string): void;
+/** A runner whose declared `costReport` is `cumulative` (Claude's `total_cost_usd`) reports the
+ * conversation total, including turns in Continue steps; its reports become deltas here. The
+ * others report new cost since their previous report. */
+export declare function recordReportedCost(store: RunStore, runId: string, stepId: string, state: ActiveRun, backend: RunnerId, reportedUsd: number): void;
+/** Fold backend-neutral completed-turn usage into the current step exactly
+ * once. Invocation/turn counters are written before the event reaches the
+ * NDJSON sink so crashes cannot preserve a falsely complete subtotal. */
+export declare function recordUsageUiEvent(store: RunStore, runId: string, state: ActiveRun, event: UiEvent): void;
+/** Usage completeness is a crash boundary, unlike high-frequency token
+ * snapshots: the checkpoint must reach `runs.json` before the runner starts
+ * or the matching UI event is persisted and forwarded. */
+export declare function persistUsageCheckpoint(store: RunStore, runId: string, stepId: string, patch: Partial<Omit<StepState, 'id'>>): void;
+/**
+ * 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.
+ */
+export declare function recordUsagePeaks(store: RunStore, host: UsageAccountingHost, runId: string): void;

package/dist/workflows/run/usage-accounting.js

@@ -0,0 +1,213 @@
+import { ReadonlyMapView, ReadonlySetView } from './readonly-collections.js';
+import { RUNNER_FACTS } from '../../core/runner-facts.js';
+import { unregisterRunProcess } from '../../core/process-usage.js';
+// These capabilities stay in this module. Static initialization grants access to private
+// state without adding a public mutation method to a group, invocation or read facade.
+let invocationWrites;
+/** Durable directional-usage accounting state for the current runner
+ * invocation. Provider-local turn ids are unique only within this epoch. */
+export class UsageInvocation {
+    #stepId;
+    #epoch;
+    #observed = false;
+    #startedTurns = new Set();
+    #recordedTurns = new Set();
+    #startedView = new ReadonlySetView(this.#startedTurns);
+    #recordedView = new ReadonlySetView(this.#recordedTurns);
+    constructor(stepId, epoch) {
+        this.#stepId = stepId;
+        this.#epoch = epoch;
+        Object.freeze(this);
+    }
+    get stepId() { return this.#stepId; }
+    get epoch() { return this.#epoch; }
+    get observed() { return this.#observed; }
+    get startedTurns() { return this.#startedView; }
+    get recordedTurns() { return this.#recordedView; }
+    static {
+        invocationWrites = {
+            start(invocation, turnId) { invocation.#startedTurns.add(turnId); invocation.#observed = true; },
+            record(invocation, turnId) { invocation.#recordedTurns.add(turnId); },
+        };
+    }
+}
+let usageWrites;
+/** Accounting state has one writer; every public property is a live read view. */
+export class UsageGroup {
+    #reportedClaudeCost;
+    #costView;
+    #usageInvocation;
+    constructor() { Object.freeze(this); }
+    /** Last cumulative Claude report per provider session during this process. */
+    get reportedClaudeCost() { return this.#costView; }
+    get usageInvocation() { return this.#usageInvocation; }
+    static {
+        usageWrites = {
+            begin(group, stepId, epoch) { group.#usageInvocation = new UsageInvocation(stepId, epoch); },
+            costs(group) {
+                if (!group.#reportedClaudeCost) {
+                    group.#reportedClaudeCost = new Map();
+                    group.#costView = new ReadonlyMapView(group.#reportedClaudeCost);
+                }
+                return group.#reportedClaudeCost;
+            },
+        };
+    }
+}
+for (const type of [UsageGroup, UsageInvocation]) {
+    Object.freeze(type.prototype);
+    Object.freeze(type);
+}
+export function createUsageGroup() { return new UsageGroup(); }
+/** Persist the invocation checkpoint before launching a runner. A throw or
+ * process exit before `turn.started` therefore leaves a durable mismatch. */
+export function beginUsageInvocation(store, runId, state, stepId) {
+    const step = store.getRun(runId)?.steps.find((candidate) => candidate.id === stepId);
+    if (!step)
+        return;
+    const epoch = (step.usageInvocationEpoch ?? 0) + 1;
+    persistUsageCheckpoint(store, runId, stepId, {
+        usageInvocationEpoch: epoch,
+        usageInvocationsStarted: (step.usageInvocationsStarted ?? 0) + 1,
+    });
+    usageWrites.begin(state.usage, stepId, epoch);
+}
+/** A runner whose declared `costReport` is `cumulative` (Claude's `total_cost_usd`) reports the
+ * conversation total, including turns in Continue steps; its reports become deltas here. The
+ * others report new cost since their previous report. */
+export function recordReportedCost(store, runId, stepId, state, backend, reportedUsd) {
+    if (!Number.isFinite(reportedUsd) || reportedUsd < 0)
+        return;
+    const run = store.getRun(runId);
+    const step = run?.steps.find((candidate) => candidate.id === stepId);
+    if (!run || !step)
+        return;
+    let delta = reportedUsd;
+    if (RUNNER_FACTS[backend].costReport === 'cumulative') {
+        const sessionKey = step.sessionId ?? step.id;
+        const costs = usageWrites.costs(state.usage);
+        let previous = costs.get(sessionKey);
+        if (previous === undefined) {
+            previous = restoreCumulativeSessionCost(store, runId, stepId, run, step, reportedUsd);
+        }
+        delta = Math.max(0, reportedUsd - previous);
+        costs.set(sessionKey, Math.max(previous, reportedUsd));
+    }
+    store.updateStep(runId, stepId, { costUsd: (step.costUsd ?? 0) + delta });
+}
+/** Rebuild a cumulative session's checkpoint and restore reports missing from step totals. */
+function restoreCumulativeSessionCost(store, runId, stepId, run, step, reportedUsd) {
+    // The current cost event was appended immediately before this call. Rebuild
+    // the checkpoint from raw reports, since older records summed cumulative
+    // reports into costUsd and cannot be used as the baseline on Continue.
+    const events = store.readEvents(runId);
+    let currentReportIndex = -1;
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.type === 'cost' && event.stepId === stepId && event.usd === reportedUsd) {
+            currentReportIndex = index;
+            break;
+        }
+    }
+    const sessionStepIds = new Set(run.steps.filter((candidate) => {
+        // A step with no recorded backend ran on the default runner, Claude.
+        return RUNNER_FACTS[candidate.backend ?? 'claude'].costReport === 'cumulative' && (step.sessionId
+            ? candidate.sessionId === step.sessionId
+            : candidate.id === step.id);
+    }).map((candidate) => candidate.id));
+    let previous = 0;
+    const priorCostByStep = new Map();
+    for (let index = 0; index < events.length; index++) {
+        if (index === currentReportIndex)
+            continue;
+        const event = events[index];
+        if (event.type === 'cost' && event.stepId && sessionStepIds.has(event.stepId) &&
+            typeof event.usd === 'number' && Number.isFinite(event.usd) && event.usd >= 0) {
+            priorCostByStep.set(event.stepId, (priorCostByStep.get(event.stepId) ?? 0) + Math.max(0, event.usd - previous));
+            previous = Math.max(previous, event.usd);
+        }
+    }
+    // The event log is appended before the step total. A process exit between
+    // those writes leaves a report whose USD never reached the run record.
+    // Restore missing amounts, while preserving older inflated totals rather
+    // than silently migrating historical run state.
+    for (const [priorStepId, expectedCost] of priorCostByStep) {
+        const priorStep = run.steps.find((candidate) => candidate.id === priorStepId);
+        if (priorStep && (priorStep.costUsd === undefined || priorStep.costUsd < expectedCost)) {
+            store.updateStep(runId, priorStepId, { costUsd: expectedCost });
+        }
+    }
+    return previous;
+}
+/** Fold backend-neutral completed-turn usage into the current step exactly
+ * once. Invocation/turn counters are written before the event reaches the
+ * NDJSON sink so crashes cannot preserve a falsely complete subtotal. */
+export function recordUsageUiEvent(store, runId, state, event) {
+    const invocation = state.usage.usageInvocation;
+    if (!invocation)
+        return;
+    const step = store.getRun(runId)?.steps.find((candidate) => candidate.id === invocation.stepId);
+    if (!step)
+        return;
+    if (event.type === 'turn.started') {
+        if (invocation.startedTurns.has(event.turnId))
+            return;
+        const firstObservedTurn = !invocation.observed;
+        invocationWrites.start(invocation, event.turnId);
+        persistUsageCheckpoint(store, runId, invocation.stepId, {
+            usageTurnsStarted: (step.usageTurnsStarted ?? 0) + 1,
+            ...(firstObservedTurn
+                ? { usageInvocationsObserved: (step.usageInvocationsObserved ?? 0) + 1 }
+                : {}),
+        });
+        return;
+    }
+    if (event.type !== 'turn.completed')
+        return;
+    recordCompletedTurnUsage(store, runId, invocation, step, event);
+}
+/** Record valid completed-turn usage after a matching start, once per turn. */
+function recordCompletedTurnUsage(store, runId, invocation, step, event) {
+    if (!invocation.startedTurns.has(event.turnId) || invocation.recordedTurns.has(event.turnId))
+        return;
+    const input = event.usage?.input;
+    const output = event.usage?.output;
+    if (typeof input !== 'number' ||
+        !Number.isFinite(input) ||
+        input < 0 ||
+        typeof output !== 'number' ||
+        !Number.isFinite(output) ||
+        output < 0) {
+        return;
+    }
+    invocationWrites.record(invocation, event.turnId);
+    persistUsageCheckpoint(store, runId, invocation.stepId, {
+        inputTokens: (step.inputTokens ?? 0) + input,
+        outputTokens: (step.outputTokens ?? 0) + output,
+        usageTurnsRecorded: (step.usageTurnsRecorded ?? 0) + 1,
+    });
+}
+/** Usage completeness is a crash boundary, unlike high-frequency token
+ * snapshots: the checkpoint must reach `runs.json` before the runner starts
+ * or the matching UI event is persisted and forwarded. */
+export function persistUsageCheckpoint(store, runId, stepId, patch) {
+    store.updateStep(runId, stepId, patch);
+    store.flush();
+}
+/**
+ * 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.
+ */
+export function recordUsagePeaks(store, host, runId) {
+    const peaks = unregisterRunProcess(runId);
+    if (!peaks || host.isDisposedDelegatedRun(runId))
+        return;
+    const run = store.getRun(runId);
+    store.updateRun(runId, {
+        peakRssBytes: Math.max(run?.peakRssBytes ?? 0, peaks.peakRssBytes),
+        peakProcCount: Math.max(run?.peakProcCount ?? 0, peaks.peakProcCount),
+    });
+}
+//# sourceMappingURL=usage-accounting.js.map

package/dist/workflows/run/usage-accounting.js.map

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