@cubicecho/agent-core 2.23.0 → 2.24.0

package/dist/calibration.js

@@ -1,5 +1,6 @@
-import { CHARS_PER_TOKEN, requestChars, toolsChars } from "./retry.js";
+import { requestChars, toolsChars } from "./retry.js";
 import { scoped } from "./scope.js";
+import { CHARS_PER_TOKEN } from "./tokens.js";
 /**
  * How many characters a token is worth on one model, learned from what its endpoint reports.
  *

package/dist/capabilities.d.ts

@@ -118,6 +118,20 @@ export interface ModelCapabilities {
      */
     assistantPrefill: boolean;
 }
+/** The name of one of a model's on/off flags: every `boolean` on `ModelCapabilities`. */
+export type ModelFlag = {
+    [Key in keyof ModelCapabilities]-?: ModelCapabilities[Key] extends boolean ? Key : never;
+}[keyof ModelCapabilities];
+/**
+ * A model's on/off flags as it starts out, every one optimistic.
+ *
+ * A record over every boolean on `ModelCapabilities`, so a flag added there does not compile until
+ * it is listed here — and this is the list a snapshot is exported, imported and judged empty by,
+ * where each of those used to name the flags again and one could be missed.
+ */
+export declare const OPTIMISTIC_MODEL: Readonly<Record<ModelFlag, true>>;
+/** The names of those flags, for a caller that reads or latches each in turn. */
+export declare const MODEL_FLAGS: ModelFlag[];
 /**
  * What this endpoint is known not to support. The same object every time, so what `negotiate`
  * latches off stays off.
@@ -210,6 +224,28 @@ export declare const EFFORT_LADDER: readonly ["none", "minimal", "low", "medium"
  * @param asked What the config asks for. `"off"` and absent mean no effort.
  */
 export declare function effortFor(refused: ModelCapabilities | undefined, asked: string | undefined): string;
+/**
+ * The reply ceiling and the temperature as this model takes them, to spread into a request body.
+ *
+ * The reasoning models want the ceiling spelled the other way, and one that will only run at the
+ * temperature it was built with is sent none. Both are tested `=== false`, so a caller that named
+ * no model sends what one that has refused nothing is sent; see `ModelCapabilities.legacyTokenLimit`.
+ *
+ * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param maxTokens The ceiling. Zero or less sends none and leaves it to the server: a zero sent
+ * as `max_tokens: 0` asks for an empty reply.
+ * @param temperature What to sample at, where the model takes one that was picked for it.
+ */
+export declare const ceilingAndTemperature: (refused: ModelCapabilities | undefined, maxTokens: number, temperature: number) => {
+    max_completion_tokens: number;
+    temperature?: number | undefined;
+} | {
+    max_tokens: number;
+    temperature?: number | undefined;
+} | {
+    temperature?: number | undefined;
+};
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/capabilities.js

@@ -2,6 +2,22 @@ import { endpointId } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isGrammarError } from "./schema-compat.js";
 import { scoped } from "./scope.js";
+/**
+ * A model's on/off flags as it starts out, every one optimistic.
+ *
+ * A record over every boolean on `ModelCapabilities`, so a flag added there does not compile until
+ * it is listed here — and this is the list a snapshot is exported, imported and judged empty by,
+ * where each of those used to name the flags again and one could be missed.
+ */
+export const OPTIMISTIC_MODEL = {
+    reasoningEffort: true,
+    legacyTokenLimit: true,
+    chosenTemperature: true,
+    structuredOutput: true,
+    assistantPrefill: true,
+};
+/** The names of those flags, for a caller that reads or latches each in turn. */
+export const MODEL_FLAGS = Object.keys(OPTIMISTIC_MODEL);
 /**
  * What each endpoint cannot do, remembered for the life of the process.
  *
@@ -51,15 +67,7 @@ export function capabilitiesFor(baseUrl, apiKey) {
 export function modelCapabilitiesFor(supports, model) {
     let known = supports.models.get(model);
     if (!known) {
-        known = {
-            reasoningEffort: true,
-            legacyTokenLimit: true,
-            chosenTemperature: true,
-            refusedFields: new Set(),
-            structuredOutput: true,
-            refusedEfforts: new Set(),
-            assistantPrefill: true,
-        };
+        known = { ...OPTIMISTIC_MODEL, refusedFields: new Set(), refusedEfforts: new Set() };
         supports.models.set(model, known);
     }
     return known;
@@ -261,6 +269,27 @@ export function effortFor(refused, asked) {
         return asked;
     return nextEffort(refused, asked) ?? asked;
 }
+/**
+ * The reply ceiling and the temperature as this model takes them, to spread into a request body.
+ *
+ * The reasoning models want the ceiling spelled the other way, and one that will only run at the
+ * temperature it was built with is sent none. Both are tested `=== false`, so a caller that named
+ * no model sends what one that has refused nothing is sent; see `ModelCapabilities.legacyTokenLimit`.
+ *
+ * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param maxTokens The ceiling. Zero or less sends none and leaves it to the server: a zero sent
+ * as `max_tokens: 0` asks for an empty reply.
+ * @param temperature What to sample at, where the model takes one that was picked for it.
+ */
+export const ceilingAndTemperature = (refused, maxTokens, temperature) => ({
+    ...(maxTokens > 0
+        ? refused?.legacyTokenLimit === false
+            ? { max_completion_tokens: maxTokens }
+            : { max_tokens: maxTokens }
+        : {}),
+    ...(refused?.chosenTemperature === false ? {} : { temperature }),
+});
 /**
  * How to answer a refused effort *value*, or `undefined` when there is nothing new to learn or
  * nowhere left to go — in which case the refusal is the caller's, as it was before this existed.
@@ -347,9 +376,58 @@ function unknownFields(detail) {
         .split(/[.[]/)[0])
         .filter(Boolean);
 }
-/** Whether a refusal names a droppable field this model has not already refused. */
-const refusesDroppable = (detail, droppable, refused) => droppable.size > 0 &&
-    unknownFields(detail).some((field) => droppable.has(field) && !refused.refusedFields.has(field));
+/** The answer to a refusal that is the endpoint's: a flag still set, and a wording that clears it. */
+const endpointAnswer = (flag, matches, notice) => ({ detail, supports }) => {
+    if (!supports[flag] || !matches(detail))
+        return undefined;
+    supports[flag] = false;
+    return notice;
+};
+/** The same for a refusal that is the model's, which only a request that named one can meet. */
+const modelAnswer = (flag, matches, notice) => ({ detail, named }) => {
+    if (!named?.refused[flag] || !matches(detail))
+        return undefined;
+    named.refused[flag] = false;
+    return notice(named.name);
+};
+/** An effort refused by value: latched, so `effortFor` sends the next rung down. */
+const effortStepAnswer = ({ detail, named }) => {
+    const stepped = named && planEffortStep(detail, named.refused);
+    if (!named || !stepped)
+        return undefined;
+    named.refused.refusedEfforts.add(stepped.value);
+    if (stepped.supported)
+        named.refused.supportedEfforts = stepped.supported;
+    return `${named.name} does not reason at ${stepped.value}; retrying at ${stepped.next}`;
+};
+/** Fields the endpoint has never heard of, where they are droppable and not refused already. */
+const droppedFieldsAnswer = ({ detail, named, droppable }) => {
+    if (!named || droppable.size === 0)
+        return undefined;
+    const fields = unknownFields(detail).filter((field) => droppable.has(field) && !named.refused.refusedFields.has(field));
+    if (!fields.length)
+        return undefined;
+    for (const field of fields)
+        named.refused.refusedFields.add(field);
+    return `${named.name} does not take ${fields.join(", ")}; retrying without ${fields.length > 1 ? "them" : "it"}`;
+};
+/**
+ * Every refusal `negotiate` answers, in the order it asks. The first to answer is the only one.
+ *
+ * The order is behaviour rather than layout: one error text can satisfy two of these — a message
+ * about `reasoning_effort` is a refused field to one and a refused value to the next — and the
+ * earlier row is the reading that wins.
+ */
+const ANSWERS = [
+    endpointAnswer("strictSchemas", isGrammarError, "server could not build a grammar; retrying without pattern/format"),
+    endpointAnswer("usageInStream", (detail) => REJECTS_USAGE.test(detail), "server rejected stream_options; token counts unavailable"),
+    modelAnswer("reasoningEffort", rejectsEffort, (name) => `${name} does not take a reasoning effort; retrying without one`),
+    effortStepAnswer,
+    modelAnswer("legacyTokenLimit", wantsCompletionLimit, (name) => `${name} wants max_completion_tokens; retrying with the limit spelled that way`),
+    modelAnswer("chosenTemperature", refusesChosenTemperature, (name) => `${name} takes only its own temperature; retrying without ours`),
+    modelAnswer("structuredOutput", rejectsResponseFormat, (name) => `${name} does not take response_format; asking for JSON in words instead`),
+    droppedFieldsAnswer,
+];
 /**
  * Sends a request, re-sending it each time the answer is this endpoint refusing something the
  * request can do without. Returns once the endpoint has answered, or throws if the refusal is
@@ -386,16 +464,13 @@ const refusesDroppable = (detail, droppable, refused) => droppable.size > 0 &&
  */
 export async function negotiate(supports, send, { produced = { any: false }, onNotice, model: name, droppable } = {}) {
     const optional = new Set(droppable);
-    // The name and what it has refused, bound together because the notices below need both. They
-    // exist or are absent as one — the second is resolved from the first — but that is a fact
-    // about two locals, and narrowing one of those tells TypeScript nothing about the other.
     const named = name === undefined ? undefined : { name, refused: modelCapabilitiesFor(supports, name) };
     const model = named?.refused;
     for (;;) {
         // What this attempt was built with. `capabilitiesFor` and `modelCapabilitiesFor` hand one
         // object per endpoint and per model to everyone on them, so a run starting alongside this
-        // one may latch a flag off while this call is in flight — and the branches below are guarded
-        // on the flag still being set.
+        // one may latch a flag off while this call is in flight — and every answer in `ANSWERS` is
+        // guarded on its flag still being set.
         const sent = flagsOf(supports, model);
         try {
             return await send(supports, produced, model);
@@ -403,47 +478,22 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
         catch (error) {
             if (produced.any)
                 throw error;
-            const detail = errorMessage(error);
-            const stepped = named && planEffortStep(detail, named.refused);
-            if (supports.strictSchemas && isGrammarError(detail)) {
-                supports.strictSchemas = false;
-                onNotice?.("server could not build a grammar; retrying without pattern/format");
-            }
-            else if (supports.usageInStream && REJECTS_USAGE.test(detail)) {
-                supports.usageInStream = false;
-                onNotice?.("server rejected stream_options; token counts unavailable");
-            }
-            else if (named?.refused.reasoningEffort && rejectsEffort(detail)) {
-                named.refused.reasoningEffort = false;
-                onNotice?.(`${named.name} does not take a reasoning effort; retrying without one`);
+            const refusal = {
+                detail: errorMessage(error),
+                supports,
+                named,
+                droppable: optional,
+            };
+            let notice;
+            for (const answer of ANSWERS) {
+                notice = answer(refusal);
+                if (notice !== undefined)
+                    break;
             }
-            else if (named && stepped) {
-                named.refused.refusedEfforts.add(stepped.value);
-                if (stepped.supported)
-                    named.refused.supportedEfforts = stepped.supported;
-                onNotice?.(`${named.name} does not reason at ${stepped.value}; retrying at ${stepped.next}`);
-            }
-            else if (named?.refused.legacyTokenLimit && wantsCompletionLimit(detail)) {
-                named.refused.legacyTokenLimit = false;
-                onNotice?.(`${named.name} wants max_completion_tokens; retrying with the limit spelled that way`);
-            }
-            else if (named?.refused.chosenTemperature && refusesChosenTemperature(detail)) {
-                named.refused.chosenTemperature = false;
-                onNotice?.(`${named.name} takes only its own temperature; retrying without ours`);
-            }
-            else if (named?.refused.structuredOutput && rejectsResponseFormat(detail)) {
-                named.refused.structuredOutput = false;
-                onNotice?.(`${named.name} does not take response_format; asking for JSON in words instead`);
-            }
-            else if (named && refusesDroppable(detail, optional, named.refused)) {
-                const fields = unknownFields(detail).filter((field) => optional.has(field) && !named.refused.refusedFields.has(field));
-                for (const field of fields)
-                    named.refused.refusedFields.add(field);
-                onNotice?.(`${named.name} does not take ${fields.join(", ")}; retrying without ${fields.length > 1 ? "them" : "it"}`);
-            }
-            else if (flagsOf(supports, model).every((flag, index) => flag === sent[index])) {
+            if (notice !== undefined)
+                onNotice?.(notice);
+            else if (flagsOf(supports, model).every((flag, index) => flag === sent[index]))
                 throw error;
-            }
             // Otherwise the refusal was answered by whoever got there first, and this attempt was
             // built before the answer existed. Two runs opening on a fresh llama.cpp box both get the
             // grammar error; the first latches it off and re-sends, and the second used to find the

package/dist/client.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import OpenAI from "openai";
+import { isPositive } from "./guards.js";
 import { scoped } from "./scope.js";
 /**
  * The SDK insists on a non-empty key even where the server will not look at it. This is what it
@@ -7,15 +8,14 @@ import { scoped } from "./scope.js";
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export const NO_KEY = "agent-core";
+/** A wait in the SDK's spelling: milliseconds, and `undefined` where zero or less means no limit. */
+const limitMs = (seconds) => (seconds > 0 ? seconds * 1000 : undefined);
 /**
  * Zero, less, or absent means no limit, which the SDK spells as `undefined`.
  *
  * @param config Read for `requestTimeoutSeconds` alone.
  */
-export const timeoutMs = (config) => {
-    const seconds = config.requestTimeoutSeconds ?? 0;
-    return seconds > 0 ? seconds * 1000 : undefined;
-};
+export const timeoutMs = (config) => limitMs(config.requestTimeoutSeconds ?? 0);
 /**
  * A client per endpoint, made once and kept.
  *
@@ -92,9 +92,8 @@ const evict = () => {
  */
 export function configureClients(options = {}) {
     for (const [name, value] of Object.entries(options)) {
-        if (typeof value === "number" && value > 0) {
+        if (isPositive(value))
             poolLimits()[name] = value;
-        }
     }
     evict();
     return { ...poolLimits() };
@@ -111,7 +110,7 @@ export const firstTokenMs = (config) => {
         const idle = timeoutMs(config);
         return idle === undefined ? undefined : idle * FIRST_TOKEN_FACTOR;
     }
-    return config.firstTokenSeconds > 0 ? config.firstTokenSeconds * 1000 : undefined;
+    return limitMs(config.firstTokenSeconds);
 };
 /**
  * The client for an endpoint, built once and kept.
@@ -163,7 +162,7 @@ const CONTEXT_KEYS = [
     "context_window",
     "n_ctx",
 ];
-const positive = (value) => (typeof value === "number" && value > 0 ? value : 0);
+const positive = (value) => (isPositive(value) ? value : 0);
 /**
  * A listing entry's window, and whether it is only the one the model was trained with.
  *
@@ -242,6 +241,8 @@ const misses = scoped(() => new Map());
  * it; see `listings`.
  */
 export const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+/** One model on one endpoint, as the caches below key it: stringified, so neither half runs into the other. */
+const modelKey = (endpoint, model) => JSON.stringify([endpoint, model]);
 /**
  * `endpointKey` hashed, for the remembered facts that can leave the process.
  *
@@ -328,7 +329,7 @@ export async function servedWindow(config) {
     const endpoint = endpointKey(config);
     if (unserved().has(endpoint))
         return 0;
-    const key = JSON.stringify([endpoint, config.model]);
+    const key = modelKey(endpoint, config.model);
     const known = served().get(key);
     if (known && (known.window > 0 || Date.now() - known.at < poolLimits().listingMissMs))
         return known.window;
@@ -424,7 +425,7 @@ export async function contextLimitFor(config, declared = 0) {
     // context meter and, in a consumer that compacts on it, compaction: the session then runs at
     // the window instead of under it and fails against the endpoint's own refusal.
     if (!listed()) {
-        const missKey = JSON.stringify([key, config.model]);
+        const missKey = modelKey(key, config.model);
         const asked = misses().get(missKey);
         // Asked again, but not on every call. A model that is never coming answers the same zero
         // however often the endpoint is asked, and a caller sizing a window per turn pays a round

package/dist/compaction.js

@@ -1,4 +1,4 @@
-import { consult, notify, turnMessages, } from "./hooks.js";
+import { consult, notify, textOf, turnMessages, } from "./hooks.js";
 import { messageTokens } from "./retry.js";
 import { ask } from "./side-task.js";
 import { holdsDefinitions } from "./tool-loading.js";
@@ -24,12 +24,6 @@ export const SUMMARY_PROMPT = "You maintain the running memory of a long convers
  * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
  */
 export const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
-/** A message's content as plain text: parts joined, anything but text left out. */
-const textOf = (content) => typeof content === "string"
-    ? content
-    : Array.isArray(content)
-        ? content.map((part) => ("text" in part ? part.text : "")).join(" ")
-        : "";
 /** What the summariser reads for one message: its text and the calls it made. */
 const messageText = (message) => {
     const calls = "tool_calls" in message && message.tool_calls
@@ -98,6 +92,8 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
     }
     return out ?? messages;
 }
+/** An index held between the start of the transcript and `most`, for a caller's `from` that is neither. */
+const clamp = (index, most) => Math.min(Math.max(index, 0), most);
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
  *
@@ -133,7 +129,7 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
     if (cost < limit * compactAt)
         return undefined;
     const head = systemHead(messages);
-    const from = Math.min(Math.max(givenFrom ?? head.from, 0), messages.length);
+    const from = clamp(givenFrom ?? head.from, messages.length);
     const previous = givenPrevious ?? head.previous;
     let cut = messages.length;
     let after;
@@ -256,7 +252,7 @@ export async function runCompaction(messages, plan, summarise, { hooks, forced =
 export function applyCompaction(messages, record, { from } = {}) {
     if (!record?.summary.trim())
         return messages;
-    const head = Math.min(Math.max(from ?? systemHead(messages).from, 0), record.through);
+    const head = clamp(from ?? systemHead(messages).from, record.through);
     return [
         ...messages.slice(0, head).filter((message) => !isSummary(message)),
         summaryMessage(record.summary),

package/dist/continuation.d.ts

@@ -1,6 +1,6 @@
-import OpenAI from "openai";
-import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
-import { type RunTurnOptions } from "./run-turn.ts";
+import type OpenAI from "openai";
+import { type Capabilities } from "./capabilities.ts";
+import { type RequestBuilder, type RunTurnOptions } from "./run-turn.ts";
 import type { Turn } from "./stream.ts";
 /**
  * Picking up an answer the token ceiling cut off, instead of keeping half of it.
@@ -56,4 +56,4 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
  * latched and each continuation finds out again — and the cap on continuations.
  */
-export declare function continueTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;
+export declare function continueTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;

package/dist/continuation.js

@@ -1,7 +1,6 @@
-import OpenAI from "openai";
 import { modelCapabilitiesFor } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { ContextOverflow } from "./retry.js";
+import { ContextOverflow, refusesRequest } from "./retry.js";
 import { runTurn } from "./run-turn.js";
 /**
  * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
@@ -79,8 +78,6 @@ function joinUsage(first, next) {
     }
     return joined;
 }
-/** Whether a failure is the endpoint refusing the request as written, rather than losing it. */
-const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
 /**
  * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
  * so far as a trailing assistant message, and joins the pieces into one turn.

package/dist/events.d.ts

@@ -175,6 +175,19 @@ export interface RunEvent {
  * a duplicate `seq`, which is the one thing the sequence is for.
  */
 export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind" | "runId" | "seq">>;
+/**
+ * A whole event from what a caller said of it: the empty defaults under it, the run and sequence over it.
+ *
+ * The one place the defaults are written, so an event the bus stamps, one the loop keeps for its
+ * own metrics and the notice a slow watcher is sent cannot come to disagree about what an unset
+ * field reads as.
+ *
+ * @param input What happened. An `at` it carries wins over the one given here.
+ * @param runId The run it belongs to. Written after `input`, which gets no say in it.
+ * @param seq Its place in that run, the same.
+ * @param at When, for an input that does not say.
+ */
+export declare const stamp: (input: RunEventInput, runId: string, seq: number, at: number) => RunEvent;
 /**
  * Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose
  * loop threw where it could not be caught. The sweep gets there on its own; this is for a

package/dist/events.js

@@ -1,3 +1,4 @@
+import { isPositive } from "./guards.js";
 import { scoped } from "./scope.js";
 import { LOAD_TOOLS } from "./tool-loading.js";
 /** The numbers a run of the shape this bus was written for wants. */
@@ -31,11 +32,34 @@ const bus = scoped(() => ({ limits: { ...DEFAULTS }, streams: new Map(), sweepin
 export function configureEvents(options = {}) {
     const { limits } = bus();
     for (const [name, value] of Object.entries(options)) {
-        if (typeof value === "number" && value > 0)
+        if (isPositive(value))
             limits[name] = value;
     }
     return { ...limits };
 }
+/**
+ * A whole event from what a caller said of it: the empty defaults under it, the run and sequence over it.
+ *
+ * The one place the defaults are written, so an event the bus stamps, one the loop keeps for its
+ * own metrics and the notice a slow watcher is sent cannot come to disagree about what an unset
+ * field reads as.
+ *
+ * @param input What happened. An `at` it carries wins over the one given here.
+ * @param runId The run it belongs to. Written after `input`, which gets no say in it.
+ * @param seq Its place in that run, the same.
+ * @param at When, for an input that does not say.
+ */
+export const stamp = (input, runId, seq, at) => ({
+    at,
+    text: "",
+    name: "",
+    step: "",
+    ok: null,
+    usage: null,
+    ...input,
+    runId,
+    seq,
+});
 const streamFor = ({ streams }, runId) => {
     const existing = streams.get(runId);
     if (existing)
@@ -114,18 +138,7 @@ export function emit(runId, input) {
     const stream = streamFor(held, runId);
     // One clock read, used for both the event and the sweep's bookkeeping.
     const at = Date.now();
-    const event = {
-        at,
-        text: "",
-        name: "",
-        step: "",
-        ok: null,
-        usage: null,
-        ...input,
-        // After the spread, not before: these are the bus's and a caller does not get a say.
-        runId,
-        seq: ++stream.seq,
-    };
+    const event = stamp(input, runId, ++stream.seq, at);
     stream.events.push(event);
     stream.touched = at;
     if (stream.events.length > limits.maxEvents + limits.trimSlack) {
@@ -228,17 +241,11 @@ async function* watching(held, runId, signal) {
                     // Inside the gap there is nothing to collide with: those seqs reach no watcher.
                     const gap = dropped;
                     dropped = 0;
-                    yield {
-                        runId,
-                        seq: event.seq - 1,
-                        at: event.at,
+                    yield stamp({
                         kind: "notice",
                         text: `${gap} event(s) dropped: this watcher fell too far behind`,
-                        name: "",
                         step: event.step,
-                        ok: null,
-                        usage: null,
-                    };
+                    }, runId, event.seq - 1, event.at);
                 }
                 yield event;
                 // `done` is the last event a run will ever have, so the subscription completes rather

package/dist/guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The checks a value read off the wire is put through before anything is read from it.
+ *
+ * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
+ * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
+ * its own copy.
+ */
+/**
+ * Whether a value is a plain keyed object: not null, and not an array.
+ *
+ * @param value Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Whether a value is a number above zero, which is what a limit has to be to be one.
+ *
+ * `Infinity` passes and `NaN` does not, so a caller lifting a bound and one handing over a
+ * half-built config are told apart without either being asked.
+ *
+ * @param value Anything, usually a setting that may be absent, zero or mistyped.
+ */
+export declare const isPositive: (value: unknown) => value is number;

package/dist/guards.js

@@ -0,0 +1,22 @@
+/**
+ * The checks a value read off the wire is put through before anything is read from it.
+ *
+ * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
+ * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
+ * its own copy.
+ */
+/**
+ * Whether a value is a plain keyed object: not null, and not an array.
+ *
+ * @param value Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is a number above zero, which is what a limit has to be to be one.
+ *
+ * `Infinity` passes and `NaN` does not, so a caller lifting a bound and one handing over a
+ * half-built config are told apart without either being asked.
+ *
+ * @param value Anything, usually a setting that may be absent, zero or mistyped.
+ */
+export const isPositive = (value) => typeof value === "number" && value > 0;

package/dist/hook-events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The points in a session a hook can be bound to, apart from everything that runs one.
+ *
+ * A leaf with no imports, because two modules need these lists and only one of them may load
+ * `node:crypto`: `hooks.ts` hashes a turn into the uuid a memory server dedups on, and `spec.ts`
+ * has to stay importable in a browser. Before this each kept its own copy, with a test holding
+ * one pair together and nothing holding the other.
+ */
+/**
+ * A point in a session a hook can be bound to. Named after Claude Code's hooks of the same shape
+ * — `sessionStart` (SessionStart), `beforeTurn` (UserPromptSubmit), `afterTurn` (Stop),
+ * `beforeCompact` (PreCompact), `sessionEnd` (SessionEnd) — plus `sessionDelete`, for when the host
+ * deletes a session's record.
+ */
+export type HookEvent = "sessionStart" | "beforeTurn" | "afterTurn" | "beforeCompact" | "sessionEnd" | "sessionDelete";
+/** Every event a hook can be bound to, in the order a session meets them. */
+export declare const HOOK_EVENTS: readonly HookEvent[];
+/**
+ * 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 declare const INJECT_EVENTS: ReadonlySet<HookEvent>;

package/dist/hook-events.js

@@ -0,0 +1,22 @@
+/**
+ * The points in a session a hook can be bound to, apart from everything that runs one.
+ *
+ * A leaf with no imports, because two modules need these lists and only one of them may load
+ * `node:crypto`: `hooks.ts` hashes a turn into the uuid a memory server dedups on, and `spec.ts`
+ * has to stay importable in a browser. Before this each kept its own copy, with a test holding
+ * one pair together and nothing holding the other.
+ */
+/** 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"]);