@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/agent-log.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Agent output formatters. Every unattended agent streams machine-readable
+ * events on stdout; each formatter turns its agent's stream into the same
+ * concise one-line activity summaries so the control center's live log reads
+ * the same whichever agent is running, and reports tool calls so stage
+ * progress can be derived from what the agent does.
+ */
+import type { AgentName, AgentUsage } from './types.js';
+export interface AgentLogFormatter {
+    /** Why the agent stopped without a successful result, once it reported one. */
+    stopReason: string | undefined;
+    /**
+     * True when the agent stopped because of a transient failure outside the
+     * task, such as an API server error mid-response, so the same session can
+     * be resumed instead of the run failing.
+     */
+    transientFailure?: boolean;
+    /** The agent's own session id, when it reported one, so the session can be resumed. */
+    sessionId?: string | undefined;
+    /**
+     * Token usage this agent session has reported so far, or undefined until the
+     * stream carries any. One formatter is one process launch, so `sessions` is
+     * always 1 here; callers merge resumed sessions with `mergeAgentUsage`.
+     */
+    readonly usage: AgentUsage | undefined;
+    /**
+     * Called for every tool call the agent makes. Tool names and inputs are
+     * normalized to Claude's vocabulary (`Bash` with `command`, `Write` with
+     * `file_path`, `mcp__<server>__<tool>`) so one classifier serves every agent.
+     */
+    onToolCall: ((tool: string, input: JsonRecord) => void) | undefined;
+    push(chunk: Buffer | string): string[];
+    finish(): string[];
+    /**
+     * What the agent is doing while its stream is quiet. Once nothing has been
+     * written for the heartbeat interval this returns one progress line naming
+     * the current phase and how long it has lasted — thinking, writing a long
+     * reply, or waiting for a tool call — so a silent stretch reads as
+     * progress instead of a hang. Callers poll it on a timer; `push` also
+     * checks it, so a stream that is busy but prints nothing reports too.
+     */
+    heartbeat(now?: number): string[];
+}
+export interface AgentLogFormatterOptions {
+    /** Clock override for tests. */
+    now?: () => number;
+    /** Quiet time before a heartbeat line is written. */
+    heartbeatMs?: number;
+}
+/** Quiet time before a formatter names what the agent is doing. */
+export declare const AGENT_LOG_HEARTBEAT_MS = 30000;
+export declare function createAgentLogFormatter(agent: AgentName, options?: AgentLogFormatterOptions): AgentLogFormatter;
+export type JsonRecord = Record<string, unknown>;
+/**
+ * Combine the usage of several agent sessions (a run that resumed, or the
+ * plan and authoring phases of one request) into one total. Counters,
+ * sessions, turns, and durations add up; the context high-water mark is the
+ * largest seen; cost is present when any part reported one.
+ */
+export declare function mergeAgentUsage(...parts: Array<AgentUsage | undefined>): AgentUsage | undefined;
+/** `1234` → `1.2k`, `1_234_567` → `1.2M`; whole thousands drop the `.0`. */
+export declare function formatTokenCount(count: number): string;
+/**
+ * One line for the UI: `1.2M tokens · 98% cached · $1.42 · 3 sessions`. Cost
+ * is omitted when the agent never reported one; sessions when there was one.
+ */
+export declare function formatAgentUsage(usage: AgentUsage): string;
+/** Convert Claude Code's JSONL stream into concise, durable UI log lines. */
+export declare class ClaudeStreamLogFormatter implements AgentLogFormatter {
+    private buffer;
+    private readonly blocks;
+    private readonly tools;
+    private readonly now;
+    private readonly pulse;
+    private streamedContent;
+    private lastText;
+    /** Why Claude stopped without a successful result, once its result event arrives. */
+    stopReason: string | undefined;
+    /** True when the stop was a transient API failure rather than a task outcome. */
+    transientFailure: boolean;
+    /** Claude's session id from its init event, so a cut-off session can be resumed. */
+    sessionId: string | undefined;
+    /** Called for every tool call Claude makes, with the parsed input when it is readable. */
+    onToolCall: ((tool: string, input: JsonRecord) => void) | undefined;
+    /**
+     * Usage per assistant message id. With `--include-partial-messages` the same
+     * assistant message is emitted once per content block, each carrying that
+     * message's usage, so the last report per id wins instead of adding up.
+     */
+    private readonly messageUsage;
+    /** Assistant messages that carried usage but no id; nothing to de-duplicate on. */
+    private anonymousUsage;
+    private maxContextTokens;
+    /** The result event's cumulative usage, preferred over the running sum once it arrives. */
+    private resultTokens;
+    private resultTurns;
+    private resultDurationMs;
+    private resultCostUsd;
+    private readonly clock;
+    constructor(options?: AgentLogFormatterOptions);
+    heartbeat(now?: number): string[];
+    get usage(): AgentUsage | undefined;
+    push(chunk: Buffer | string): string[];
+    finish(): string[];
+    private formatLine;
+    private formatStreamEvent;
+    /** Claude Code runs the tool as soon as its call is complete; the result arrives as a user message. */
+    private beginToolCall;
+    /** A block or tool result just ended: the next event is either another tool result or Claude's own. */
+    private awaitNextStep;
+    private recordAssistantUsage;
+    /**
+     * The result event's totals: its `usage` object when present, else the sum
+     * of its per-model `modelUsage` map, else nothing (the running sum stands).
+     */
+    private recordResultUsage;
+    private formatAssistantMessage;
+    private formatToolResults;
+    private formatSystem;
+    private formatResult;
+    private textLines;
+}
+/**
+ * Failures that come from the Claude API or the network rather than from the
+ * task: the session is intact and continues where it stopped when resumed.
+ */
+export declare function isTransientClaudeApiFailure(text: string): boolean;
+/**
+ * Codex `exec --json` emits one JSON object per line: thread and turn
+ * lifecycle events plus `item.started` / `item.completed` for each message,
+ * command, file change, and MCP call.
+ */
+export declare class CodexStreamLogFormatter implements AgentLogFormatter {
+    private readonly lines;
+    /** Items Codex has started, by id, with the time they started. */
+    private readonly startedItems;
+    private readonly now;
+    private readonly pulse;
+    private lastText;
+    stopReason: string | undefined;
+    onToolCall: ((tool: string, input: JsonRecord) => void) | undefined;
+    /** Sum of every `turn.completed` usage, or the last cumulative `token_count` total when the stream carries one. */
+    private tokens;
+    private turns;
+    private maxContextTokens;
+    private readonly clock;
+    constructor(options?: AgentLogFormatterOptions);
+    heartbeat(now?: number): string[];
+    get usage(): AgentUsage | undefined;
+    /**
+     * Codex counts cached prompt tokens inside `input_tokens`; Claude reports
+     * them separately. Split them out so "input" means uncached input for every
+     * agent and the four counters add up to the total either way.
+     */
+    private static tokensOf;
+    push(chunk: Buffer | string): string[];
+    finish(): string[];
+    private formatLine;
+    private itemStarted;
+    private itemCompleted;
+    private activity;
+    /** Report the call in Claude's tool vocabulary so one classifier fits all agents. */
+    private reportTool;
+    private textLines;
+}
+/**
+ * Gemini CLI `--output-format stream-json` emits init, message, tool_use,
+ * tool_result, error, and result events. Assistant text arrives as deltas
+ * that are joined until the next event of another kind.
+ */
+export declare class GeminiStreamLogFormatter implements AgentLogFormatter {
+    private readonly lines;
+    private readonly tools;
+    private readonly now;
+    private readonly pulse;
+    private assistantText;
+    private lastText;
+    stopReason: string | undefined;
+    onToolCall: ((tool: string, input: JsonRecord) => void) | undefined;
+    /** Set from the result event's `stats` when it carries token counts; Gemini reports nothing per message. */
+    usage: AgentUsage | undefined;
+    private readonly clock;
+    constructor(options?: AgentLogFormatterOptions);
+    heartbeat(now?: number): string[];
+    push(chunk: Buffer | string): string[];
+    finish(): string[];
+    private formatLine;
+    private reportTool;
+    private flushText;
+    private textLines;
+}
+export declare function compactLogText(value: string, maximum?: number): string;
+export declare function formatLogDuration(milliseconds: number): string;
+export declare function jsonRecord(value: unknown): JsonRecord | undefined;
+export declare function stringField(record: JsonRecord, key: string): string | undefined;
+export declare function numberField(record: JsonRecord, key: string): number | undefined;
+//# sourceMappingURL=agent-log.d.ts.map