@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/trajectory/aggregate.js

@@ -0,0 +1,208 @@
+/**
+ * Trajectory aggregate — the hotspot view's data and the session totals.
+ *
+ * The ledger answers "what happened, in order". This module answers the other
+ * question a long session raises: **where did the time go**. Chronological
+ * order is the worst order for that, so everything here is grouped and ranked
+ * instead: cost per tool, cost per model phase (decode vs. waiting for the
+ * first token vs. retry backoff), cost per turn.
+ *
+ * Three details make the numbers trustworthy rather than merely plausible:
+ *
+ * - **Own duration only.** A turn's cost is its own bracket, never the sum of
+ *   its children — summing both would double-count every tool inside it.
+ * - **No fabricated spans.** A step that produced no stream output (no
+ *   `assistant/chunk` pre-0.1.5, no embedded settlement stream since — the
+ *   request failed, or the log predates chunk capture) contributes no TTFT and
+ *   no decode sample rather than a zero that would drag the average down.
+ * - **Bursts expand.** A folded run is one ledger row but N calls; the counts
+ *   and totals here are over calls, so `count` matches what actually ran.
+ */
+/** Zero token accounting, used as the reduce seed. */
+const NO_TOKENS = { input: 0, output: 0, think: 0, cacheRead: 0, cacheWrite: 0 };
+/**
+ * Visit every logical call in ledger order, expanding burst rows.
+ *
+ * @param nodes - The folded ledger.
+ * @param visit - Receives each call node plus the ledger index of the row it
+ *   is displayed under (the burst row's index, for folded members).
+ */
+export function forEachCall(nodes, visit) {
+    for (let index = 0; index < nodes.length; index++) {
+        const node = nodes[index];
+        if (node.burst !== undefined) {
+            for (const member of node.burst.members)
+                visit(member, index);
+            continue;
+        }
+        if (node.kind === 'tool' || node.kind === 'subtool')
+            visit(node, index);
+    }
+}
+/** Get or create a bucket, remembering the first ledger index that hit it. */
+function bucket(map, key, ledgerIndex) {
+    let slot = map.get(key);
+    if (slot === undefined) {
+        slot = { totalMs: 0, count: 0, tokens: 0, firstIndex: ledgerIndex };
+        map.set(key, slot);
+    }
+    return slot;
+}
+/** Materialize and rank buckets. */
+function rank(map, sort) {
+    const rows = [];
+    for (const [label, slot] of map) {
+        rows.push({
+            label,
+            totalMs: slot.totalMs,
+            count: slot.count,
+            tokens: slot.tokens,
+            error: slot.error,
+            firstIndex: slot.firstIndex,
+        });
+    }
+    return sortRows(rows, sort);
+}
+/**
+ * Rank hotspot rows by the active sort key.
+ *
+ * Ties break on label so the order is total — an unstable order would make
+ * rows jump between frames while the session streams.
+ */
+export function sortRows(rows, sort) {
+    const key = (row) => sort === 'count' ? row.count : sort === 'tokens' ? row.tokens : row.totalMs;
+    return [...rows].sort((a, b) => key(b) - key(a) || a.label.localeCompare(b.label));
+}
+/**
+ * Derive the hotspot groups and session totals from a projection.
+ *
+ * @param build - The current projection.
+ * @param sort - Ranking key for the tool and turn groups.
+ * @returns Ranked groups plus the counters the scene header and status badge
+ *   read. Pure: nothing here mutates the build.
+ */
+export function aggregate(build, sort = 'duration') {
+    const { nodes, timing, counts } = build;
+    const tools = new Map();
+    const turns = new Map();
+    let calls = 0;
+    let toolMs = 0;
+    let retryMs = 0;
+    let steps = 0;
+    let turnCount = 0;
+    let tokens = NO_TOKENS;
+    forEachCall(nodes, (node, ledgerIndex) => {
+        calls += 1;
+        const slot = bucket(tools, node.label, ledgerIndex);
+        slot.count += 1;
+        slot.totalMs += node.durationMs ?? 0;
+        toolMs += node.durationMs ?? 0;
+        if (node.status === 'error')
+            slot.error = true;
+    });
+    for (let index = 0; index < nodes.length; index++) {
+        const node = nodes[index];
+        switch (node.kind) {
+            case 'turn': {
+                turnCount += 1;
+                const slot = bucket(turns, node.label, index);
+                slot.count += 1;
+                slot.totalMs += node.durationMs ?? 0;
+                if (node.status === 'error')
+                    slot.error = true;
+                break;
+            }
+            case 'step':
+                steps += 1;
+                break;
+            case 'retry':
+                retryMs += node.durationMs ?? 0;
+                break;
+            default:
+                break;
+        }
+        if (node.tokens !== undefined) {
+            tokens = {
+                input: tokens.input + node.tokens.input,
+                output: tokens.output + node.tokens.output,
+                think: tokens.think + node.tokens.think,
+                cacheRead: tokens.cacheRead + node.tokens.cacheRead,
+                cacheWrite: tokens.cacheWrite + node.tokens.cacheWrite,
+            };
+        }
+    }
+    // Attribute each step's token cost to its turn, so the turn ranking can be
+    // sorted by tokens as well as by wall-clock.
+    for (const node of nodes) {
+        if (node.tokens === undefined)
+            continue;
+        const slot = turns.get(`turn ${node.turn}`);
+        if (slot !== undefined) {
+            slot.tokens += node.tokens.input + node.tokens.output + node.tokens.think;
+        }
+    }
+    const { decodeMs, ttftMs, ttftSamples } = modelTiming(timing);
+    const model = [];
+    if (decodeMs > 0)
+        model.push({ label: 'decode', totalMs: decodeMs, count: ttftSamples, tokens: tokens.output, firstIndex: 0 });
+    if (ttftSamples > 0)
+        model.push({ label: 'ttft', totalMs: ttftMs, count: ttftSamples, tokens: 0, firstIndex: 0 });
+    if (retryMs > 0 || counts.retries > 0) {
+        const firstRetry = nodes.findIndex(node => node.kind === 'retry');
+        model.push({ label: 'retry', totalMs: retryMs, count: counts.retries, tokens: 0, error: true, firstIndex: Math.max(0, firstRetry) });
+    }
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    const spanMs = first === undefined || last === undefined ? 0 : Math.max(0, lastTime(last) - first.time);
+    const totals = {
+        turns: turnCount,
+        steps,
+        rows: nodes.length,
+        calls,
+        // Failure and retry counts come from the fold's own O(1) counters rather
+        // than being recomputed here: the status-line chip reads them on every
+        // chat frame, and two independent tallies of the same session would
+        // eventually disagree — which is exactly what they did.
+        errors: counts.errors,
+        retries: counts.retries,
+        spanMs,
+        toolMs,
+        decodeMs,
+        ttftMs,
+        ttftSamples,
+        retryMs,
+        tokens,
+    };
+    return {
+        tools: rank(tools, sort),
+        model: sortRows(model, sort),
+        turns: rank(turns, sort),
+        totals,
+    };
+}
+/** The latest instant a node covers — its close, or its start when open. */
+function lastTime(node) {
+    return node.time + (node.durationMs ?? 0);
+}
+/**
+ * Sum decode and time-to-first-token across steps.
+ *
+ * A step contributes only when it actually streamed: `firstChunk` present
+ * means the model produced output, so `firstChunk - startTime` is a real TTFT
+ * and `lastChunk - firstChunk` a real decode span. Steps without chunks are
+ * skipped entirely rather than counted as zero.
+ */
+function modelTiming(timing) {
+    let decodeMs = 0;
+    let ttftMs = 0;
+    let ttftSamples = 0;
+    for (const slot of timing.values()) {
+        if (slot.firstChunk === undefined)
+            continue;
+        ttftMs += Math.max(0, slot.firstChunk - slot.startTime);
+        ttftSamples += 1;
+        if (slot.lastChunk !== undefined)
+            decodeMs += Math.max(0, slot.lastChunk - slot.firstChunk);
+    }
+    return { decodeMs, ttftMs, ttftSamples };
+}

package/lib/types/dsh-adapter/trajectory/guards.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Structural guards for the session events the trajectory projection reads.
+ *
+ * ## Why guards instead of the declared types
+ *
+ * `SessionEventMap` declares a dozen-odd core event types. Everything else in
+ * the `KNOWN_SESSION_EVENT_TYPES` vocabulary arrives through *module
+ * augmentation* from the plugin that owns it — `llm/retry` from the LLM
+ * layer, `hook/*` from the hook runner, `tool/code-dispatch*` (pre-0.1.5) /
+ * `tool/ptc-dispatch*` (0.1.5) from the code/PTC runtime. Those declaration
+ * packages are not all in this bundle's dependency
+ * graph, so `event.type === 'llm/retry'` does not even type-check here: the
+ * literal is not a member of the union TypeScript can see.
+ *
+ * The answer is the one the adapter boundary already prescribes for upstream
+ * coupling — widen once, at a single auditable point ({@link asRawEvents}),
+ * then validate shapes at runtime. Every guard below is a *total function*:
+ * a payload that does not match returns `undefined` and the fold skips that
+ * event. An upstream release that renames a field degrades the trajectory by
+ * one row kind; it never throws inside a render.
+ *
+ * ## Why these exact shapes
+ *
+ * Each guard was written against payloads decoded out of real session logs
+ * (39 sessions, 96,836 events) rather than from documentation, and the
+ * corresponding fixture in `verify-trace-projection.mjs` reproduces the same
+ * shape. Where a field was absent from every observed sample it is optional
+ * here, so a future harness that starts emitting it is picked up for free.
+ */
+import type { TimedStreamChunk } from '@deepseek-ai/dsh-llm';
+import type { RawTrajEvent } from '../../adapter/ports/channel-view.js';
+export type { RawTrajEvent } from '../../adapter/ports/channel-view.js';
+/**
+ * A session event reduced to the envelope the projection relies on. Only
+ * `type`, `seq` and `time` are contractual across every event; `data` is
+ * deliberately `unknown` so nothing downstream can read it without a guard.
+ */
+/**
+ * The single widening point for the whole trajectory feature.
+ *
+ * `SessionEvent`'s `type` is a union of the *locally declared* event names;
+ * the projection must also reason about augmented names it cannot see in the
+ * type graph. Widening the array element to {@link RawTrajEvent} keeps every
+ * field the projection reads (envelope) while forcing `data` through the
+ * guards below. The cast is structural-only — no property is added, removed,
+ * or reinterpreted — and it is the one place a reviewer must check.
+ *
+ * @param events - The session's immutable event snapshot.
+ * @returns The same array, typed for guard-mediated access.
+ */
+export declare function asRawEvents(events: readonly RawTrajEvent[]): readonly RawTrajEvent[];
+/**
+ * An `llm/retry` payload.
+ *
+ * Observed shape: `{ retryId, turn, step, provider, mode, policyKey, retry,
+ * maxRetries, delayMs, failure: { message, code } }`. `retryId` pairs the
+ * event with the `llm/retry-started` that follows; `failure.code` is the
+ * classifier (`RATE_LIMIT` / `SERVER` / `TIMEOUT` / `TRANSPORT` /
+ * `EMPTY_RESPONSE`) shown as the row's error identity.
+ */
+export interface RetryPayload {
+    readonly retryId: string;
+    readonly turn?: number;
+    readonly step?: number;
+    /** Provider whose request failed — shown as an inspector fact. */
+    readonly provider?: string;
+    readonly retry: number;
+    readonly maxRetries?: number;
+    readonly delayMs: number;
+    readonly code?: string;
+    readonly message?: string;
+}
+/** Narrow an `llm/retry` payload; `undefined` when the shape does not match. */
+export declare function readRetry(data: unknown): RetryPayload | undefined;
+/** The `retryId` of an `llm/retry-started`, used to close the retry bracket. */
+export declare function readRetryStarted(data: unknown): string | undefined;
+/**
+ * A `tool/code-dispatch*` / `tool/ptc-dispatch*` payload — the code runner's
+ * nested tool calls, and the only source of SUBTOOL rows.
+ *
+ * The dispatch bracket was renamed with the runtime: pre-0.1.5 logs carry
+ * `tool/code-dispatch-start` ↔ `tool/code-dispatch`, 0.1.5 logs carry
+ * `tool/ptc-dispatch-start` ↔ `tool/ptc-dispatch`, paired by `subCallId` in
+ * both generations; `rootCallId`/`parentCallId` give the enclosing
+ * model-issued call. The payload shape is identical across the rename, so
+ * this one guard serves both. `subCallId` is treated as an OPAQUE pairing
+ * key: the fold never parses the `<parent>:code:<n>` / `<parent>:ptc:<n>`
+ * infix, so a renamed (or future) id scheme cannot break pairing.
+ * `arguments` is a structured value here (unlike `tool/call`, whose
+ * `arguments` is the model's raw JSON string), so it is stringified for the
+ * preview at guard time — the payload object is small and already
+ * materialized by the log reader.
+ */
+export interface DispatchPayload {
+    readonly subCallId: string;
+    readonly rootCallId?: string;
+    readonly parentCallId?: string;
+    readonly name: string;
+    readonly args?: string;
+    readonly isError?: boolean;
+}
+/** Narrow a `tool/code-dispatch*` / `tool/ptc-dispatch*` payload. */
+export declare function readDispatch(data: unknown): DispatchPayload | undefined;
+/**
+ * Expand the compact `stream` of a V3 `assistant/message` / `assistant/attempt`
+ * into timed chunks, or `undefined` when the event carries no usable stream.
+ *
+ * V3 logs replace per-token `assistant/chunk` events with one compact
+ * `AssistantStreamRecord[]` embedded in the settlement event. Upstream's
+ * `expandAssistantStream` is the validating read path for that record list —
+ * and it landed with the record type itself (0.1.5), so the binding is
+ * feature-detected through the namespace rather than named-imported: a
+ * pre-0.1.5 host lacks the export, and a named import would fail the whole
+ * module at link time instead of degrading this one read. The same
+ * never-throw contract as every guard here applies on both axes: a missing
+ * expander or a malformed record (the expander throws `TypeError`) yields
+ * `undefined`, and the fold simply contributes no stream timing.
+ */
+export declare function readAssistantStream(data: unknown): readonly TimedStreamChunk[] | undefined;
+/**
+ * A `request/header` payload, reduced to the route facts the trajectory
+ * shows: which model actually served this request, at which effort. The full
+ * header (system prompt, tool catalog) stays in the log for the inspector.
+ */
+export interface RequestHeaderPayload {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly effort?: string;
+    readonly reason?: string;
+}
+/** Narrow a `request/header` payload. */
+export declare function readRequestHeader(data: unknown): RequestHeaderPayload | undefined;
+/** A `subagent/descriptor` payload: what kind of child this session is. */
+export interface SubagentPayload {
+    readonly label?: string;
+    readonly model?: string;
+    readonly mode?: string;
+}
+/** Narrow a `subagent/descriptor` payload. */
+export declare function readSubagent(data: unknown): SubagentPayload | undefined;
+/** An `approval/asked` payload. `id` pairs it with the `approval/decided`. */
+export interface ApprovalAskedPayload {
+    readonly id: string;
+    readonly toolName?: string;
+    readonly callId?: string;
+    readonly reason?: string;
+}
+/** Narrow an `approval/asked` payload. */
+export declare function readApprovalAsked(data: unknown): ApprovalAskedPayload | undefined;
+/**
+ * An `approval/decided` payload. `outcome` is a union upstream; it is read as
+ * a plain string here and only compared against the denial spellings, so a
+ * new outcome name degrades to "not a denial" rather than to a crash.
+ */
+export interface ApprovalDecidedPayload {
+    readonly id: string;
+    readonly outcome: string;
+}
+/** Narrow an `approval/decided` payload. */
+export declare function readApprovalDecided(data: unknown): ApprovalDecidedPayload | undefined;
+/** True when an approval outcome should render as an error. */
+export declare function isApprovalDenied(outcome: string): boolean;
+/** A `hook/invoked` payload. */
+export interface HookPayload {
+    readonly id?: string;
+    readonly name: string;
+    readonly event?: string;
+}
+/**
+ * Narrow a `hook/invoked` / `hook/result` payload. No sample appeared in the
+ * surveyed logs (no hooks were configured), so the accepted key spellings are
+ * deliberately broad: any of `name`/`hook`/`hookName` identifies the hook.
+ */
+export declare function readHook(data: unknown): HookPayload | undefined;
+/** A `sandbox/mode`, `plan/mode`, `approval/policy` or `permission/preset` value. */
+export declare function readModeValue(data: unknown): string | undefined;
+/** A `command/run` payload — the slash command the user dispatched. */
+export declare function readCommandRun(data: unknown): {
+    name: string;
+    args?: string;
+} | undefined;
+/** A `compaction/*` payload; every field is optional across the bracket. */
+export interface CompactionPayload {
+    readonly id?: string;
+    readonly reason?: string;
+    readonly removed?: number;
+}
+/** Narrow a `compaction/start` or `compaction/end` payload. */
+export declare function readCompaction(data: unknown): CompactionPayload;
+/** A `todo/write` payload, reduced to the progress counters. */
+export declare function readTodos(data: unknown): {
+    done: number;
+    total: number;
+    current?: string;
+} | undefined;
+//# sourceMappingURL=guards.d.ts.map

package/lib/types/dsh-adapter/trajectory/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/trajectory/guards.ts"],"names":[],"mappings":"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"}

package/lib/types/dsh-adapter/trajectory/guards.js

@@ -0,0 +1,273 @@
+/**
+ * Structural guards for the session events the trajectory projection reads.
+ *
+ * ## Why guards instead of the declared types
+ *
+ * `SessionEventMap` declares a dozen-odd core event types. Everything else in
+ * the `KNOWN_SESSION_EVENT_TYPES` vocabulary arrives through *module
+ * augmentation* from the plugin that owns it — `llm/retry` from the LLM
+ * layer, `hook/*` from the hook runner, `tool/code-dispatch*` (pre-0.1.5) /
+ * `tool/ptc-dispatch*` (0.1.5) from the code/PTC runtime. Those declaration
+ * packages are not all in this bundle's dependency
+ * graph, so `event.type === 'llm/retry'` does not even type-check here: the
+ * literal is not a member of the union TypeScript can see.
+ *
+ * The answer is the one the adapter boundary already prescribes for upstream
+ * coupling — widen once, at a single auditable point ({@link asRawEvents}),
+ * then validate shapes at runtime. Every guard below is a *total function*:
+ * a payload that does not match returns `undefined` and the fold skips that
+ * event. An upstream release that renames a field degrades the trajectory by
+ * one row kind; it never throws inside a render.
+ *
+ * ## Why these exact shapes
+ *
+ * Each guard was written against payloads decoded out of real session logs
+ * (39 sessions, 96,836 events) rather than from documentation, and the
+ * corresponding fixture in `verify-trace-projection.mjs` reproduces the same
+ * shape. Where a field was absent from every observed sample it is optional
+ * here, so a future harness that starts emitting it is picked up for free.
+ */
+import * as dshLlm from '@deepseek-ai/dsh-llm';
+/**
+ * A session event reduced to the envelope the projection relies on. Only
+ * `type`, `seq` and `time` are contractual across every event; `data` is
+ * deliberately `unknown` so nothing downstream can read it without a guard.
+ */
+/**
+ * The single widening point for the whole trajectory feature.
+ *
+ * `SessionEvent`'s `type` is a union of the *locally declared* event names;
+ * the projection must also reason about augmented names it cannot see in the
+ * type graph. Widening the array element to {@link RawTrajEvent} keeps every
+ * field the projection reads (envelope) while forcing `data` through the
+ * guards below. The cast is structural-only — no property is added, removed,
+ * or reinterpreted — and it is the one place a reviewer must check.
+ *
+ * @param events - The session's immutable event snapshot.
+ * @returns The same array, typed for guard-mediated access.
+ */
+export function asRawEvents(events) {
+    return events;
+}
+/** True for a non-null object — the precondition of every guard below. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Read a string property, or `undefined` when absent or the wrong type. */
+function str(source, key) {
+    const value = source[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Read a finite number property, or `undefined` when absent or non-finite. */
+function num(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Narrow an `llm/retry` payload; `undefined` when the shape does not match. */
+export function readRetry(data) {
+    if (!isRecord(data))
+        return undefined;
+    const retryId = str(data, 'retryId');
+    const retry = num(data, 'retry');
+    const delayMs = num(data, 'delayMs');
+    if (retryId === undefined || retry === undefined || delayMs === undefined)
+        return undefined;
+    const failure = isRecord(data.failure) ? data.failure : undefined;
+    return {
+        retryId,
+        turn: num(data, 'turn'),
+        step: num(data, 'step'),
+        provider: str(data, 'provider'),
+        retry,
+        maxRetries: num(data, 'maxRetries'),
+        delayMs,
+        code: failure === undefined ? undefined : str(failure, 'code'),
+        message: failure === undefined ? undefined : str(failure, 'message'),
+    };
+}
+/** The `retryId` of an `llm/retry-started`, used to close the retry bracket. */
+export function readRetryStarted(data) {
+    return isRecord(data) ? str(data, 'retryId') : undefined;
+}
+/** Narrow a `tool/code-dispatch*` / `tool/ptc-dispatch*` payload. */
+export function readDispatch(data) {
+    if (!isRecord(data))
+        return undefined;
+    const subCallId = str(data, 'subCallId');
+    const name = str(data, 'name');
+    if (subCallId === undefined || name === undefined)
+        return undefined;
+    const rawArgs = data.arguments;
+    let args;
+    if (typeof rawArgs === 'string')
+        args = rawArgs;
+    else if (rawArgs !== undefined) {
+        // Structured arguments: a bounded stringify. JSON.stringify throws on
+        // circular references, which a JSON-validated log cannot contain — but
+        // the guard contract is "never throw", so it is caught regardless.
+        try {
+            args = JSON.stringify(rawArgs);
+        }
+        catch {
+            args = undefined;
+        }
+    }
+    const isError = data.isError;
+    return {
+        subCallId,
+        rootCallId: str(data, 'rootCallId'),
+        parentCallId: str(data, 'parentCallId'),
+        name,
+        args,
+        isError: typeof isError === 'boolean' ? isError : undefined,
+    };
+}
+/**
+ * Expand the compact `stream` of a V3 `assistant/message` / `assistant/attempt`
+ * into timed chunks, or `undefined` when the event carries no usable stream.
+ *
+ * V3 logs replace per-token `assistant/chunk` events with one compact
+ * `AssistantStreamRecord[]` embedded in the settlement event. Upstream's
+ * `expandAssistantStream` is the validating read path for that record list —
+ * and it landed with the record type itself (0.1.5), so the binding is
+ * feature-detected through the namespace rather than named-imported: a
+ * pre-0.1.5 host lacks the export, and a named import would fail the whole
+ * module at link time instead of degrading this one read. The same
+ * never-throw contract as every guard here applies on both axes: a missing
+ * expander or a malformed record (the expander throws `TypeError`) yields
+ * `undefined`, and the fold simply contributes no stream timing.
+ */
+export function readAssistantStream(data) {
+    if (!isRecord(data))
+        return undefined;
+    const stream = data.stream;
+    if (!Array.isArray(stream) || stream.length === 0)
+        return undefined;
+    const expand = dshLlm.expandAssistantStream;
+    if (typeof expand !== 'function')
+        return undefined;
+    try {
+        return expand(stream);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Narrow a `request/header` payload. */
+export function readRequestHeader(data) {
+    if (!isRecord(data))
+        return undefined;
+    const header = isRecord(data.header) ? data.header : undefined;
+    if (header === undefined)
+        return undefined;
+    const config = isRecord(header.config) ? header.config : undefined;
+    return {
+        provider: config === undefined ? undefined : str(config, 'provider'),
+        model: config === undefined ? undefined : str(config, 'model'),
+        effort: config === undefined ? undefined : str(config, 'reasoningEffort'),
+        reason: str(data, 'reason'),
+    };
+}
+/** Narrow a `subagent/descriptor` payload. */
+export function readSubagent(data) {
+    if (!isRecord(data))
+        return undefined;
+    return {
+        label: str(data, 'label'),
+        model: str(data, 'agentModel'),
+        mode: str(data, 'mode'),
+    };
+}
+/** Narrow an `approval/asked` payload. */
+export function readApprovalAsked(data) {
+    if (!isRecord(data))
+        return undefined;
+    const id = str(data, 'id');
+    if (id === undefined)
+        return undefined;
+    return {
+        id,
+        toolName: str(data, 'toolName'),
+        callId: str(data, 'callId'),
+        reason: str(data, 'reason'),
+    };
+}
+/** Narrow an `approval/decided` payload. */
+export function readApprovalDecided(data) {
+    if (!isRecord(data))
+        return undefined;
+    const id = str(data, 'id');
+    if (id === undefined)
+        return undefined;
+    const raw = data.outcome;
+    const outcome = typeof raw === 'string'
+        ? raw
+        : isRecord(raw)
+            ? (str(raw, 'kind') ?? str(raw, 'decision') ?? '')
+            : '';
+    return { id, outcome };
+}
+/** Outcomes that mark an approval row as failed. */
+const DENIED = new Set(['denied', 'deny', 'rejected', 'cancelled', 'canceled', 'unavailable']);
+/** True when an approval outcome should render as an error. */
+export function isApprovalDenied(outcome) {
+    return DENIED.has(outcome.toLowerCase());
+}
+/**
+ * Narrow a `hook/invoked` / `hook/result` payload. No sample appeared in the
+ * surveyed logs (no hooks were configured), so the accepted key spellings are
+ * deliberately broad: any of `name`/`hook`/`hookName` identifies the hook.
+ */
+export function readHook(data) {
+    if (!isRecord(data))
+        return undefined;
+    const name = str(data, 'name') ?? str(data, 'hook') ?? str(data, 'hookName');
+    if (name === undefined)
+        return undefined;
+    return { id: str(data, 'id') ?? str(data, 'invocationId'), name, event: str(data, 'event') };
+}
+/** A `sandbox/mode`, `plan/mode`, `approval/policy` or `permission/preset` value. */
+export function readModeValue(data) {
+    if (!isRecord(data))
+        return undefined;
+    return str(data, 'mode') ?? str(data, 'policy') ?? str(data, 'preset') ?? str(data, 'name');
+}
+/** A `command/run` payload — the slash command the user dispatched. */
+export function readCommandRun(data) {
+    if (!isRecord(data))
+        return undefined;
+    const name = str(data, 'name');
+    if (name === undefined)
+        return undefined;
+    return { name, args: str(data, 'args') };
+}
+/** Narrow a `compaction/start` or `compaction/end` payload. */
+export function readCompaction(data) {
+    if (!isRecord(data))
+        return {};
+    return {
+        id: str(data, 'id') ?? str(data, 'compactionId'),
+        reason: str(data, 'reason') ?? str(data, 'trigger'),
+        removed: num(data, 'removed') ?? num(data, 'pruned'),
+    };
+}
+/** A `todo/write` payload, reduced to the progress counters. */
+export function readTodos(data) {
+    if (!isRecord(data))
+        return undefined;
+    const todos = data.todos;
+    if (!Array.isArray(todos))
+        return undefined;
+    let done = 0;
+    let current;
+    for (const item of todos) {
+        if (!isRecord(item))
+            continue;
+        const status = str(item, 'status');
+        if (status === 'completed')
+            done += 1;
+        else if (status === 'in_progress' && current === undefined)
+            current = str(item, 'content');
+    }
+    return { done, total: todos.length, current };
+}