@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/compaction.d.ts

@@ -1,7 +1,7 @@
-import type OpenAI from "openai";
-import type { Endpoint } from "./config.ts";
-import { type HookContext, type HookNote, type HookRunner } from "./hooks.ts";
-import { type SideTaskOptions } from "./side-task.ts";
+import type OpenAI from 'openai';
+import type { Endpoint } from './config.ts';
+import { type HookContext, type HookRunner, type OnNote } from './hooks.ts';
+import { type SideTaskOptions } from './side-task.ts';
 /**
  * Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded
  * into a summary the model writes itself.
@@ -20,6 +20,7 @@ export declare const KEEP_RATIO = 0.35;
 /**
  * The summariser's instruction when the caller gives none.
  *
+ * @remarks
  * Asks for notes rather than a retelling, because what the summary replaces is the model's only
  * record of what was decided, and a narrative spends its words on the order things happened in.
  */
@@ -30,14 +31,28 @@ export declare const SUMMARY_PROMPT: string;
 export declare const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
 /** What `pruneToolResults` takes. */
 export interface PruneOptions {
-    /** How many of the latest tool results are left whole, 5 by default. */
+    /**
+     * How many of the latest tool results are left whole.
+     *
+     * @defaultValue `5`
+     */
     keepLast?: number;
-    /** A result this long or shorter is left whole wherever it is, 256 characters by default. */
+    /**
+     * A result this long or shorter, in characters, is left whole wherever it is.
+     *
+     * @defaultValue `256`
+     */
     maxChars?: number;
 }
 /**
  * The transcript with every tool result but the latest few replaced by a one-line stub.
  *
+ * @param messages - The transcript. Not written to.
+ * @param [options] - How many results to keep and how long one must be to clear.
+ * @returns `messages` itself when nothing was cleared, otherwise a new array in which each cleared
+ * result is a new message and every other one the same object.
+ *
+ * @remarks
  * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
  * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
  * call answered — a call with no result is a malformed transcript — and says how much was there,
@@ -46,9 +61,6 @@ export interface PruneOptions {
  * only copy of them the model has (`holdsDefinitions`); either still counts as one of the latest
  * few. Returns the same array when there was nothing to clear. Rewrites the prefix;
  * see the module comment on when to run it.
- *
- * @param messages The transcript. Not written to.
- * @param options How many results to keep and how long one must be to clear.
  */
 export declare function pruneToolResults(messages: Message[], { keepLast, maxChars }?: PruneOptions): Message[];
 /** What `planCompaction` takes. */
@@ -60,9 +72,17 @@ export interface CompactionOptions {
      * absent is the estimate of the whole transcript.
      */
     used?: number;
-    /** The fraction of `limit` in use before compacting. `COMPACT_AT` by default. */
+    /**
+     * The fraction of `limit` in use before compacting.
+     *
+     * @defaultValue `COMPACT_AT`
+     */
     compactAt?: number;
-    /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
+    /**
+     * The fraction of `limit` the kept tail may fill.
+     *
+     * @defaultValue `KEEP_RATIO`
+     */
     keepRatio?: number;
     /**
      * The fraction of `limit` the whole request should come down to, in place of `keepRatio`: the
@@ -72,15 +92,22 @@ export interface CompactionOptions {
     target?: number;
     /**
      * What the summary is assumed to cost when planning to a `target` — the ceiling its writer is
-     * held to, since the plan is made before it is written. 1024 by default, which is `summariser`'s.
+     * held to, since the plan is made before it is written.
+     *
+     * @defaultValue `1024`, which is `summariser`'s ceiling
      */
     summaryTokens?: number;
-    /** One message's tokens. `messageTokens` by default, divided by `charsPerToken`. */
+    /**
+     * One message's tokens.
+     *
+     * @defaultValue `messageTokens` divided by `charsPerToken`
+     */
     estimate?: (message: Message) => number;
     /**
      * The divisor the default `estimate` uses — `charsPerTokenFor` the model, for a transcript
-     * weighed the way `runTurn` sizes its requests. `CHARS_PER_TOKEN` when absent; ignored beside
-     * an `estimate` of the caller's own.
+     * weighed the way `runTurn` sizes its requests. Ignored beside an `estimate` of the caller's own.
+     *
+     * @defaultValue `CHARS_PER_TOKEN`
      */
     charsPerToken?: number;
     /**
@@ -114,6 +141,13 @@ export interface CompactionPlan {
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
  *
+ * @param messages - The transcript, system prompts included if the caller keeps them in it.
+ * @param options - The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
+ * @returns The plan, its `toSummarise` a new array of the same message objects, or `undefined` when
+ * there is nothing to fold. `messages` is not written to.
+ *
+ * @remarks
  * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
  * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
  * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
@@ -134,26 +168,26 @@ export interface CompactionPlan {
  * comes, and `after` says how far short it fell. An earlier summary the new one replaces is not
  * credited, so `after` errs high by at most that much. It is only as good as `estimate` — see
  * `estimateFrom` for one that is measured.
- *
- * @param messages The transcript, system prompts included if the caller keeps them in it.
- * @param options The window, what is in use, the ratios, and where the last fold ended. See
- * `CompactionOptions`.
  */
 export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, target, summaryTokens, charsPerToken, estimate, from: givenFrom, previous: givenPrevious, }: CompactionOptions): CompactionPlan | undefined;
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.
  *
- * @param plan What `planCompaction` returned.
+ * @param plan - What `planCompaction` returned.
+ * @returns The text for the summariser, messages a blank line apart. A message with neither text
+ * nor calls is left out, and a plan with a `previous` opens with it under `Notes so far:`.
  */
 export declare function summaryInput(plan: CompactionPlan): string;
 /**
  * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
  *
- * @param config The endpoint the summary is written through.
- * @param model The model to write it, which may be a smaller one than the run's.
- * @param options Cancellation and notices; the ceiling is 1024 and the instruction
- * `SUMMARY_PROMPT` unless given.
+ * @param config - The endpoint the summary is written through.
+ * @param model - The model to write it, which may be a smaller one than the run's.
+ * @param [options] - Cancellation and notices, and the instruction and ceiling the summary is
+ * written under.
+ * @returns A function from `summaryInput`'s text to the summary. It rejects as `ask` does, and
+ * resolves with an empty string where the model wrote nothing.
  */
 export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
     system?: string;
@@ -161,6 +195,7 @@ export declare const summariser: (config: Endpoint, model: string, { system, max
 /**
  * One fold, as a host that keeps its transcript append-only stores it.
  *
+ * @remarks
  * The other half of `compactTranscript`: the same work, recorded rather than applied. A host that
  * persists this beside an untouched transcript still shows the user every message, can undo a fold
  * by dropping one row, and rebuilds the request with `applyCompaction` — where a host that keeps
@@ -179,12 +214,12 @@ export interface CompactionRunOptions {
     /**
      * Hooks to tell. `context` is extended with `compacting` and `range`, whose indexes are the
      * plan's — and so the host's own, for a plan made over a stored transcript. `honourVeto` waits
-     * for the hooks and lets one stop the compaction; off by default, which adds no latency.
+     * for the hooks and lets one stop the compaction; without it they add no latency.
      */
     hooks?: {
         run: HookRunner;
         context: HookContext;
-        onNote?: (note: HookNote) => void;
+        onNote?: OnNote;
         honourVeto?: boolean;
     };
     /**
@@ -196,58 +231,75 @@ export interface CompactionRunOptions {
 /**
  * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *
- * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
- * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
- * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
- *
- * @param messages The transcript the plan was made for. Read only, and only for the hooks.
- * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param messages - The transcript the plan was made for. Read only, and only for the hooks.
+ * @param plan - What `planCompaction` returned for it.
+ * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @param [options] - Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
  * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
  * so the caller stores nothing and the transcript is still whole.
+ *
+ * @remarks
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
  */
 export declare function runCompaction(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced }?: CompactionRunOptions): Promise<CompactionRecord | undefined>;
 /**
  * The transcript as the server should see it: the folded head replaced by its summary.
  *
- * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
- * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
- * continues these notes rather than summarising them a second time. Any earlier summary message in
- * the kept head is dropped, since the record's already contains it.
- *
- * @param messages The stored transcript, whole. Not written to.
- * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * @param messages - The stored transcript, whole. Not written to.
+ * @param [record] - The fold, or `undefined` for a session that has not been compacted, which hands
  * back `messages` itself.
- * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * @param [options] - `from` is the first message the fold was allowed to take — the plan's, for a host
  * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
  * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
  * case for a host whose system prompt is a separate argument.
+ * @returns `messages` itself when there is no record or its summary is blank, otherwise a new
+ * array: the kept head, one summary message, then everything from the record's `through` on.
+ *
+ * @remarks
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
  */
-export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, "summary" | "through">, { from }?: {
+export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, 'summary' | 'through'>, { from }?: {
     from?: number;
 }): Message[];
 /**
  * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
  * everything after it.
  *
+ * @param index - The position in the stored transcript.
+ * @param [record] - The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param [head] - How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero is the stored-fold case,
+ * where the summary is the request's first message.
+ * @returns The index in the request. One before the record's `through` gives `head`, where the
+ * summary sits — an index among the kept head messages themselves included.
+ *
+ * @remarks
  * A transcript that stays append-only and a request that does not are two numberings of the same
  * conversation, and anything that names a position — `withContext`'s index, a range handed to a
  * hook — has to say which it is in. An index inside the folded stretch answers with the summary
  * message that now stands for it.
- *
- * @param index The position in the stored transcript.
- * @param record The fold in force, or `undefined` for a session that has none, which hands the
- * index straight back.
- * @param head How many messages the request keeps ahead of the summary — the leading system
- * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
- * where the summary is the request's first message.
  */
-export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, "through">, head?: number) => number;
+export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, 'through'>, head?: number) => number;
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *
+ * @param messages - The transcript the plan was made for. Not written to.
+ * @param plan - What `planCompaction` returned for it.
+ * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
+ * @param [options] - Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
+ *
+ * @remarks
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
  * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
@@ -261,15 +313,6 @@ export declare const requestIndex: (index: number, record?: Pick<CompactionRecor
  * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
  * order, so a host that stores the fold instead of the array gets the same summary at the same
  * cut rather than a second implementation that drifts from this one.
- *
- * @param messages The transcript the plan was made for. Not written to.
- * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
- * when a hook vetoes.
- * @param options Hooks to tell and whether the window is already past. See
- * `CompactionRunOptions`.
- * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
- * new array.
  */
 export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, options?: CompactionRunOptions): Promise<Message[]>;
 export {};