@cubicecho/agent-core 2.8.1 → 2.9.0

package/README.md

@@ -504,6 +504,18 @@ Either one given something that is not a number above zero keeps what was there,
 `configureEvents` does, so a `0` threaded through for "no opinion" does not switch recall off.
 `resetHooks` (and `resetAll`) puts the default back.
 
+The preface said above the blocks moves the same way. `HOOK_PREFACE` names no host, so a host that
+wants its own name says so once with `configureHooks({ preface })`, and a `preface` passed to
+`withContext` (or on `runAgentLoop`'s `hooks`) wins over it for one request. An empty string is a
+preface of nothing — the blocks lead the question on their own, with no blank line above them —
+and anything that is not a string keeps what was there:
+
+```ts
+configureHooks({ preface: "Added by my-host's hooks — background, not the user's words:" });
+const request = withContext(messages, messages.length - 1, gathered.context); // says it
+withContext(messages, messages.length - 1, gathered.context, ""); // says nothing
+```
+
 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/agent-loop.d.ts

@@ -105,7 +105,7 @@ export interface AgentLoopHooks {
     events?: readonly HookEvent[];
     /** The shared context budget. Absent is `configureHooks`'s. */
     maxTokens?: number;
-    /** Said above the context blocks. Absent is `HOOK_PREFACE`. */
+    /** Said above the context blocks. Absent is `configureHooks`'s; empty is none. */
     preface?: string;
     /** Hears each note, from before the request and from `afterTurn`. */
     onNote?: (note: HookNote) => void;

package/dist/hooks.d.ts

@@ -129,6 +129,12 @@ export interface Gathered {
  * `configureHooks` moves it for a process, and `gather` and `assembleContext` for one request.
  */
 export declare const HOOK_CONTEXT_TOKENS = 2000;
+/**
+ * Said once, above the blocks, so the model reads them as background rather than instructions.
+ * Names no host; `configureHooks` sets another for a process that wants to, and `withContext`
+ * for one request.
+ */
+export declare const HOOK_PREFACE: string;
 /** What hooks are held to across a process. Every field optional; see `configureHooks`. */
 export interface HookOptions {
     /**
@@ -136,31 +142,34 @@ export interface HookOptions {
      * held to its own `maxTokens` inside it.
      */
     contextTokens?: number;
+    /**
+     * Said above the context blocks, when a call does not give its own. Empty says nothing, and the
+     * blocks lead the question on their own.
+     */
+    preface?: string;
 }
 /**
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
- * were chosen for.
+ * were chosen for, or whose host wants its own name above the context.
  *
- * 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.
+ * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
+ * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
+ * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
- * @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.
+ * @param options The settings to change. A field left out keeps what it has, and so does one given
+ * the wrong kind of value — `contextTokens` anything but a number above zero, `preface` anything
+ * but a string — so a half-built config narrows nothing. `Infinity` is a number above zero, and
+ * lifts the shared budget entirely. An empty `preface` is a string, and turns the preface off.
  * @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.
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface 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.
  *
@@ -192,7 +201,8 @@ export declare function assembleContext(outcomes: readonly HookOutcome[], maxTok
  * 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`.
+ * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
+ * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @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[];

package/dist/hooks.js

@@ -23,49 +23,58 @@ export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
  * `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 };
+/**
+ * Said once, above the blocks, so the model reads them as background rather than instructions.
+ * Names no host; `configureHooks` sets another for a process that wants to, and `withContext`
+ * for one request.
+ */
+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.";
+/** The settings this module was written with. */
+const HOOK_DEFAULTS = {
+    contextTokens: HOOK_CONTEXT_TOKENS,
+    preface: HOOK_PREFACE,
+};
 /** What is in force now. Read where it is used, so a change applies from the next request. */
-let hookLimits = { ...HOOK_DEFAULTS };
+let hookSettings = { ...HOOK_DEFAULTS };
 /**
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
- * were chosen for.
+ * were chosen for, or whose host wants its own name above the context.
  *
- * 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.
+ * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
+ * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
+ * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
- * @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.
+ * @param options The settings to change. A field left out keeps what it has, and so does one given
+ * the wrong kind of value — `contextTokens` anything but a number above zero, `preface` anything
+ * but a string — so a half-built config narrows nothing. `Infinity` is a number above zero, and
+ * lifts the shared budget entirely. An empty `preface` is a string, and turns the preface off.
  * @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;
+    const { contextTokens, preface } = options;
+    if (typeof contextTokens === "number" && contextTokens > 0) {
+        hookSettings.contextTokens = contextTokens;
     }
-    return { ...hookLimits };
+    if (typeof preface === "string")
+        hookSettings.preface = preface;
+    return { ...hookSettings };
 }
 /**
- * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the
+ * next's.
  * `resetAll` calls it.
  */
 export const resetHooks = () => {
-    hookLimits = { ...HOOK_DEFAULTS };
+    hookSettings = { ...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 budget = (given) => typeof given === "number" && given > 0 ? given : hookSettings.contextTokens;
 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.
@@ -124,14 +133,15 @@ export function assembleContext(outcomes, maxTokens) {
  * 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`.
+ * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
+ * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @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) {
+export function withContext(history, index, context, preface = hookSettings.preface) {
     const message = history[index];
     if (!context || message?.role !== "user")
         return history;
-    const lead = `${preface}\n\n${context}\n\n`;
+    const lead = preface ? `${preface}\n\n${context}\n\n` : `${context}\n\n`;
     const content = typeof message.content === "string"
         ? `${lead}${message.content}`
         : [{ type: "text", text: lead }, ...message.content];

package/dist/reset.d.ts

@@ -4,9 +4,9 @@
  * 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, 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.
+ * hints, the event bus, and the hooks' configured budget and preface. `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 they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the

package/dist/reset.js

@@ -9,9 +9,9 @@ import { resetHints } from "./side-task.js";
  * 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, 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.
+ * hints, the event bus, and the hooks' configured budget and preface. `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 they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the

package/llms.txt

@@ -108,7 +108,7 @@ 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.
+- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for, or whose host wants its own name above the context.
 - `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 by default, in estimated tokens.
@@ -123,7 +123,7 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 - `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.
+- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface 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.
 - `UNTRUSTED_PREFACE` — One sentence for a system prompt, saying what an `untrusted` block is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.8.1",
+  "version": "2.9.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",