@iloveagents/foundry-agent 0.7.1 → 0.9.0

package/dist/client/agui-runner.d.ts

@@ -28,6 +28,17 @@ export interface AGUIRunnerOptions {
      * three missed 15s server heartbeats. Pass `Infinity` to disable.
      */
     stallAfterMs?: number;
+    /**
+     * When a run ends with a client-side tool call that never produced a
+     * result, synthesize an error result for it instead of leaving the call
+     * dangling. Defaults to `true`.
+     *
+     * Defence-in-depth for the failure this runner already had once: an
+     * unanswered tool call makes the model re-issue the tool and then report
+     * that it "didn't complete", while the Responses API rejects a replayed
+     * history whose `function_call` has no matching output.
+     */
+    autoCancelPendingToolCalls?: boolean;
 }
 export interface AGUIRunInput {
     /** AG-UI messages — caller is responsible for runtime-specific message conversion. */
@@ -50,6 +61,7 @@ export interface AGUIRunInput {
 export declare class AGUIRunner {
     private readonly httpAgent;
     private readonly stallAfterMs;
+    private readonly autoCancelPendingToolCalls;
     constructor(options?: AGUIRunnerOptions);
     get threadId(): string;
     get state(): unknown;

package/dist/client/agui-runner.js

@@ -14,6 +14,7 @@
  * @see https://docs.ag-ui.com/sdk/js/client/subscriber
  */
 import { HttpAgent } from "@ag-ui/client";
+import { reasoningEffortStore } from "../store/reasoning-effort-store.js";
 function shouldPreserveAcrossVisibleHistory(message) {
     return message.role === "system" || message.role === "developer" || message.role === "reasoning";
 }
@@ -107,6 +108,7 @@ export class AGUIRunner {
             ...(options.fetchFn ? { fetch: options.fetchFn } : {}),
         });
         this.stallAfterMs = options.stallAfterMs ?? 45000;
+        this.autoCancelPendingToolCalls = options.autoCancelPendingToolCalls ?? true;
     }
     get threadId() {
         return this.httpAgent.threadId;
@@ -147,6 +149,12 @@ export class AGUIRunner {
                 // Build the request input now, before runAgent fires — dev tooling
                 // consumes this snapshot via the request-sent event. `runId` is
                 // pre-generated so the snapshot matches what runAgent emits.
+                // The user's reasoning-effort choice rides on every turn as an
+                // AG-UI forwardedProp — read at request time so changing it
+                // mid-conversation takes effect on the next message. "default"
+                // sends nothing so the backend keeps its configured level.
+                const chosenEffort = reasoningEffortStore.getState().effort;
+                const forwardedProps = chosenEffort === "default" ? {} : { reasoningEffort: chosenEffort };
                 const runInputSnapshot = {
                     threadId: this.httpAgent.threadId,
                     runId,
@@ -154,6 +162,7 @@ export class AGUIRunner {
                     messages: currentMessages,
                     tools,
                     context: context ?? [],
+                    forwardedProps,
                 };
                 // --- Liveness + protocol-integrity bookkeeping (per turn) ---
                 // AG-UI requires a terminal RUN_FINISHED or RUN_ERROR. A stream that
@@ -211,6 +220,81 @@ export class AGUIRunner {
                     onTextMessageEndEvent: () => {
                         push({ type: "text-message-end" });
                     },
+                    // Reasoning/thinking. `@ag-ui/client` normalizes the deprecated
+                    // THINKING_* events onto REASONING_* via its backward-compat
+                    // middleware, so subscribing here covers both wire dialects.
+                    onReasoningMessageStartEvent: () => {
+                        push({ type: "streaming-status", status: { status: "reasoning" } });
+                    },
+                    onReasoningMessageContentEvent: ({ event }) => {
+                        push({ type: "reasoning-delta", delta: event.delta });
+                    },
+                    onReasoningEndEvent: () => {
+                        push({ type: "reasoning-end" });
+                        // Reasoning ended but the answer hasn't started — back to the
+                        // generic working state rather than leaving "reasoning" stuck.
+                        push({ type: "streaming-status", status: { status: "thinking" } });
+                    },
+                    onStepStartedEvent: ({ event }) => {
+                        push({ type: "step-started", name: event.stepName });
+                        push({
+                            type: "streaming-status",
+                            status: { status: lastStatus.status, stepName: event.stepName },
+                        });
+                    },
+                    onStepFinishedEvent: ({ event }) => {
+                        push({ type: "step-finished", name: event.stepName });
+                    },
+                    // Reasoning has two nested boundaries: a BLOCK
+                    // (REASONING_START…REASONING_END) may contain several MESSAGES
+                    // (REASONING_MESSAGE_START…REASONING_MESSAGE_END). `reasoning-end`
+                    // means "the model stopped thinking", so it is emitted only for the
+                    // block terminal in `onReasoningEndEvent`. Emitting it per message
+                    // too would fire it repeatedly and let consumers treat reasoning as
+                    // finished while it is still going.
+                    onReasoningStartEvent: () => {
+                        push({ type: "streaming-status", status: { status: "reasoning" } });
+                    },
+                    // Server-published agent state. The AG-UI client has already
+                    // applied the snapshot/patch to `httpAgent.state`; forward the
+                    // result so consumers don't reach into the client.
+                    onStateSnapshotEvent: () => {
+                        push({ type: "agent-state", state: this.httpAgent.state });
+                    },
+                    onStateDeltaEvent: ({ event }) => {
+                        push({
+                            type: "agent-state",
+                            state: this.httpAgent.state,
+                            patch: event.delta,
+                        });
+                    },
+                    // Server-authoritative history (e.g. after backend compaction).
+                    // Deliberately does NOT touch the in-flight turn: upstream saw
+                    // mid-run snapshots truncate a streaming answer.
+                    onMessagesSnapshotEvent: ({ event }) => {
+                        push({ type: "messages-snapshot", messages: event.messages });
+                    },
+                    // Generative-UI surfaces (MCP apps / A2UI), passed through.
+                    onActivitySnapshotEvent: ({ event }) => {
+                        push({
+                            type: "activity",
+                            messageId: event.messageId,
+                            activityType: event.activityType,
+                            content: event.content,
+                        });
+                    },
+                    onActivityDeltaEvent: ({ event }) => {
+                        push({
+                            type: "activity",
+                            messageId: event.messageId,
+                            activityType: event.activityType,
+                            patch: event.patch,
+                        });
+                    },
+                    // Provider passthrough — never interpreted here.
+                    onRawEvent: ({ event }) => {
+                        push({ type: "raw", event: event.event, source: event.source });
+                    },
                     onCustomEvent: ({ event }) => {
                         // Server heartbeat: liveness proof during long tool calls /
                         // thinking phases (also keeps intermediary idle-timeouts at bay
@@ -320,7 +404,7 @@ export class AGUIRunner {
                 //      the protocol violation here.
                 //   2. Transport-level rejection (fetch failure, TLS reset).
                 const runPromise = this.httpAgent
-                    .runAgent({ runId, tools, context: context ?? [] }, subscriber)
+                    .runAgent({ runId, tools, context: context ?? [], forwardedProps }, subscriber)
                     .then(() => {
                     if (!sawTerminal && !abortSignal?.aborted) {
                         push({ type: "streaming-status", status: { status: "idle" } });
@@ -357,6 +441,26 @@ export class AGUIRunner {
                     abortSignal?.removeEventListener("abort", onAbort);
                     await runPromise; // ensure the run task is settled
                 }
+                // Any client-side tool that was STARTED but never produced a
+                // result leaves a `function_call` with no output. Settle it here so
+                // the replayed history stays valid and the model isn't left waiting
+                // on an answer that will never come.
+                if (this.autoCancelPendingToolCalls) {
+                    for (const tc of toolCalls.values()) {
+                        if (!registry.isRegistered(tc.name))
+                            continue;
+                        if (tc.result !== undefined || tc.followedUp)
+                            continue;
+                        tc.result = { error: "Tool call did not complete before the run ended." };
+                        tc.isError = true;
+                        yield {
+                            type: "tool-call-result",
+                            id: tc.id,
+                            result: tc.result,
+                            isError: true,
+                        };
+                    }
+                }
                 // Decide whether to re-issue: any client-side tool that resolved
                 // during this turn and hasn't been replayed yet.
                 const pendingClientTools = Array.from(toolCalls.values()).filter((tc) => registry.isRegistered(tc.name) && tc.result !== undefined && !tc.followedUp);
@@ -366,29 +470,59 @@ export class AGUIRunner {
                     tc.followedUp = true;
                 // Build follow-up messages with the SAME toolCallId the agent emitted.
                 // Tool results are appended to the agent's message history (AG-UI
-                // convention — append, never replace). Preserve any pre-tool text
-                // the model emitted in this turn so the next-turn context matches
-                // what the user actually saw.
-                const assistantMsg = {
-                    id: crypto.randomUUID(),
-                    role: "assistant",
-                    content: turnAssistantText,
-                    toolCalls: pendingClientTools.map((tc) => ({
-                        id: tc.id,
-                        type: "function",
-                        function: { name: tc.name, arguments: tc.args },
-                    })),
-                };
-                const toolResultMsgs = pendingClientTools.map((tc) => ({
-                    id: crypto.randomUUID(),
-                    role: "tool",
-                    toolCallId: tc.id,
-                    content: typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result),
-                }));
-                currentMessages = [...currentMessages, assistantMsg, ...toolResultMsgs];
-                for (const m of [assistantMsg, ...toolResultMsgs]) {
+                // convention — append, never replace).
+                //
+                // The AG-UI client folds the streamed assistant message — tool calls
+                // included — into `httpAgent.messages` itself (AbstractAgent applies
+                // the event stream to its own history). Appending an unconditional
+                // second copy put the SAME toolCallId in the history twice with only
+                // one matching tool result, so the model saw an unanswered tool call:
+                // it re-issued the tool (a duplicate card in the UI) and then reported
+                // that the call "didn't complete", even though the tool had succeeded.
+                // Only synthesize what the client hasn't already recorded.
+                const recordedToolCallIds = new Set();
+                const recordedToolResultIds = new Set();
+                for (const message of this.httpAgent.messages) {
+                    if (message.role === "assistant" && message.toolCalls) {
+                        for (const call of message.toolCalls)
+                            recordedToolCallIds.add(call.id);
+                    }
+                    else if (message.role === "tool" && message.toolCallId) {
+                        recordedToolResultIds.add(message.toolCallId);
+                    }
+                }
+                const followUpMessages = [];
+                // Preserve any pre-tool text the model emitted in this turn so the
+                // next-turn context matches what the user actually saw.
+                const unrecordedToolCalls = pendingClientTools.filter((tc) => !recordedToolCallIds.has(tc.id));
+                if (unrecordedToolCalls.length > 0) {
+                    followUpMessages.push({
+                        id: crypto.randomUUID(),
+                        role: "assistant",
+                        content: turnAssistantText,
+                        toolCalls: unrecordedToolCalls.map((tc) => ({
+                            id: tc.id,
+                            type: "function",
+                            function: { name: tc.name, arguments: tc.args },
+                        })),
+                    });
+                }
+                for (const tc of pendingClientTools) {
+                    if (recordedToolResultIds.has(tc.id))
+                        continue;
+                    followUpMessages.push({
+                        id: crypto.randomUUID(),
+                        role: "tool",
+                        toolCallId: tc.id,
+                        content: typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result),
+                    });
+                }
+                for (const m of followUpMessages) {
                     this.httpAgent.addMessage(m);
                 }
+                // Re-sync from the client's history: it is the authority on what the
+                // next request carries (`prepareRunAgentInput` reads it directly).
+                currentMessages = [...this.httpAgent.messages];
             }
         }
         finally {

package/dist/client/runner-events.d.ts

@@ -46,6 +46,75 @@ export type RunnerEvent = {
 } | {
     type: "streaming-status";
     status: StreamingStatus;
+}
+/**
+ * Model reasoning/thinking text (AG-UI `REASONING_*`; the deprecated
+ * `THINKING_*` events are normalized onto these by `@ag-ui/client`'s
+ * backward-compatibility middleware). Kept separate from `text-delta`
+ * because reasoning is not the answer — consumers render it as its own
+ * collapsed part, never inline with the reply.
+ */
+ | {
+    type: "reasoning-delta";
+    delta: string;
+} | {
+    type: "reasoning-end";
+}
+/**
+ * Named agent step (AG-UI `STEP_STARTED` / `STEP_FINISHED`). A long
+ * agentic run otherwise presents as one opaque "thinking" state for
+ * minutes; the step name is what makes the wait legible.
+ */
+ | {
+    type: "step-started";
+    name: string;
+} | {
+    type: "step-finished";
+    name: string;
+}
+/**
+ * Agent state published by the server (`STATE_SNAPSHOT` / `STATE_DELTA`).
+ * The AG-UI client applies deltas (JSON Patch) to its own state; this
+ * event carries the RESULT so consumers can react without reaching into
+ * the client. `patch` is present only for deltas, for consumers that want
+ * to know what changed rather than just the new value.
+ */
+ | {
+    type: "agent-state";
+    state: unknown;
+    patch?: unknown[];
+}
+/**
+ * Server-authoritative history replacement (`MESSAGES_SNAPSHOT`). Emitted
+ * when the backend rewrites the conversation — e.g. after compaction. The
+ * runner does NOT interrupt an in-flight message for this: upstream saw
+ * mid-run snapshots truncate streaming answers, so consumers should
+ * reconcile persisted history and leave the streaming turn alone.
+ */
+ | {
+    type: "messages-snapshot";
+    messages: unknown[];
+}
+/**
+ * Generative-UI surface (`ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA`) — MCP
+ * apps and A2UI. Passed through verbatim; hosts that don't render
+ * activities can ignore it.
+ */
+ | {
+    type: "activity";
+    messageId: string;
+    activityType: string;
+    content?: unknown;
+    patch?: unknown[];
+}
+/**
+ * Provider passthrough (`RAW`). Never interpreted here — hosts use it for
+ * provider-specific behaviour and debugging.
+ */
+ | {
+    type: "raw";
+    event: unknown;
+    source?: string;
 } | {
     type: "run-finished";
 } | {

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { AGUIRunner, type AGUIRunnerOptions, type AGUIRunInput } from "./client/
 export type { RunnerEvent } from "./client/runner-events.js";
 export { createServiceFetch, type ServiceFetch, type ServiceFetchOptions, } from "./client/service-fetch.js";
 export { clientToolRegistry, type ClientToolEntry, type ToolRegistry } from "./tools/registry.js";
+export { agentStateStore } from "./store/agent-state-store.js";
+export { reasoningEffortStore, REASONING_EFFORT_LABELS, type ReasoningEffort, } from "./store/reasoning-effort-store.js";
 export { streamingStatusStore, type StreamingStatus } from "./store/streaming-status-store.js";
 export { citationStore, type CitationResult, type CitationHandler, } from "./store/citation-store.js";
 export { linkStore, resolveLinkHandler, type LinkHandler, type ResolvedLinkHandler, } from "./store/link-store.js";

package/dist/index.js

@@ -5,6 +5,8 @@ export { createServiceFetch, } from "./client/service-fetch.js";
 // --- Tool registry ---
 export { clientToolRegistry } from "./tools/registry.js";
 // --- Stores (vanilla) ---
+export { agentStateStore } from "./store/agent-state-store.js";
+export { reasoningEffortStore, REASONING_EFFORT_LABELS, } from "./store/reasoning-effort-store.js";
 export { streamingStatusStore } from "./store/streaming-status-store.js";
 export { citationStore, } from "./store/citation-store.js";
 export { linkStore, resolveLinkHandler, } from "./store/link-store.js";

package/dist/store/agent-state-store.d.ts

@@ -0,0 +1,21 @@
+interface AgentStateState {
+    /** Latest server-published agent state, or `null` before the first snapshot. */
+    state: unknown;
+    /** JSON Patch from the most recent `STATE_DELTA`, if the last update was one. */
+    lastPatch: unknown[] | null;
+    setAgentState: (state: unknown, patch?: unknown[]) => void;
+    reset: () => void;
+}
+/**
+ * Server-published agent state (AG-UI `STATE_SNAPSHOT` / `STATE_DELTA`).
+ *
+ * The AG-UI client already applies snapshots and JSON-Patch deltas to its
+ * own internal state, but nothing surfaced that to the UI — a page could
+ * only read it by reaching into the transport. This store is the seam:
+ * the runner publishes each update, React consumers bind with
+ * `useStore(agentStateStore, selector)`.
+ *
+ * Vanilla store — this package stays zero-React.
+ */
+export declare const agentStateStore: import("zustand/vanilla").StoreApi<AgentStateState>;
+export {};

package/dist/store/agent-state-store.js

@@ -0,0 +1,18 @@
+import { createStore } from "zustand/vanilla";
+/**
+ * Server-published agent state (AG-UI `STATE_SNAPSHOT` / `STATE_DELTA`).
+ *
+ * The AG-UI client already applies snapshots and JSON-Patch deltas to its
+ * own internal state, but nothing surfaced that to the UI — a page could
+ * only read it by reaching into the transport. This store is the seam:
+ * the runner publishes each update, React consumers bind with
+ * `useStore(agentStateStore, selector)`.
+ *
+ * Vanilla store — this package stays zero-React.
+ */
+export const agentStateStore = createStore((set) => ({
+    state: null,
+    lastPatch: null,
+    setAgentState: (state, patch) => set({ state, lastPatch: patch ?? null }),
+    reset: () => set({ state: null, lastPatch: null }),
+}));

package/dist/store/reasoning-effort-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How hard the model should think before answering.
+ *
+ * `"default"` sends nothing and leaves the backend's configured level
+ * alone — the user hasn't expressed a preference, so we don't override
+ * one. The remaining levels map to the AG-UI/Responses reasoning effort.
+ */
+export type ReasoningEffort = "default" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Level names follow the convention users already know from other assistants
+ * (Instant / Medium / High / Extra High) rather than inventing a private
+ * vocabulary. `Auto` is ours: it means "no preference — use whatever the app
+ * is configured for", which the protocol enum has no member for.
+ */
+export declare const REASONING_EFFORT_LABELS: Record<ReasoningEffort, string>;
+interface ReasoningEffortState {
+    effort: ReasoningEffort;
+    setEffort: (effort: ReasoningEffort) => void;
+}
+/**
+ * The user's chosen reasoning effort, persisted across reloads.
+ *
+ * Vanilla store (this package is zero-React); the runner reads it when
+ * building each request so the choice applies per turn — change it
+ * mid-conversation and the next message uses the new level.
+ */
+export declare const reasoningEffortStore: import("zustand/vanilla").StoreApi<ReasoningEffortState>;
+export {};

package/dist/store/reasoning-effort-store.js

@@ -0,0 +1,39 @@
+import { createStore } from "zustand/vanilla";
+/**
+ * Level names follow the convention users already know from other assistants
+ * (Instant / Medium / High / Extra High) rather than inventing a private
+ * vocabulary. `Auto` is ours: it means "no preference — use whatever the app
+ * is configured for", which the protocol enum has no member for.
+ */
+export const REASONING_EFFORT_LABELS = {
+    default: "Auto",
+    low: "Instant",
+    medium: "Medium",
+    high: "High",
+    xhigh: "Extra High",
+};
+const STORAGE_KEY = "foundry:reasoning-effort";
+function readPersisted() {
+    if (typeof localStorage === "undefined")
+        return "default";
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw === "low" || raw === "medium" || raw === "high" || raw === "xhigh" || raw === "default"
+        ? raw
+        : "default";
+}
+/**
+ * The user's chosen reasoning effort, persisted across reloads.
+ *
+ * Vanilla store (this package is zero-React); the runner reads it when
+ * building each request so the choice applies per turn — change it
+ * mid-conversation and the next message uses the new level.
+ */
+export const reasoningEffortStore = createStore((set) => ({
+    effort: readPersisted(),
+    setEffort: (effort) => {
+        if (typeof localStorage !== "undefined") {
+            localStorage.setItem(STORAGE_KEY, effort);
+        }
+        set({ effort });
+    },
+}));

package/dist/store/streaming-status-store.d.ts

@@ -1,7 +1,14 @@
 /** Streaming status emitted by the AG-UI runner. */
 export interface StreamingStatus {
-    status: "thinking" | "calling" | "streaming" | "stalled" | "idle";
+    status: "thinking" | "reasoning" | "calling" | "streaming" | "stalled" | "idle";
     toolName?: string;
+    /**
+     * Name of the agent step currently running, from AG-UI `STEP_STARTED`.
+     * Long agentic runs otherwise show one opaque "thinking" state for
+     * minutes; the step name is what makes that wait legible. Undefined when
+     * the agent doesn't emit step events.
+     */
+    stepName?: string;
 }
 interface StreamingStatusState {
     streamingStatus: StreamingStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "Cross-runtime AG-UI transport for Foundry UI — AGUIRunner protocol engine, vanilla zustand stores, optional MSAL auth subpath, service-fetch factory. Zero React, zero DOM.",
   "keywords": [