@nanobpm/urban 0.92.1 → 0.93.0

package/src/runtime/core/host.ts

@@ -3,6 +3,19 @@
 // written against these interfaces and MUST NOT import `node:*` or reference `Deno`.
 // The adapters/ directory supplies concrete implementations.
 
+// The engine-native AgentHistory read shapes ({@link AgentHistoryRecord}) reuse the
+// Camunda `AgentHistoryRecordValue`-parity types the transcript store already models
+// (roles, content blocks, per-turn metrics, tool calls) rather than forking a second
+// projection of the same conversation grammar (No Drift Surfaces). This is a type-only
+// import — fully erased at runtime — so `core/` stays free of any concrete host/engine
+// module load, exactly as the rule above requires.
+import type {
+  TranscriptContentBlock,
+  TranscriptToolCall,
+  TranscriptTurnMetrics,
+  TranscriptTurnRole,
+} from "@nanobpm/agentic/transcript";
+
 /** A minimal HTTP request as seen by a mounted surface/trigger handler. */
 export interface HttpRequest {
   method: string;
@@ -603,6 +616,100 @@ export interface JobSummary {
   readonly deadline?: string;
 }
 
+/**
+ * Aggregated metrics for an agent instance across all of its model calls — the
+ * `AgentInstanceMetrics` the engine rolls up on the instance itself (distinct from the
+ * per-turn {@link TranscriptTurnMetrics} carried on an {@link AgentHistoryRecord}). Total
+ * `inputTokens`/`outputTokens` consumed, and the count of `modelCalls`/`toolCalls` made.
+ */
+export interface AgentInstanceMetrics {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly modelCalls: number;
+  readonly toolCalls: number;
+}
+
+/**
+ * A single engine-native agent instance as {@link EngineClient.searchAgentInstances} /
+ * {@link EngineClient.getAgentInstance} report it — the projection of the engine's
+ * `AgentInstanceResult`. Carries the `agentInstanceKey` a caller passes to
+ * {@link EngineClient.searchAgentInstanceHistory}, the lifecycle `status` (a bare string —
+ * the engine's `AgentInstanceStatusEnum` is broad: `INITIALIZING`/`THINKING`/`TOOL_CALLING`/
+ * `IDLE`/`COMPLETED`/…), the owning `processInstanceKey`, and best-effort diagnostics
+ * (`elementId`, the owning `elementInstanceKeys`, the process-definition linkage, aggregated
+ * `metrics`, and the creation/update/completion timestamps). Optional fields are omitted when
+ * the engine does not report them.
+ */
+export interface AgentInstanceSummary {
+  readonly agentInstanceKey: string;
+  readonly status: string;
+  readonly processInstanceKey: string;
+  readonly elementId?: string;
+  readonly elementInstanceKeys?: readonly string[];
+  readonly rootProcessInstanceKey?: string;
+  readonly processDefinitionKey?: string;
+  readonly processDefinitionId?: string;
+  readonly metrics?: AgentInstanceMetrics;
+  readonly creationDate?: string;
+  readonly lastUpdatedDate?: string;
+  readonly completionDate?: string;
+}
+
+/**
+ * A single agent-instance history item as {@link EngineClient.searchAgentInstanceHistory}
+ * reports it — the projection of the engine's `AgentInstanceHistoryItemResult`, i.e. one
+ * Camunda `AgentHistoryRecordValue`. Its conversation grammar (`role`, `content` blocks,
+ * `toolCalls`, per-turn `metrics`) reuses the `@nanobpm/agentic/transcript` parity types the
+ * transcript store already models, so the engine-read seam and the transcript store project
+ * the same shape (No Drift Surfaces). `historyItemKey` is the stable, creation-ordered
+ * identity; `loopIteration` is the agent-loop counter (one LLM call + its tool dispatches +
+ * their results share an iteration); `commitStatus` is the engine's `COMMITTED`/`PENDING`/
+ * `DISCARDED` flag (a bare string). `metrics` is present only when the engine recorded per-call
+ * metrics for the item; `elementInstanceKey`/`jobKey`/`producedAt` are best-effort diagnostics,
+ * omitted when unreported.
+ */
+export interface AgentHistoryRecord {
+  readonly historyItemKey: string;
+  readonly agentInstanceKey: string;
+  readonly loopIteration: number;
+  readonly role: TranscriptTurnRole;
+  readonly content: readonly TranscriptContentBlock[];
+  readonly toolCalls: readonly TranscriptToolCall[];
+  readonly metrics?: TranscriptTurnMetrics;
+  readonly commitStatus: string;
+  readonly elementInstanceKey?: string;
+  readonly jobKey?: string;
+  readonly producedAt?: string;
+}
+
+/** Selectors for {@link EngineClient.searchAgentInstances}. Every field is optional; an
+ *  omitted/blank selector is not applied (No Drift Surfaces — the same presence rule the key
+ *  selectors elsewhere in this seam use). */
+export interface AgentInstanceFilter {
+  /** Only agent instances owned by this process instance. */
+  readonly processInstanceKey?: string;
+  /** Only agent instances belonging to this *root* process-instance hierarchy. */
+  readonly rootProcessInstanceKey?: string;
+  /** Only agent instances in this lifecycle status (the engine's `AgentInstanceStatusEnum`). */
+  readonly status?: string;
+  /** Only agent instances owned by this BPMN element (the AI-agent task / ad-hoc sub-process). */
+  readonly elementId?: string;
+}
+
+/** Selectors for {@link EngineClient.searchAgentInstanceHistory} (the `agentInstanceKey` is a
+ *  required positional argument, not a filter field). Every field is optional. Note the engine
+ *  defaults an unfiltered history search to `COMMITTED` items only. */
+export interface AgentHistoryFilter {
+  /** Only history items with this conversation role. Note that `TranscriptTurnRole` is the wider
+   *  transcript union: only the engine-side subset `"USER" | "ASSISTANT" | "TOOL_RESULT"` is
+   *  applied as a filter — `"CONFIGURATION"`/`"UNSPECIFIED"` are ignored (not forwarded). */
+  readonly role?: TranscriptTurnRole;
+  /** Only history items produced in this agent-loop iteration. */
+  readonly loopIteration?: number;
+  /** Only history items produced under this element instance. */
+  readonly elementInstanceKey?: string;
+}
+
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -772,6 +879,42 @@ export interface EngineClient {
    * caller distinguishes "have it" from "don't" without a try/catch. A zero-wait read.
    */
   getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
+  /**
+   * Search engine-native agent instances (`POST /agent-instances/search`), optionally narrowed
+   * by owning `processInstanceKey`/`rootProcessInstanceKey`, lifecycle `status`, or `elementId`.
+   * The read entry point onto the engine's AgentInstance/AgentHistory model: an
+   * {@link AgentInstanceSummary} carries the `agentInstanceKey` a caller passes to
+   * {@link searchAgentInstanceHistory} to read that instance's conversation. An eventually
+   * consistent (zero-wait) read; each malformed row (no `agentInstanceKey`/`processInstanceKey`)
+   * is dropped rather than surfaced.
+   */
+  searchAgentInstances(filter?: AgentInstanceFilter): Promise<AgentInstanceSummary[]>;
+  /**
+   * Search one agent instance's conversation history
+   * (`POST /agent-instances/{agentInstanceKey}/history/search`) — the ordered
+   * {@link AgentHistoryRecord}s (turns) the engine retains for `agentInstanceKey`, optionally
+   * narrowed by `role`/`loopIteration`/`elementInstanceKey`. This is the production read path
+   * onto engine AgentHistory the historical-transcript + metrics consumer builds on
+   * (nanobpm/nano-workforce#747). Each record's conversation grammar reuses the
+   * `@nanobpm/agentic/transcript` parity shapes (roles, content blocks, per-turn metrics, tool
+   * calls). Note the engine defaults an unfiltered search to `COMMITTED` items only. A blank
+   * `agentInstanceKey` addresses no instance, so it returns the empty list rather than issuing a
+   * request with an empty path segment. An eventually consistent (zero-wait) read; malformed rows
+   * are dropped.
+   */
+  searchAgentInstanceHistory(
+    agentInstanceKey: string,
+    filter?: AgentHistoryFilter,
+  ): Promise<AgentHistoryRecord[]>;
+  /**
+   * Fetch a single agent instance by its key (`GET /agent-instances/{agentInstanceKey}`), or
+   * `null` when it cannot be resolved — the key is blank, no such agent instance exists (a 404),
+   * or the fetch otherwise fails. A read is treated as absence rather than propagating (mirroring
+   * {@link getForm}/{@link getElementInstance}/{@link getProcessDefinitionXml}), so a caller
+   * distinguishes "have it" from "don't" without a try/catch. A zero-wait read returning the same
+   * {@link AgentInstanceSummary} shape as {@link searchAgentInstances}.
+   */
+  getAgentInstance(agentInstanceKey: string): Promise<AgentInstanceSummary | null>;
   /**
    * Resolve an open incident by key (`POST /v2/incidents/{incidentKey}/resolution`), unblocking
    * the parked token: a job incident returns the job to the activatable pool (so it must have
@@ -839,6 +982,9 @@ export const ENGINE_CLIENT_METHODS = [
   "searchVariables",
   "searchJobs",
   "getProcessDefinitionXml",
+  "searchAgentInstances",
+  "searchAgentInstanceHistory",
+  "getAgentInstance",
   "resolveIncident",
   "updateJobRetries",
   "setVariables",

package/src/runtime/core/modules/actions.test.ts

@@ -40,6 +40,9 @@ const engine: EngineClient = {
   searchVariables: async () => [],
   searchJobs: async () => [],
   getProcessDefinitionXml: async () => null,
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

package/src/runtime/core/modules/agent.test.ts

@@ -25,6 +25,9 @@ const fakeEngine: EngineClient = {
   searchVariables: async () => [],
   searchJobs: async () => [],
   getProcessDefinitionXml: async () => null,
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

package/src/runtime/core/modules/api.test.ts

@@ -38,6 +38,9 @@ const engine: EngineClient = {
   searchVariables: async () => [],
   searchJobs: async () => [],
   getProcessDefinitionXml: async () => null,
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

package/src/runtime/core/modules/cancel.test.ts

@@ -92,6 +92,9 @@ function cancelEngine(opts: {
     searchVariables: notUsed("searchVariables"),
     searchJobs: notUsed("searchJobs"),
     getProcessDefinitionXml: notUsed("getProcessDefinitionXml"),
+    searchAgentInstances: notUsed("searchAgentInstances"),
+    searchAgentInstanceHistory: notUsed("searchAgentInstanceHistory"),
+    getAgentInstance: notUsed("getAgentInstance"),
     resolveIncident: notUsed("resolveIncident"),
     updateJobRetries: notUsed("updateJobRetries"),
     setVariables: notUsed("setVariables"),

package/src/runtime/core/modules/connectors.test.ts

@@ -28,6 +28,9 @@ class MiniEngine implements EngineClient {
   async searchVariables(): Promise<never[]> { return []; }
   async searchJobs(): Promise<never[]> { return []; }
   async getProcessDefinitionXml(): Promise<null> { return null; }
+  async searchAgentInstances(): Promise<never[]> { return []; }
+  async searchAgentInstanceHistory(): Promise<never[]> { return []; }
+  async getAgentInstance(): Promise<null> { return null; }
   async resolveIncident(): Promise<void> {}
   async updateJobRetries(): Promise<void> {}
   async setVariables(): Promise<void> {}

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -27,6 +27,9 @@ const noEngine: EngineClient = {
   searchVariables: async () => [],
   searchJobs: async () => [],
   getProcessDefinitionXml: async () => null,
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -97,6 +97,9 @@ function fakeEngine(
     searchVariables: notUsed("searchVariables"),
     searchJobs: notUsed("searchJobs"),
     getProcessDefinitionXml: notUsed("getProcessDefinitionXml"),
+    searchAgentInstances: notUsed("searchAgentInstances"),
+    searchAgentInstanceHistory: notUsed("searchAgentInstanceHistory"),
+    getAgentInstance: notUsed("getAgentInstance"),
     resolveIncident: notUsed("resolveIncident"),
     updateJobRetries: notUsed("updateJobRetries"),
     setVariables: notUsed("setVariables"),

package/src/runtime/core/modules/mcp.test.ts

@@ -93,6 +93,9 @@ function fakeEngine(overrides: Partial<EngineClient> = {}): EngineClient {
     searchVariables: async () => [],
     searchJobs: async () => [],
     getProcessDefinitionXml: async () => null,
+    searchAgentInstances: async () => [],
+    searchAgentInstanceHistory: async () => [],
+    getAgentInstance: async () => null,
     resolveIncident: async () => {},
     updateJobRetries: async () => {},
     setVariables: async () => {},
@@ -646,6 +649,9 @@ test("urban_debug_search_variables / search_jobs / get_process_definition_xml ar
       seenXmlKeys.push(key);
       return key === "pd-1" ? "<bpmn:definitions/>" : null;
     },
+    searchAgentInstances: async () => [],
+    searchAgentInstanceHistory: async () => [],
+    getAgentInstance: async () => null,
   });
   const { router } = buildHarness({ engine });
   const session = await connect(router);

package/src/runtime/core/modules/pages.test.ts

@@ -55,6 +55,9 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
     async searchVariables() { return []; },
     async searchJobs() { return []; },
     async getProcessDefinitionXml() { return null; },
+    async searchAgentInstances() { return []; },
+    async searchAgentInstanceHistory() { return []; },
+    async getAgentInstance() { return null; },
     async resolveIncident() {},
     async updateJobRetries() {},
     async setVariables() {},

package/src/runtime/core/modules/surfaces.test.ts

@@ -41,6 +41,9 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     searchVariables: async () => [],
     searchJobs: async () => [],
     getProcessDefinitionXml: async () => null,
+    searchAgentInstances: async () => [],
+    searchAgentInstanceHistory: async () => [],
+    getAgentInstance: async () => null,
     resolveIncident: async () => {},
     updateJobRetries: async () => {},
     setVariables: async () => {},
@@ -67,6 +70,9 @@ const fakeEngine: EngineClient = {
   searchVariables: async () => [],
   searchJobs: async () => [],
   getProcessDefinitionXml: async () => null,
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

package/src/runtime/core/modules/triggers.test.ts

@@ -42,6 +42,9 @@ class MiniEngine implements EngineClient {
   async searchVariables(): Promise<never[]> { return []; }
   async searchJobs(): Promise<never[]> { return []; }
   async getProcessDefinitionXml(): Promise<null> { return null; }
+  async searchAgentInstances(): Promise<never[]> { return []; }
+  async searchAgentInstanceHistory(): Promise<never[]> { return []; }
+  async getAgentInstance(): Promise<null> { return null; }
   async resolveIncident(): Promise<void> {}
   async updateJobRetries(): Promise<void> {}
   async setVariables(): Promise<void> {}

package/src/runtime/core/modules/workers.test.ts

@@ -39,6 +39,9 @@ class MiniEngine implements EngineClient {
   async searchVariables(): Promise<never[]> { return []; }
   async searchJobs(): Promise<never[]> { return []; }
   async getProcessDefinitionXml(): Promise<null> { return null; }
+  async searchAgentInstances(): Promise<never[]> { return []; }
+  async searchAgentInstanceHistory(): Promise<never[]> { return []; }
+  async getAgentInstance(): Promise<null> { return null; }
   async resolveIncident(): Promise<void> {}
   async updateJobRetries(): Promise<void> {}
   async setVariables(): Promise<void> {}

package/src/runtime/core/runtime.extensions.test.ts

@@ -53,6 +53,15 @@ class NoopEngine implements EngineClient {
   async getProcessDefinitionXml() {
     return null;
   }
+  async searchAgentInstances() {
+    return [];
+  }
+  async searchAgentInstanceHistory() {
+    return [];
+  }
+  async getAgentInstance() {
+    return null;
+  }
   async resolveIncident() {}
   async updateJobRetries() {}
   async setVariables() {}

package/src/runtime/core/runtime.test.ts

@@ -74,6 +74,15 @@ class FakeEngine implements EngineClient {
   async getProcessDefinitionXml() {
     return null;
   }
+  async searchAgentInstances() {
+    return [];
+  }
+  async searchAgentInstanceHistory() {
+    return [];
+  }
+  async getAgentInstance() {
+    return null;
+  }
   async resolveIncident() {}
   async updateJobRetries() {}
   async setVariables() {}

package/src/runtime/engine/nanosdk.test.ts

@@ -109,6 +109,18 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("getProcessDefinitionXml");
       return "";
     },
+    async searchAgentInstances() {
+      calls.push("searchAgentInstances");
+      return { items: [] };
+    },
+    async searchAgentInstanceHistory() {
+      calls.push("searchAgentInstanceHistory");
+      return { items: [] };
+    },
+    async getAgentInstance() {
+      calls.push("getAgentInstance");
+      return {};
+    },
     async resolveIncident(input) {
       calls.push("resolveIncident");
       return { ...input };
@@ -1408,3 +1420,200 @@ test("publishMessage threads lineage so message-started instances inherit it", a
   }
   assert.deepEqual(readLineage(client.msgVars), { rootRequestKey: "root-9", causedByInstanceKey: "pi-9" });
 });
+
+// ── Engine-native AgentInstance / AgentHistory read seam (nanobpm/nano-ide#563) ──
+// The read path onto engine AgentInstance/AgentHistory that unblocks the historical-transcript
+// consumer (nanobpm/nano-workforce#747). These pin the request-mapping + response-mapping
+// contract of the three `EngineClient` methods against the fake nano-sdk client, mirroring the
+// other search-seam tests above (so the same scenarios would hold against a live engine).
+
+test("searchAgentInstances normalizes selectors, reads zero-wait, and maps rows", async () => {
+  let seenInput: { filter?: Record<string, unknown> } | undefined;
+  let seenConsistency: unknown;
+  const client = fakeSdkClient({
+    searchAgentInstances: async (input, consistency) => {
+      seenInput = input;
+      seenConsistency = consistency;
+      return {
+        items: [
+          {
+            agentInstanceKey: " ai-1 ", // padded → trimmed
+            status: "THINKING",
+            processInstanceKey: 10,
+            elementId: "agent",
+            rootProcessInstanceKey: 30,
+            processDefinitionKey: "pd-1",
+            processDefinitionId: "proc",
+            elementInstanceKeys: ["ei-1", "", 42],
+            metrics: { inputTokens: 5, outputTokens: 7, modelCalls: 2, toolCalls: 1 },
+            creationDate: "2024-01-01T00:00:00Z",
+            lastUpdatedDate: "2024-01-02T00:00:00Z",
+            completionDate: null,
+          },
+          { status: "IDLE", processInstanceKey: "11" }, // keyless → skipped
+          { agentInstanceKey: "ai-2" }, // no processInstanceKey → skipped
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchAgentInstances({
+    processInstanceKey: " 10 ", // padded → trimmed
+    rootProcessInstanceKey: "   ", // whitespace-only → dropped
+    status: "THINKING",
+    elementId: "agent",
+  });
+  assert.deepEqual(seenInput, {
+    filter: { processInstanceKey: "10", status: "THINKING", elementId: "agent" },
+  });
+  assert.deepEqual(seenConsistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(out, [
+    {
+      agentInstanceKey: "ai-1",
+      status: "THINKING",
+      processInstanceKey: "10",
+      elementId: "agent",
+      elementInstanceKeys: ["ei-1", "42"],
+      rootProcessInstanceKey: "30",
+      processDefinitionKey: "pd-1",
+      processDefinitionId: "proc",
+      metrics: { inputTokens: 5, outputTokens: 7, modelCalls: 2, toolCalls: 1 },
+      creationDate: "2024-01-01T00:00:00Z",
+      lastUpdatedDate: "2024-01-02T00:00:00Z",
+    },
+  ]);
+});
+
+test("searchAgentInstanceHistory keys the path, maps the transcript grammar, and short-circuits a blank key", async () => {
+  let seenInput: { agentInstanceKey?: string; filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchAgentInstanceHistory: async (input) => {
+      seenInput = input;
+      return {
+        items: [
+          {
+            historyItemKey: "h-1",
+            agentInstanceKey: "ai-1",
+            loopIteration: 3,
+            role: "ASSISTANT",
+            content: [
+              { contentType: "TEXT", text: "hi" },
+              { contentType: "OBJECT", object: { a: 1 } },
+              { contentType: "MYSTERY" }, // unknown → UNSPECIFIED
+            ],
+            toolCalls: [
+              { toolCallId: "t-1", toolName: "search", elementId: "tool", arguments: { q: "x" } },
+              { toolName: "no-id", arguments: null }, // no toolCallId → dropped
+            ],
+            metrics: { inputTokens: 11, outputTokens: null, durationMs: 42 },
+            commitStatus: "COMMITTED",
+            elementInstanceKey: "ei-9",
+            jobKey: "job-9",
+            producedAt: "2024-01-01T00:00:00Z",
+          },
+          { agentInstanceKey: "ai-1", role: "USER" }, // no historyItemKey → skipped
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchAgentInstanceHistory(" ai-1 ", {
+    role: "ASSISTANT",
+    loopIteration: 3,
+    elementInstanceKey: " ei-9 ",
+  });
+  assert.deepEqual(seenInput, {
+    agentInstanceKey: "ai-1",
+    filter: { role: "ASSISTANT", loopIteration: 3, elementInstanceKey: "ei-9" },
+  });
+  assert.deepEqual(out, [
+    {
+      historyItemKey: "h-1",
+      agentInstanceKey: "ai-1",
+      loopIteration: 3,
+      role: "ASSISTANT",
+      content: [
+        { contentType: "TEXT", text: "hi" },
+        { contentType: "OBJECT", object: { a: 1 } },
+        { contentType: "UNSPECIFIED" },
+      ],
+      toolCalls: [{ toolCallId: "t-1", toolName: "search", elementId: "tool", arguments: { q: "x" } }],
+      metrics: {
+        inputTokens: 11,
+        outputTokens: 0,
+        reasoningTokenCount: 0,
+        cacheCreationTokenCount: 0,
+        cacheReadTokenCount: 0,
+        durationMs: 42,
+      },
+      commitStatus: "COMMITTED",
+      elementInstanceKey: "ei-9",
+      jobKey: "job-9",
+      producedAt: "2024-01-01T00:00:00Z",
+    },
+  ]);
+
+  // A blank key addresses no instance → empty list, no request issued.
+  seenInput = undefined;
+  const blank = await engine.searchAgentInstanceHistory("   ");
+  assert.deepEqual(blank, []);
+  assert.equal(seenInput, undefined, "no history search is issued for a blank key");
+});
+
+test("searchAgentInstanceHistory drops a transcript role the engine filter does not accept", async () => {
+  // `TranscriptTurnRole` is the wider transcript union; only `USER`/`ASSISTANT`/`TOOL_RESULT` are
+  // valid engine history filters. An unsupported role (e.g. `CONFIGURATION`/`UNSPECIFIED`) must not
+  // be forwarded, else the engine 4xxes on the request. Guards the fix against reintroduction.
+  let seenInput: { agentInstanceKey?: string; filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchAgentInstanceHistory: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.searchAgentInstanceHistory("ai-1", { role: "CONFIGURATION", loopIteration: 2 });
+  assert.deepEqual(
+    seenInput,
+    { agentInstanceKey: "ai-1", filter: { loopIteration: 2 } },
+    "an unsupported role is not forwarded as an engine filter",
+  );
+
+  await engine.searchAgentInstanceHistory("ai-1", { role: "UNSPECIFIED" });
+  assert.deepEqual(
+    seenInput,
+    { agentInstanceKey: "ai-1", filter: {} },
+    "UNSPECIFIED is dropped, leaving no role filter",
+  );
+
+  await engine.searchAgentInstanceHistory("ai-1", { role: "TOOL_RESULT" });
+  assert.deepEqual(
+    seenInput,
+    { agentInstanceKey: "ai-1", filter: { role: "TOOL_RESULT" } },
+    "a supported engine role is forwarded",
+  );
+});
+
+test("getAgentInstance reads-as-absence on a blank key and on a fetch error", async () => {
+  let calls = 0;
+  const client = fakeSdkClient({
+    getAgentInstance: async (input) => {
+      calls++;
+      if (input.agentInstanceKey === "boom") throw new Error("404");
+      return { agentInstanceKey: input.agentInstanceKey, status: "COMPLETED", processInstanceKey: "10" };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  assert.equal(await engine.getAgentInstance("   "), null, "blank key → null without a fetch");
+  assert.equal(calls, 0);
+
+  assert.equal(await engine.getAgentInstance("boom"), null, "a failed fetch is absence, not a throw");
+
+  assert.deepEqual(await engine.getAgentInstance(" ai-7 "), {
+    agentInstanceKey: "ai-7",
+    status: "COMPLETED",
+    processInstanceKey: "10",
+  });
+});