@stigmer/sdk 3.12.6 → 3.12.7

package/execution/conversation-rules.js

@@ -0,0 +1,113 @@
+// Framework-agnostic conversation-assembly rules for every Stigmer surface.
+//
+// A session's conversation is reassembled from its AgentExecution list by
+// several independent consumers: the React thread (@stigmer/react
+// buildThreadItems / useSessionConversation), the CLI's session replay
+// (snapshotToEvents), and the canonical transcript assembler (transcript.ts).
+// Before this module each consumer carried its own copy of the same small
+// rules, and the copies had already drifted (the CLI's replay lacks the
+// Build-from-plan skip). These are the shared, canonical rules; presentation
+// concerns (plan cards, todos anchoring, event interleaving) stay in the
+// consumers.
+//
+// This module has no React or framework dependency so it can be shared by
+// @stigmer/react, @stigmer/ink, and the CLI.
+/**
+ * Returns the executions in chronological (oldest-first) order — the order a
+ * conversation reads top-to-bottom.
+ *
+ * Defense-in-depth against an unordered list response: the executions ARE the
+ * transcript, so a scrambled order drops the newest turns out of view (they no
+ * longer sort to the bottom). The server orders this list, but consumers must
+ * never depend on that alone. Resource ids are time-sortable ULIDs
+ * (`aex_01k…`), so an ascending id sort is creation order without parsing
+ * timestamps; entries missing an id sort last but keep a stable relative order.
+ */
+export function sortChronologically(executions) {
+    return [...executions].sort((a, b) => {
+        const aId = a.metadata?.id ?? "";
+        const bId = b.metadata?.id ?? "";
+        if (aId === bId)
+            return 0;
+        if (!aId)
+            return 1;
+        if (!bId)
+            return -1;
+        return aId < bId ? -1 : 1;
+    });
+}
+/**
+ * Collects the ids of executions replaced via edit-and-resubmit.
+ *
+ * The successor execution carries `spec.supersedes_execution_id`; hiding the
+ * superseded turn makes the edited message read as a single corrected exchange
+ * (in-place replace). The raw execution list still contains superseded records
+ * — execution-history surfaces show them deliberately — so this is a
+ * conversation-view rule, applied by whoever renders or exports a
+ * conversation.
+ *
+ * @param extraSupersededId An id known only outside the list — the live stream
+ * copy's `supersedesExecutionId`: right after a resubmit, the successor
+ * streams before the list refetch delivers it.
+ */
+export function supersededExecutionIds(executions, extraSupersededId) {
+    const ids = new Set();
+    for (const e of executions) {
+        const superseded = e.spec?.supersedesExecutionId;
+        if (superseded)
+            ids.add(superseded);
+    }
+    if (extraSupersededId)
+        ids.add(extraSupersededId);
+    return ids;
+}
+/**
+ * `true` when the execution is a Build-from-plan turn.
+ *
+ * Such a turn's `spec.message` is a machine-written label ("Build from
+ * plan"), not user prose — the real instruction is runner-injected from the
+ * same flag. Rendering or exporting the label as a user message would
+ * attribute words to the user they never typed; the plan the turn builds from
+ * is the visible cause.
+ */
+export function isBuildFromPlanTurn(exec) {
+    return exec.spec?.executionConfig?.buildFromPlan === true;
+}
+/**
+ * The user prose that opens an execution's turn, or `null` when the turn has
+ * none.
+ *
+ * `spec.message` is the submitted prompt, but three shapes of it are not user
+ * prose and synthesize no user turn:
+ *  - empty — nothing was typed (programmatic creates);
+ *  - the literal `"execute"` — the legacy placeholder stamped on runs started
+ *    without a message;
+ *  - a Build-from-plan turn's machine-written label (see
+ *    {@link isBuildFromPlanTurn}).
+ */
+export function syntheticUserPrompt(exec) {
+    const specMessage = exec.spec?.message;
+    if (!specMessage || specMessage === "execute" || isBuildFromPlanTurn(exec)) {
+        return null;
+    }
+    return specMessage;
+}
+/**
+ * Extracts the execution id from an artifact storage key of the form
+ * `artifacts/{executionId}/...`. Returns `null` for an unexpected shape so the
+ * caller skips the fetch rather than issuing a request the server would
+ * reject.
+ *
+ * The fetch id must always derive from the key, never from render or export
+ * context: offloaded outputs inside a sub-agent's transcript are stored under
+ * the PARENT execution's id (the execution whose status was persisted), and
+ * the key is the record of that.
+ */
+export function execIdFromStorageKey(storageKey) {
+    const parts = storageKey.split("/");
+    if (parts.length >= 3 && parts[0] === "artifacts" && parts[1]) {
+        return parts[1];
+    }
+    return null;
+}
+//# sourceMappingURL=conversation-rules.js.map

package/execution/conversation-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-rules.js","sourceRoot":"","sources":["../../src/execution/conversation-rules.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,uEAAuE;AACvE,8EAA8E;AAC9E,0EAA0E;AAC1E,wEAAwE;AACxE,6EAA6E;AAC7E,yEAAyE;AACzE,aAAa;AACb,EAAE;AACF,0EAA0E;AAC1E,6CAA6C;AAI7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAqC;IAErC,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnC,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;QACjC,IAAI,GAAG,KAAK,GAAG;YAAE,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG;YAAE,OAAO,CAAC,CAAC;QACnB,IAAI,CAAC,GAAG;YAAE,OAAO,CAAC,CAAC,CAAC;QACpB,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAqC,EACrC,iBAAiC;IAEjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,EAAE,qBAAqB,CAAC;QACjD,IAAI,UAAU;YAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,iBAAiB;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAClD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAoB;IACtD,OAAO,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,aAAa,KAAK,IAAI,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAoB;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;IACvC,IAAI,CAAC,WAAW,IAAI,WAAW,KAAK,SAAS,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/execution/transcript.d.ts

@@ -0,0 +1,171 @@
+import { type JsonValue } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { GetArtifactContentResponse, ListAgentExecutionsBySessionRequest, AgentExecutionList, GetArtifactContentRequest } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+/**
+ * The fetched content of one offloaded tool output
+ * ({@link ToolCallOutputRef}), keyed in the transcript by its storage key —
+ * the one identifier that is unique across executions and sub-agents.
+ */
+export interface ResolvedToolOutput {
+    /** The `output_ref.storage_key` this content belongs to. */
+    readonly storageKey: string;
+    /**
+     * The resolved text, possibly truncated at the server's content cap
+     * (512 KB by default). `undefined` when the fetch failed or was skipped —
+     * serializers fall back to the ref's `truncated_preview`.
+     */
+    readonly content?: string;
+    /** `true` when the server truncated {@link content} at the byte cap. */
+    readonly truncated: boolean;
+    /** Full stored size in bytes, when known. */
+    readonly totalSizeBytes?: number;
+    /** MIME type recorded on the ref. */
+    readonly mimeType: string;
+    /** `true` for image outputs — never inlined; serializers note them. */
+    readonly isImage: boolean;
+    /** Fetch failure, when resolution was attempted and failed. */
+    readonly error?: string;
+}
+/** One execution's contribution to the conversation, with the canonical
+ * rules' verdicts precomputed so consumers never re-derive them. */
+export interface TranscriptTurn {
+    /** The execution, verbatim — messages, tool calls, sub-agents, timestamps. */
+    readonly execution: AgentExecution;
+    /**
+     * The user prose that opened this turn, or `null` when the turn has none
+     * (programmatic create, `"execute"` placeholder, Build-from-plan label) —
+     * the shared `syntheticUserPrompt` rule.
+     */
+    readonly userPrompt: string | null;
+    /** `true` for a Build-from-plan turn (machine-labeled, no user prose). */
+    readonly isBuildFromPlan: boolean;
+    /** `true` when the turn was replaced by an edit-and-resubmit. Only ever
+     * `true` when the transcript was assembled with `includeSuperseded`. */
+    readonly superseded: boolean;
+    /** `true` when the execution had not reached a terminal phase at assembly
+     * time — its content is the last-persisted snapshot of a running turn. */
+    readonly inProgress: boolean;
+}
+/** The canonical whole-conversation record of one session. */
+export interface SessionTranscript {
+    /** The session, verbatim. */
+    readonly session: Session;
+    /** The conversation's turns, in chronological (ULID) order. */
+    readonly turns: readonly TranscriptTurn[];
+    /**
+     * Fetched offloaded tool outputs, keyed by storage key. Empty when
+     * resolution was skipped; serializers then fall back to each ref's
+     * `truncated_preview`.
+     */
+    readonly resolvedOutputs: Readonly<Record<string, ResolvedToolOutput>>;
+    /** Whether superseded (edit-and-resubmit) turns were kept. */
+    readonly includesSuperseded: boolean;
+}
+/** Options for {@link assembleSessionTranscript}. */
+export interface AssembleSessionTranscriptOptions {
+    /**
+     * Keep turns replaced by edit-and-resubmit, marked
+     * `superseded: true`. Defaults to `false` — the conversation as the
+     * viewer shows it.
+     */
+    readonly includeSuperseded?: boolean;
+    /** Fetched offloaded outputs to embed (see {@link resolveOffloadedOutputs}). */
+    readonly resolvedOutputs?: Readonly<Record<string, ResolvedToolOutput>>;
+}
+/**
+ * Assembles the canonical transcript from a session and its executions.
+ *
+ * Pure — same inputs, same transcript. Ordering, superseded filtering, and
+ * user-turn synthesis are the shared conversation rules from
+ * `conversation-rules.ts`, so this cannot drift from what the conversation
+ * view renders.
+ */
+export declare function assembleSessionTranscript(session: Session, executions: readonly AgentExecution[], options?: AssembleSessionTranscriptOptions): SessionTranscript;
+/**
+ * The client slice {@link fetchSessionTranscript} needs — structurally
+ * satisfied by the `Stigmer` client, and small enough to fake in tests and
+ * satisfy from any host.
+ */
+export interface SessionTranscriptClient {
+    readonly session: {
+        get(id: string): Promise<Session>;
+    };
+    readonly agentExecution: {
+        listBySession(input: ListAgentExecutionsBySessionRequest): Promise<AgentExecutionList>;
+        getArtifactContent(input: GetArtifactContentRequest): Promise<GetArtifactContentResponse>;
+    };
+}
+/** Options for {@link fetchSessionTranscript}. */
+export interface FetchSessionTranscriptOptions {
+    /** See {@link AssembleSessionTranscriptOptions.includeSuperseded}. */
+    readonly includeSuperseded?: boolean;
+    /**
+     * Fetch offloaded tool outputs (`output_ref`) so the transcript carries
+     * them in full instead of their truncated previews. Defaults to `true` —
+     * resolution is the fidelity bar of #814. Individual fetch failures never
+     * fail the export; the failed ref falls back to its preview, with the
+     * error recorded on its {@link ResolvedToolOutput}.
+     */
+    readonly resolveOutputs?: boolean;
+    /** Concurrent output fetches. Defaults to 4. */
+    readonly concurrency?: number;
+}
+/**
+ * Fetches everything a session's transcript needs and assembles it.
+ *
+ * One `listBySession` call returns the complete execution set — both server
+ * editions answer this RPC unpaginated today (Go: `TODO: Implement
+ * pagination`; Java: "not using pagination with authorized IDs approach").
+ * If a future server starts paginating (`total_pages > 1`), this fails with
+ * a descriptive error rather than silently exporting a truncated
+ * "full-fidelity" transcript.
+ */
+export declare function fetchSessionTranscript(client: SessionTranscriptClient, sessionId: string, options?: FetchSessionTranscriptOptions): Promise<SessionTranscript>;
+/**
+ * Fetches the content behind every offloaded tool output in the given
+ * executions (parent and sub-agent transcripts alike), keyed by storage key.
+ *
+ * Image refs are never fetched — serializers render them as notes. The
+ * execution id for each fetch derives from the storage key itself
+ * (`execIdFromStorageKey`): sub-agent outputs are stored under the PARENT
+ * execution's id, and the key is the record of that.
+ */
+export declare function resolveOffloadedOutputs(client: Pick<SessionTranscriptClient, "agentExecution">, executions: readonly AgentExecution[], options?: {
+    readonly concurrency?: number;
+}): Promise<Record<string, ResolvedToolOutput>>;
+/** Options for {@link transcriptToMarkdown}. */
+export interface TranscriptToMarkdownOptions {
+    /**
+     * ISO timestamp stamped in the document header as the export time.
+     * Omitted when not provided, keeping the serializer deterministic for
+     * fixture pinning.
+     */
+    readonly generatedAt?: string;
+}
+/**
+ * Renders the transcript as a self-contained Markdown document.
+ *
+ * Deterministic: same transcript, same bytes — the format is a pinned
+ * contract (see `__tests__/transcript.test.ts`). Roles are bold labels
+ * (User / Assistant / Thinking / System), thinking and system content is
+ * blockquoted, tool calls carry fenced args and output, and sub-agent turns
+ * are blockquoted sections. Fences self-size past any backtick runs in the
+ * content, so hostile content cannot break out of its block.
+ */
+export declare function transcriptToMarkdown(transcript: SessionTranscript, options?: TranscriptToMarkdownOptions): string;
+/**
+ * Renders the transcript as a plain JSON value for programmatic analysis.
+ *
+ * Proto parts serialize through `toJson` with `useProtoFieldName: true` —
+ * the platform-wide protojson parity contract (snake_case fields, int64 as
+ * strings, `fromJson` round-trippable). Never `JSON.stringify` a raw proto
+ * object here: int64 fields are `bigint` and would throw.
+ *
+ * One deliberate omission: `status.callback_token` is stripped. It is an
+ * internal Temporal task token (runtime plumbing for workflow-triggered
+ * executions), not conversation material, and has no place in a document
+ * users share and paste around.
+ */
+export declare function transcriptToJson(transcript: SessionTranscript): JsonValue;
+//# sourceMappingURL=transcript.d.ts.map

package/execution/transcript.d.ts.map

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