@adonis-agora/agent 0.30.2 → 0.33.0

package/dist/src/memory.js

@@ -0,0 +1,330 @@
+/**
+ * Memory: what the assistant has concluded about a person or an organisation, carried across turns
+ * and across threads.
+ *
+ * HOW A READER TELLS IT FROM RAG. Retrieval answers "what do the documents say"; memory answers
+ * "what did I decide about you". A passage is content a person authored and can correct at its
+ * source, and it is cited. A memory has no source to go and fix: it is the agent's own inference,
+ * which is why every record carries an {@link MemoryOrigin} (who wrote it, in which conversation),
+ * why the block tells the model to treat it as fallible, and why `forget` is a REQUIRED method on
+ * the provider rather than an optional one. A wrong document is a content problem. A wrong memory is
+ * the assistant being confidently wrong about someone with nobody aware it is there, so the whole
+ * design is arranged around making it visible and removable.
+ *
+ * WHAT IT COSTS THE PROMPT. One line per memory, capped by `maxMemories`, and each line capped by
+ * `maxFactChars` at WRITE time — so the block a turn can carry is the product of two numbers an
+ * operator sets, rather than however much the model felt like writing down. Unlike a skill, a memory
+ * has no body/catalog split: a fact that cannot be stated in a line is not a memory, it is a
+ * document, and documents are retrieval's job.
+ *
+ * WHAT IT IS NOT: recall over a TRANSCRIPT. Searching what was said earlier is retrieval, and this
+ * library already has `Retriever`/`Reranker` for that.
+ *
+ * RECALL OVER THE MEMORIES THEMSELVES IS A DIFFERENT QUESTION, and it is answered here. The prompt
+ * budget must be bounded; the store has no reason to be. A person accumulates preferences over
+ * months and an organisation publishes facts for everyone in it, so the applicable set outgrows
+ * `maxMemories` quickly — and once it does, WHICH of them the block carries is a decision somebody
+ * has to make. Making it by scope starves the widest scopes first, which is precisely backwards: the
+ * facts that apply to the most people are the ones nobody sees. So a provider MAY supply
+ * {@link MemoryProvider.search}, and where it does, the block is filled by relevance to the turn
+ * (see {@link resolveMemoryDigest}) with scope still a hard filter and never a ranking signal.
+ * `maxMemories` then means "how many matter right now" rather than "how many a person may have".
+ */
+import { actorScope, defaultScopeResolver, } from './skills.js';
+/**
+ * How many memories the block carries. The same ceiling shape as `maxSkills`, and for the same
+ * reason: a prompt that grows with how much the agent has written down is a prompt whose cost nobody
+ * set. A budget on the PROMPT and never on the store — with a provider that can
+ * {@link MemoryProvider.search}, it is how many matter right now rather than how many a person may
+ * have.
+ */
+export const DEFAULT_MAX_MEMORIES = 20;
+/**
+ * How long one memory may be, enforced when it is WRITTEN rather than when it is rendered. Enforcing
+ * it at render time would make the prompt disagree with the store; enforcing it at write time makes
+ * the block's whole ceiling a multiplication an operator can do — `maxMemories × maxFactChars` — and
+ * pushes back on the model at the moment it is writing an essay instead of a fact.
+ */
+export const DEFAULT_MAX_FACT_CHARS = 240;
+export function resolveMemoryDigest({ records, scopes, maxMemories = DEFAULT_MAX_MEMORIES, ranked = false, }) {
+    const rank = new Map(scopes.map((scope, index) => [scope, index]));
+    const byKey = new Map();
+    for (const entry of records) {
+        // A scope the resolver did not return is one this actor has no claim on, whatever the provider
+        // thinks. Dropping it here is what makes over-returning a performance mistake, not a leak.
+        if (!rank.has(entry.scope)) {
+            continue;
+        }
+        const existing = byKey.get(entry.key);
+        if (existing === undefined) {
+            byKey.set(entry.key, [entry]);
+        }
+        else {
+            existing.push(entry);
+        }
+    }
+    const resolved = [];
+    for (const candidates of byKey.values()) {
+        const ordered = [...candidates].sort((a, b) => (rank.get(a.scope) ?? 0) - (rank.get(b.scope) ?? 0));
+        const winner = ordered[0];
+        if (winner === undefined) {
+            continue;
+        }
+        const overrides = ordered.slice(1).map((beaten) => ({
+            scope: beaten.scope,
+            text: beaten.text,
+            author: beaten.origin.author,
+        }));
+        // A pin belongs to the QUESTION, not to the record that currently answers it: pinning "which
+        // fiscal year" and then letting a personal override of it fall out of the block would make
+        // always-on mean "always-on until someone disagrees with it".
+        const pinned = ordered.some((candidate) => candidate.pinned === true);
+        resolved.push({
+            ...winner,
+            ...(pinned ? { pinned: true } : {}),
+            ...(overrides.length > 0 ? { overrides } : {}),
+        });
+    }
+    // Three orders, answering three different questions.
+    //
+    // ALWAYS-ON FIRST, whatever else is true: a pinned fact is in the block whether or not the turn is
+    // about it. It spends the same budget as everything else, so the ceiling stays a product of two
+    // numbers an operator set rather than growing with how much got pinned.
+    //
+    // Then SELECTION among the rest — by relevance where the candidates were ranked, else by narrowest
+    // scope and newest within it. That second rule is right only while nothing is being starved, which
+    // is the case a host running no index is in: `list` returns the whole applicable set, so a ceiling
+    // that bites is dropping what the deployment can best afford to lose. Once the set outgrows the
+    // block it is exactly wrong, because the scopes it drops first are the ones shared by the most
+    // people — one person's twentieth note would end every chance their organisation's facts had.
+    //
+    // RENDERING is by scope then key, stable between turns: ordering the block by recency or by score
+    // would reshuffle it on every write and throw away the provider's prompt cache. Pinned entries
+    // lead, because they are the part of the block that does not move from turn to turn.
+    const byPrecedence = (a, b) => (rank.get(a.scope) ?? 0) - (rank.get(b.scope) ?? 0) ||
+        compare(b.updatedAt, a.updatedAt) ||
+        compare(a.key, b.key);
+    const selected = resolved
+        .map((entry, index) => ({ entry, index }))
+        .sort((a, b) => pinRank(a.entry) - pinRank(b.entry) ||
+        (ranked && a.entry.pinned !== true ? a.index - b.index : byPrecedence(a.entry, b.entry)))
+        .slice(0, maxMemories)
+        .map((candidate) => candidate.entry);
+    const pinnedOmitted = resolved.filter((entry) => entry.pinned === true).length -
+        selected.filter((entry) => entry.pinned === true).length;
+    selected.sort((a, b) => pinRank(a) - pinRank(b) ||
+        (rank.get(a.scope) ?? 0) - (rank.get(b.scope) ?? 0) ||
+        compare(a.key, b.key));
+    return {
+        entries: selected,
+        omitted: Math.max(0, resolved.length - maxMemories),
+        pinnedOmitted,
+    };
+}
+function pinRank(entry) {
+    return entry.pinned === true ? 0 : 1;
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Resolve the scopes and the digest for one turn. Called INSIDE the loop's `memory:digest` step, and
+ * that placement is the whole of its determinism: a search is the most re-derivable thing in this
+ * library — the index moves, a neighbour is written, embeddings are recomputed — so its result has
+ * to be part of the checkpoint every replay reads back, never something a replaying process asks
+ * again.
+ */
+export async function offerMemories({ config, ctx, query, }) {
+    const scopes = await (config.scopes ?? defaultScopeResolver).resolve(ctx);
+    const maxMemories = config.maxMemories ?? DEFAULT_MAX_MEMORIES;
+    // A search keyed on nothing ranks on noise, so a turn with no text to search with reads the scope
+    // plainly rather than making a worse selection out of it. What carries a fact through a turn like
+    // that is `pinned`, not a cleverer query.
+    const trimmed = query?.trim() ?? '';
+    const search = trimmed.length > 0 ? config.provider.search : undefined;
+    const records = search !== undefined
+        ? await search({ scopes, query: trimmed, limit: maxMemories, ctx })
+        : await config.provider.list({ scopes, ctx });
+    return {
+        scopes,
+        recalled: search !== undefined,
+        ...resolveMemoryDigest({ records, scopes, maxMemories, ranked: search !== undefined }),
+    };
+}
+const ASSERTED_FRAMING = 'Stated by people. A person wrote each of these deliberately — the user about themselves, or someone administering their organisation. Treat them as you would any other instruction you were given. If the user says something that contradicts one, say which note it conflicts with and at what scope it is held, rather than quietly setting it aside.';
+const CONCLUDED_FRAMING = 'Concluded by you. These are your own notes from earlier turns, not documents anyone wrote: they may be wrong or out of date, so prefer what the user says now, and say where a note came from if you act on it.';
+const PARTIAL_FRAMING = 'You are being shown a selection, not everything on file. Other notes exist that are not in this list, so never read something’s absence from it as evidence that it was never recorded.';
+function memorySection(framing, entries) {
+    if (entries.length === 0) {
+        return [];
+    }
+    return [
+        framing,
+        ...entries.flatMap((entry) => [
+            `- [${entry.scope}] ${entry.key}: ${entry.text}`,
+            ...(entry.overrides ?? []).map((beaten) => `    ↳ [${beaten.scope}] ${beaten.author === 'human' ? 'a person stated' : 'instead has'}: ${beaten.text}`),
+        ]),
+    ];
+}
+export function buildMemoryBlock({ entries, writable, partial }) {
+    const writeLine = writable
+        ? [
+            `When you learn something durable about this user, record it with the \`${REMEMBER_TOOL_NAME}\` tool; when one of these turns out to be wrong, record the corrected fact under the same key. What you record that way is one of your own notes, not something stated by a person.`,
+        ]
+        : [];
+    const body = [
+        'What is on file about this user and their organisation, carried over from earlier conversations. Each line is a scope, a key and the fact. A narrower scope overrides a wider one; where the wider value is shown underneath, tell the user their setting differs from it rather than silently choosing one.',
+        ...(partial ? [PARTIAL_FRAMING] : []),
+        ...writeLine,
+        // People before inferences: the model meets what it was told before what it worked out.
+        ...memorySection(ASSERTED_FRAMING, entries.filter((entry) => entry.origin.author === 'human')),
+        ...memorySection(CONCLUDED_FRAMING, entries.filter((entry) => entry.origin.author !== 'human')),
+    ];
+    return `<memory>\n${body.join('\n')}\n</memory>`;
+}
+/** The reserved name of the built-in memory-writing tool. */
+export const REMEMBER_TOOL_NAME = 'remember';
+const REMEMBER_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['key', 'fact'],
+    properties: {
+        key: {
+            type: 'string',
+            description: 'A short, stable handle for what this fact is ABOUT (e.g. "fiscal-year", "preferred-units"). Reusing an existing key replaces that fact rather than adding a second one.',
+        },
+        fact: {
+            type: 'string',
+            description: 'The fact itself, in one sentence, stated so it still makes sense in a conversation months from now.',
+        },
+    },
+};
+function issue(path, message) {
+    return { message, path };
+}
+/**
+ * The `remember` tool's input schema. Hand-written for the same reason `askInputSchema` and
+ * `skillInputSchema` are: core depends on no validator and has to publish a JSON Schema a provider
+ * can constrain generation against.
+ *
+ * THERE IS NO SCOPE PARAMETER, and that is the enforcement rather than a simplification. An agent
+ * may only ever write the actor it is running for (see {@link memoryWriteVerdict}), so a scope
+ * argument could only ever be a request that gets refused — and a refusable request is one a model
+ * will keep making, and one a future reader will be tempted to make grantable.
+ */
+export const rememberInputSchema = {
+    '~standard': {
+        version: 1,
+        vendor: 'adonis-agora-agent',
+        validate: (value) => {
+            if (typeof value !== 'object' || value === null) {
+                return { issues: [issue([], 'must be an object')] };
+            }
+            const candidate = value;
+            if (typeof candidate.key !== 'string' || candidate.key.length === 0) {
+                return { issues: [issue(['key'], 'must be a non-empty string')] };
+            }
+            if (typeof candidate.fact !== 'string' || candidate.fact.length === 0) {
+                return { issues: [issue(['fact'], 'must be a non-empty string')] };
+            }
+            return { value: { key: candidate.key, fact: candidate.fact } };
+        },
+        jsonSchema: { input: () => REMEMBER_JSON_SCHEMA },
+    },
+};
+export const REMEMBER_TOOL_DESCRIPTION = 'Record one durable fact about this user under a key, so later conversations start knowing it. For things that will still be true another day — how they work, what their organisation requires, a correction they made. Not for what this conversation is about, and not for anything you were not told or could not reasonably infer. The user can read and delete everything you record here.';
+/**
+ * The `remember` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like
+ * `ask` and `skill`: it has no handler, because the loop serves it against the digest the journal
+ * holds. Keeping it out of the `ToolRegistry` is also what keeps its kind off a process-local
+ * lookup — see `claimToolCall`.
+ */
+export function rememberToolDefinition() {
+    return {
+        name: REMEMBER_TOOL_NAME,
+        kind: 'memory',
+        description: REMEMBER_TOOL_DESCRIPTION,
+        inputSchema: rememberInputSchema,
+    };
+}
+/**
+ * May this author write a memory at this scope?
+ *
+ * The same four rules as `skillWriteVerdict`, deliberately duplicated rather than shared: they are
+ * the same rules about two different things, and folding them into one function would mean a future
+ * change to how skills are authored silently changing who may edit what the assistant believes about
+ * a person. Rule three is the one that matters, and it bites harder here than it does for skills:
+ *
+ * 1. You may only write into a scope you are yourself in.
+ * 2. Your OWN scope is yours. A memory at `actor:<you>` affects exactly one prompt — your own.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. A skill an agent
+ *    could publish at `tenant:` is a procedure anyone in the tenant can edit by talking to the
+ *    assistant; a MEMORY it could publish there is a fact everyone in the tenant is then answered
+ *    from, with no document to inspect and nobody aware it was written. An agent that has genuinely
+ *    learned something the organisation should know proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+export function memoryWriteVerdict(request) {
+    const { scope, scopes, author, actor } = request;
+    if (!scopes.includes(scope)) {
+        return { allowed: false, reason: `"${scope}" is not a scope this actor belongs to` };
+    }
+    const own = actorScope(actor);
+    if (scope === own) {
+        return { allowed: true };
+    }
+    if (author.kind !== 'human') {
+        return {
+            allowed: false,
+            reason: `only a human may write a memory at "${scope}"; an agent may write only at "${own}"`,
+        };
+    }
+    return request.elevated === true
+        ? { allowed: true }
+        : { allowed: false, reason: `writing at "${scope}" requires an elevated human author` };
+}
+export function memoryForgetVerdict({ record, actor }) {
+    return record.scope === actorScope(actor)
+        ? { allowed: true }
+        : {
+            allowed: false,
+            reason: `"${record.scope}" is not this actor's own scope; deleting it is an administrative action`,
+        };
+}
+export async function writeMemory({ config, digest, call, ctx, runId, }) {
+    const write = config.provider.write;
+    if (write === undefined) {
+        return { ok: false, error: 'Memory is read-only in this deployment.' };
+    }
+    const key = call.key.trim();
+    const text = call.fact.trim();
+    if (key.length === 0 || text.length === 0) {
+        return { ok: false, error: 'A memory needs both a key and a fact.' };
+    }
+    const maxFactChars = config.maxFactChars ?? DEFAULT_MAX_FACT_CHARS;
+    if (text.length > maxFactChars) {
+        return {
+            ok: false,
+            error: `A memory must be at most ${maxFactChars} characters; that was ${text.length}. State the fact more briefly.`,
+        };
+    }
+    const scope = actorScope(ctx.actor);
+    const verdict = memoryWriteVerdict({
+        scope,
+        actor: ctx.actor,
+        scopes: digest.scopes,
+        author: { kind: 'agent', actorRef: ctx.actor.id },
+    });
+    if (!verdict.allowed) {
+        return { ok: false, error: verdict.reason };
+    }
+    const record = await write({
+        key,
+        text,
+        scope,
+        origin: { author: 'agent', threadId: ctx.threadId, runId, actorRef: ctx.actor.id },
+        ctx,
+    });
+    return { ok: true, record };
+}
+//# sourceMappingURL=memory.js.map

package/dist/src/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/memory.ts"],"names":[],"mappings":"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"}

package/dist/src/pagination.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The ecosystem's cursor-pagination vocabulary.
+ *
+ * These two types **intentionally mirror `@adonis-agora/filter`'s `CursorParams` / `CursorPage<T>`
+ * STRUCTURALLY** — same property names, same meanings — so every `@adonis-agora/*` package speaks the
+ * one pagination interface and a consumer can move a page between them without a translation layer.
+ * The mirroring is deliberate and must be kept in sync by hand: this package does NOT depend on
+ * `@adonis-agora/filter` (it has no need for the rest of it, and a runtime dependency purely to share
+ * two interfaces would be a worse trade than the duplication). If `@adonis-agora/filter` changes the
+ * shape, change it here too.
+ *
+ * The one intentional difference is that every paginated surface in THIS package is **forward-only**,
+ * so {@link CursorParams} omits `before`/`last` — see its docblock.
+ */
+/**
+ * Cursor pagination parameters, as a caller supplies them.
+ *
+ * - `after` — return the page immediately following this opaque cursor.
+ * - `first` — page size.
+ *
+ * **Forward-only.** `@adonis-agora/filter`'s `CursorParams` also carries `before`/`last` for backward
+ * paging, because it builds keyset predicates over SQL it controls and can therefore run the keyset
+ * comparison in reverse. Neither backend behind this package's paginated surfaces can:
+ *
+ * - Qdrant's scroll returns an opaque `next_page_offset` (the id to resume *after*) and offers no
+ *   "previous page" token at all — there is nothing to send.
+ * - The governance run read-model paginates the runs table with an opaque forward cursor of the same
+ *   shape, and its consumers (a "load more" table) only ever page forward.
+ *
+ * So `before`/`last` are omitted rather than declared-and-ignored: a parameter that type-checks and
+ * then silently does nothing is worse than one that does not exist.
+ */
+export interface CursorParams {
+    /** Opaque cursor from a prior page's {@link CursorPage.nextCursor}; omit for the first page. */
+    after?: string;
+    /** Page size. Each surface documents its own default and ceiling. */
+    first?: number;
+}
+/**
+ * One page of cursor-paginated results.
+ *
+ * - `items` — the rows for this page, in the surface's documented order.
+ * - `nextCursor` — opaque cursor to pass back as {@link CursorParams.after} for the next page, or
+ *   `null` when this was the last page.
+ * - `prevCursor` / `hasPrev` — **always `null` / `false` here.** Every backend in this package is
+ *   forward-only (see {@link CursorParams}), so there is no backward cursor to hand out. The fields
+ *   are still present because the point of this type is that it is the SAME shape as
+ *   `@adonis-agora/filter`'s `CursorPage`: a consumer written against one renders the other without a
+ *   conditional, and a surface that later gains backward paging fills them in without a breaking
+ *   change. They are constants, not a bug.
+ * - `hasNext` — mirrors `nextCursor !== null`.
+ *
+ * Cursor values are **opaque**: they encode whatever the backend needs to resume (for Qdrant, its own
+ * `next_page_offset`), and callers must treat them as bytes to hand back, never parse.
+ */
+export interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+//# sourceMappingURL=pagination.d.ts.map

package/dist/src/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/src/pagination.js

@@ -0,0 +1,16 @@
+/**
+ * The ecosystem's cursor-pagination vocabulary.
+ *
+ * These two types **intentionally mirror `@adonis-agora/filter`'s `CursorParams` / `CursorPage<T>`
+ * STRUCTURALLY** — same property names, same meanings — so every `@adonis-agora/*` package speaks the
+ * one pagination interface and a consumer can move a page between them without a translation layer.
+ * The mirroring is deliberate and must be kept in sync by hand: this package does NOT depend on
+ * `@adonis-agora/filter` (it has no need for the rest of it, and a runtime dependency purely to share
+ * two interfaces would be a worse trade than the duplication). If `@adonis-agora/filter` changes the
+ * shape, change it here too.
+ *
+ * The one intentional difference is that every paginated surface in THIS package is **forward-only**,
+ * so {@link CursorParams} omits `before`/`last` — see its docblock.
+ */
+export {};
+//# sourceMappingURL=pagination.js.map

package/dist/src/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/src/processors.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Running the processor chains, and the stream buffering an output gate requires. See
+ * `./spi/processors.ts` for the seams themselves and the boundary against `HistoryWindow`.
+ */
+import { type InputProcessor, type ModelAnswer, type OutputProcessor, type ProcessedPrompt, type ProcessorContext } from './spi/processors.js';
+import type { SinkWriter, StreamFrame } from './spi/token-stream-sink.js';
+/**
+ * Holds a model call's stream frames instead of letting them reach the subscriber. `end` is
+ * swallowed because the loop owns the run's stream lifecycle across however many steps the turn
+ * takes, and the model call is one step of it.
+ *
+ * A {@link StreamFrame} is a plain typed object, so the buffer rides a durable checkpoint as-is —
+ * which it has to, since the gate must survive a suspend between the model call and the verdict.
+ */
+export interface FrameBuffer {
+    writer: SinkWriter;
+    /** Everything written so far, in write order. */
+    frames(): StreamFrame[];
+}
+export declare function createFrameBuffer(): FrameBuffer;
+/**
+ * The frames a passed gate releases to the live stream: the held ones, with every text frame
+ * collapsed into ONE carrying `text` — the answer as the chain left it, which is the only version
+ * anything downstream is allowed to see. The substitution happens in place, so the answer keeps its
+ * position relative to any non-text frame the provider interleaved with it.
+ */
+export declare function releaseGatedFrames(args: {
+    frames: readonly StreamFrame[];
+    text: string;
+}): StreamFrame[];
+/**
+ * Fold the prompt through each processor in order, every one seeing what the previous one produced.
+ * A throw is wrapped so it cannot read as the model call failing — see {@link ProcessorFailedError}.
+ */
+export declare function runInputProcessors(args: {
+    processors: readonly InputProcessor[];
+    prompt: ProcessedPrompt;
+    ctx: ProcessorContext;
+}): Promise<ProcessedPrompt>;
+/** Who refused an answer, and why. Carried out of a checkpoint, so it stays JSON-round-trippable. */
+export interface GateRejection {
+    processor: string;
+    reason: string;
+}
+/** A settled output chain: the answer as the chain left it, plus who refused it if anyone did. */
+export interface OutputGateResult {
+    /** The text every downstream consumer sees — the stream, the persisted message, the next step. */
+    text: string;
+    /** Set only on a refusal; the run ends with an `OutputRejectedError` naming these. */
+    rejection?: GateRejection;
+}
+/**
+ * Fold the answer through each processor in order. The FIRST rejection ends the chain: a later
+ * processor has nothing to add about text that is never going anywhere, and running it would bill a
+ * moderation call for a turn already refused.
+ */
+export declare function runOutputProcessors(args: {
+    processors: readonly OutputProcessor[];
+    answer: ModelAnswer;
+    ctx: ProcessorContext;
+}): Promise<OutputGateResult>;
+/**
+ * How much of a turn's stream an output chain costs the reader.
+ *
+ * `off` — nothing registered, the model writes straight to the run's sink.
+ * `whole` — at least one processor needs the complete answer, so every frame is held until the chain
+ * has passed and the answer arrives as one `text` frame.
+ * `incremental` — every processor declared {@link import('./spi/processors.js').IncrementalGating},
+ * so a lookback-bounded prefix is released while the call streams.
+ */
+export type OutputGateMode = 'off' | 'whole' | 'incremental';
+/**
+ * ALL or nothing: one undeclared processor puts the whole chain on the whole-answer path. Its author
+ * wrote `process` against the complete text, and a chain that ran it on a prefix because a neighbour
+ * opted in would be handing it an input it never agreed to read.
+ */
+export declare function resolveOutputGateMode(processors: readonly OutputProcessor[]): OutputGateMode;
+/**
+ * The chain's window is the WIDEST any member asked for: a release safe for the shortest-sighted
+ * processor is not safe for the one that matches longer patterns, and the gate makes one release
+ * decision for all of them.
+ *
+ * An undeclared processor contributes nothing rather than the default — it has no window, because a
+ * chain containing one never reaches the incremental path at all.
+ */
+export declare function resolveGateLookback(processors: readonly OutputProcessor[]): number;
+/** A live gate over one model call: the sink the model writes to, plus what it let through. */
+export interface IncrementalGate {
+    /** Hand this to the model instead of the run's writer. */
+    writer: SinkWriter;
+    /** Resolves once every frame handed to {@link IncrementalGate.writer} has been ruled on. */
+    settled(): Promise<void>;
+    /** The transformed prefix already written to the run's sink. */
+    released(): string;
+    /** Set once a prefix was refused; nothing further was released after that. */
+    rejection(): GateRejection | undefined;
+}
+/**
+ * Releases a model call's answer to `writer` as it arrives, holding back the last `lookbackChars`
+ * characters of what the chain produces so a processor can still change them.
+ *
+ * The chain runs over the whole PREFIX accumulated so far rather than over each new frame, so a
+ * processor always sees well-formed text and never has to reassemble a pattern split across frames —
+ * which is what makes {@link import('./spi/processors.js').IncrementalGating}'s promise a claim
+ * about prefixes. It runs once per streamed text frame.
+ *
+ * Only an EXTENSION of what the reader already has is ever written: a chain whose output stops
+ * agreeing with its earlier output has broken its promise, and the loop's whole-answer pass reports
+ * that rather than this gate papering over it by re-sending a different answer.
+ *
+ * Frames that are not text are forwarded live, in arrival order — they are not the answer, so the
+ * gate does not own them.
+ */
+export declare function createIncrementalGate(args: {
+    processors: readonly OutputProcessor[];
+    ctx: ProcessorContext;
+    lookbackChars: number;
+    writer: SinkWriter;
+}): IncrementalGate;
+/**
+ * The tail an incremental gate still owes the reader once the whole-answer pass has settled: the
+ * authoritative text minus the prefix already released.
+ *
+ * Throws when the settled answer is not an extension of that prefix. That check is the reason the
+ * final pass stays authoritative for both the stream and the store rather than the stream being
+ * stitched together from per-prefix results: agreement between what was streamed and what was stored
+ * becomes structural instead of assumed.
+ */
+export declare function gateTail(args: {
+    processors: readonly OutputProcessor[];
+    released: string;
+    text: string;
+}): string;
+//# sourceMappingURL=processors.d.ts.map

package/dist/src/processors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../src/processors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,MAAM,IAAI,WAAW,EAAE,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAW/C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,WAAW,EAAE,CAkBhB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,GAAG,EAAE,gBAAgB,CAAC;CACvB,GAAG,OAAO,CAAC,eAAe,CAAC,CAU3B;AAED,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,gBAAgB,CAAC;CACvB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkB5B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,cAAc,CAO5F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAWlF;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,EAAE,UAAU,CAAC;IACnB,4FAA4F;IAC5F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,gEAAgE;IAChE,QAAQ,IAAI,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,IAAI,aAAa,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,GAAG,EAAE,gBAAgB,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;CACpB,GAAG,eAAe,CAsElB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAYT"}