@open-everywhere/core 0.1.0

package/dist/agent/model/stream-drop-retry.js

@@ -0,0 +1,316 @@
+// ONE RETRY FOR A DELEGATED WORKER'S DROPPED MODEL STREAM (OPE-2132).
+//
+// WHAT HAPPENED. Board #242 leg S24: a delegated worker had already FOUND the Notion page when its
+// next model step died with `MODEL_CALL_FAILED "Upstream stream ended before terminal chunk"` — the
+// gateway closed the response stream without the model's terminal chunk. The worker turn failed, the
+// task settled `failed`, and the seat told the room it could not complete the search. Honest, and a
+// non-answer bought by ONE dropped socket.
+//
+// 🔴 WHY eve's OWN RETRY DOES NOT COVER IT — AND WHERE IT DOES, THIS MODULE STAYS OUT. eve retries a
+// model call up to three times, but only for the class its classifier calls `retry`
+// (`harness/tool-loop.js runModelCallWithRetries`, keyed on `harness/model-call-error.js
+// classifyModelCallError`): a retryable gateway type, a 408/409/429, a 5xx, an `isRetryable` flag, and
+// anything its semantic-error catalogue tags `transient`. That catalogue's
+// `harness/semantic-errors/rules/system.js NETWORK_ERROR_CODES` already holds every socket-level code
+// — `ECONNRESET`, `EPIPE`, `UND_ERR_SOCKET`, the undici timeouts — matched over the whole cause chain.
+// 🔴 SO THIS MODULE MUST NOT ADMIT ONE OF THOSE. Admitting a code eve also retries multiplies the two
+// loops: two attempts here, each of which eve then retries, is up to six provider calls for one step.
+// {@link STREAM_DROP_CODES} therefore holds only what eve's catalogue does NOT, and
+// {@link STREAM_DROP_MESSAGES} carries no member of eve's own exact-match list (`fetch failed`,
+// `socket hang up`, `terminated`). `scripts/worker-stream-drop-retry-test.ts` §1 reads eve's INSTALLED
+// list and reds on any overlap, so an eve release that widens its own class reds here.
+//
+// The S24 class is genuinely uncovered: the row OBSERVED on board #242 was `MODEL_CALL_FAILED`, which
+// in task mode eve emits on the `terminal` verdict (a `recoverable` one is rethrown for a durable step
+// retry instead). Which signal made the gateway's drop terminal is not derivable from the classifier —
+// a bare message falls through to `recoverable` — so that is the transcript's observation, not a
+// deduction. Either way nothing re-ran the step.
+//
+// 🔴 AND THERE IS NO CONTINUATION ROAD TO ROUTE IT INTO. `access/worker-continuation.ts` REFUSES
+// worker continuation outright — `agentId` is stripped from the delegation schema and a call carrying
+// one is refused — because a second turn on the same child clears its taint bit over unchanged
+// hostile history. A failed worker therefore has no second turn to be resumed into, which is why
+// this is a retry of the STEP and not a re-wake of the child.
+//
+// WHERE IT SITS. It decorates the BACKEND, in the same position as the soak capture shim
+// (`model/call-capture.ts`) and for the same reason: that is the last seam before the transport, so
+// the retried call carries byte-identical options — the route rewrite, the wrap-up notice and the
+// capture shim have all already run outside it. The worker's found state is untouched: the retry
+// re-sends the SAME composed request, whose messages already hold every tool result the worker has.
+//
+// 🔴 A `doStream` ATTEMPT IS BUFFERED WHOLE BEFORE ANY PART IS FORWARDED, and that is what makes the
+// retry safe. A drop can arrive after the model has already emitted text, so forwarding parts as they
+// arrive and then retrying would hand eve attempt 1's partial text followed by attempt 2's complete
+// answer — a duplicated, self-contradicting response, which is worse than the failure it replaces.
+// So a failed attempt's parts are DISCARDED, never forwarded. The cost is that the step no longer
+// streams incrementally, and it is paid only where it cannot be seen: this decorator is armed for a
+// DELEGATED WORKER alone, whose consumer is eve's own accumulator and never a human watching text
+// land.
+//
+// 🔴 "DELEGATED WORKER" IS THE GRAIN-`task` BIT, NOT "A SUBAGENT CHILD". The repo's own worker
+// discriminator is `access/worker-seat-state.ts currentWorkerWake()`, written at `turn.started` by
+// `hooks/lean-seat.ts classifyWorkerSeat` off `grainOf(ctx) === "task"`, and it is what every other
+// worker-scoped rule reads. `isSubagentChildContext` is WIDER — it answers true for any
+// subagent-shaped session — so arming on it would buffer children this ticket never scoped and make
+// the paragraph above false. It fails closed to `false`, which here means "do not wrap": a wake this
+// deployment could not classify keeps today's behaviour rather than gaining a retry.
+//
+// 🔴 ONE RETRY, ONE CLASS. The second drop fails the turn exactly as today, and so does every other
+// error on the first attempt — a refusal, a tool error, a policy stop, a content filter, an aborted
+// turn. {@link isTransientStreamDrop} is the whole admission list and it matches on the transport's
+// own words, never on "the call failed".
+import { defineState } from "eve/context";
+/**
+ * The message fragments that mean "the byte stream ended without the model's terminal chunk",
+ * lowercase. Read as a SUBSTRING of any message in the error's cause chain.
+ *
+ * 🔴 EVERY ENTRY NAMES THE TRANSPORT, NOT THE OUTCOME. A fragment like "failed" or "error" would
+ * admit a refusal, a content filter and a schema violation, and retrying one of those re-sends a
+ * request the provider has already judged — it burns a second call and can only fail again. The list
+ * is meant to be short and to stay short.
+ */
+const STREAM_DROP_MESSAGES = [
+    // The gateway's own words on the observed failure (S24, board #242).
+    "stream ended before terminal chunk",
+    // Node/undici's two spellings for a response body that closed mid-flight.
+    "premature close",
+    "other side closed",
+    // The AI SDK's wrapper around a stream that ended with no completed response.
+    "stream closed before completion",
+];
+/**
+ * Node error `code` values for the same class. Compared exactly, because a code is an enum and a
+ * substring match on one would be sloppy for no gain.
+ *
+ * 🔴 IT HOLDS ONE CODE, AND THE ABSENCES ARE THE POINT. `ECONNRESET`, `EPIPE`, `UND_ERR_SOCKET` and
+ * the undici timeouts all sit in eve's own `NETWORK_ERROR_CODES`, which eve's classifier tags
+ * `transient` and retries three times by itself — see the header. Adding one here would compound the
+ * two loops, not fix anything. `ERR_STREAM_PREMATURE_CLOSE` is absent from eve's list, so it is this
+ * module's to hold.
+ */
+const STREAM_DROP_CODES = ["ERR_STREAM_PREMATURE_CLOSE"];
+/** Names that mean the TURN was cancelled or aborted. They are excluded FIRST and unconditionally:
+ *  an abort can surface as a closed socket, and retrying one would re-issue a call the caller has
+ *  already given up on. */
+const ABORT_NAMES = ["AbortError", "TimeoutError"];
+/** Walk an error's `cause` chain, bounded, so a wrapped transport error is still reachable. The bound
+ *  is what keeps a self-referential chain from hanging the decorator. */
+function causeChain(error) {
+    const out = [];
+    let current = error;
+    for (let depth = 0; depth < 8 && current !== null && current !== undefined; depth++) {
+        out.push(current);
+        if (typeof current !== "object")
+            break;
+        const next = current.cause;
+        if (next === current)
+            break;
+        current = next;
+    }
+    return out;
+}
+function stringField(value, field) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const held = value[field];
+    return typeof held === "string" ? held : undefined;
+}
+/**
+ * Is this the ONE transient class this module retries — a model stream that ended before the
+ * provider's terminal chunk, or the socket-level sibling of the same drop?
+ *
+ * FAIL DIRECTION: NO RETRY. Anything it cannot recognise fails the turn exactly as it does today, so
+ * a widening of this predicate is the only way a non-transient error can ever be re-sent.
+ */
+export function isTransientStreamDrop(error) {
+    const chain = causeChain(error);
+    // The abort exclusion is checked over the WHOLE chain before any admission, so a drop wrapping an
+    // abort — or an abort wrapping a drop — is never retried.
+    for (const link of chain) {
+        const name = stringField(link, "name");
+        if (name !== undefined && ABORT_NAMES.includes(name))
+            return false;
+    }
+    for (const link of chain) {
+        const code = stringField(link, "code");
+        if (code !== undefined && STREAM_DROP_CODES.includes(code))
+            return true;
+        const message = stringField(link, "message") ?? (typeof link === "string" ? link : undefined);
+        if (message === undefined)
+            continue;
+        const lowered = message.toLowerCase();
+        if (STREAM_DROP_MESSAGES.some((fragment) => lowered.includes(fragment)))
+            return true;
+    }
+    return false;
+}
+/** How many times this turn's model steps have been retried on a stream drop. It rides a per-turn
+ *  slot rather than a counter inside the decorator, because a step resolves a NEW model instance and
+ *  the row that has to name the retry (`delegation.worker_turn_failed`) is written by a hook. */
+const streamDropRetries = defineState("open-everywhere.worker-stream-drop-retries", () => ({ count: 0 }));
+/** Record one retry, or nothing when there is no eve context to record it in. */
+function noteStreamDropRetry() {
+    try {
+        streamDropRetries.update((s) => ({ count: s.count + 1 }));
+    }
+    catch {
+        /* no context — the retry still happens; only the row's `retried` field is lost */
+    }
+}
+/** How many stream-drop retries this turn spent, for the row a failing worker turn writes. Answers 0
+ *  outside a context, which is the honest reading: nothing was recorded. */
+export function streamDropRetriesThisTurn() {
+    try {
+        return streamDropRetries.get().count;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Reset the per-turn count. Called from the worker's own `turn.started`, so the number on a failure
+ *  row describes THIS turn and never accumulates across a session's turns. */
+export function clearStreamDropRetries() {
+    try {
+        streamDropRetries.update(() => ({ count: 0 }));
+    }
+    catch {
+        /* no context — the default is already 0 */
+    }
+}
+/** A stream part eve reads as a failure. The AI SDK surfaces a mid-stream transport death this way
+ *  rather than by rejecting the reader, so an `error` part carrying a drop is the SAME failure as a
+ *  throw and has to be admitted as one. */
+function errorPartPayload(part) {
+    if (part === null || typeof part !== "object")
+        return undefined;
+    const typed = part;
+    return typed.type === "error" ? typed.error : undefined;
+}
+/**
+ * Drain one `doStream` attempt into memory.
+ *
+ * A rejection of `doStream` itself propagates — that is the shape eve already sees for a call that
+ * never produced a stream. A rejection of the stream READER is classified instead: the transient
+ * class becomes `drop` (a retry candidate) and everything else becomes `fatal`, which {@link replay}
+ * re-emits as the stream error it was.
+ */
+async function bufferAttempt(model, options) {
+    const result = (await model.doStream(options));
+    const parts = [];
+    const reader = result.stream.getReader();
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done === true)
+                break;
+            const failure = errorPartPayload(next.value);
+            if (failure !== undefined && isTransientStreamDrop(failure)) {
+                // 🔴 CANCEL, DO NOT MERELY RELEASE. An in-band `error` part is not a dead socket — the
+                // response body is often still open, and this attempt is about to be abandoned for a retry.
+                // Releasing the lock alone would leave that body held until the provider or undici timed it
+                // out, once per retried step. The success path below needs no cancel, because the stream has
+                // already ended; a READER REJECTION needs none either, because the stream is already errored.
+                await reader.cancel().catch(() => undefined);
+                return { result, parts, drop: failure };
+            }
+            parts.push(next.value);
+        }
+    }
+    catch (err) {
+        if (!isTransientStreamDrop(err))
+            return { result, parts, fatal: err };
+        return { result, parts, drop: err };
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* already released, or released by the cancel above */
+        }
+    }
+    return { result, parts };
+}
+/** Replay a buffered attempt as a fresh stream result, so eve consumes it exactly as it would have
+ *  consumed the live one. */
+function replay(attempt) {
+    const parts = [...attempt.parts];
+    const drop = attempt.drop;
+    const fatal = attempt.fatal;
+    return {
+        ...attempt.result,
+        stream: new ReadableStream({
+            start(controller) {
+                for (const part of parts)
+                    controller.enqueue(part);
+                // An error this module does not retry is re-emitted as the READER rejection it arrived as, so
+                // eve's normalisation and classification see exactly what they see today.
+                if (fatal !== undefined) {
+                    controller.error(fatal);
+                    return;
+                }
+                // A second drop that arrived as an `error` PART is replayed as one, so eve classifies the
+                // failure from the provider's own payload rather than from a shape this module invented.
+                if (drop !== undefined)
+                    controller.enqueue({ type: "error", error: drop });
+                controller.close();
+            },
+        }),
+    };
+}
+/** Decorate ONE model instance with the single retry. */
+function retryingModel(model) {
+    const decorated = {
+        specificationVersion: model.specificationVersion,
+        provider: model.provider,
+        modelId: model.modelId,
+        supportedUrls: model.supportedUrls,
+        async doGenerate(options) {
+            try {
+                return await model.doGenerate(options);
+            }
+            catch (err) {
+                if (!isTransientStreamDrop(err))
+                    throw err;
+                noteStreamDropRetry();
+                return await model.doGenerate(options);
+            }
+        },
+        async doStream(options) {
+            let first;
+            try {
+                first = await bufferAttempt(model, options);
+            }
+            catch (err) {
+                if (!isTransientStreamDrop(err))
+                    throw err;
+                noteStreamDropRetry();
+                return replay(await bufferAttempt(model, options));
+            }
+            if (first.drop === undefined)
+                return replay(first);
+            noteStreamDropRetry();
+            // The SECOND attempt is replayed whatever it holds — a clean answer, or its own drop as an
+            // error part. There is no third attempt, so the turn fails here exactly as it does today.
+            return replay(await bufferAttempt(model, options));
+        },
+    };
+    return decorated;
+}
+/**
+ * Arm the retry on a backend, or return it untouched.
+ *
+ * `armed` is the CALLER's verdict, not a read from in here: `model/routing.ts` reads
+ * `currentWorkerWake()` at the resolver, which is the grain-`task` bit the header names. Disarmed,
+ * this returns `deps` unchanged, so a seat's step is not wrapped and its stream is not buffered.
+ */
+export function withStreamDropRetry(deps, armed) {
+    if (!armed)
+        return deps;
+    const backend = {
+        model: (id) => retryingModel(deps.backend.model(id)),
+        applyOptions: (route, options, ids) => deps.backend.applyOptions(route, options, ids),
+    };
+    return { ...deps, backend };
+}
+//# sourceMappingURL=stream-drop-retry.js.map

package/dist/agent/model/stream-drop-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-drop-retry.js","sourceRoot":"","sources":["../../../agent/model/stream-drop-retry.ts"],"names":[],"mappings":"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"}

package/dist/agent/model/turn-closeout.d.ts

@@ -0,0 +1,61 @@
+import { type BindableContext } from "../identity/binding.js";
+import { type DurableCloseout } from "./turn-state.js";
+/**
+ * How many post-closeout refusals arm the latch. ONE — see the header's "why the limit is one".
+ * Exported as a named constant rather than a setting: this is not a policy dial. Every value above
+ * one buys the model more rounds of the exact behaviour the refusal text has already told it to
+ * stop, and the prod trace is 68 of them.
+ */
+export declare const CLOSEOUT_REFUSAL_LIMIT = 1;
+/**
+ * Record one post-closeout event for THIS turn and return the latch's new count (`0` when nothing
+ * could be recorded). Called from the refusal arms in `tools/reply.ts` and `tools/no_reply.ts` BEFORE
+ * they throw, so the row the refusal writes and the turn ending share one cause — and from the reply
+ * tool's repeated-override arm AFTER its post has landed, so ending the turn can never cost the
+ * message (OPE-1659, and see the header's fourth arm).
+ *
+ * `reason` is the caller's own audit reason — this module owns no vocabulary of its own, so a new
+ * arming shape needs no edit here.
+ *
+ * Never throws: a latch that cannot be written must not turn a refusal into a different error than
+ * the one the model needs to read.
+ */
+export declare function noteTurnCloseoutRefusal(ctx: BindableContext, reason: string): Promise<number>;
+/** This turn's CACHED latch state, or `undefined` when this instance has not seen one. PURE — it
+ *  neither creates a latch nor marks one reported, so a test (or a future reader) can ask the
+ *  question without changing the answer. It reads only the in-memory cache: the durable row reaches
+ *  this map through {@link claimTurnCloseoutReport}, which is the one caller on the round-trip path
+ *  that has the row in hand. */
+export declare function turnCloseoutFor(sessionId: string | undefined, turnId: string | undefined): {
+    count: number;
+    reason: string;
+} | undefined;
+/** Has this turn's cached latch tripped — has it drawn at least {@link CLOSEOUT_REFUSAL_LIMIT}
+ *  refusals? Cache-only, exactly like {@link turnCloseoutFor}. */
+export declare function turnCloseoutTripped(sessionId: string | undefined, turnId: string | undefined): boolean;
+/** This turn's merged latch, for the caller that PERSISTS the durable row. `undefined` when the turn
+ *  has armed nothing, which is what a writer stores as "no closeout". */
+export declare function turnCloseoutSnapshot(sessionId: string | undefined, turnId: string | undefined): DurableCloseout | undefined;
+/**
+ * The reader `model/step-boundary.ts` calls once per model round-trip: the tripped latch's reason
+ * plus whether THIS call is the FIRST to see it. It flips the `reported` flag, which is what keeps
+ * one turn to one console line and one audit row however many round-trips the stub then serves —
+ * within an instance always, and across an instance change as far as the durable row got written.
+ * `undefined` whenever the latch is unset or has not reached the limit.
+ *
+ * `durable` is the closeout half of the turn's durable row (OPE-1522), which the caller has already
+ * read for its own step count — passing it in keeps this one store read per round-trip rather than
+ * two, and keeps this function synchronous. It is merged into the cache first, so a latch armed on a
+ * PREVIOUS instance trips here, and the flipped `reported` flag then rides back out through
+ * {@link turnCloseoutSnapshot} for the caller to persist.
+ */
+export declare function claimTurnCloseoutReport(sessionId: string | undefined, turnId: string | undefined, durable?: DurableCloseout): {
+    reason: string;
+    count: number;
+    first: boolean;
+} | undefined;
+/** Test seam: forget every tracked latch's CACHE entry, leaving the durable rows alone — the pair a
+ *  fresh serverless instance sees mid-turn, and so how a test stages an instance change (OPE-1522).
+ *  `deleteTurnState` drops the row itself. */
+export declare function _resetTurnCloseoutForTest(): void;
+//# sourceMappingURL=turn-closeout.d.ts.map

package/dist/agent/model/turn-closeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-closeout.d.ts","sourceRoot":"","sources":["../../../agent/model/turn-closeout.ts"],"names":[],"mappings":"AAyHA,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAA8D,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAuDxC;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCnG;AAED;;;;gCAIgC;AAChC,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAIxI;AAED;kEACkE;AAClE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGtG;AAED;yEACyE;AACzE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAG3H;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAQ/D;AAQD;;8CAE8C;AAC9C,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}