@code-yeongyu/senpi-agent-core 2026.10.30-1 → 2026.10.30-2

package/dist/agent-loop.js

@@ -7,6 +7,7 @@ import { createTerminalFailureAssistantMessage, isStreamIdleTimeoutError, normal
 import { createResponseTimingRecorder } from "./response-timing.js";
 import { internalProgressSink } from "./internal-events.js";
 import { getDefaultStreamFn, withEmptyAssistantRecovery } from "./stream-fn.js";
+import { createTransportLiveness, StreamKeepAliveTimeoutError } from "./stream-keepalive.js";
 import { prepareAgentToolCallArguments } from "./tool-arguments.js";
 import { resolveCallTool, withToolNameCorrection } from "./tool-name-alias.js";
 /**
@@ -465,6 +466,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
     // Dedicated controller for the provider request so the loop can tear the
     // request down itself (idle timeout), not only when the caller aborts.
     const requestAbortController = new AbortController();
+    const liveness = createTransportLiveness(normalizeTimeoutMs(config.streamKeepAliveTimeoutMs));
     let detachCallerAbort;
     if (signal !== undefined) {
         if (signal.aborted) {
@@ -490,6 +492,10 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
             streamKind: "main",
             apiKey: resolvedApiKey,
             signal: requestAbortController.signal,
+            onTransportActivity: () => {
+                liveness.noteActivity();
+                config.onTransportActivity?.();
+            },
             // Cursor exec bridging (ignored by every other provider): handlers
             // execute mid-stream; their paired results buffer here.
             ...(config.cursorExecHandlers
@@ -515,7 +521,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
         const sink = config[internalProgressSink];
         const records = sink ? assistantRecords(response) : response;
         const iterator = records[Symbol.asyncIterator]();
-        const eventReader = createAssistantEventReader(iterator, streamIdleTimeoutMs, requestAbortController.signal, (error) => requestAbortController.abort(error), preStream.remainingStartMs(), response, normalizeTimeoutMs(config.streamStartTimeoutMs));
+        const eventReader = createAssistantEventReader(iterator, streamIdleTimeoutMs, requestAbortController.signal, (error) => requestAbortController.abort(error), preStream.remainingStartMs(), response, normalizeTimeoutMs(config.streamStartTimeoutMs), liveness);
         try {
             while (true) {
                 const next = await eventReader.next();
@@ -660,7 +666,10 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
         // A step that rethrows the caller's own reason (`throwIfAborted()`, a fetch rejected with it) shows that reason
         // through the same shaping and cap (#3510).
         const callerAbortedPastBound = signal?.aborted === true &&
-            (error instanceof StreamStartTimeoutError || isStreamIdleTimeoutError(error) || error === signal.reason);
+            (error instanceof StreamStartTimeoutError ||
+                error instanceof StreamKeepAliveTimeoutError ||
+                isStreamIdleTimeoutError(error) ||
+                error === signal.reason);
         const finalMessage = createTerminalFailureAssistantMessage(config.model, signal?.aborted ? "aborted" : "error", callerAbortedPastBound ? abortError(signal.reason) : error, partialMessage);
         stampTiming(finalMessage);
         if (addedPartial) {
@@ -763,7 +772,7 @@ function normalizeTimeoutMs(timeoutMs) {
 function createAssistantEventReader(iterator, timeoutMs, signal, onIdleTimeout, streamStartTimeoutMs, stream, 
 // The bound the error names, when the timer only gets what is left of it (the steps before the stream used
 // the rest); the error must name the configured bound, which users raise.
-configuredStartTimeoutMs) {
+configuredStartTimeoutMs, liveness) {
     const idleTimeoutMs = normalizeTimeoutMs(timeoutMs);
     const startTimeoutMs = normalizeTimeoutMs(streamStartTimeoutMs);
     const reportedStartTimeoutMs = configuredStartTimeoutMs ?? startTimeoutMs;
@@ -798,20 +807,24 @@ configuredStartTimeoutMs) {
                 ? (ms) => new StreamStartTimeoutError(reportedStartTimeoutMs ?? ms)
                 : (ms) => new StreamIdleTimeoutError(idleTimeoutMs ?? ms);
             const readStartedAt = Date.now();
-            const result = await readNextAssistantEvent(iterator, readTimeoutMs === undefined ? undefined : Math.max(1, readTimeoutMs - silentMs), makeTimeoutError, abortPromise, onIdleTimeout, stream, signal);
+            // Keep-alives are judged against the whole configured bound, not the share of it left for this read.
+            const windowMs = useStartBound ? (reportedStartTimeoutMs ?? startTimeoutMs) : idleTimeoutMs;
+            const result = await readNextAssistantEvent(iterator, readTimeoutMs === undefined ? undefined : Math.max(1, readTimeoutMs - silentMs), makeTimeoutError, abortPromise, onIdleTimeout, stream, signal, liveness && windowMs !== undefined ? { liveness, windowMs } : undefined);
             if (!result.done && isAssistantProgress(result.value))
                 silentMs += Date.now() - readStartedAt;
             else {
                 silentMs = 0;
-                if (!result.done)
+                if (!result.done) {
                     sawFirstEvent = true;
+                    liveness?.contentArrived();
+                }
             }
             return result;
         },
         dispose: () => removeAbortListener?.(),
     };
 }
-async function readNextAssistantEvent(iterator, idleTimeoutMs, makeTimeoutError, abortPromise, onIdleTimeout, stream, signal) {
+async function readNextAssistantEvent(iterator, idleTimeoutMs, makeTimeoutError, abortPromise, onIdleTimeout, stream, signal, keepAlive) {
     if (idleTimeoutMs === undefined && abortPromise === undefined) {
         return iterator.next();
     }
@@ -837,7 +850,13 @@ async function readNextAssistantEvent(iterator, idleTimeoutMs, makeTimeoutError,
                     timeout = setTimeout(onIdleDeadline, idleTimeoutMs);
                     return;
                 }
-                const error = makeTimeoutError(idleTimeoutMs);
+                // A provider that accepted the request and is still sending keep-alive bytes is working, not dead.
+                const verdict = keepAlive?.liveness.onSilenceDeadline(keepAlive.windowMs);
+                if (verdict?.kind === "extend") {
+                    timeout = setTimeout(onIdleDeadline, verdict.delayMs);
+                    return;
+                }
+                const error = verdict?.kind === "keep-alive-exhausted" ? verdict.error : makeTimeoutError(idleTimeoutMs);
                 closeAssistantIterator(iterator);
                 settle(() => reject(error));
                 // Abort after settling so the failure surfaces as an idle timeout,

package/dist/agent.d.ts

@@ -34,6 +34,7 @@ export interface AgentOptions {
     transport?: Transport;
     timeoutMs?: number;
     streamStartTimeoutMs?: number;
+    streamKeepAliveTimeoutMs?: number;
     maxRetryDelayMs?: number;
     toolExecution?: ToolExecutionMode;
     removedToolHints?: Record<string, string>;
@@ -106,6 +107,8 @@ export declare class Agent {
     timeoutMs?: number;
     /** Optional bound on the wait for the first provider stream event. */
     streamStartTimeoutMs?: number;
+    /** Optional bound on how long keep-alives alone may hold a provider request without content. */
+    streamKeepAliveTimeoutMs?: number;
     /** Optional cap for provider-requested retry delays. */
     maxRetryDelayMs?: number;
     /** Tool execution strategy for assistant messages that contain multiple tool calls. */

package/dist/agent.js

@@ -163,6 +163,7 @@ export class Agent {
         this.transport = runtimeOptions.transport ?? "auto";
         this.timeoutMs = runtimeOptions.timeoutMs;
         this.streamStartTimeoutMs = runtimeOptions.streamStartTimeoutMs;
+        this.streamKeepAliveTimeoutMs = runtimeOptions.streamKeepAliveTimeoutMs;
         this.maxRetryDelayMs = runtimeOptions.maxRetryDelayMs;
         this.toolExecution = runtimeOptions.toolExecution ?? "parallel";
         this.removedToolHints = runtimeOptions.removedToolHints ?? {};
@@ -473,6 +474,7 @@ export class Agent {
             thinkingBudgets: this.thinkingBudgets,
             timeoutMs: this.timeoutMs,
             streamStartTimeoutMs: this.streamStartTimeoutMs,
+            streamKeepAliveTimeoutMs: this.streamKeepAliveTimeoutMs,
             initialRequestTimeoutMs: options.initialRequestTimeoutMs,
             initialRequestStreamStartTimeoutMs: options.initialRequestStreamStartTimeoutMs,
             maxRetryDelayMs: this.maxRetryDelayMs,

package/dist/stream-keepalive.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Transport liveness for one provider request (senpi#4608).
+ *
+ * The loop's silence bounds count public assistant events. A provider that accepted the request and keeps its
+ * connection alive - SSE `ping` events, `:` comment keep-alives a relay sends while the upstream model is still
+ * thinking - emits none of those, so a slow first token used to be killed as if the connection were dead. Providers
+ * report received bytes through `onTransportActivity`; a silence bound that fires within one bound of the last
+ * byte is extended instead of ending the request, and keep-alives alone are bounded by their own budget.
+ */
+export declare class StreamKeepAliveTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+export type SilenceDeadlineVerdict = {
+    kind: "expire";
+} | {
+    kind: "extend";
+    delayMs: number;
+} | {
+    kind: "keep-alive-exhausted";
+    error: StreamKeepAliveTimeoutError;
+};
+export interface TransportLiveness {
+    readonly noteActivity: () => void;
+    contentArrived(): void;
+    onSilenceDeadline(windowMs: number): SilenceDeadlineVerdict;
+}
+export declare function createTransportLiveness(keepAliveTimeoutMs: number | undefined): TransportLiveness;
+//# sourceMappingURL=stream-keepalive.d.ts.map

package/dist/stream-keepalive.js

@@ -0,0 +1,42 @@
+/**
+ * Transport liveness for one provider request (senpi#4608).
+ *
+ * The loop's silence bounds count public assistant events. A provider that accepted the request and keeps its
+ * connection alive - SSE `ping` events, `:` comment keep-alives a relay sends while the upstream model is still
+ * thinking - emits none of those, so a slow first token used to be killed as if the connection were dead. Providers
+ * report received bytes through `onTransportActivity`; a silence bound that fires within one bound of the last
+ * byte is extended instead of ending the request, and keep-alives alone are bounded by their own budget.
+ */
+// The wording keeps "timed out" so the retryable-error classifier treats it like the other stream bounds.
+export class StreamKeepAliveTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Provider stream sent only keep-alives and timed out after ${timeoutMs}ms (raise streamKeepAliveTimeoutMs: retry.provider.keepAliveTimeoutMs in senpi settings; 0 disables)`);
+        this.name = "StreamKeepAliveTimeoutError";
+    }
+}
+export function createTransportLiveness(keepAliveTimeoutMs) {
+    let lastActivityAt;
+    let contentSilenceSince = Date.now();
+    return {
+        noteActivity: () => {
+            lastActivityAt = Date.now();
+        },
+        contentArrived: () => {
+            contentSilenceSince = Date.now();
+        },
+        onSilenceDeadline: (windowMs) => {
+            const now = Date.now();
+            if (lastActivityAt === undefined || now - lastActivityAt >= windowMs)
+                return { kind: "expire" };
+            const delayMs = windowMs - (now - lastActivityAt);
+            if (keepAliveTimeoutMs === undefined)
+                return { kind: "extend", delayMs };
+            const keepAliveLeftMs = keepAliveTimeoutMs - (now - contentSilenceSince);
+            if (keepAliveLeftMs <= 0) {
+                return { kind: "keep-alive-exhausted", error: new StreamKeepAliveTimeoutError(keepAliveTimeoutMs) };
+            }
+            return { kind: "extend", delayMs: Math.max(1, Math.min(delayMs, keepAliveLeftMs)) };
+        },
+    };
+}
+//# sourceMappingURL=stream-keepalive.js.map

package/dist/types.d.ts

@@ -185,6 +185,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Unset or non-positive values disable the start bound.
      */
     streamStartTimeoutMs?: number;
+    /**
+     * Bytes the provider reports through `onTransportActivity` (SSE pings, keep-alive comments) keep the start and
+     * idle bounds from firing while they keep arriving within one bound. This caps how long keep-alives alone may
+     * hold a request without any assistant event. Unset or non-positive values leave keep-alives unbounded.
+     */
+    streamKeepAliveTimeoutMs?: number;
     /** Provider/SDK timeout override for only the first request in this loop invocation. */
     initialRequestTimeoutMs?: number;
     /** Stream-start timeout override for only the first request in this loop invocation. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-agent-core",
-	"version": "2026.10.30-1",
+	"version": "2026.10.30-2",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -70,8 +70,8 @@
 	},
 	"dependencies": {
 		"@earendil-works/chord": "0.99.1",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.30-1",
-		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.30-1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.30-2",
+		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.30-2",
 		"diff": "9.0.0",
 		"ignore": "7.0.9",
 		"typebox": "1.3.34",