@adonis-agora/agent 0.31.0 → 0.33.0

package/dist/src/skills.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Skills: an authored procedure the model pulls in when a task calls for it, instead of every
+ * instruction living in the system prompt.
+ *
+ * WHAT A SKILL IS NOT: an agent. An agent is WHO is answering — its persona, its tools, its history
+ * window, its output schema. A skill is HOW one particular task is done, and any agent may pull one
+ * in. That is why a skill carries no model, no tool list and no schema: the moment it did, the two
+ * would be the same thing wearing different names, and a consumer would have to choose between them
+ * for reasons nobody could state.
+ *
+ * WHAT IT COSTS THE PROMPT: one line per skill. The catalog block below carries names, scopes and
+ * descriptions only; a BODY reaches the model as a tool result, on the transcript, where the
+ * `HistoryWindow` ceiling already governs it. So skills are not a fourth thing competing for the
+ * system block with the agent's own prompt, its persona and injected retrieval — see
+ * `AgentLoopDeps.skills` for how they compose.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Actor, PageContext, ToolDefinition } from './types.js';
+/** How a skill is identified in the catalog, to the model and to a `/`-autocomplete alike. */
+export interface SkillSummary {
+    /** Unique within a scope. The handle the model passes to the `skill` tool. */
+    name: string;
+    /** One line: what task this covers, and therefore when to load it. Read by the MODEL to choose. */
+    description: string;
+    /** The opaque scope token this skill is published at — see {@link ScopeResolver}. */
+    scope: string;
+}
+/** A skill with the instructions themselves. Only ever materialized when something loads it. */
+export interface Skill extends SkillSummary {
+    body: string;
+}
+/** Whose turn is asking, and therefore which scopes apply. */
+export interface ScopeContext {
+    actor: Actor;
+    threadId: string;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/**
+ * The skills-facing name for {@link ScopeContext}, so a `SkillProvider`'s signature reads in its own
+ * vocabulary. Deliberately the SAME type rather than a parallel one: skills and memory resolve
+ * scopes through one {@link ScopeResolver}, and a deployment that could answer "which scopes does
+ * this actor have" twice would eventually answer it differently.
+ */
+export type SkillContext = ScopeContext;
+/** The scope token every deployment has: skills nobody narrowed. */
+export declare const GLOBAL_SCOPE = "global";
+/** The token for one actor's own skills. */
+export declare function actorScope(actor: Actor): string;
+/** The token for a tenant's skills — `Actor.tenantRef` is the only tenant key this library knows. */
+export declare function tenantScope(tenantRef: string): string;
+/**
+ * Which scopes a turn may draw from, MOST SPECIFIC FIRST. Precedence is the order: an entry from an
+ * earlier token outranks a same-named one from a later token, and the model is shown which won.
+ *
+ * A HOST-SUPPLIED FUNCTION rather than an enum this library owns, because the axes a deployment
+ * scopes by are the deployment's own. `Actor` gives an id and a tenant; it does not give a sector, a
+ * squadron, a base, a shift — and every one of those is a real axis in some consumer. An enum here
+ * would make each of them a schema change in a library that has no business knowing they exist,
+ * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:base-7',
+ * 'global']` and precedence follows, with nothing in this package edited.
+ *
+ * MUST be a pure function of its context. It runs inside the `skills:catalog` / `memory:digest`
+ * checkpoint and its result is journaled, so a resumed run reads back the scopes the first attempt
+ * resolved rather than asking a membership table that may have changed since — which would let a
+ * run's prompt differ from the one its journal records. Read a database here at your peril; read it
+ * in the provider, whose answer is journaled at the same position.
+ */
+export interface ScopeResolver {
+    resolve(ctx: ScopeContext): string[] | Promise<string[]>;
+}
+/**
+ * The scopes derivable from an {@link Actor} alone — the common case, so a consumer wiring skills
+ * for the first time supplies no resolver at all: the actor's own, their tenant's (when they have
+ * one), and the deployment's. A host adding an axis of its own replaces this rather than extending
+ * it, since the ORDER is the precedence and only the host knows where its axis belongs.
+ */
+export declare const defaultScopeResolver: ScopeResolver;
+/** Arguments to {@link SkillProvider.list}. */
+export interface ListSkillsInput {
+    scopes: readonly string[];
+    ctx: SkillContext;
+}
+/**
+ * Arguments to {@link SkillProvider.load}. An object rather than positional arguments because `name`
+ * and `scope` are both strings: transposed, a positional call compiles clean, returns `null`, and
+ * the skill silently fails to load.
+ */
+export interface LoadSkillInput {
+    name: string;
+    scope: string;
+    ctx: SkillContext;
+}
+/**
+ * Where skills come from. Deliberately two calls rather than one: `list` is asked on EVERY turn and
+ * must stay cheap, while a body is read only when the model decides it needs that procedure — the
+ * whole point of the surface. A provider over a table selects name/description/scope for the first
+ * and one row for the second.
+ *
+ * This library owns no skill table. A skill's real scoping axes, its authoring UI and its audit
+ * trail are all the host's, and a host that related its own entity into a table this package created
+ * at boot would be writing migrations against a schema the boot-time heal also edits. Tokens split
+ * it the other way round: the library owns the contract (what a scope means, how precedence works,
+ * what is journaled), the host owns the rows.
+ */
+export interface SkillProvider {
+    /**
+     * Every skill visible at `scopes`, in any order — this library sorts and resolves precedence. A
+     * provider MAY return skills outside `scopes`; they are dropped rather than trusted, so a filter
+     * bug in a host cannot widen what an actor is offered.
+     */
+    list(input: ListSkillsInput): SkillSummary[] | Promise<SkillSummary[]>;
+    /**
+     * The instructions for one skill, or `null` when it is gone. Called only from inside the loading
+     * checkpoint, so the body it returns is journaled and every replay reads THAT text back — an
+     * edited skill never rewrites the prompt of a run already in flight.
+     */
+    load(input: LoadSkillInput): string | null | Promise<string | null>;
+}
+/** A source of skills that is a fixed list — module config, or a host's own constant. */
+export declare function staticSkillProvider(skills: readonly Skill[]): SkillProvider;
+/**
+ * Read several sources as one. The order is the tie-break and nothing else: precedence between
+ * skills is by SCOPE, so two sources only ever compete when they publish the same name at the same
+ * scope, and then the earlier source wins. Wire the host's own provider first — a row it can edit is
+ * a better answer than a body that needs a deploy to change.
+ */
+export declare function compositeSkillProvider(providers: readonly SkillProvider[]): SkillProvider;
+/**
+ * One skill as it is offered — to the model in the catalog block, and to a client listing what a
+ * user may type after a `/`. Both read the same list, built by the same call, so what a user can
+ * reach and what the model can reach cannot drift apart.
+ */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    /** The scope token it resolved from — the provenance a user is entitled to see. */
+    scope: string;
+    /**
+     * Scope tokens of same-named skills this one outranks, widest last. Present ONLY when something
+     * was shadowed, so a reader can tell "there is no org default" from "there is one and yours wins".
+     * The model is shown it for the same reason: a silent override is indistinguishable from an
+     * instruction nobody wrote, and the user can only be told "your setting differs from the org
+     * default" by something that knows both existed.
+     */
+    shadows?: string[];
+}
+/** What a turn resolved — journaled whole, so the prompt is reconstructible from the journal alone. */
+export interface SkillOffer {
+    /** The scope tokens this turn drew from, most specific first. */
+    scopes: string[];
+    /** The skills offered, most specific first then by name. */
+    entries: SkillCatalogEntry[];
+    /** Applicable skills `maxSkills` left out. Non-zero means the catalog is not the whole truth. */
+    omitted: number;
+}
+/**
+ * How many skills a catalog offers before it starts leaving some out. A ceiling on the SYSTEM
+ * PROMPT's share, not on how many a deployment may have: the block costs one line each, and a
+ * hundred lines of "here is something you could load" crowds out the agent's own instructions while
+ * making the choice harder rather than easier.
+ */
+export declare const DEFAULT_MAX_SKILLS = 20;
+/** How a turn reaches its skills. See `AgentLoopDeps.skills`. */
+export interface SkillsConfig {
+    provider: SkillProvider;
+    /** Undefined → {@link defaultScopeResolver}: the actor's own, their tenant's, the deployment's. */
+    scopes?: ScopeResolver;
+    /** Undefined → {@link DEFAULT_MAX_SKILLS}. */
+    maxSkills?: number;
+}
+/**
+ * Resolve a provider's skills against an ordered scope list: most specific wins, and the loser's
+ * scope is recorded rather than discarded.
+ *
+ * Pure, and separately exported, because two callers must reach the identical answer — the loop, so
+ * the model is offered it, and the listing endpoint, so a user is. A second implementation of "which
+ * skills apply" is a second answer, and the two diverge the first time either is edited.
+ */
+export declare function resolveSkillCatalog(summaries: readonly SkillSummary[], scopes: readonly string[], maxSkills?: number): Omit<SkillOffer, 'scopes'>;
+/** Resolve the scopes and the catalog for one turn. Called INSIDE the loop's `skills:catalog` step. */
+export declare function offerSkills(config: SkillsConfig, ctx: SkillContext): Promise<SkillOffer>;
+/** The reserved name of the built-in skill-loading tool. */
+export declare const SKILL_TOOL_NAME = "skill";
+/**
+ * The catalog as the model reads it. One line per skill — name, scope, description, and what it
+ * overrides — because the entire claim of progressive disclosure is that choosing what to read costs
+ * far less than reading everything.
+ */
+export declare function buildSkillsBlock(entries: readonly SkillCatalogEntry[]): string;
+/** What the model passes to the `skill` tool. */
+export interface SkillToolInput {
+    name: string;
+}
+/**
+ * The `skill` tool's input schema. Hand-written for the same reason `askInputSchema` is: this
+ * package depends on no validator, and the schema has to publish a JSON Schema a provider can
+ * constrain generation against.
+ *
+ * The available names are deliberately NOT an enum here. A per-turn enum would make the tool's
+ * definition depend on the catalog, and a tool list re-derived by whichever process serves a turn is
+ * exactly the process-local lookup this design keeps off a turn's decisions. The names live in the
+ * prompt, where the journal holds them; a name that is not in the catalog comes back as an ordinary
+ * tool failure listing the ones that are.
+ */
+export declare const skillInputSchema: StandardSchemaV1<unknown, SkillToolInput>;
+export declare const SKILL_TOOL_DESCRIPTION = "Read one of the procedures listed in <skills>. Call it before doing a task a listed skill covers, and follow what it returns. It performs nothing and changes nothing \u2014 it only gives you instructions you do not yet have.";
+/**
+ * The `skill` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like `ask`:
+ * it has no handler, because the loop serves it from the catalog the journal holds. Keeping it out
+ * of the `ToolRegistry` is also what keeps its kind off a process-local lookup — see
+ * `claimToolCall`.
+ */
+export declare function skillToolDefinition(): ToolDefinition;
+/** What a `skill` call resolved to — the body, or why it did not. */
+export type SkillLoadOutcome = {
+    ok: true;
+    skill: Skill;
+    shadows?: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Serve one `skill` call against the catalog THIS TURN was offered.
+ *
+ * The catalog is the authorization boundary, not just a menu: a name the turn was never offered is
+ * refused here, so a model that invents one (or repeats one it saw in another actor's thread) cannot
+ * reach a body through a provider that would happily serve it. Because the catalog came out of the
+ * `skills:catalog` checkpoint, that boundary is the one the journal records rather than the one this
+ * process's provider currently believes in.
+ */
+export declare function loadSkill(args: {
+    config: SkillsConfig;
+    offer: SkillOffer;
+    name: string;
+    ctx: SkillContext;
+}): Promise<SkillLoadOutcome>;
+/** Who is trying to write a skill. */
+export interface SkillAuthor {
+    /**
+     * `'human'` is a person acting through a UI; `'agent'` is anything else — a tool, a turn, a batch
+     * job. The distinction is the whole of the rule below, so it is not inferable and has to be stated
+     * by the caller.
+     */
+    kind: 'human' | 'agent';
+    actorRef?: string;
+}
+/** A request to author a skill at a scope. */
+export interface SkillWriteRequest {
+    /** The scope token the skill would be published at. */
+    scope: string;
+    actor: Actor;
+    /** The actor's resolved scopes, most specific first — the same list a turn draws from. */
+    scopes: readonly string[];
+    author: SkillAuthor;
+    /**
+     * The host's own answer to "may this person administer that scope" — a sector lead editing their
+     * sector's skills, an operator editing the deployment's. This library cannot know it: it has no
+     * notion of who administers `sector:logistics`, and inventing one would be a second, weaker
+     * authorization model next to the host's real one. Undefined/false → a wider scope is refused.
+     */
+    elevated?: boolean;
+}
+export type SkillWriteVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * May this author publish a skill at this scope?
+ *
+ * A skill's body is instructions the model follows, which makes writing one at a scope an edit to
+ * everyone in that scope's system prompt. The rules follow from that, and only the third is
+ * interesting:
+ *
+ * 1. You may only write into a scope you are yourself in. Writing into a scope you are not in is
+ *    authoring for people you have no relationship with.
+ * 2. Your OWN scope is yours. A per-actor skill affects exactly one prompt — the author's.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. An agent that can
+ *    write a `tenant:` skill is an agent whose prompt anyone in the tenant can edit by talking to
+ *    it: the user asks for something, the turn writes the instruction, and every later turn for
+ *    every other user follows it. That is prompt injection with persistence, and no elevation a host
+ *    could grant makes it a different shape. An agent that has genuinely learned something worth
+ *    sharing proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+export declare function skillWriteVerdict(request: SkillWriteRequest): SkillWriteVerdict;
+//# sourceMappingURL=skills.d.ts.map

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

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

package/dist/src/skills.js.map

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

package/dist/src/spi/agent-runner.d.ts

@@ -1,10 +1,12 @@
-import type { AgentRunInput, Decision } from '../types.js';
+import type { HumanReply } from '../elicitation.js';
+import type { AgentRunInput } from '../types.js';
 /**
  * Runs an agent turn. Two impls exist:
  *  - InlineAgentRunner (default): the loop runs in-process — no extra dependencies. This is what
- *    `AGENT_RUNNER` binds to unless `durable: true` is set.
- *  - DurableAgentRunner (opt-in via `durable: true`): the turn is a `@dudousxd/nestjs-durable`
- *    `@Workflow`, so each model/tool call is a checkpointed step and HITL is `ctx.waitForSignal`.
+ *    the provider builds unless `durable: true` is set.
+ *  - DurableAgentRunner (opt-in via `durable: true`): the turn is an `@adonis-agora/durable`
+ *    {@link import('../durable/agent-run-workflow.js').AgentRunWorkflow}, so each model/tool call is
+ *    a checkpointed step and HITL is `ctx.waitForSignal`.
  *
  * `start` ENQUEUES and returns immediately with the runId — the live tokens flow on the
  * TokenStreamSink, not through this call.
@@ -13,8 +15,20 @@ export interface AgentRunner {
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    /** Deliver a HITL decision for a pending action tool call. */
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    /**
+     * Deliver a human's reply to a parked tool call — an approve/reject {@link import('../types.js').Decision}
+     * for an `action`, or an {@link import('../elicitation.js').ElicitationReply} for a question set.
+     * One channel for both, because a question set parks as a `pending_approval` action and therefore
+     * reaches a run through the inbox a deployment already has.
+     *
+     * A `Decision` reaching a question set is the documented reduction ("confirmed the pre-picked
+     * answers"). The reverse is not: answers carry no `approved`, so an implementation that can tell
+     * which wait it is settling MUST refuse them with
+     * {@link import('../elicitation.js').HumanReplyMismatchError} rather than deliver them. An
+     * implementation that cannot tell delivers, and the loop discards the reply and stays parked —
+     * either way, no rejection is recorded against a human who only submitted a form.
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
     cancel(runId: string): Promise<void>;
 }
 //# sourceMappingURL=agent-runner.d.ts.map

package/dist/src/spi/agent-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../src/spi/agent-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../src/spi/agent-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/dist/src/spi/agent-store.d.ts

@@ -59,6 +59,14 @@ export interface RecordRunStartInput {
     actor: Actor;
     /** The agent that handled the run; `null`/omitted for the default agent. */
     agentName?: string;
+    /**
+     * The run that started this one, for a delegation's child run. The parent->child edge exists in
+     * the durable runtime's own journal, but only there: a governance surface reading run rows alone
+     * cannot roll a delegation's cost up to the turn that asked for it.
+     *
+     * Optional, and a store that persists nothing for it still works — it loses the tree, not the run.
+     */
+    parentRunId?: string;
     /** True when the run executes as a replay-safe durable workflow, false for the inline runner. */
     durable?: boolean;
 }
@@ -79,6 +87,40 @@ export interface RecordRunEndInput {
     costUsd?: number;
     error?: string;
 }
+/** Which thread, and how many of its newest messages, {@link ThreadTurnReader.loadThreadForTurn} reads. */
+export interface ThreadTurnQuery {
+    threadId: string;
+    /** Omitted reads every message; `0` reads none. */
+    messageLimit?: number;
+}
+/** What a turn reads off a thread — a bounded window, not the transcript. */
+export interface ThreadTurnPage {
+    title: string;
+    /** Whether the THREAD has ever been answered, not whether {@link messages} holds an answer. */
+    hasAssistantMessage: boolean;
+    /** Oldest first, carrying only the fields a model turn reads. */
+    messages: StoredMessage[];
+}
+/**
+ * A store that can hand a turn the WINDOW it is about to send, instead of the thread's transcript.
+ *
+ * {@link AgentStore.getThread} materializes every message row, every attachment and every tool
+ * output a thread ever recorded, and `load:thread` then journals what it loaded — so a long thread
+ * pays for its whole history on every turn and again on every replay, to send a prompt bounded to
+ * its last few messages. This read is bounded by the database (`order by created_at desc limit ?`),
+ * projected to the columns a model turn actually reads.
+ *
+ * `hasAssistantMessage` is answered over the WHOLE thread, never the page: it answers "has this
+ * conversation been answered before?" — what a `thread-start` intake asks — and a thread whose
+ * window happens to hold only the user's last questions has still been answered. `null` for a thread
+ * that is unknown or soft-deleted, matching `getThread`.
+ *
+ * Probed STRUCTURALLY rather than declared on {@link AgentStore}: it is an optimization a store
+ * either offers or does not, and one that offers none still answers correctly through the full read.
+ */
+export interface ThreadTurnReader {
+    loadThreadForTurn(query: ThreadTurnQuery): Promise<ThreadTurnPage | null>;
+}
 /** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
 export interface AgentStore {
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
@@ -95,6 +137,17 @@ export interface AgentStore {
     setTitle(threadId: string, title: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    /**
+     * Attach a turn's settled tool RESULTS to a message already appended, replacing whatever it held.
+     * A message's tool calls are known when it is written and their outputs are not, but a thread
+     * reader pairs the two off THAT MESSAGE — so an output that only ever reaches the tool-call table
+     * leaves every call on a reopened thread looking like a tool still running.
+     *
+     * Required rather than optional: a store that silently declines this renders a finished turn as a
+     * permanently in-flight one, with nothing logged and nothing to notice. A missing method should
+     * fail to compile instead.
+     */
+    setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;

package/dist/src/spi/agent-store.d.ts.map

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

package/dist/src/spi/governance-queries.d.ts

@@ -95,6 +95,11 @@ export interface RunSummaryRow {
     actorLabel?: string;
     tenantRef: string | null;
     agentName: string | null;
+    /**
+     * The run that delegated this one, or `null` for a turn a person started. Without it a delegation's
+     * spend reads as an orphan turn on every surface built over these rows.
+     */
+    parentRunId: string | null;
     status: string;
     /** ISO timestamp. */
     startedAt: string;

package/dist/src/spi/governance-queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"governance-queries.d.ts","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEjE,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,yHAAyH;IACzH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAID,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;AAEvD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yGAAyG;AACzG,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,aAAa,CAAC;IACnB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,2GAA2G;IAC3G,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,oGAAoG;IACpG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,kGAAkG;IAClG,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACjC,4GAA4G;IAC5G,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,uGAAuG;AACvG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,sFAAsF;QACtF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,wFAAwF;IACxF,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/D,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC/D,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC/D,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAI3D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3D,yGAAyG;IACzG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACpD,2FAA2F;IAC3F,gBAAgB,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACjF,+FAA+F;IAC/F,YAAY,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAChE,2EAA2E;IAC3E,cAAc,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAChE;;;;OAIG;IACH,YAAY,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CACzE"}
+{"version":3,"file":"governance-queries.d.ts","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"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"}

package/dist/src/spi/history-window.d.ts

@@ -1,24 +1,78 @@
-import type { Actor, ModelMessage } from '../types.js';
+import type { Actor, MessageUsage, ModelMessage } from '../types.js';
 /** What a {@link HistoryWindow} needs to know about the run it's compacting history for. */
 export interface HistoryWindowContext {
     actor: Actor;
     threadId: string;
 }
+/** How a window split the thread: what rides into the turn, and what the ceiling left out. */
+export interface HistorySelection {
+    /** Sent to the model, oldest-first. */
+    keep: ModelMessage[];
+    /** Left out, oldest-first. Folded into a leading summary when the window implements `summarize`. */
+    drop: ModelMessage[];
+}
+/** A stand-in for the messages a window left out, plus what producing it cost. */
+export interface HistorySummary {
+    /** Prose the loop folds into the window as a leading `system` message. */
+    text: string;
+    /**
+     * What the summarizer spent, when it called a model. Recorded as a `summary` usage row, so a
+     * ceiling on context cost cannot itself become spend nothing accounts for — the quota sums the
+     * whole ledger without filtering purpose, so this also counts against the daily cap. Omit for a
+     * summarizer that calls no model (a rollup of tool names, a digest the app already stored).
+     */
+    usage?: MessageUsage;
+    /** Accounting label for the model that produced it; falls back to `AgentLoopDeps.modelId`. */
+    modelId?: string;
+}
 /**
  * Compaction seam for long-lived threads. The loop maps the ENTIRE persisted thread into
  * `ModelMessage[]` before every turn (see `runAgentLoop` in `agent-loop.ts`); with no window
  * configured that whole history rides every turn, so input tokens (cost + latency, and eventually
- * the model's context limit) grow without bound as a thread accumulates messages. A `HistoryWindow`
- * is a black box like {@link import('./retriever.js').Retriever} — the loop hands it the full
- * mapped history and uses whatever it returns, whether that's a plain truncation (this package
- * ships {@link import('../history-window.js').SlidingWindowHistory}) or a summarizing impl that
- * calls a model to fold dropped messages into a synthetic recap message.
+ * the model's context limit) grow without bound as a thread accumulates messages. This package
+ * ships {@link import('../history-window.js').SlidingWindowHistory}; anything satisfying the seam
+ * works.
  *
- * Applied inside `hooks.step` so durable replay reuses the SAME windowed result deterministically —
- * required for any impl that calls a model (its own cost must not be paid twice on resume) and
- * harmless for a pure truncator.
+ * The two halves run in deliberately different places, and that split is what lets a window exist
+ * without moving a single one of the loop's checkpoint positions — see each method.
  */
 export interface HistoryWindow {
-    apply(messages: ModelMessage[], ctx: HistoryWindowContext): ModelMessage[] | Promise<ModelMessage[]>;
+    /**
+     * The most messages {@link select} can ever keep, where the ceiling can be stated as a row count.
+     *
+     * A hint the loop hands to the store, which then reads that many of the thread's newest rows
+     * rather than its whole transcript (see {@link import('./agent-store.js').ThreadTurnReader}).
+     * Declaring it is a PROMISE about `select`: that it keeps at most this many messages, and that
+     * they are the NEWEST ones — so a window of this size is indistinguishable, to `select`, from the
+     * full transcript. A window that can keep more than this, or something older than the newest
+     * `maxMessages`, must omit it rather than select over rows the store was never asked for.
+     *
+     * Omit where the ceiling is not a row count at all. Omitting costs only the bound on the READ; the
+     * prompt is identical either way.
+     */
+    readonly maxMessages?: number;
+    /**
+     * Decide what the model sees.
+     *
+     * MUST be a pure function of `messages`. The loop calls it OUTSIDE any checkpoint, which is safe
+     * only because its input already IS one (`load:thread`'s cached result), so a replay re-runs it
+     * over the same messages and reaches the same split. Read a clock, a feature flag or a database
+     * here and the resumed run windows differently from the one that suspended: the model gets a
+     * different prompt, and any step whose existence depends on the split lands at a position the
+     * history has no room for. Anything non-deterministic belongs in {@link summarize}.
+     *
+     * The newest message must always be in `keep` — dropping it leaves the turn with nothing to answer.
+     */
+    select(messages: ModelMessage[], ctx: HistoryWindowContext): HistorySelection;
+    /**
+     * Fold the dropped messages into prose the model reads in their place, prepended to the window as
+     * a `system` message. Optional — without it, dropped messages are simply gone.
+     *
+     * Runs inside the loop's `history:summarize` checkpoint, so it may call a model or hit the
+     * network: the first attempt's result is journaled and every replay reads it back instead of
+     * re-summarizing (and instead of paying for it twice). It runs once per RUN, not per model step,
+     * and only when `select` actually dropped something.
+     */
+    summarize?(dropped: ModelMessage[], ctx: HistoryWindowContext): Promise<HistorySummary>;
 }
 //# sourceMappingURL=history-window.d.ts.map

package/dist/src/spi/history-window.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history-window.d.ts","sourceRoot":"","sources":["../../../src/spi/history-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvD,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CACH,QAAQ,EAAE,YAAY,EAAE,EACxB,GAAG,EAAE,oBAAoB,GACxB,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"history-window.d.ts","sourceRoot":"","sources":["../../../src/spi/history-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,oGAAoG;IACpG,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,oBAAoB,GAAG,gBAAgB,CAAC;IAC9E;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACzF"}