@cubicecho/agent-core 2.2.4 → 2.4.0

package/dist/hooks.js

@@ -0,0 +1,256 @@
+import { createHash } from "node:crypto";
+import { errorMessage } from "./errors.js";
+import { estimateTokens } from "./tokens.js";
+/** Every event a hook can be bound to, in the order a session meets them. */
+export const HOOK_EVENTS = [
+    "sessionStart",
+    "beforeTurn",
+    "afterTurn",
+    "beforeCompact",
+    "sessionEnd",
+    "sessionDelete",
+];
+/**
+ * The events whose hooks run before a request, and so the only ones whose output can reach it.
+ * Anything later runs once the model has already answered.
+ */
+export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
+/**
+ * The most context all of a request's hooks add between them by default, in estimated tokens.
+ *
+ * Enough for a handful of recalled memories, and small against any window worth running an agent
+ * in. The point is that a generous hook cannot crowd out the conversation it was meant to inform.
+ * `configureHooks` moves it for a process, and `gather` and `assembleContext` for one request.
+ */
+export const HOOK_CONTEXT_TOKENS = 2000;
+/** The numbers this module was written with. */
+const HOOK_DEFAULTS = { contextTokens: HOOK_CONTEXT_TOKENS };
+/** What is in force now. Read where it is used, so a change applies from the next request. */
+let hookLimits = { ...HOOK_DEFAULTS };
+/**
+ * Changes what hooks are held to, for a process whose windows are not the size these defaults
+ * were chosen for.
+ *
+ * Module-level for the same reason `configureEvents` is: a budget is a deployment's setting, said
+ * once at startup. A caller that sizes it per model or per agent — a 128k window can afford more
+ * recall than an 8k one — passes `maxTokens` to `gather` instead, which wins over this.
+ *
+ * @param options The limits to change. A field left out — or given anything that is not a number
+ * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
+ * above zero, and lifts the shared budget entirely.
+ * @returns Everything in force afterwards, including what this call did not change.
+ */
+export function configureHooks(options = {}) {
+    for (const [name, value] of Object.entries(options)) {
+        if (typeof value === "number" && value > 0)
+            hookLimits[name] = value;
+    }
+    return { ...hookLimits };
+}
+/**
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * `resetAll` calls it.
+ */
+export const resetHooks = () => {
+    hookLimits = { ...HOOK_DEFAULTS };
+};
+/**
+ * The budget a call is held to: its own when it gave a usable one, the process's otherwise. The
+ * same rule `configureHooks` applies, so a `0` threaded through for "no opinion" does not quietly
+ * turn every hook's context off.
+ */
+const budget = (given) => typeof given === "number" && given > 0 ? given : hookLimits.contextTokens;
+/**
+ * Said once, above the blocks, so the model reads them as background rather than instructions.
+ * Names no host; `withContext` takes another for one that wants to.
+ */
+export const HOOK_PREFACE = "The <context> blocks below were added for this message by the host's hooks. They are " +
+    "background the user did not write and may not be relevant. The user's message follows them.";
+const attribute = (text) => text.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+/**
+ * Builds the context a set of outcomes adds and the notes that go with it.
+ *
+ * Each injected outcome is wrapped in `<context source="…">` naming its label, so a model reading
+ * a recalled line can tell it is a memory rather than something the user said. Each is held to
+ * its own `maxTokens` and the whole to `maxTokens` here, and a block past the total is dropped
+ * whole rather than cut to a stub. For any hooks the pool's `validateHooks` accepts, the text is
+ * what its `contextBlocks` builds from the same outcomes, character for character, so a host
+ * moving between the two sends the same request.
+ *
+ * The note keeps each hook's text as it was cut, so a host can show exactly what the model was
+ * given without re-deriving the caps or parsing the wrapper back off.
+ *
+ * @param outcomes What the runners returned. An injecting outcome on an event that cannot inject
+ * adds nothing; a failed one is noted wherever it falls, including past the budget.
+ * @param maxTokens The budget every block shares. Absent, or not a number above zero, is what
+ * `configureHooks` last set — `HOOK_CONTEXT_TOKENS` unless something moved it.
+ */
+export function assembleContext(outcomes, maxTokens) {
+    const blocks = [];
+    const notes = [];
+    let remaining = budget(maxTokens);
+    for (const outcome of outcomes) {
+        const base = { event: outcome.event, source: outcome.label, hookId: outcome.hookId };
+        if (!outcome.ok) {
+            notes.push({ ...base, error: outcome.error ?? "failed" });
+            continue;
+        }
+        if (!outcome.inject || !INJECT_EVENTS.has(outcome.event))
+            continue;
+        let text = outcome.text?.trim();
+        if (!text)
+            continue;
+        const cap = Math.min(outcome.maxTokens, remaining);
+        if (cap <= 0)
+            continue;
+        if (estimateTokens(text) > cap)
+            text = `${text.slice(0, cap * 4 - 1).trimEnd()}…`;
+        const tokens = estimateTokens(text);
+        remaining -= tokens;
+        blocks.push(`<context source="${attribute(outcome.label)}">\n${text}\n</context>`);
+        notes.push({ ...base, tokens, text });
+    }
+    return { context: blocks.join("\n\n"), notes };
+}
+/**
+ * The request, with the hooks' context added to this turn's question.
+ *
+ * It goes on the question and not in the system prompt, because it is about the question — and a
+ * system prompt that changed every turn would miss the prompt cache every turn. Nothing is written
+ * back: a host that stores what the user typed never remembers the context as something they said.
+ *
+ * @param history The request's messages. Neither the array nor any message in it is changed.
+ * @param index Where this turn's question sits in `history` — which is not where it sits in the
+ * session once a compaction has folded the head into a summary. Anything but a user message there
+ * leaves the request as it was.
+ * @param context What `assembleContext` built. Empty returns `history` itself.
+ * @param preface Said above the blocks. Defaults to `HOOK_PREFACE`.
+ * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
+ */
+export function withContext(history, index, context, preface = HOOK_PREFACE) {
+    const message = history[index];
+    if (!context || message?.role !== "user")
+        return history;
+    const lead = `${preface}\n\n${context}\n\n`;
+    const content = typeof message.content === "string"
+        ? `${lead}${message.content}`
+        : [{ type: "text", text: lead }, ...message.content];
+    return history.map((item, at) => (at === index ? { ...message, content } : item));
+}
+/** A message's text, whether its content is a string or a list of parts. */
+const textOf = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => (typeof part?.text === "string" && part.type !== "refusal" ? part.text : ""))
+        .join("");
+};
+/**
+ * A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing
+ * else.
+ *
+ * Tool calls and their results are left out. They are the model's working rather than the
+ * conversation, and most of a transcript's characters; a memory server that filed them would
+ * recall a directory listing ahead of the decision it led to.
+ *
+ * The uuid is the session, the position and a digest of what was said. Position alone is not
+ * stable — a retry cuts the transcript back and writes a new answer at the same index, and a
+ * server deduping on it would keep the answer that was thrown away — and text alone would make
+ * two identical "ok"s one memory. The same message sent twice, after its turn and again when it
+ * is compacted, is one.
+ *
+ * @param sessionId Prefixes every uuid, so two sessions never share one.
+ * @param messages The transcript, in whatever shape the host stores it, so long as each message
+ * has an OpenAI-style `role` and `content`.
+ * @param from The first index, inclusive. Below zero reads from the start.
+ * @param to The end, exclusive. Absent, or past the end, reads to the end.
+ */
+export function turnMessages(sessionId, messages, from, to) {
+    const end = Math.min(to ?? messages.length, messages.length);
+    const out = [];
+    for (let at = Math.max(0, from); at < end; at++) {
+        const message = messages[at];
+        if (message.role !== "user" && message.role !== "assistant")
+            continue;
+        const text = textOf(message.content).trim();
+        if (!text)
+            continue;
+        const digest = createHash("sha256").update(`${message.role}\0${text}`).digest("hex");
+        out.push({ speaker: message.role, text, uuid: `${sessionId}:${at}:${digest.slice(0, 12)}` });
+    }
+    return out;
+}
+/**
+ * Which turn of a session begins at a point, from 0: the user messages ahead of it.
+ *
+ * @param messages The transcript.
+ * @param before Where the turn begins. Absent is the end, which is the index of a turn whose
+ * question has not been appended yet.
+ */
+export const turnIndex = (messages, before = messages.length) => messages.slice(0, before).filter((message) => message.role === "user").length;
+/** A runner that rejected, as the one outcome its event can still be noted by. */
+const rejected = (event, error) => ({
+    serverId: "",
+    label: "",
+    hookId: "",
+    event,
+    ok: false,
+    error: errorMessage(error),
+    ms: 0,
+    inject: false,
+    maxTokens: 0,
+});
+const runSafely = (run, event, context, signal) => Promise.resolve()
+    .then(() => run(event, context, { signal }))
+    .catch((error) => [rejected(event, error)]);
+/**
+ * Runs the hooks ahead of a request and builds what they add to it.
+ *
+ * This is on the path of the first token, so the events run together rather than one after the
+ * other, and a hook that fails costs the turn its context and never the turn — a runner that
+ * rejects outright is noted once for its event, with an empty `hookId` and `source`, and the rest
+ * go ahead. Bounding each hook's time is the runner's job; `signal` is how the turn ends all of
+ * them.
+ *
+ * @param run Runs one event's hooks.
+ * @param events Which to run: `["beforeTurn"]` ordinarily, and `sessionStart` ahead of it on a
+ * session's first turn. The outcomes are assembled in this order, so it is also the order the
+ * budget is spent in.
+ * @param context What the hooks are told.
+ * @param options `signal` is handed to the runner, and should be the turn's own: a user who
+ * stopped the turn stopped its recall. `onNote` hears each note as the whole is assembled.
+ * `maxTokens` is the shared budget for this request, read as `assembleContext` reads it: absent
+ * or unusable is the process's, from `configureHooks`.
+ */
+export async function gather(run, events, context, { signal, onNote, maxTokens, } = {}) {
+    const outcomes = await Promise.all(events.map((event) => runSafely(run, event, context, signal)));
+    const gathered = assembleContext(outcomes.flat(), maxTokens);
+    for (const note of gathered.notes)
+        onNote?.(note);
+    return gathered;
+}
+/**
+ * Runs the hooks for an event that reads what happened and adds nothing to a request. Never
+ * rejects, so a host can fire it without awaiting it.
+ *
+ * No signal: these run once the turn has been answered, and a reader who stops listening at that
+ * point has not asked for the turn not to be remembered.
+ *
+ * @param run Runs the event's hooks.
+ * @param event `afterTurn`, `beforeCompact`, `sessionEnd` or `sessionDelete`. An injecting event
+ * works too, but what its hooks return is dropped, since there is no request here to add it to.
+ * @param context What the hooks are told.
+ * @param onNote Hears each note — which, with nothing injected, is only ever a failure.
+ * @returns The same notes.
+ */
+export async function notify(run, event, context, onNote) {
+    const outcomes = await runSafely(run, event, context);
+    const notes = outcomes
+        .filter((outcome) => !outcome.ok)
+        .map((outcome) => assembleContext([outcome]).notes[0]);
+    for (const note of notes)
+        onNote?.(note);
+    return notes;
+}

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
  * all of them, reading one streamed turn back into a message, answering an endpoint that
- * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
- * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * refuses one of those, one-shot calls that support a run, the host's side of lifecycle hooks,
+ * the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration,
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
@@ -14,7 +14,8 @@ export type { CatalogServer } from "./catalog.ts";
 export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, timeoutMs, } from "./client.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
-export { emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
+export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
+export { assembleContext, configureHooks, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
@@ -22,4 +23,4 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { estimateTokens } from "./tokens.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -4,15 +4,16 @@
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
  * all of them, reading one streamed turn back into a message, answering an endpoint that
- * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
- * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * refuses one of those, one-shot calls that support a run, the host's side of lifecycle hooks,
+ * the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration,
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
 export { errorMessage } from "./errors.js";
-export { emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
+export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
+export { assembleContext, configureHooks, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
@@ -20,4 +21,4 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { streamTurn, } from "./stream.js";
 export { estimateTokens } from "./tokens.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/reset.d.ts

@@ -1,20 +1,21 @@
 /**
  * Forgets everything this package remembers between calls.
  *
- * Four modules here keep state for the life of the process, each for a good reason and each
+ * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` stay
- * exported, because a test that means to clear one thing should say so.
+ * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
+ * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
+ * one thing should say so.
  *
- * This is for the other case, which is every teardown. What all four hold is *latched
+ * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
  * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
  * locally and fails in CI on a different shard: the test that latched it still passes, and the
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export declare function resetAll(): void;

package/dist/reset.js

@@ -1,24 +1,26 @@
 import { resetCapabilities } from "./capabilities.js";
 import { resetClients } from "./client.js";
 import { resetEvents } from "./events.js";
+import { resetHooks } from "./hooks.js";
 import { resetHints } from "./side-task.js";
 /**
  * Forgets everything this package remembers between calls.
  *
- * Four modules here keep state for the life of the process, each for a good reason and each
+ * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` stay
- * exported, because a test that means to clear one thing should say so.
+ * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
+ * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
+ * one thing should say so.
  *
- * This is for the other case, which is every teardown. What all four hold is *latched
+ * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
  * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
  * locally and fails in CI on a different shard: the test that latched it still passes, and the
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export function resetAll() {
@@ -26,4 +28,5 @@ export function resetAll() {
     resetCapabilities();
     resetHints();
     resetEvents();
+    resetHooks();
 }

package/dist/retry.d.ts

@@ -14,6 +14,11 @@ export declare class EndpointSilent extends Error {
 /**
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
+ *
+ * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
+ * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
+ * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
+ * it was built from as `cause`.
  */
 export declare class ContextOverflow extends Error {
     readonly name = "ContextOverflow";

package/dist/retry.js

@@ -15,6 +15,11 @@ export class EndpointSilent extends Error {
 /**
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
+ *
+ * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
+ * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
+ * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
+ * it was built from as `cause`.
  */
 export class ContextOverflow extends Error {
     name = "ContextOverflow";

package/dist/run-turn.d.ts

@@ -12,6 +12,11 @@ import { type StreamTurnOptions, type Turn } from "./stream.ts";
  * The outer one is the endpoint being unreachable, busy or silent, which is not about this
  * request at all and is worth simply waiting out.
  *
+ * A request too big for the window is neither, and comes out of here as `ContextOverflow`
+ * however it was found out about — by the `contextLimit` guard below before a round trip was
+ * spent, or by the endpoint's own refusal after one. The option decides how early the caller
+ * hears, not what it hears.
+ *
  * Both are bounded by the same rule: nothing is sent again once the model has started
  * answering. The tokens are already out and on their way to whoever is watching, and a second
  * attempt would say everything twice. That is what `produced` is, one box per attempt — set by

package/dist/run-turn.js

@@ -1,6 +1,6 @@
 import { negotiate } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { backoffMs, ContextOverflow, compact, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+import { backoffMs, ContextOverflow, compact, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 import { streamTurn } from "./stream.js";
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -46,6 +46,19 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
             // rules in `retry.ts` — so classifying first brings a cancelled run back from the dead.
             if (produced.any || stream.signal?.aborted)
                 throw error;
+            // The endpoint's own refusal, classified here rather than left to the caller. One failure
+            // had two error types depending on an option about something else: a caller that gave a
+            // `contextLimit` got `ContextOverflow` from the guard above, and one that did not — the
+            // default — got a raw SDK error and had to know to run `isOverflow` over its message
+            // itself. `runTurn` is offered as the whole loop, so the classification this package
+            // already knows how to do belongs inside it.
+            //
+            // The original is kept as `cause`, because the endpoint's wording is the half that names
+            // the number. A rate limit borrows the same words and is not one of these — `isOverflow`
+            // rules it out, and it goes on to be retried below as the 429 it is.
+            if (!(error instanceof ContextOverflow) && isOverflow(errorMessage(error))) {
+                throw new ContextOverflow(errorMessage(error), { cause: error });
+            }
             if (attempt >= maxRetries || !isTransient(error))
                 throw error;
             const wait = backoffMs(attempt);

package/dist/side-task.js

@@ -1,6 +1,6 @@
 import OpenAI from "openai";
 import { capabilitiesFor, negotiate } from "./capabilities.js";
-import { getClient } from "./client.js";
+import { endpointKey, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
 /**
@@ -24,10 +24,10 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
 /**
  * The models that turned out not to take the hints, by endpoint and model.
  *
- * Keyed rather than global for the reason the client cache is keyed: a refusal is a fact about
- * what is on the other end, not about this process. A llama.cpp box and a cloud API are both
- * reachable from one consumer over its lifetime, and the first one's refusal must not stop the
- * second from ever being asked.
+ * Keyed rather than global for the reason the client cache is keyed, and on the same
+ * `endpointKey` it is: a refusal is a fact about what is on the other end, not about this
+ * process. A llama.cpp box and a cloud API are both reachable from one consumer over its
+ * lifetime, and the first one's refusal must not stop the second from ever being asked.
  *
  * The model belongs in the key for the same reason. One base URL is routinely many models —
  * OpenRouter, LiteLLM, vLLM serving several at once — and whether `chat_template_kwargs` reaches
@@ -38,7 +38,7 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
  * the same (endpoint, model) pair, where a run on that model can read it too.
  */
 const noHints = new Set();
-const hintKey = (baseUrl, model) => JSON.stringify([baseUrl, model]);
+const hintKey = (config, model) => JSON.stringify([endpointKey(config), model]);
 /** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
 export const resetHints = () => noHints.clear();
 /**
@@ -108,12 +108,12 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
     // whether a run or a side task found it out, and the point of latching it is that only one of
     // them has to pay for it. Nothing here sends tools or `stream_options`, so the two
     // endpoint-level flags are not in play — the model's three are the whole of what this meets.
-    const supports = capabilitiesFor(config.baseUrl);
+    const supports = capabilitiesFor(config.baseUrl, config.apiKey);
     const attempt = (hints) => negotiate(supports, (_supports, _produced, refused) => send(hints, refused), {
         model,
         onNotice,
     });
-    const key = hintKey(config.baseUrl, model);
+    const key = hintKey(config, model);
     const hints = !noHints.has(key);
     let response;
     try {

package/dist/stream.d.ts

@@ -18,8 +18,26 @@ export interface TurnUsage {
 /** One streamed turn, put back together into the shape a loop and a transcript work with. */
 export interface Turn {
     content: string;
-    toolCalls: OpenAI.ChatCompletionMessageToolCall[];
+    /**
+     * The narrower of the SDK's two tool-call shapes, because it is the only one built here — a
+     * streamed `tool_calls` delta carries a function and nothing else. Typed as the union it
+     * belongs to, every caller had to narrow before it could read `.function`, to rule out a
+     * custom call that this loop cannot produce. Still assignable wherever the union is wanted.
+     */
+    toolCalls: OpenAI.ChatCompletionMessageFunctionToolCall[];
     usage: TurnUsage;
+    /**
+     * Why the model stopped, in the endpoint's own words — `stop`, `length`, `tool_calls`, or `""`
+     * where it never said.
+     *
+     * Reported because `length` is otherwise invisible. A turn cut off at the token ceiling comes
+     * back as a well-formed `Turn` with truncated `content`, or with a tool call whose `arguments`
+     * stop mid-JSON — so the caller meets a parse failure with nothing to attribute it to. Being
+     * cut off looking whole is the same trap `throwIfAborted` below answers for the abort; this
+     * half is not an error, because the tokens are real and a caller may still want them, so it is
+     * handed over rather than raised.
+     */
+    finishReason: string;
 }
 /**
  * Whether the model has said anything a second attempt would say twice.

package/dist/stream.js

@@ -51,6 +51,7 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
         const content = [];
         const calls = new Map();
         const usage = { prompt: 0, completion: 0, total: 0 };
+        let finishReason = "";
         for await (const chunk of stream) {
             // Rearmed on every chunk, latched below on only some: a priming chunk is the endpoint
             // being alive, which is all the watchdog is asking about.
@@ -64,7 +65,15 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
                 usage.completion = chunk.usage.completion_tokens ?? 0;
                 usage.total = chunk.usage.total_tokens ?? 0;
             }
-            const delta = chunk.choices[0]?.delta;
+            // One choice, because that is what an agent loop asks for. A body with `n` above one
+            // keeps only the first; nothing here is built to reassemble several at once.
+            const choice = chunk.choices[0];
+            // Read before the delta guard rather than beside the content. The chunk that carries the
+            // reason usually carries an empty delta, and some servers send it with no delta at all —
+            // either of which the guard below skips, taking the reason with it.
+            if (choice?.finish_reason)
+                finishReason = choice.finish_reason;
+            const delta = choice?.delta;
             if (!delta)
                 continue;
             const thinking = delta.reasoning_content || delta.reasoning || "";
@@ -112,6 +121,7 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
                 function: { name: call.name, arguments: call.arguments },
             })),
             usage,
+            finishReason,
         };
     }
 }