@yaklabs-ai/plugin-sdk 0.13.6 → 0.13.8

package/dist/transcript-review.d.ts

@@ -0,0 +1,310 @@
+/** Builds a {@link TranscriptReview} from a session's records streamed in commit order. */
+export declare function createTranscriptReview(options?: TranscriptReviewOptions): TranscriptReviewBuilder;
+
+/** An instant as UTC ISO-8601 with milliseconds (`2026-10-15T07:00:00.000Z`). */
+export declare function formatReviewInstant(ms: number): string;
+
+declare type Obj = Readonly<Record<string, unknown>>;
+
+/** A content array's blocks; a string content is one text block. */
+export declare function reviewContentBlocks(content: unknown): readonly Obj[];
+
+/** The text blocks of a content value, joined by newlines. */
+export declare function reviewContentText(content: unknown): string;
+
+/** A context record's `{customType, details, content}`, from either stored spelling. */
+export declare function reviewContextOf(entry: unknown): {
+    readonly customType?: string;
+    readonly details?: Obj;
+    readonly content: unknown;
+} | undefined;
+
+/** What one entry is, read without a fold (also what the fold records per entry). */
+export declare interface ReviewEntryDescription {
+    readonly entryId?: string;
+    /** The stored-transcript kind (`user`, `tool_result`, `custom_message:<t>`, `custom:<t>`, ...). */
+    readonly kind: string;
+    readonly recordClass: TranscriptReviewRecordClass;
+    /** A context record's or custom entry's type. */
+    readonly customType?: string;
+    /** The record's own time: the message timestamp, else the entry's, else a run marker's. */
+    readonly timestampMs?: number;
+    /** A human message's `clientIntentId`; a context record's `details.clientIntentId`. */
+    readonly clientIntentId?: string;
+}
+
+/**
+ * Epoch ms from a number or an ISO-8601 instant with an offset (`2026-10-15T07:00:00Z`);
+ * `undefined` otherwise. Stored entries carry either, by generation.
+ */
+export declare function reviewInstantMs(value: unknown): number | undefined;
+
+/** Records that hold system prompt content: never expanded, never shown. */
+export declare const SYSTEM_PROMPT_CUSTOM_TYPES: ReadonlySet<string>;
+
+/**
+ * Context records that carry a task or its result, and that a reader of a span must see:
+ * a child's report, a collaborator's message, a finished background task, a person's answer
+ * delivered as context (`ui_action`), pasted content, a sent draft, a service turn. Only these
+ * may open a span when they carry the opening input's id. `dynamic_context` also carries
+ * `details.clientIntentId` and is never one of them.
+ */
+export declare const TASK_CONTEXT_TYPES: ReadonlySet<string>;
+
+/** One `toolCall` block of an assistant message. */
+export declare interface ToolCallAttempt {
+    /** 0-based, in store order. */
+    readonly index: number;
+    readonly position: number;
+    readonly entryId?: string;
+    /** The block's index in the message content. */
+    readonly block: number;
+    readonly toolCallId?: string;
+    readonly tool: string;
+    /**
+     * A label for the call: `command` for shell tools, else `path` / `uri` / `url`, else
+     * `command`. At most {@link ATTEMPT_SUBJECT_MAX_CHARS} characters, so a fold over a long
+     * session never holds whole commands; the full call is one `&entry=` read away.
+     */
+    readonly subject?: string;
+    /** The subject's full length in characters, when it was cut to the label limit. */
+    readonly subjectLength?: number;
+    /** Every string argument value (at any depth) that starts with `<scheme>://`. */
+    readonly uris: readonly string[];
+    /** Position of the result paired to it. */
+    readonly result?: number;
+    /** Results that answered its id again after it was paired. */
+    readonly extraResults: readonly number[];
+    /** Results that matched it among several open attempts. */
+    readonly ambiguousResults: readonly number[];
+}
+
+export declare interface ToolCallOutcome {
+    /** `ambiguous` when a result matched it among several open attempts and none was paired. */
+    readonly status: "ok" | "failed" | "no-result" | "ambiguous";
+    readonly isError: boolean;
+    readonly exitCode?: number;
+    readonly timedOut: boolean;
+    readonly resultPosition?: number;
+    readonly resultEntryId?: string;
+    readonly firstErrorLine?: string;
+}
+
+/** One tool result record. */
+export declare interface ToolResultFact {
+    readonly position: number;
+    readonly entryId?: string;
+    readonly toolCallId?: string;
+    readonly tool?: string;
+    readonly pairing: ToolResultPairing;
+    /** The paired attempt (`paired`), or the answered attempt (`extra`). */
+    readonly attempt?: number;
+    /** The open attempts it matched (`ambiguous`). */
+    readonly candidates: readonly number[];
+    readonly isError: boolean;
+    /** A shell tool's `details.exitCode`. */
+    readonly exitCode?: number;
+    readonly timedOut: boolean;
+    /** isError, a non-zero exit code, or a time-out. */
+    readonly failed: boolean;
+    /** The first error line of a failed result (see {@link firstErrorLine}). */
+    readonly firstErrorLine?: string;
+}
+
+/** Where a tool result's pairing landed. */
+export declare type ToolResultPairing = 
+/** The single earlier open attempt with its id. */
+"paired"
+/** Its id's attempt was already answered: a further result. */
+| "extra"
+/** Several attempts with its id were open: not paired. */
+| "ambiguous"
+/** No earlier attempt carried its id (a result before its call). */
+| "orphan"
+/** The result carries no `toolCallId`. */
+| "no-id";
+
+/** The finished fold over one session. */
+export declare interface TranscriptReview {
+    readonly records: readonly TranscriptReviewRecord[];
+    /** The first record at or after the time bound; it and everything after are invisible. */
+    readonly cutAt?: {
+        readonly position: number;
+        readonly entryId?: string;
+        readonly timestampMs: number;
+    };
+    readonly untilMs?: number;
+    readonly inputs: readonly TranscriptReviewRunInput[];
+    readonly runs: ReadonlyMap<string, TranscriptReviewRun>;
+    /** The store has run records; without them spans fall back to human-verified messages. */
+    readonly hasRuns: boolean;
+    readonly spans: readonly TranscriptReviewSpan[];
+    readonly attempts: readonly ToolCallAttempt[];
+    readonly results: readonly ToolResultFact[];
+    /** One past the last visible position. */
+    readonly endPosition: number;
+    recordAt(position: number): TranscriptReviewRecord | undefined;
+    recordOfEntry(entryId: string): TranscriptReviewRecord | undefined;
+    /** The span whose own work holds this position; `undefined` before the first span. */
+    spanAt(position: number): TranscriptReviewSpan | undefined;
+    /** A run's own extent: its boundary to the next run's boundary (or the end). */
+    runExtent(runId: string): {
+        readonly start: number;
+        readonly end: number;
+    } | undefined;
+    /** The run input carrying this input id. */
+    inputById(inputId: string): TranscriptReviewRunInput | undefined;
+    attemptAt(position: number, block: number): ToolCallAttempt | undefined;
+    /** Every attempt of the assistant message at this position, in block order. */
+    attemptsAt(position: number): readonly ToolCallAttempt[];
+    resultAt(position: number): ToolResultFact | undefined;
+    /**
+     * An attempt's outcome. `uptoPosition` ignores a paired result after it (a range that ends
+     * before the answer reads `no-result`).
+     */
+    outcome(attempt: ToolCallAttempt, uptoPosition?: number): ToolCallOutcome;
+}
+
+export declare interface TranscriptReviewBuilder {
+    /** `"stop"` once the time bound is reached: this record and every later one are ignored. */
+    add(record: TranscriptReviewRecordInput): "continue" | "stop";
+    finish(): TranscriptReview;
+}
+
+/** Why a span's own work ends where it does. */
+export declare type TranscriptReviewClose = "next-opener" | "next-opener-unresolved" | "time-bound" | "end-of-store";
+
+export declare interface TranscriptReviewOpener {
+    readonly position: number;
+    readonly entryId?: string;
+    readonly customType?: string;
+}
+
+/** How a span's opener was found. */
+export declare type TranscriptReviewOpenerVia = 
+/** A human-verified message whose `clientIntentId` equals the run's first input id. */
+"message"
+/** A task-bearing context record whose `details.clientIntentId` equals it (a card answer). */
+| "context"
+/** No record carries the first input id: the span exists, reachable by run. */
+| "unresolved"
+/** The store has no run records: each human-verified message opens a span. */
+| "fallback";
+
+export declare interface TranscriptReviewOptions {
+    /**
+     * Time bound in epoch milliseconds. The first record whose own timestamp is at or after it,
+     * and every record after that one, are invisible: `add` answers `"stop"` from then on.
+     */
+    readonly untilMs?: number;
+}
+
+/** The facts the fold keeps about one record. */
+export declare interface TranscriptReviewRecord extends ReviewEntryDescription {
+    readonly position: number;
+    readonly messageLine?: number;
+    /** An assistant message with visible text (the "previous answer" a span shows). */
+    readonly hasProse: boolean;
+}
+
+/** What a record is, for review. Finer than the stored-transcript kind where review needs it. */
+export declare type TranscriptReviewRecordClass = 
+/** A user-role message the daemon verified as a person's (`clientIntentId` + `details.deliveryId`). */
+"human"
+/** A user-role message of unrecorded origin (a joined steer's delivered text, an old log). */
+| "user" | "assistant" | "tool_result"
+/** A custom-role context message (`custom_message:<type>`). */
+| "context"
+/** A system-role message. */
+| "system"
+/** `session_run_started`, `session_run_input` or `session_run_state`. */
+| "run_marker"
+/** Any other custom entry: bookkeeping the model never sees. */
+| "custom" | "compaction" | "branch_summary" | "other" | "unreadable";
+
+/** One stored record, as a caller streams it in. */
+export declare interface TranscriptReviewRecordInput {
+    /** 1-based, commit order, every record (the port's position). */
+    readonly position: number;
+    /** Its line in the default `sessions://<id>.jsonl` view, when it is one. */
+    readonly messageLine?: number;
+    /** The parsed stored entry; absent for a record that did not parse. */
+    readonly entry?: unknown;
+}
+
+/** One run, by id. */
+export declare interface TranscriptReviewRun {
+    readonly runId: string;
+    readonly startedPosition?: number;
+    readonly firstInput?: TranscriptReviewRunInput;
+    /** The last `session_run_state` value seen, and where. */
+    readonly lastState?: {
+        readonly position: number;
+        readonly state?: string;
+    };
+    /**
+     * Where the run begins: the earliest of its start record, its first input and (for a run
+     * with neither) its first state record.
+     */
+    readonly boundary: number;
+}
+
+/** One `session_run_input` record. */
+export declare interface TranscriptReviewRunInput {
+    readonly position: number;
+    readonly entryId?: string;
+    readonly runId?: string;
+    /** `prompt`, `steer`, `follow_up`, ... */
+    readonly channel?: string;
+    /** `human_send`, `queued_human`, `scheduled_wake`, ... */
+    readonly cause?: string;
+    readonly inputId?: string;
+    readonly acceptedAtMs?: number;
+    /** Its cause is one of {@link HUMAN_INPUT_CAUSES}. */
+    readonly human: boolean;
+    /** The first input of its run: it opened that run. Otherwise it JOINED a running run. */
+    readonly opensRun: boolean;
+    /** Position of the human-verified message whose `clientIntentId` equals `inputId`. */
+    readonly linkedMessage?: number;
+    /** Position of the task-bearing context record whose `details.clientIntentId` equals `inputId`. */
+    readonly linkedContext?: number;
+}
+
+/**
+ * One review span: from a person's run-opening input to the next one. It holds every later run
+ * (wakes, continuations) and every human input that joined a running run. A grouping for review,
+ * not a claim about causality.
+ */
+export declare interface TranscriptReviewSpan {
+    /** 0-based, in store order. */
+    readonly index: number;
+    /**
+     * First position of the span's own work: its run's boundary, or the opener's position when
+     * the opener was stored before its run's markers.
+     */
+    readonly boundary: number;
+    /** One past the last position of its own work: the next span's boundary, or the end. */
+    readonly end: number;
+    /**
+     * One past the last position of the closing context: through the next span's opener when it
+     * resolved (that run's start and the person's next message, shown and not attributed), else
+     * equal to `end`.
+     */
+    readonly closingEnd: number;
+    readonly runId?: string;
+    readonly opener?: TranscriptReviewOpener;
+    readonly openerVia: TranscriptReviewOpenerVia;
+    /** The opening run's first input (the opener's own input). */
+    readonly firstInput?: TranscriptReviewRunInput;
+    /** Runs with a start record or an input inside the span's own work, in order. */
+    readonly ownRuns: readonly string[];
+    /** Runs with an input only in the closing context. */
+    readonly closingRuns: readonly string[];
+    /** Human inputs inside the span that joined a running run (steer, follow-up). */
+    readonly joined: readonly TranscriptReviewRunInput[];
+    readonly close: TranscriptReviewClose;
+    /** The last assistant message with visible text before the span. */
+    readonly previousAnswer?: number;
+}
+
+export { }