@stigmer/sdk 3.12.6 → 3.12.8

package/src/execution/conversation-rules.ts

@@ -0,0 +1,119 @@
+// 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.
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+/**
+ * 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: readonly AgentExecution[],
+): AgentExecution[] {
+  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: readonly AgentExecution[],
+  extraSupersededId?: string | null,
+): Set<string> {
+  const ids = new Set<string>();
+  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: AgentExecution): boolean {
+  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: AgentExecution): string | null {
+  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: string): string | null {
+  const parts = storageKey.split("/");
+  if (parts.length >= 3 && parts[0] === "artifacts" && parts[1]) {
+    return parts[1];
+  }
+  return null;
+}

package/src/execution/tool-view.ts

@@ -120,6 +120,18 @@ export type ToolResultView =
       readonly blocks: readonly ToolContentBlock[];
       readonly mcpServerSlug: string;
     }
+  // The first-party remember tool's answer (DD-005): the created Memory
+  // record's identity and verbatim fact, parsed from the tool's
+  // {outcome, memory} payload (pinned by the mcp-server's memory
+  // integration test on the writer side). The consent chip renders from
+  // this — memoryId is the handle the confirm/reject RPCs take, and fact
+  // is the EXACT stored text (DD-005 D6: what you confirm is what is
+  // injected, byte for byte).
+  | {
+      readonly type: "memoryProposal";
+      readonly memoryId: string;
+      readonly fact: string;
+    }
   | { readonly type: "text"; readonly text: string }
   | { readonly type: "json"; readonly value: unknown }
   | { readonly type: "error"; readonly message: string }
@@ -216,8 +228,22 @@ export function resolveToolKind(toolCall: Pick<ToolCall, "name" | "mcpServerSlug
   return resolveToolKindByName(toolCall.name, toolCall.mcpServerSlug);
 }
 
+/**
+ * The reserved slug of the runner-synthesized memory attachment (DD-005).
+ * Mirrors the runner's MEMORY_ATTACHMENT_SLUG (shared/memory-attachment.ts);
+ * kept honest by test/fixtures/tool-view/classification.json.
+ */
+export const MEMORY_ATTACHMENT_SLUG = "stigmer-memory";
+
 /** Name-based classification used as the legacy fallback for resolveToolKind. */
 export function resolveToolKindByName(name: string, mcpServerSlug?: string): ToolKind {
+  // The first-party remember tool (DD-005), slug-scoped on purpose: only
+  // the synthesized memory attachment's reserved slug earns the MEMORY
+  // kind (and its consent-chip rendering) — a third-party MCP server's
+  // coincidental `remember` stays a plain MCP tool.
+  if (name === "remember" && mcpServerSlug === MEMORY_ATTACHMENT_SLUG) {
+    return ToolKind.MEMORY;
+  }
   const builtin = NAME_TO_KIND.get(name);
   if (builtin !== undefined) {
     return builtin;
@@ -344,6 +370,8 @@ export function normalizeToolResult(toolCall: ToolCall): ToolResultView {
       return normalizeThink(args, result);
     case ToolKind.MCP:
       return normalizeMcp(result, toolCall.mcpServerSlug);
+    case ToolKind.MEMORY:
+      return normalizeMemory(result);
     default:
       return genericView(result);
   }
@@ -621,6 +649,34 @@ function normalizeThink(args: Args, result: string): ToolResultView {
   return { type: "text", text: thought };
 }
 
+// The remember tool answers {outcome, memory} (memory = the created record
+// as proto JSON — the mcp-server's calls.ts is the writer). Depending on the
+// harness the persisted result is that JSON directly or wrapped in MCP
+// content blocks, so both are unwrapped here; anything unrecognized degrades
+// to the generic json/text view rather than a broken chip.
+function normalizeMemory(result: string): ToolResultView {
+  const parsed = tryParseJson(result);
+
+  // Content-block wrapping: the payload rides the first text block.
+  const blocks = extractContentBlocks(parsed);
+  const payload = blocks
+    ? tryParseJson(blocks.find((b) => b.type === "text")?.text ?? "")
+    : parsed;
+
+  if (isRecord(payload) && isRecord(payload.memory)) {
+    const memory = payload.memory;
+    const metadata = isRecord(memory.metadata) ? memory.metadata : undefined;
+    const spec = isRecord(memory.spec) ? memory.spec : undefined;
+    const memoryId = asString(metadata?.id) ?? "";
+    const fact = asString(spec?.content) ?? "";
+    if (memoryId !== "" && fact !== "") {
+      return { type: "memoryProposal", memoryId, fact };
+    }
+  }
+
+  return genericView(result);
+}
+
 function normalizeMcp(result: string, mcpServerSlug: string): ToolResultView {
   const parsed = tryParseJson(result);
   const blocks = extractContentBlocks(parsed);