@iloveagents/foundry-agent 0.8.0 → 0.10.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

@@ -108,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;
@@ -151,7 +152,8 @@ export class AGUIRunner {
                 // 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.
+                // sends nothing, which is what makes the backend's own configured
+                // level apply; the picker shows the user what that resolves to.
                 const chosenEffort = reasoningEffortStore.getState().effort;
                 const forwardedProps = chosenEffort === "default" ? {} : { reasoningEffort: chosenEffort };
                 const runInputSnapshot = {
@@ -244,6 +246,56 @@ export class AGUIRunner {
                     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
@@ -390,6 +442,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);

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

@@ -71,6 +71,50 @@ export type RunnerEvent = {
 } | {
     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,7 +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 { reasoningEffortStore, REASONING_EFFORT_LABELS, type ReasoningEffort, } from "./store/reasoning-effort-store.js";
+export { agentStateStore } from "./store/agent-state-store.js";
+export { reasoningDefaultStore, reasoningEffortStore, REASONING_EFFORT_LABELS, type ReasoningEffort, type ResolvedReasoningEffort, } 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,7 +5,8 @@ export { createServiceFetch, } from "./client/service-fetch.js";
 // --- Tool registry ---
 export { clientToolRegistry } from "./tools/registry.js";
 // --- Stores (vanilla) ---
-export { reasoningEffortStore, REASONING_EFFORT_LABELS, } from "./store/reasoning-effort-store.js";
+export { agentStateStore } from "./store/agent-state-store.js";
+export { reasoningDefaultStore, 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

@@ -1,12 +1,55 @@
 /**
  * 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.
+ * `"default"` is a deferral, not a level: it sends nothing, so whatever the
+ * backend is configured for applies. Every other member maps to a real
+ * AG-UI/Responses reasoning effort and is sent verbatim.
+ *
+ * A deferral is only honest if the user can see what it currently resolves
+ * to — otherwise you believe you are on Extra High and are quietly running
+ * Instant, and the control silently decides cost and latency. That is what
+ * {@link reasoningDefaultStore} is for.
+ */
+export type ReasoningEffort = "default" | "low" | "medium" | "high" | "xhigh";
+/** A real effort level — everything except the deferral. */
+export type ResolvedReasoningEffort = Exclude<ReasoningEffort, "default">;
+/**
+ * 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, for the case the protocol enum has no member
+ * for: follow whatever the app is configured for.
  */
-export type ReasoningEffort = "default" | "low" | "medium" | "high";
 export declare const REASONING_EFFORT_LABELS: Record<ReasoningEffort, string>;
+interface ReasoningDefaultState {
+    /**
+     * What `"default"` resolves to right now, or `null` while unknown.
+     *
+     * `null` also covers a backend with reasoning switched off entirely, where
+     * there is no level to name.
+     */
+    resolved: ResolvedReasoningEffort | null;
+    /**
+     * Where that came from, for the picker's hint — e.g. `"this workspace"`.
+     * `null` means unattributed, and the hint stays generic.
+     */
+    scope: string | null;
+    setResolved: (resolved: ResolvedReasoningEffort | null, scope?: string | null) => void;
+}
+/**
+ * What the backend will actually do when the client sends no effort.
+ *
+ * Populated by the host app, never derived here. Re-deriving the backend's
+ * fallback chain client-side is exactly how a label goes stale and starts
+ * lying: the backend changes its default and the UI keeps claiming the old
+ * one. The app fetches this from the server and sets it, and updates it
+ * when the context it depends on changes — switching workspace, say — so
+ * `Auto` always names the level that will really be used.
+ *
+ * Left unset, the picker says it does not know rather than guessing.
+ *
+ * Vanilla store — this package stays zero-React.
+ */
+export declare const reasoningDefaultStore: import("zustand/vanilla").StoreApi<ReasoningDefaultState>;
 interface ReasoningEffortState {
     effort: ReasoningEffort;
     setEffort: (effort: ReasoningEffort) => void;
@@ -17,6 +60,9 @@ interface ReasoningEffortState {
  * 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.
+ *
+ * An explicit level is a pin: nothing moves it, including a change of
+ * context. Only `"default"` follows.
  */
 export declare const reasoningEffortStore: import("zustand/vanilla").StoreApi<ReasoningEffortState>;
 export {};

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

@@ -1,16 +1,44 @@
 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, for the case the protocol enum has no member
+ * for: follow whatever the app is configured for.
+ */
 export const REASONING_EFFORT_LABELS = {
     default: "Auto",
-    low: "Fast",
-    medium: "Balanced",
-    high: "Thorough",
+    low: "Instant",
+    medium: "Medium",
+    high: "High",
+    xhigh: "Extra High",
 };
+/**
+ * What the backend will actually do when the client sends no effort.
+ *
+ * Populated by the host app, never derived here. Re-deriving the backend's
+ * fallback chain client-side is exactly how a label goes stale and starts
+ * lying: the backend changes its default and the UI keeps claiming the old
+ * one. The app fetches this from the server and sets it, and updates it
+ * when the context it depends on changes — switching workspace, say — so
+ * `Auto` always names the level that will really be used.
+ *
+ * Left unset, the picker says it does not know rather than guessing.
+ *
+ * Vanilla store — this package stays zero-React.
+ */
+export const reasoningDefaultStore = createStore((set) => ({
+    resolved: null,
+    scope: null,
+    setResolved: (resolved, scope) => set({ resolved, scope: scope ?? null }),
+}));
 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 === "default" ? raw : "default";
+    return raw === "low" || raw === "medium" || raw === "high" || raw === "xhigh" || raw === "default"
+        ? raw
+        : "default";
 }
 /**
  * The user's chosen reasoning effort, persisted across reloads.
@@ -18,6 +46,9 @@ function readPersisted() {
  * 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.
+ *
+ * An explicit level is a pin: nothing moves it, including a change of
+ * context. Only `"default"` follows.
  */
 export const reasoningEffortStore = createStore((set) => ({
     effort: readPersisted(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.8.0",
+  "version": "0.10.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": [