@nanobpm/urban 0.92.1 → 0.93.0

package/dist/runtime/core/host.d.ts

@@ -1,3 +1,4 @@
+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;
@@ -537,6 +538,95 @@ export interface JobSummary {
     readonly elementId?: string;
     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.
@@ -712,6 +802,39 @@ 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
@@ -766,4 +889,4 @@ export interface EngineClient {
  * and `getForm` before it) that a purely structural `implements EngineClient` check no
  * longer catches once the fake is published/compiled against an older `@nanobpm/urban`.
  */
-export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "searchVariables", "searchJobs", "getProcessDefinitionXml", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];
+export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "searchVariables", "searchJobs", "getProcessDefinitionXml", "searchAgentInstances", "searchAgentInstanceHistory", "getAgentInstance", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];

package/dist/runtime/core/host.js

@@ -123,6 +123,9 @@ export const ENGINE_CLIENT_METHODS = [
     "searchVariables",
     "searchJobs",
     "getProcessDefinitionXml",
+    "searchAgentInstances",
+    "searchAgentInstanceHistory",
+    "getAgentInstance",
     "resolveIncident",
     "updateJobRetries",
     "setVariables",

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -55,6 +55,18 @@ export declare function mapVariableRow(row: Record<string, unknown>, log: Log):
  *  `state` is passed through as a bare string (the engine's job-state enum is broad). The single
  *  source of truth `searchJobs` extracts through. */
 export declare function mapJobRow(row: Record<string, unknown>, log: Log): JobSummary | undefined;
+/** Map one engine `AgentInstanceResult` row onto an {@link AgentInstanceSummary}, or `undefined`
+ *  when the row is malformed (missing the `agentInstanceKey` or owning `processInstanceKey`). The
+ *  single source of truth `searchAgentInstances`/`getAgentInstance` extract through, so the two
+ *  cannot drift. Optional linkage/metrics/timestamp fields are emitted only when the engine
+ *  reports them. */
+export declare function mapAgentInstanceRow(row: Record<string, unknown>, log: Log): AgentInstanceSummary | undefined;
+/** Map one engine `AgentInstanceHistoryItemResult` row onto an {@link AgentHistoryRecord}, or
+ *  `undefined` when the row is malformed (missing the `historyItemKey` or owning
+ *  `agentInstanceKey`). `content`/`toolCalls` drop any individually-malformed block; `loopIteration`
+ *  defaults to `0` when unreported; `commitStatus` passes through as a bare string. The single
+ *  source of truth `searchAgentInstanceHistory` extracts through. */
+export declare function mapAgentHistoryRow(row: Record<string, unknown>, log: Log): AgentHistoryRecord | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -161,6 +173,18 @@ export interface NanoSdkClient {
     getProcessDefinitionXml(input: {
         processDefinitionKey: string;
     }, consistency?: unknown, options?: unknown): Promise<unknown>;
+    searchAgentInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchAgentInstanceHistory(input: {
+        agentInstanceKey: string;
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    getAgentInstance(input: {
+        agentInstanceKey: string;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     resolveIncident(input: {
         incidentKey: string;
     }, options?: unknown): Promise<unknown>;
@@ -246,6 +270,9 @@ export declare class SdkEngineClient implements EngineClient {
     searchVariables(filter?: VariableFilter): Promise<VariableSummary[]>;
     searchJobs(filter?: JobFilter): Promise<JobSummary[]>;
     getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
+    searchAgentInstances(filter?: AgentInstanceFilter): Promise<AgentInstanceSummary[]>;
+    searchAgentInstanceHistory(agentInstanceKey: string, filter?: AgentHistoryFilter): Promise<AgentHistoryRecord[]>;
+    getAgentInstance(agentInstanceKey: string): Promise<AgentInstanceSummary | null>;
     resolveIncident(input: {
         incidentKey: string;
     }): Promise<void>;

package/dist/runtime/engine/nanosdk.js

@@ -405,6 +405,191 @@ export function mapJobRow(row, log) {
         ...(deadline ? { deadline } : {}),
     };
 }
+/** The agent-instance conversation roles the engine's `AgentInstanceHistoryRoleEnum` reports —
+ *  a strict subset of the transcript {@link TranscriptTurnRole} union it maps onto, so the two
+ *  cannot drift. A row whose role is anything else is normalized to `"UNSPECIFIED"`. */
+const AGENT_HISTORY_ROLES = ["USER", "ASSISTANT", "TOOL_RESULT"];
+/** Map an engine history-item role onto the transcript {@link TranscriptTurnRole} union, or
+ *  `"UNSPECIFIED"` when the engine reports an unknown/absent role — a lossy-but-safe fallback so a
+ *  record is surfaced rather than dropped for a role the engine grows later. */
+function normalizeAgentHistoryRole(value) {
+    const role = AGENT_HISTORY_ROLES.find((r) => r === value);
+    return role ?? "UNSPECIFIED";
+}
+/** The content-block type discriminators the engine's `AgentInstanceMessageContentTypeEnum`
+ *  reports, mapped onto the transcript {@link TranscriptContentType} union. */
+const AGENT_CONTENT_TYPES = ["TEXT", "DOCUMENT", "OBJECT"];
+/** Map one engine `AgentInstanceMessageContent` row onto a transcript {@link TranscriptContentBlock},
+ *  or `undefined` when malformed. TEXT carries `text`, DOCUMENT carries `documentReference`, OBJECT
+ *  carries `object` — exactly the per-`contentType` payload the transcript shape pins, so the
+ *  engine-read seam and the transcript store project content identically (No Drift Surfaces). An
+ *  unknown/absent discriminator maps to an `UNSPECIFIED` block carrying no payload. */
+function mapAgentContentBlock(value) {
+    if (!isRecord(value))
+        return undefined;
+    const contentType = AGENT_CONTENT_TYPES.find((t) => t === value.contentType) ?? "UNSPECIFIED";
+    if (contentType === "TEXT") {
+        return { contentType, text: typeof value.text === "string" ? value.text : "" };
+    }
+    if (contentType === "DOCUMENT") {
+        const documentReference = presentText(value.documentReference);
+        return { contentType, documentReference: documentReference ?? "" };
+    }
+    if (contentType === "OBJECT") {
+        return { contentType, object: value.object };
+    }
+    return { contentType };
+}
+/** Map one engine `AgentInstanceToolCall` row onto a transcript {@link TranscriptToolCall}, or
+ *  `undefined` when it carries no `toolCallId`/`toolName` (the identity a caller correlates on). A
+ *  TOOL_RESULT item reports `arguments: null`; normalize that to an empty object so the
+ *  transcript shape's non-null `arguments` invariant holds. */
+function mapAgentToolCall(value) {
+    if (!isRecord(value))
+        return undefined;
+    const toolCallId = presentText(value.toolCallId);
+    const toolName = presentText(value.toolName);
+    if (toolCallId === undefined || toolName === undefined)
+        return undefined;
+    const elementId = presentText(value.elementId);
+    const args = isRecord(value.arguments) ? value.arguments : {};
+    return {
+        toolCallId,
+        toolName,
+        ...(elementId ? { elementId } : {}),
+        arguments: args,
+    };
+}
+/** Map one engine `AgentInstanceHistoryItemMetrics` onto per-turn {@link TranscriptTurnMetrics},
+ *  or `undefined` when the engine recorded none (a `null` metrics object). The engine's per-item
+ *  metrics carry only `inputTokens`/`outputTokens`/`durationMs` (each nullable); the transcript
+ *  shape additionally models reasoning/cache token counts the engine does not report per item, so
+ *  those default to `0` (the "none reported" count) — a coercion, not a second projection. */
+function mapAgentHistoryMetrics(value) {
+    if (!isRecord(value))
+        return undefined;
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    return {
+        inputTokens: num(value.inputTokens),
+        outputTokens: num(value.outputTokens),
+        reasoningTokenCount: 0,
+        cacheCreationTokenCount: 0,
+        cacheReadTokenCount: 0,
+        durationMs: num(value.durationMs),
+    };
+}
+/** Map one engine `AgentInstanceMetrics` (the instance-level aggregate) onto
+ *  {@link AgentInstanceMetrics}, or `undefined` when the row carries none. */
+function mapAgentInstanceMetrics(value) {
+    if (!isRecord(value))
+        return undefined;
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    return {
+        inputTokens: num(value.inputTokens),
+        outputTokens: num(value.outputTokens),
+        modelCalls: num(value.modelCalls),
+        toolCalls: num(value.toolCalls),
+    };
+}
+/** Map one engine `AgentInstanceResult` row onto an {@link AgentInstanceSummary}, or `undefined`
+ *  when the row is malformed (missing the `agentInstanceKey` or owning `processInstanceKey`). The
+ *  single source of truth `searchAgentInstances`/`getAgentInstance` extract through, so the two
+ *  cannot drift. Optional linkage/metrics/timestamp fields are emitted only when the engine
+ *  reports them. */
+export function mapAgentInstanceRow(row, log) {
+    const agentInstanceKey = presentEngineKey(row.agentInstanceKey);
+    if (agentInstanceKey === undefined) {
+        log("warn", "skipping agent instance with no agentInstanceKey in engine response");
+        return undefined;
+    }
+    const processInstanceKey = presentEngineKey(row.processInstanceKey);
+    if (processInstanceKey === undefined) {
+        log("warn", "skipping agent instance with no processInstanceKey in engine response", {
+            agentInstanceKey,
+        });
+        return undefined;
+    }
+    const status = presentText(row.status) ?? "UNKNOWN";
+    const elementId = presentText(row.elementId);
+    const rootProcessInstanceKey = presentEngineKey(row.rootProcessInstanceKey);
+    const processDefinitionKey = presentEngineKey(row.processDefinitionKey);
+    const processDefinitionId = presentText(row.processDefinitionId);
+    const elementInstanceKeys = Array.isArray(row.elementInstanceKeys)
+        ? row.elementInstanceKeys
+            .map((k) => presentEngineKey(k))
+            .filter((k) => k !== undefined)
+        : undefined;
+    const metrics = mapAgentInstanceMetrics(row.metrics);
+    const creationDate = presentText(row.creationDate);
+    const lastUpdatedDate = presentText(row.lastUpdatedDate);
+    const completionDate = presentText(row.completionDate);
+    return {
+        agentInstanceKey,
+        status,
+        processInstanceKey,
+        ...(elementId ? { elementId } : {}),
+        ...(elementInstanceKeys && elementInstanceKeys.length > 0 ? { elementInstanceKeys } : {}),
+        ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
+        ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...(processDefinitionId ? { processDefinitionId } : {}),
+        ...(metrics ? { metrics } : {}),
+        ...(creationDate ? { creationDate } : {}),
+        ...(lastUpdatedDate ? { lastUpdatedDate } : {}),
+        ...(completionDate ? { completionDate } : {}),
+    };
+}
+/** Map one engine `AgentInstanceHistoryItemResult` row onto an {@link AgentHistoryRecord}, or
+ *  `undefined` when the row is malformed (missing the `historyItemKey` or owning
+ *  `agentInstanceKey`). `content`/`toolCalls` drop any individually-malformed block; `loopIteration`
+ *  defaults to `0` when unreported; `commitStatus` passes through as a bare string. The single
+ *  source of truth `searchAgentInstanceHistory` extracts through. */
+export function mapAgentHistoryRow(row, log) {
+    const historyItemKey = presentEngineKey(row.historyItemKey);
+    if (historyItemKey === undefined) {
+        log("warn", "skipping agent history item with no historyItemKey in engine response");
+        return undefined;
+    }
+    const agentInstanceKey = presentEngineKey(row.agentInstanceKey);
+    if (agentInstanceKey === undefined) {
+        log("warn", "skipping agent history item with no agentInstanceKey in engine response", {
+            historyItemKey,
+        });
+        return undefined;
+    }
+    const loopIteration = typeof row.loopIteration === "number" && Number.isFinite(row.loopIteration)
+        ? row.loopIteration
+        : 0;
+    const content = Array.isArray(row.content)
+        ? row.content.flatMap((c) => {
+            const block = mapAgentContentBlock(c);
+            return block ? [block] : [];
+        })
+        : [];
+    const toolCalls = Array.isArray(row.toolCalls)
+        ? row.toolCalls.flatMap((t) => {
+            const call = mapAgentToolCall(t);
+            return call ? [call] : [];
+        })
+        : [];
+    const metrics = mapAgentHistoryMetrics(row.metrics);
+    const commitStatus = presentText(row.commitStatus) ?? "COMMITTED";
+    const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+    const jobKey = presentEngineKey(row.jobKey);
+    const producedAt = presentText(row.producedAt);
+    return {
+        historyItemKey,
+        agentInstanceKey,
+        loopIteration,
+        role: normalizeAgentHistoryRole(row.role),
+        content,
+        toolCalls,
+        ...(metrics ? { metrics } : {}),
+        commitStatus,
+        ...(elementInstanceKey ? { elementInstanceKey } : {}),
+        ...(jobKey ? { jobKey } : {}),
+        ...(producedAt ? { producedAt } : {}),
+    };
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -780,6 +965,83 @@ export class SdkEngineClient {
         // as "no XML" (null) so a caller distinguishes "have it" from "don't".
         return typeof xml === "string" && xml.trim() !== "" ? xml : null;
     }
+    async searchAgentInstances(filter) {
+        // Same shape as `searchIncidents`: build the engine filter from the transport-agnostic
+        // selectors, read at zero-wait consistency (an agent-instance search is eventually
+        // consistent), and map each row through the single `mapAgentInstanceRow` gate, dropping
+        // malformed rows. Normalize the request key selectors the same way the response mapper
+        // normalizes keys so a blank/padded selector cannot reach the engine as a garbage filter.
+        const f = {};
+        const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+        if (processInstanceKey)
+            f.processInstanceKey = processInstanceKey;
+        const rootProcessInstanceKey = presentEngineKey(filter?.rootProcessInstanceKey);
+        if (rootProcessInstanceKey)
+            f.rootProcessInstanceKey = rootProcessInstanceKey;
+        const status = filter?.status?.trim();
+        if (status)
+            f.status = status;
+        const elementId = filter?.elementId?.trim();
+        if (elementId)
+            f.elementId = elementId;
+        const body = await this.client.searchAgentInstances({ filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapAgentInstanceRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async searchAgentInstanceHistory(agentInstanceKey, filter) {
+        // A blank key can never address an agent instance — short-circuit to the empty list rather
+        // than issue a `POST /agent-instances//history/search` with an empty path segment. Normalize a
+        // padded-but-valid key so `" 5 "` addresses the same instance, mirroring `getElementInstance`.
+        const key = presentEngineKey(agentInstanceKey);
+        if (key === undefined)
+            return [];
+        const f = {};
+        // `AgentHistoryFilter.role` is typed as the wider transcript `TranscriptTurnRole` union, which
+        // also carries `CONFIGURATION`/`UNSPECIFIED` — roles the engine's history filter does not
+        // accept and would 4xx on. Gate the selector through the same `AGENT_HISTORY_ROLES` subset the
+        // response mapper uses (No Drift Surfaces) so an unsupported role is dropped, not forwarded.
+        if (filter?.role && AGENT_HISTORY_ROLES.includes(filter.role))
+            f.role = filter.role;
+        if (typeof filter?.loopIteration === "number" && Number.isFinite(filter.loopIteration)) {
+            f.loopIteration = filter.loopIteration;
+        }
+        const elementInstanceKey = presentEngineKey(filter?.elementInstanceKey);
+        if (elementInstanceKey)
+            f.elementInstanceKey = elementInstanceKey;
+        const body = await this.client.searchAgentInstanceHistory({ agentInstanceKey: key, filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapAgentHistoryRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async getAgentInstance(agentInstanceKey) {
+        // A blank key can never address an agent instance — short-circuit to null rather than issue a
+        // `GET /agent-instances/` with an empty segment. Normalize a padded-but-valid key, mirroring
+        // `getElementInstance`/`getProcessDefinitionXml`.
+        const key = presentEngineKey(agentInstanceKey);
+        if (key === undefined)
+            return null;
+        let body;
+        try {
+            body = await this.client.getAgentInstance({ agentInstanceKey: key }, { consistency: { waitUpToMs: 0 } });
+        }
+        catch (err) {
+            // A 404 (no such agent instance) is an expected "not found", not a fault — mirror `getForm`/
+            // `getElementInstance`, which treat a failed fetch as absence (null) rather than propagating.
+            this.log("warn", "getAgentInstance: engine fetch failed", {
+                agentInstanceKey: key,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        if (!isRecord(body))
+            return null;
+        return mapAgentInstanceRow(body, this.log) ?? null;
+    }
     async resolveIncident(input) {
         await this.client.resolveIncident({
             incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),

package/dist/runtime/index.d.ts

@@ -8,7 +8,8 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceMetrics, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { TranscriptContentBlock, TranscriptContentType, TranscriptToolCall, TranscriptTurnMetrics, TranscriptTurnRole, } from "@nanobpm/agentic/transcript";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.92.1",
+	"version": "0.93.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -103,6 +103,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@nanobpm/agentic": "^0.13.0",
 		"@nanobpm/nano-app-schema": "^0.9.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",