@cubicecho/agent-core 2.3.0 → 2.4.0

package/README.md

@@ -273,6 +273,22 @@ host that stores what the user typed never stores the context as something they
 injecting hook shares `HOOK_CONTEXT_TOKENS` (2000) by default, each held to its own `maxTokens`
 inside that, so a generous hook cannot crowd out the conversation it was meant to inform.
 
+The budget is the caller's to move, at either level. `configureHooks` sets it for the process, and
+`maxTokens` on `gather` (or the second argument to `assembleContext`) sets it for one request and
+wins over it — the one to reach for when the budget follows the model, since a 128k window can
+afford more recall than an 8k one:
+
+```ts
+import { configureHooks, gather } from "@cubicecho/agent-core";
+
+configureHooks({ contextTokens: 4000 });
+const gathered = await gather(run, ["beforeTurn"], context, { maxTokens: contextLimit / 20 });
+```
+
+Either one given something that is not a number above zero keeps what was there, as
+`configureEvents` does, so a `0` threaded through for "no opinion" does not switch recall off.
+`resetHooks` (and `resetAll`) puts the default back.
+
 Neither function rejects. A hook failing is an outcome, and a runner that throws outright is
 noted once for its event and costs only that event's context. `notify` takes no signal: a reader
 who leaves once the turn is answered has not asked for it not to be remembered.

package/dist/hooks.d.ts

@@ -122,12 +122,40 @@ export interface Gathered {
     notes: HookNote[];
 }
 /**
- * The most context all of a request's hooks add between them, in estimated tokens.
+ * 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.
@@ -148,7 +176,8 @@ export declare const HOOK_PREFACE: string;
  *
  * @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. Defaults to `HOOK_CONTEXT_TOKENS`.
+ * @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;
 /**
@@ -217,7 +246,8 @@ export declare const turnIndex: (messages: readonly {
  * @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, `HOOK_CONTEXT_TOKENS` if absent.
+ * `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;

package/dist/hooks.js

@@ -16,12 +16,50 @@ export const HOOK_EVENTS = [
  */
 export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
 /**
- * The most context all of a request's hooks add between them, in estimated tokens.
+ * 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.
@@ -44,12 +82,13 @@ const attribute = (text) => text.replaceAll("&", "&").replaceAll('"', "&quot
  *
  * @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. Defaults to `HOOK_CONTEXT_TOKENS`.
+ * @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 = HOOK_CONTEXT_TOKENS) {
+export function assembleContext(outcomes, maxTokens) {
     const blocks = [];
     const notes = [];
-    let remaining = maxTokens;
+    let remaining = budget(maxTokens);
     for (const outcome of outcomes) {
         const base = { event: outcome.event, source: outcome.label, hookId: outcome.hookId };
         if (!outcome.ok) {
@@ -182,7 +221,8 @@ const runSafely = (run, event, context, signal) => Promise.resolve()
  * @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, `HOOK_CONTEXT_TOKENS` if absent.
+ * `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)));

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetCl
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
-export { assembleContext, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.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";

package/dist/index.js

@@ -13,7 +13,7 @@ export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, }
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
 export { errorMessage } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
-export { assembleContext, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.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";

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/llms.txt

@@ -73,19 +73,22 @@ What a run is doing, while it is doing it.
 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.
 
 - `assembleContext` — Builds the context a set of outcomes adds and the notes that go with it.
+- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for.
 - `Gathered` (type) — The context a set of outcomes adds to a request, and a note for each hook worth mentioning.
 - `gather` — Runs the hooks ahead of a request and builds what they add to it.
-- `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them, in estimated tokens.
+- `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them by default, in estimated tokens.
 - `HOOK_EVENTS` — Every event a hook can be bound to, in the order a session meets them.
 - `HOOK_PREFACE` — Said once, above the blocks, so the model reads them as background rather than instructions.
 - `HookContext` (type) — What a host knows at an event.
 - `HookEvent` (type) — A point in a session a hook can be bound to.
 - `HookMessage` (type) — One message of a session as a hook is handed it.
 - `HookNote` (type) — One hook's line for whoever is watching: the context it added, or why it added none.
+- `HookOptions` (type) — What hooks are held to across a process.
 - `HookOutcome` (type) — What one hook did.
 - `HookRunner` (type) — Runs one event's hooks.
 - `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
 - `notify` — Runs the hooks for an event that reads what happened and adds nothing to a request.
+- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
 - `turnIndex` — Which turn of a session begins at a point, from 0: the user messages ahead of it.
 - `turnMessages` — A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing else.
 - `withContext` — The request, with the hooks' context added to this turn's question.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",