@cubicecho/agent-core 2.2.4 → 2.4.0

package/dist/events.js

@@ -9,35 +9,40 @@
  * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
  * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
  */
-/** How many events one run keeps for a watcher that joins late. A chatty run loses its oldest. */
-const MAX_EVENTS = 1000;
+/** The numbers a run of the shape this bus was written for wants. */
+const DEFAULTS = {
+    maxEvents: 1000,
+    trimSlack: 256,
+    retainMs: 60_000,
+    retainUnendedMs: 30 * 60_000,
+};
+/** What is in force now. Read where it is used, so a change applies from the next event. */
+let limits = { ...DEFAULTS };
 /**
- * How far past the cap the backlog is allowed to run before it is trimmed.
+ * Changes what the bus keeps, for a process whose runs are not shaped like the ones these
+ * defaults were chosen for.
  *
- * Dropping the oldest event on every push means shifting a thousand-element array tens of
- * thousands of times over a reasoning run — the one thing in here that would ever show up in a
- * profile. Trimming in batches makes it a few dozen splices instead, at the cost of the backlog
- * sometimes being a little longer than the cap, which nothing depends on.
- */
-const TRIM_SLACK = 256;
-/** How long a finished run stays readable, for a watcher that arrives just after the end. */
-const RETAIN_MS = 60_000;
-/**
- * The same for a run that has not said `done`, which is a far more dangerous thing to drop.
+ * The bus is one module-level thing rather than an object a caller holds, so this is too: it is
+ * a deployment's setting, said once at startup, and not something to move around under a run.
+ * What it costs is memory against how much of a run a late or slow watcher can still read —
+ * a server with hundreds of concurrent runs wants a smaller backlog, and one whose tool calls
+ * take an hour wants a longer `retainUnendedMs` than the thirty minutes assumed here.
  *
- * A finished run has nothing more to say, so forgetting it a minute later costs a late watcher
- * a backlog and nothing else. An unfinished one is still writing: `touched` only moves on
- * `emit`, so a live run that spends a minute inside one slow tool call looked exactly like an
- * abandoned one and was reaped out from under itself. What made that more than a lost backlog
- * is that the next `emit` builds a fresh stream with `seq` back at zero — and `seq` is the
- * field `RunEvent` documents for ordering and de-duplication, so a client that reconnects
- * across the gap discards the new events as ones it has already seen.
+ * Changes apply from the next event and the next sweep. Nothing already buffered is trimmed to
+ * a cap that has just come down, because the trim happens on push; the backlog settles to the
+ * new number as the run goes on.
  *
- * The sweep still has to reap them, because a run killed by a signal or simply forgotten
- * reaches no `done` either. This is the backstop for a caller that never says so; `endRun` is
- * for one that knows.
+ * @param options The bounds to change. A field left out — or given anything that is not a
+ * number above zero — keeps what it has, so a partial or a half-built config narrows nothing.
+ * @returns Everything in force afterwards, including what this call did not change.
  */
-const RETAIN_UNENDED_MS = 30 * 60_000;
+export function configureEvents(options = {}) {
+    for (const [name, value] of Object.entries(options)) {
+        if (typeof value === "number" && value > 0)
+            limits[name] = value;
+    }
+    return { ...limits };
+}
 const streams = new Map();
 const streamFor = (runId) => {
     const existing = streams.get(runId);
@@ -72,7 +77,7 @@ function sweep() {
     for (const [runId, stream] of streams) {
         if (stream.listeners.size)
             continue;
-        if (stream.touched <= now - (stream.ended ? RETAIN_MS : RETAIN_UNENDED_MS))
+        if (stream.touched <= now - (stream.ended ? limits.retainMs : limits.retainUnendedMs))
             streams.delete(runId);
     }
     scheduleSweep();
@@ -80,7 +85,7 @@ function sweep() {
 function scheduleSweep() {
     if (sweeping || streams.size === 0)
         return;
-    sweeping = setTimeout(sweep, RETAIN_MS);
+    sweeping = setTimeout(sweep, limits.retainMs);
     sweeping.unref?.();
 }
 /**
@@ -128,8 +133,8 @@ export function emit(runId, input) {
     };
     stream.events.push(event);
     stream.touched = at;
-    if (stream.events.length > MAX_EVENTS + TRIM_SLACK) {
-        stream.events.splice(0, stream.events.length - MAX_EVENTS);
+    if (stream.events.length > limits.maxEvents + limits.trimSlack) {
+        stream.events.splice(0, stream.events.length - limits.maxEvents);
     }
     // Kept for a moment so a watcher that arrives just after the end still sees how it went,
     // then dropped: a finished run's record is the row, not this.
@@ -153,20 +158,26 @@ export function emit(runId, input) {
  * inside the retention window — reads the same story as one that was there from the start.
  *
  * @param runId The run to follow. One that has not started yet is waited on, not refused.
+ * @param signal Stops following. The only other way out is the run's own `done`, and a watcher
+ * with no way out is a leak rather than a lost backlog: the sweep below skips any stream a
+ * listener is on, so a run that dies without `done` pins its backlog for the life of the process.
+ * Returning the generator is not that way out — parked on the promise at the foot of this
+ * function it is suspended at an `await` rather than at a `yield`, and a `return()` there is
+ * queued behind a promise only the next event can settle. An abort resolves that promise itself.
  */
-export async function* watch(runId) {
+export async function* watch(runId, signal) {
     const stream = streamFor(runId);
     // A cursor rather than `shift()`. Draining a backlog an event at a time off the front of an
     // array is a copy of the whole array per event, which on the ten-thousand-delta run this bus
     // is built for is the one quadratic left in the file. The prefix behind the cursor is dropped
-    // in one `slice` per `MAX_EVENTS` instead — the same amortised trade the bus itself makes.
+    // in one `slice` per `maxEvents` instead — the same amortised trade the bus itself makes.
     let queue = [...stream.events];
     let head = 0;
     let dropped = 0;
     let wake = null;
     const listener = (event) => {
         queue.push(event);
-        // The bus caps its own backlog at `MAX_EVENTS`; without this the watcher downstream of it
+        // The bus caps its own backlog at `maxEvents`; without this the watcher downstream of it
         // had no cap at all, so a client too slow to keep up held every delta a run ever emitted.
         // The oldest go, which is what the backlog does, and the gap is reported once below.
         //
@@ -174,8 +185,8 @@ export async function* watch(runId) {
         // the slots behind it, to be freed by the compaction in the drain below — which a consumer
         // that has stalled does not reach, and a stalled consumer is the whole reason for the cap.
         // It read as capped and held every event anyway: 16MB where the cap promises a third of one.
-        const cut = queue.length - head - MAX_EVENTS;
-        if (cut > TRIM_SLACK) {
+        const cut = queue.length - head - limits.maxEvents;
+        if (cut > limits.trimSlack) {
             queue = queue.slice(head + cut);
             head = 0;
             dropped += cut;
@@ -183,9 +194,16 @@ export async function* watch(runId) {
         wake?.();
     };
     stream.listeners.add(listener);
+    // The same wake the listener uses: an abort is another reason to stop waiting, and what the
+    // loop does about it is decided in one place below rather than here.
+    const onAbort = () => wake?.();
+    signal?.addEventListener("abort", onAbort, { once: true });
     try {
         for (;;) {
-            while (head < queue.length) {
+            // Guarding the drain rather than sitting after it, so an already-aborted signal leaves
+            // without replaying the backlog and one raised mid-drain stops at the next event instead
+            // of finishing the queue first.
+            while (!signal?.aborted && head < queue.length) {
                 const event = queue[head++];
                 // What is behind the cursor is released rather than left there. Resetting only on catch-up
                 // was not enough: a watcher that keeps pace but never quite empties the queue never
@@ -194,7 +212,7 @@ export async function* watch(runId) {
                     queue = [];
                     head = 0;
                 }
-                else if (head > MAX_EVENTS) {
+                else if (head > limits.maxEvents) {
                     queue = queue.slice(head);
                     head = 0;
                 }
@@ -227,6 +245,8 @@ export async function* watch(runId) {
                 if (event.kind === "done")
                     return;
             }
+            if (signal?.aborted)
+                return;
             await new Promise((resolve) => {
                 wake = resolve;
             });
@@ -234,6 +254,10 @@ export async function* watch(runId) {
         }
     }
     finally {
+        // `once` covers the abort that fired; this is for the one that never did, which would
+        // otherwise hold this generator and its queue alive for as long as the caller holds the
+        // signal — a run's whole backlog kept by a watcher that finished on `done`.
+        signal?.removeEventListener("abort", onAbort);
         stream.listeners.delete(listener);
         // A watcher can name a run that has not started, or will never start. Nothing was recorded
         // under it, so nothing is left behind either — and a run that has ended has nothing more to
@@ -251,6 +275,11 @@ export async function* watch(runId) {
 /**
  * The backlog alone, for a caller that wants a snapshot rather than a subscription.
  *
+ * The array is a copy; the events in it are not. They are the same objects the bus holds and
+ * every watcher was handed, so writing to one rewrites the run for everybody — which is what
+ * `fold` copies to avoid, and this is the other half of the same warning. Read them, or copy
+ * what you mean to change.
+ *
  * @param runId The run to read. An unknown or already-swept run gives an empty array.
  */
 export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
@@ -260,12 +289,18 @@ export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
  * Named for what it forgets rather than bare `reset`, which sat in a consumer's imports beside
  * `resetAll`, `resetClients`, `resetCapabilities` and `resetHints` saying nothing about which
  * of the five it was — `reset.ts` had to alias it on the way in to stay readable.
+ *
+ * `configureEvents` is undone too, for the reason `reset.ts` gives about latches: a bus left
+ * holding a cap one test set is the same order-dependent suite, passing where that test ran
+ * first and failing where it did not. A consumer that configures at startup and resets at
+ * teardown configures again, which is the same line it already wrote once.
  */
 export const resetEvents = () => {
     streams.clear();
     if (sweeping)
         clearTimeout(sweeping);
     sweeping = null;
+    limits = { ...DEFAULTS };
 };
 /**
  * Consecutive tokens of one kind are one thing being said, not hundreds of things.

package/dist/hooks.d.ts

@@ -0,0 +1,271 @@
+import type OpenAI from "openai";
+/**
+ * Lifecycle hooks, from the host's side: what a session looks like to them, where their context
+ * lands in a request, and what is said about each one.
+ *
+ * Running a hook is not here. What a hook *is* — an MCP tool call in `@cubicecho/agent-mcp-pool`,
+ * something else in another host — is the runner's business, and this takes the runner as a
+ * function. The types are the pool's shapes restated rather than imported, so the pool's
+ * `runHooks` is a runner as it stands and its outcomes pass straight through, without this
+ * package depending on it.
+ */
+/**
+ * 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>;
+/**
+ * One message of a session as a hook is handed it. The shape a memory server's `remember` takes,
+ * so a template can pass a turn straight through.
+ */
+export interface HookMessage {
+    speaker: string;
+    text: string;
+    /** Stable across retries, so a server that dedups on it files a re-sent turn once. */
+    uuid: string;
+}
+/**
+ * What a host knows at an event. Every field but `session` is optional because no event carries
+ * all of them.
+ */
+export interface HookContext {
+    session: {
+        id: string;
+    };
+    /** Which program is running the session, for a hook shared by several. */
+    host?: string;
+    /** ISO 8601. */
+    now?: string;
+    /** The user's message this turn, or the session's opening one. */
+    prompt?: string;
+    /** The assistant's final text. */
+    reply?: string;
+    turn?: {
+        /** Which turn of the session this is, from 0. See `turnIndex`. */
+        index: number;
+        /** The turn's user and assistant text, tool traffic left out. See `turnMessages`. */
+        messages?: HookMessage[];
+    };
+    /** The messages about to be summarised away. */
+    compacting?: HookMessage[];
+    /** Message indexes of that range, `through` exclusive. */
+    range?: {
+        from: number;
+        through: number;
+    };
+    /** How a run ended. */
+    status?: "ok" | "stopped" | "error";
+    /** The host's own extras — a card id, a task step. */
+    vars?: Record<string, unknown>;
+}
+/** What one hook did. A runner returns one per hook it considered, in configuration order. */
+export interface HookOutcome {
+    /** Whatever the hook belongs to — for the pool, the server row. Together with `hookId`, unique. */
+    serverId: string;
+    /** What an injected block and a note call it. */
+    label: string;
+    hookId: string;
+    event: HookEvent;
+    /** The hook ran and did not report an error. */
+    ok: boolean;
+    /** What it returned. Absent when it returned nothing, and when it failed. */
+    text?: string;
+    /** Why it failed or was skipped. */
+    error?: string;
+    /** Set when the hook never ran. */
+    skipped?: boolean;
+    /** Wall time, dispatch to answer. */
+    ms: number;
+    /** Hand `text` to the model. Only honoured on `INJECT_EVENTS`. */
+    inject: boolean;
+    /** The most of `text` that is injected, in estimated tokens. */
+    maxTokens: number;
+}
+/**
+ * One hook's line for whoever is watching: the context it added, or why it added none. A hook
+ * that worked and added nothing gets no note — a remember that succeeded is not news.
+ */
+export interface HookNote {
+    event: HookEvent;
+    /** The outcome's `label`. */
+    source: string;
+    hookId: string;
+    /** Estimated tokens of context it added to the request. */
+    tokens?: number;
+    /** The context it added, as the model read it: after the cap, without the `<context>` tags. */
+    text?: string;
+    /** Why it added nothing: it failed, timed out, or never ran. */
+    error?: string;
+}
+/**
+ * Runs one event's hooks. Should resolve rather than reject — a hook failing is an outcome — but
+ * `gather` and `notify` survive one that does not.
+ *
+ * The pool's `runHooks` fits as it is; wrap it to pass its scope or `onNotice`.
+ */
+export type HookRunner = (event: HookEvent, context: HookContext, options: {
+    signal?: AbortSignal;
+}) => Promise<readonly HookOutcome[]>;
+/** The context a set of outcomes adds to a request, and a note for each hook worth mentioning. */
+export interface Gathered {
+    /** The `<context>` blocks, blank-line separated, or empty when no hook added anything. */
+    context: string;
+    notes: HookNote[];
+}
+/**
+ * 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 declare const HOOK_CONTEXT_TOKENS = 2000;
+/** What hooks are held to across a process. Every field optional; see `configureHooks`. */
+export interface HookOptions {
+    /**
+     * The budget every injecting hook shares, when a call does not give its own. Each hook is still
+     * held to its own `maxTokens` inside it.
+     */
+    contextTokens?: number;
+}
+/**
+ * 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 declare function configureHooks(options?: HookOptions): Required<HookOptions>;
+/**
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * `resetAll` calls it.
+ */
+export declare const resetHooks: () => void;
+/**
+ * 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 declare const HOOK_PREFACE: string;
+/**
+ * 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 declare function assembleContext(outcomes: readonly HookOutcome[], maxTokens?: number): Gathered;
+/**
+ * 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 declare function withContext(history: OpenAI.ChatCompletionMessageParam[], index: number, context: string, preface?: string): OpenAI.ChatCompletionMessageParam[];
+/**
+ * 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 declare function turnMessages(sessionId: string, messages: readonly {
+    role: string;
+    content?: unknown;
+}[], from: number, to?: number): HookMessage[];
+/**
+ * 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 declare const turnIndex: (messages: readonly {
+    role: string;
+}[], before?: number) => number;
+/**
+ * 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 declare function gather(run: HookRunner, events: readonly HookEvent[], context: HookContext, { signal, onNote, maxTokens, }?: {
+    signal?: AbortSignal;
+    onNote?: (note: HookNote) => void;
+    maxTokens?: number;
+}): Promise<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 declare function notify(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<HookNote[]>;