@iloveagents/foundry-agent 0.4.0 → 0.5.0

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

@@ -21,6 +21,13 @@ export interface AGUIRunnerOptions {
     threadId?: string;
     /** Optional override for the underlying fetch — useful for auth-attached fetch. */
     fetchFn?: typeof fetch;
+    /**
+     * Emit a `streaming-status: stalled` event when no AG-UI event (including
+     * server heartbeats) has arrived for this many ms during an active run.
+     * The status recovers automatically on the next event. Default 45s —
+     * three missed 15s server heartbeats. Pass `Infinity` to disable.
+     */
+    stallAfterMs?: number;
 }
 export interface AGUIRunInput {
     /** AG-UI messages — caller is responsible for runtime-specific message conversion. */
@@ -42,6 +49,7 @@ export interface AGUIRunInput {
  */
 export declare class AGUIRunner {
     private readonly httpAgent;
+    private readonly stallAfterMs;
     constructor(options?: AGUIRunnerOptions);
     get threadId(): string;
     get state(): unknown;

package/dist/client/agui-runner.js

@@ -106,6 +106,7 @@ export class AGUIRunner {
             threadId: options.threadId ?? crypto.randomUUID(),
             ...(options.fetchFn ? { fetch: options.fetchFn } : {}),
         });
+        this.stallAfterMs = options.stallAfterMs ?? 45000;
     }
     get threadId() {
         return this.httpAgent.threadId;
@@ -154,33 +155,83 @@ export class AGUIRunner {
                     tools,
                     context: context ?? [],
                 };
-                queue.push({ type: "turn-started" });
-                queue.push({ type: "streaming-status", status: { status: "thinking" } });
-                queue.push({ type: "request-sent", input: runInputSnapshot });
+                // --- Liveness + protocol-integrity bookkeeping (per turn) ---
+                // AG-UI requires a terminal RUN_FINISHED or RUN_ERROR. A stream that
+                // merely closes (proxy idle-timeout, dropped connection, dead
+                // replica) would otherwise look like a clean completion and a
+                // truncated answer would render as final — the silent-wedge bug.
+                let sawTerminal = false;
+                let stalled = false;
+                let lastStatus = { status: "thinking" };
+                let lastEventAt = Date.now();
+                const push = (evt) => {
+                    lastEventAt = Date.now();
+                    if (evt.type === "streaming-status") {
+                        if (evt.status.status === "stalled") {
+                            stalled = true;
+                        }
+                        else {
+                            lastStatus = evt.status;
+                            stalled = false;
+                        }
+                        queue.push(evt);
+                        return;
+                    }
+                    if (stalled) {
+                        // First live signal after a stall — restore the pre-stall phase.
+                        stalled = false;
+                        queue.push({ type: "streaming-status", status: lastStatus });
+                    }
+                    queue.push(evt);
+                };
+                const stallTimer = Number.isFinite(this.stallAfterMs)
+                    ? setInterval(() => {
+                        if (stalled || sawTerminal)
+                            return;
+                        if (Date.now() - lastEventAt >= this.stallAfterMs) {
+                            push({ type: "streaming-status", status: { status: "stalled" } });
+                        }
+                    }, Math.min(5000, Math.max(25, Math.floor(this.stallAfterMs / 3))))
+                    : null;
+                push({ type: "turn-started" });
+                push({ type: "streaming-status", status: { status: "thinking" } });
+                push({ type: "request-sent", input: runInputSnapshot });
                 const subscriber = {
                     onRunStartedEvent: () => {
-                        queue.push({ type: "run-started" });
-                        queue.push({ type: "streaming-status", status: { status: "thinking" } });
+                        push({ type: "run-started" });
+                        push({ type: "streaming-status", status: { status: "thinking" } });
                     },
                     onTextMessageStartEvent: () => {
-                        queue.push({ type: "streaming-status", status: { status: "streaming" } });
+                        push({ type: "streaming-status", status: { status: "streaming" } });
                     },
                     onTextMessageContentEvent: ({ event }) => {
                         turnAssistantText += event.delta;
-                        queue.push({ type: "text-delta", delta: event.delta });
+                        push({ type: "text-delta", delta: event.delta });
                     },
                     onTextMessageEndEvent: () => {
-                        queue.push({ type: "text-message-end" });
+                        push({ type: "text-message-end" });
+                    },
+                    onCustomEvent: ({ event }) => {
+                        // Server heartbeat: liveness proof during long tool calls /
+                        // thinking phases (also keeps intermediary idle-timeouts at bay
+                        // server-side). Not a UI-visible event.
+                        if (event.name !== "heartbeat")
+                            return;
+                        const value = event.value;
+                        push({
+                            type: "heartbeat",
+                            ...(typeof value?.elapsedMs === "number" ? { elapsedMs: value.elapsedMs } : {}),
+                        });
                     },
                     onToolCallStartEvent: ({ event }) => {
                         const id = event.toolCallId;
                         const name = event.toolCallName;
                         toolCalls.set(id, { id, name, args: "" });
-                        queue.push({
+                        push({
                             type: "streaming-status",
                             status: { status: "calling", toolName: name },
                         });
-                        queue.push({
+                        push({
                             type: "tool-call-start",
                             id,
                             name,
@@ -191,7 +242,7 @@ export class AGUIRunner {
                         const tc = toolCalls.get(event.toolCallId);
                         if (tc)
                             tc.args += event.delta;
-                        queue.push({ type: "tool-call-args", id: event.toolCallId, delta: event.delta });
+                        push({ type: "tool-call-args", id: event.toolCallId, delta: event.delta });
                     },
                     onToolCallEndEvent: async ({ event }) => {
                         const tc = toolCalls.get(event.toolCallId);
@@ -211,7 +262,7 @@ export class AGUIRunner {
                                 tc.isError = true;
                             }
                         }
-                        queue.push({
+                        push({
                             type: "tool-call-end",
                             id: event.toolCallId,
                             args: tc.args,
@@ -238,7 +289,7 @@ export class AGUIRunner {
                         }
                         tc.result = parsedResult;
                         tc.isError = isError;
-                        queue.push({
+                        push({
                             type: "tool-call-result",
                             id: event.toolCallId,
                             result: parsedResult,
@@ -246,24 +297,51 @@ export class AGUIRunner {
                         });
                     },
                     onRunFinishedEvent: () => {
-                        queue.push({ type: "streaming-status", status: { status: "idle" } });
-                        queue.push({ type: "run-finished" });
+                        sawTerminal = true;
+                        push({ type: "streaming-status", status: { status: "idle" } });
+                        push({ type: "run-finished" });
                     },
                     onRunErrorEvent: ({ event }) => {
-                        queue.push({ type: "streaming-status", status: { status: "idle" } });
-                        queue.push({ type: "run-error", message: event.message ?? "Run error" });
+                        sawTerminal = true;
+                        push({ type: "streaming-status", status: { status: "idle" } });
+                        push({ type: "run-error", message: event.message ?? "Run error" });
                     },
                 };
                 // Wire abort: AG-UI exposes abortRun(); call it when the caller's signal fires.
                 const onAbort = () => this.httpAgent.abortRun();
                 abortSignal?.addEventListener("abort", onAbort, { once: true });
                 // Kick off the run — completion ends the queue. Errors during the
-                // run surface via onRunErrorEvent; transport-level rejections
-                // (e.g. fetch failure) are propagated through queue.end(err).
+                // run surface via onRunErrorEvent. Two failure shapes are normalized
+                // onto the same `run-error` surface so every failure renders in chat
+                // instead of dying silently:
+                //   1. The stream closed WITHOUT a terminal RUN_FINISHED/RUN_ERROR
+                //      (proxy idle-timeout, dropped connection, dead replica) — the
+                //      AG-UI client treats that as a clean completion, so we detect
+                //      the protocol violation here.
+                //   2. Transport-level rejection (fetch failure, TLS reset).
                 const runPromise = this.httpAgent
                     .runAgent({ runId, tools, context: context ?? [] }, subscriber)
-                    .then(() => queue.end())
-                    .catch((err) => queue.end(err));
+                    .then(() => {
+                    if (!sawTerminal && !abortSignal?.aborted) {
+                        push({ type: "streaming-status", status: { status: "idle" } });
+                        push({
+                            type: "run-error",
+                            message: "Connection to the agent was lost before the response finished — " +
+                                "the answer may be incomplete. Please retry.",
+                        });
+                    }
+                    queue.end();
+                })
+                    .catch((err) => {
+                    if (!sawTerminal && !abortSignal?.aborted) {
+                        push({ type: "streaming-status", status: { status: "idle" } });
+                        push({
+                            type: "run-error",
+                            message: err instanceof Error ? err.message : "The request to the agent failed.",
+                        });
+                    }
+                    queue.end();
+                });
                 try {
                     for await (const evt of queue.drain()) {
                         yield evt;
@@ -274,6 +352,8 @@ export class AGUIRunner {
                     }
                 }
                 finally {
+                    if (stallTimer !== null)
+                        clearInterval(stallTimer);
                     abortSignal?.removeEventListener("abort", onAbort);
                     await runPromise; // ensure the run task is settled
                 }

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

@@ -51,4 +51,14 @@ export type RunnerEvent = {
 } | {
     type: "run-error";
     message: string;
+}
+/**
+ * Server liveness signal (AG-UI CUSTOM event named `heartbeat`, emitted by
+ * the backend between real events so long tool calls / thinking phases are
+ * distinguishable from a dead pipe). Carries the server-side elapsed run
+ * time when provided. Consumers refresh their liveness clock; no UI yield.
+ */
+ | {
+    type: "heartbeat";
+    elapsedMs?: number;
 };

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

@@ -1,11 +1,23 @@
 /** Streaming status emitted by the AG-UI runner. */
 export interface StreamingStatus {
-    status: "thinking" | "calling" | "streaming" | "idle";
+    status: "thinking" | "calling" | "streaming" | "stalled" | "idle";
     toolName?: string;
 }
 interface StreamingStatusState {
     streamingStatus: StreamingStatus;
+    /**
+     * Wall-clock ms of the last signal proving the run is alive — any runner
+     * event or a server heartbeat. `null` outside a run. Consumers use it to
+     * distinguish "quietly working" from "pipe is dead".
+     */
+    lastSignalAt: number | null;
+    /** Wall-clock ms when the active run started; `null` when idle. */
+    runStartedAt: number | null;
     setStreamingStatus: (status: StreamingStatus) => void;
+    /** Record liveness (runner event or server heartbeat arrived). */
+    touchSignal: () => void;
+    markRunStarted: () => void;
+    markRunEnded: () => void;
 }
 /**
  * Vanilla store for streaming status. Use `useStore(streamingStatusStore, ...)`

package/dist/store/streaming-status-store.js

@@ -5,5 +5,10 @@ import { createStore } from "zustand/vanilla";
  */
 export const streamingStatusStore = createStore((set) => ({
     streamingStatus: { status: "idle" },
-    setStreamingStatus: (streamingStatus) => set({ streamingStatus }),
+    lastSignalAt: null,
+    runStartedAt: null,
+    setStreamingStatus: (streamingStatus) => set({ streamingStatus, lastSignalAt: Date.now() }),
+    touchSignal: () => set({ lastSignalAt: Date.now() }),
+    markRunStarted: () => set({ runStartedAt: Date.now(), lastSignalAt: Date.now() }),
+    markRunEnded: () => set({ runStartedAt: null, lastSignalAt: null }),
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",