@songsid/agend 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/log-steps.d.ts

@@ -0,0 +1,169 @@
+import { type LongLine } from "./transcript-jsonl.js";
+export type StepKind = "user" | "assistant" | "tool" | "error" | "turn_end" | "state";
+/** What a tool call does, for its icon and words on the page. */
+export type StepCat = "read" | "edit" | "search" | "run" | "web" | "mcp" | "agent" | "plan" | "message" | "other";
+export type StepStatus = "running" | "done" | "failed" | "interrupted";
+export interface LogStep {
+    /**
+     * Stable for the step's life, and the same whichever range of the transcript is parsed: a tool call's own id, or
+     * `o<byte offset of its record>.<n>`. A later emission with the same id updates it (a call, then its result) — the
+     * page merges it into what it shows.
+     */
+    id: string;
+    /** The turn it belongs to: the transcript's own id for it (claude: the prompt record's uuid; codex: turn_id); "" before the first. */
+    turn: string;
+    /** When the record was written (ms), or 0 when the record has no time. */
+    ts: number;
+    kind: StepKind;
+    /** tool: the CLI's tool name ("Bash", "exec_command", "fs_read"). */
+    tool?: string;
+    cat?: StepCat;
+    /** tool: what it acts on — a path, a command, a pattern, `server:tool` — masked, ≤ SUBJECT_MAX. */
+    subject?: string;
+    /** tool: its arguments as text (JSON or the command), masked, ≤ INPUT_MAX — the page shows it on demand. */
+    input?: string;
+    inputCut?: number;
+    status?: StepStatus;
+    durationMs?: number;
+    exitCode?: number;
+    /** user / assistant / error text, or a tool's result, masked and cut (≤ TEXT_MAX / RESULT_MAX). */
+    body?: string;
+    /** Characters cut from `body` (0 or absent: nothing), or the bytes of a result too long to read (`bodyBytes`). */
+    bodyCut?: number;
+    bodyBytes?: number;
+    /** state: what happened ("compacted"); error: a status code. */
+    note?: string;
+}
+export declare const SUBJECT_MAX = 300;
+export declare const INPUT_MAX = 2000;
+export declare const TEXT_MAX = 4000;
+export declare const RESULT_MAX = 4000;
+/**
+ * Mask secret values in `text` (#1788 review P1: every common way a secret is written, since arguments and results are
+ * shown): a private key block; a secret-named JSON field, flag or assignment (any identifier containing password,
+ * secret, token, api/access/private key, credential — DB_PASSWORD, "api_key", --password); then the bubble's redactor
+ * (known key shapes, Bearer, URL userinfo); then long mixed-case opaque tokens. Numbers, booleans and null are kept.
+ */
+export declare function maskSecrets(text: string): string;
+/**
+ * `text` masked and cut to `max` characters (never inside a surrogate pair), with how many were cut. Only the part that
+ * can be shown (plus MASK_MARGIN) is masked: a tool result can be megabytes.
+ */
+export declare function bounded(text: string, max: number): {
+    text: string;
+    cut: number;
+};
+/** A "tool" that is the model's thinking (kiro's `thinking`): never a step (the user's decision: thinking is never shown). */
+export declare const THINKING_TOOLS: ReadonlySet<string>;
+/** The category and subject of a tool call, from its name and input. An unknown tool: "other", its name. */
+export declare function describeTool(name: string, input: unknown): {
+    cat: StepCat;
+    subject?: string;
+};
+/** What a parser gives back for one record: the steps it created or changed (each a complete, latest copy). */
+export type Emission = LogStep[];
+declare abstract class StepParser {
+    protected turn: string;
+    private open;
+    private n;
+    /** The byte offset of the record being parsed (-1: unknown), for ids that do not depend on where parsing began. */
+    protected at: number;
+    private k;
+    /** Steps in the order they were first seen (updated in place). */
+    readonly steps: LogStep[];
+    protected abstract record(entry: Record<string, unknown>): Emission;
+    /** A record too long to parse: what its head still says (by default nothing). */
+    protected long(_head: string, _bytes: number): Emission;
+    /** One transcript line (JSON text) or a long line's head: the steps it created or changed. Malformed: none. */
+    push(item: string | LongLine, at?: number): Emission;
+    protected add(step: Omit<LogStep, "id" | "turn"> & {
+        id?: string;
+    }): LogStep;
+    protected openTool(id: string): LogStep | undefined;
+    protected close(id: string): LogStep | undefined;
+    /** A new turn (`key`: the transcript's id for it): every tool still running in the last one is interrupted. */
+    protected newTurn(key: string): Emission;
+    protected endOpen(status: StepStatus): Emission;
+}
+/**
+ * claude-code: the JSONL at statusline.json's transcript_path. user: a prompt (string content; `isMeta` records and
+ * tool results are not prompts); assistant: `text` (thinking never), `tool_use` (running); a `tool_result` (by
+ * `tool_use_id`, `is_error`) completes its call; an API error is an assistant record with `isApiErrorMessage`;
+ * `system` `turn_duration` ends a turn, `compact_boundary` is a state.
+ */
+export declare class ClaudeStepParser extends StepParser {
+    private started;
+    protected record(e: Record<string, unknown>): Emission;
+    private result;
+    /** A tool result too long to parse (most long claude lines are): its call completes, with the start of its text. */
+    protected long(head: string, bytes: number): Emission;
+}
+/**
+ * codex: the rollout JSONL. `response_item`: `message` (user / assistant), `function_call` / `custom_tool_call` /
+ * `local_shell_call` (running, by `call_id`) and their `*_output` (exec_command's output says its exit code and wall
+ * time); `event_msg`: `task_started` (a turn), `task_complete` / `turn_aborted` (its end), and — on versions that
+ * write them — `item_completed` items: CommandExecution (a command, with exit code and duration), McpToolCall,
+ * FileChange. Their AgentMessage / UserMessage duplicate the response items and are not shown twice; reasoning never.
+ */
+export declare class CodexStepParser extends StepParser {
+    private started;
+    protected record(e: Record<string, unknown>): Emission;
+    private item;
+    /** A long rollout line: an output completes its call with the start of its text; a call starts by its name. */
+    protected long(head: string, bytes: number): Emission;
+}
+/**
+ * kiro TUI (v2): the session's message log `<KIRO_HOME>/sessions/cli/<id>.jsonl` — `Prompt` (a turn: its text),
+ * `AssistantMessage` (`text`; `toolUse` running, by `toolUseId`; `thinking` never), `ToolResults` (`toolResult`
+ * completes its call: status, stdout/stderr, exit status). Only a Prompt carries a time.
+ */
+export declare class KiroV2StepParser extends StepParser {
+    private skipped;
+    protected record(e: Record<string, unknown>): Emission;
+    /**
+     * A tool result too long to parse (a command's whole output): its first call completes with the start of its output
+     * and the exit code the head shows. A long reply or prompt is read whole by the Log instead (log-service.ts).
+     */
+    protected long(head: string, bytes: number): Emission;
+}
+/**
+ * kiro classic (v1): one conversation row's `history` — each entry a user side (`Prompt`, `ToolUseResults`,
+ * `CancelledToolUses`) and an assistant side (`ToolUse` with its text and calls, or `Response`). The row is rewritten
+ * as the conversation goes on, so its steps are the whole history's; ids are by entry (`h<i>.<n>`) and calls by their
+ * own id. Read in the kiro worker (never on the fleet loop); `max` bounds what comes back.
+ */
+export declare function kiroClassicSteps(value: unknown, max?: number): {
+    steps: LogStep[];
+    entries: number;
+};
+export declare const BACKFILL_MAX_BYTES: number;
+/**
+ * The last records of a JSONL transcript, in file order, each with its byte offset — complete lines, and long lines (over LINE_MAX_BYTES) by
+ * their head and size — read backwards in BACKFILL_CHUNK chunks, at most `maxBytes`, stopping once `maxLines` records
+ * are held. A record still being written (after the last line end) is not included. `truncated`: older records exist
+ * that were not read. Async and bounded — for an on-demand backfill when a Log is opened, never a whole-file read.
+ * `end` (a record start from an earlier read) reads the records before it instead: the older page.
+ *
+ * Of the record that crosses a chunk's left edge only its first LINE_MAX_BYTES + LONG_HEAD_BYTES are kept (with its
+ * exact length): enough for a short record whole, or for a long one's head.
+ */
+/** A record and where it starts in the file (its byte offset). */
+export interface TailRecord {
+    record: string | LongLine;
+    at: number;
+}
+export declare function readTailRecords(path: string, opts?: {
+    maxBytes?: number;
+    maxLines?: number;
+    end?: number;
+}): Promise<{
+    records: TailRecord[];
+    truncated: boolean;
+    end: number;
+}>;
+/** Parse `records` (file order) with `parser` and return its last `max` steps. */
+export declare function stepsOf(parser: {
+    push(item: string | LongLine, at?: number): Emission;
+    steps: LogStep[];
+}, records: readonly TailRecord[], max?: number): LogStep[];
+export {};