@slopus/happy-agent-base 0.0.1 → 0.0.3

package/dist/{AgentBasePersistence.d.ts → AgentPersistence.d.ts}

@@ -9,7 +9,7 @@ import type { Context } from "@steve.kite/stdlib";
  * written in the same transaction that physically deletes the superseded records, so it opens
  * the store; the records after it append as usual.
  */
-export type AgentBaseRecord = {
+export type AgentRecord = {
     readonly type: "user";
     readonly message: SessionUserMessage;
 } | {
@@ -29,11 +29,12 @@ export type AgentBaseRecord = {
  * Storage for one agent: an append-only main context store plus a sorted key-value store held
  * alongside it. A sent message is first written under a `pending.` key ordered by append time;
  * it reaches the main store only when a turn consumes it into the context, and its pending key
- * is deleted at that moment. The agent serializes all calls through one lock, so an
- * implementation never sees two operations in flight at the same time and needs no internal
- * locking.
+ * is deleted at that moment. Exactly one owner connects to a store, and the agent serializes its
+ * own record and bookkeeping writes through one lock, so history order always matches storage
+ * order. Key-value operations — a feature's or a tool's — run as they come, so each one has to be
+ * atomic on its own, but no implementation ever has to defend against a second owner.
  */
-export interface AgentBasePersistence {
+export interface AgentPersistence {
     /**
      * Run work atomically. The implementation opens a transaction and passes work a derived
      * context that its own operations recognize; how the transaction rides on that context is
@@ -41,8 +42,10 @@ export interface AgentBasePersistence {
      * error rolls them all back.
      */
     transaction<Result>(ctx: Context, work: (ctx: Context) => Promise<Result>): Promise<Result>;
-    load(ctx: Context): Promise<readonly AgentBaseRecord[]>;
-    append(ctx: Context, record: AgentBaseRecord): Promise<void>;
+    /** Every record in the main context store, in append order. */
+    load(ctx: Context): Promise<readonly AgentRecord[]>;
+    /** Add one more record to the end of the main context store. */
+    append(ctx: Context, record: AgentRecord): Promise<void>;
     /**
      * Physically delete every record in the main context store. Called only inside the
      * compaction transaction, immediately before the replacement compaction record is appended,
@@ -54,7 +57,9 @@ export interface AgentBasePersistence {
         readonly key: string;
         readonly value: unknown;
     }[]>;
+    /** Store the value under `key`, replacing whatever was there before. */
     writeValue(ctx: Context, key: string, value: unknown): Promise<void>;
+    /** Remove the entry stored under `key`, if any. */
     deleteValue(ctx: Context, key: string): Promise<void>;
 }
-//# sourceMappingURL=AgentBasePersistence.d.ts.map
+//# sourceMappingURL=AgentPersistence.d.ts.map

package/dist/AgentPersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentPersistence.d.ts","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnE;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD,CAAC;AAER;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACpD,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,UAAU,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IACzE,wEAAwE;IACxE,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,mDAAmD;IACnD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD"}

package/dist/AgentPersistence.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentPersistence.js.map

package/dist/AgentPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentPersistence.js","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":""}

package/dist/AgentProviders.d.ts

@@ -1,17 +1,32 @@
 import type { BaseProvider, ProviderModelCompatibilityType } from "@slopus/happy-providers";
+/** The serializable provider/model selection a provider source resolves. */
+export interface AgentProviderSelection {
+    /** The caller-defined registration ID of the provider. */
+    readonly id: string;
+    /** The model whose provider instance is needed, if the agent selected one. */
+    readonly model: string | undefined;
+}
+/**
+ * Either one provider suitable for every selected model or a lazy model-aware provider factory.
+ * Providers own no session lifetime; each AgentBase owns and destroys the sessions it opens.
+ */
+export type AgentProviderSource = BaseProvider | ((selection: AgentProviderSelection) => BaseProvider | Promise<BaseProvider>);
 /**
- * Mutable registry of happy-providers instances keyed by a caller-supplied provider ID, so the
- * same provider class can be registered under several IDs (for example per credential). Each
- * entry carries its compatibility type, which decides how far a model change can go before the
- * conversation must reset. Providers can be added and removed while the process runs; lookups
- * return the live reference or null when absent.
+ * Mutable registry of model-aware provider sources keyed by caller-supplied IDs. Each entry carries
+ * its compatibility type, which decides how far a model change can go before the conversation
+ * must reset.
  */
 export declare class AgentProviders {
     #private;
-    add(id: string, provider: BaseProvider, type: ProviderModelCompatibilityType): void;
+    /** Register a provider source under `id`. Throws if that ID is already registered. */
+    add(id: string, source: AgentProviderSource, type: ProviderModelCompatibilityType): void;
+    /** Unregister the provider at `id`. Returns whether one was actually removed. */
     remove(id: string): boolean;
-    get(id: string): BaseProvider | null;
+    /** Resolve the provider suitable for `model`, or null when `id` is not registered. */
+    resolve(id: string, model: string | undefined): Promise<BaseProvider | null>;
+    /** The compatibility type the provider at `id` was registered with, or null when absent. */
     typeOf(id: string): ProviderModelCompatibilityType | null;
+    /** Every currently registered provider ID. */
     get ids(): readonly string[];
 }
 //# sourceMappingURL=AgentProviders.d.ts.map

package/dist/AgentProviders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProviders.d.ts","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAE5F;;;;;;GAMG;AACH,qBAAa,cAAc;;IAMvB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,8BAA8B,GAAG,IAAI,CAKlF;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1B;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAEnC;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,8BAA8B,GAAG,IAAI,CAExD;IAED,IAAI,GAAG,IAAI,SAAS,MAAM,EAAE,CAE3B;CACJ"}
+{"version":3,"file":"AgentProviders.d.ts","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAE5F,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GACzB,YAAY,GACZ,CAAC,CAAC,SAAS,EAAE,sBAAsB,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,qBAAa,cAAc;;IAOvB,sFAAsF;IACtF,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,8BAA8B,GAAG,IAAI,CAKvF;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1B;IAED,sFAAsF;IAChF,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAMjF;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,8BAA8B,GAAG,IAAI,CAExD;IAED,8CAA8C;IAC9C,IAAI,GAAG,IAAI,SAAS,MAAM,EAAE,CAE3B;CACJ"}

package/dist/AgentProviders.js

@@ -1,27 +1,36 @@
 /**
- * Mutable registry of happy-providers instances keyed by a caller-supplied provider ID, so the
- * same provider class can be registered under several IDs (for example per credential). Each
- * entry carries its compatibility type, which decides how far a model change can go before the
- * conversation must reset. Providers can be added and removed while the process runs; lookups
- * return the live reference or null when absent.
+ * Mutable registry of model-aware provider sources keyed by caller-supplied IDs. Each entry carries
+ * its compatibility type, which decides how far a model change can go before the conversation
+ * must reset.
  */
 export class AgentProviders {
+    /** Registered provider sources keyed by their caller-supplied ID and compatibility type. */
     #providers = new Map();
-    add(id, provider, type) {
+    /** Register a provider source under `id`. Throws if that ID is already registered. */
+    add(id, source, type) {
         if (this.#providers.has(id)) {
             throw new Error(`Provider "${id}" is already registered.`);
         }
-        this.#providers.set(id, { provider, type });
+        this.#providers.set(id, { source, type });
     }
+    /** Unregister the provider at `id`. Returns whether one was actually removed. */
     remove(id) {
         return this.#providers.delete(id);
     }
-    get(id) {
-        return this.#providers.get(id)?.provider ?? null;
+    /** Resolve the provider suitable for `model`, or null when `id` is not registered. */
+    async resolve(id, model) {
+        const entry = this.#providers.get(id);
+        if (entry === undefined)
+            return null;
+        return typeof entry.source === "function"
+            ? await entry.source({ id, model })
+            : entry.source;
     }
+    /** The compatibility type the provider at `id` was registered with, or null when absent. */
     typeOf(id) {
         return this.#providers.get(id)?.type ?? null;
     }
+    /** Every currently registered provider ID. */
     get ids() {
         return [...this.#providers.keys()];
     }

package/dist/AgentProviders.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProviders.js","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACd,UAAU,GAAG,IAAI,GAAG,EAG1B,CAAC;IAEJ,GAAG,CAAC,EAAU,EAAE,QAAsB,EAAE,IAAoC;QACxE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,EAAU;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IACrD,CAAC;IAED,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,IAAI,GAAG;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ"}
+{"version":3,"file":"AgentProviders.js","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACvB,4FAA4F;IACnF,UAAU,GAAG,IAAI,GAAG,EAG1B,CAAC;IAEJ,sFAAsF;IACtF,GAAG,CAAC,EAAU,EAAE,MAA2B,EAAE,IAAoC;QAC7E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAyB;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU;YACrC,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;YACnC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ"}

package/dist/AgentRef.d.ts

@@ -0,0 +1,41 @@
+import type { SessionUserMessage } from "@slopus/happy-providers";
+import type { Context } from "@steve.kite/stdlib";
+import type { Agent } from "./Agent.js";
+import type { AgentBaseMessageOptions } from "./AgentBase.js";
+/**
+ * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
+ * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
+ * except inside that agent's loop, which is holding the lock the write needs. The proof is the
+ * caller's context naming a different agent; a context naming none proves nothing.
+ */
+export declare function acceptanceIsWaitable(ctx: Context, target: string): boolean;
+/**
+ * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
+ * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
+ * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
+ * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
+ * this caller must not make.
+ *
+ * Messages are different, because accepting one is a durable queue write rather than a turn.
+ * Addressed to another agent, `steer` and `send` resolve once the message really is part of that
+ * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
+ * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
+ * to perform that write — the message is queued and not waited for. The context decides, since it
+ * names the agent the caller is in; a context that names none proves nothing and waits for
+ * nothing.
+ */
+export declare class AgentRef {
+    #private;
+    constructor(agent: Agent);
+    /** The wrapped agent's ID. */
+    get id(): string;
+    /** Queue a message that injects as soon as the current response and its tool batch finish. */
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /** Queue a message that injects when the agent would otherwise stop. */
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /** Ask the agent to compact, which it does between turns. */
+    compact(ctx: Context): Promise<void>;
+    /** Cancel the agent's active turn. */
+    abort(ctx: Context): Promise<void>;
+}
+//# sourceMappingURL=AgentRef.d.ts.map

package/dist/AgentRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRef.d.ts","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;;IAIjB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,8BAA8B;IAC9B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,8FAA8F;IACxF,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,wEAAwE;IAClE,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,6DAA6D;IACvD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,sCAAsC;IAChC,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;CACJ"}

package/dist/AgentRef.js

@@ -0,0 +1,60 @@
+import { agentId } from "./AgentContexts.js";
+/**
+ * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
+ * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
+ * except inside that agent's loop, which is holding the lock the write needs. The proof is the
+ * caller's context naming a different agent; a context naming none proves nothing.
+ */
+export function acceptanceIsWaitable(ctx, target) {
+    const caller = agentId(ctx);
+    return caller !== undefined && caller !== target;
+}
+/**
+ * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
+ * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
+ * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
+ * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
+ * this caller must not make.
+ *
+ * Messages are different, because accepting one is a durable queue write rather than a turn.
+ * Addressed to another agent, `steer` and `send` resolve once the message really is part of that
+ * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
+ * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
+ * to perform that write — the message is queued and not waited for. The context decides, since it
+ * names the agent the caller is in; a context that names none proves nothing and waits for
+ * nothing.
+ */
+export class AgentRef {
+    /** The agent this reference wraps. */
+    #agent;
+    constructor(agent) {
+        this.#agent = agent;
+    }
+    /** The wrapped agent's ID. */
+    get id() {
+        return this.#agent.id;
+    }
+    /** Queue a message that injects as soon as the current response and its tool batch finish. */
+    async steer(ctx, message, options) {
+        await this.#agent.steer(ctx, message, {
+            ...options,
+            await: acceptanceIsWaitable(ctx, this.#agent.id),
+        });
+    }
+    /** Queue a message that injects when the agent would otherwise stop. */
+    async send(ctx, message, options) {
+        await this.#agent.send(ctx, message, {
+            ...options,
+            await: acceptanceIsWaitable(ctx, this.#agent.id),
+        });
+    }
+    /** Ask the agent to compact, which it does between turns. */
+    async compact(ctx) {
+        await this.#agent.compact(ctx, { await: false });
+    }
+    /** Cancel the agent's active turn. */
+    async abort(ctx) {
+        await this.#agent.abort(ctx, { await: false });
+    }
+}
+//# sourceMappingURL=AgentRef.js.map

package/dist/AgentRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRef.js","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,MAAc;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IACjB,sCAAsC;IAC7B,MAAM,CAAQ;IAEvB,YAAY,KAAY;QACpB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,8BAA8B;IAC9B,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1B,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,KAAK,CACP,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;YAClC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;YACjC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,OAAO,CAAC,GAAY;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,KAAK,CAAC,GAAY;QACpB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;CACJ"}

package/dist/AgentStorage.d.ts

@@ -0,0 +1,39 @@
+import type { Context } from "@steve.kite/stdlib";
+import type { AgentKV } from "./AgentKV.js";
+import type { AgentPersistence } from "./AgentPersistence.js";
+/**
+ * The exclusive ownership of one durable agent store. The storage adapter must back this with
+ * the database's hard process-level lock rather than an in-memory convention.
+ */
+export interface AgentStorageLock {
+    /** Release the hard lock after the owning AgentSystem has stopped every agent. */
+    release(ctx: Context): Promise<void>;
+}
+/** What an `AgentStorage` is built from. */
+export interface AgentStorageOptions {
+    /**
+     * Acquire exclusive ownership of the whole store. This must fail while any other process or
+     * AgentSystem owns the same durable store.
+     */
+    readonly acquireLock: (ctx: Context) => Promise<AgentStorageLock>;
+    /** Shared key-value storage used for state spanning all agents. */
+    readonly kv: AgentKV;
+    /** Produce the isolated persistence used by one agent. */
+    readonly persistence: (agentId: string) => AgentPersistence;
+}
+/** Storage roots shared by an `AgentSystemLocal` collection. */
+export declare class AgentStorage {
+    #private;
+    /** Shared key-value storage used for state spanning all agents. */
+    readonly kv: AgentKV;
+    constructor(options: AgentStorageOptions);
+    /**
+     * Acquire exclusive ownership until the returned lock is released. The adapter's lock
+     * enforces this across processes; the local guard also rejects accidental reuse of this
+     * object.
+     */
+    acquireLock(ctx: Context): Promise<AgentStorageLock>;
+    /** The isolated persistence for the given agent. */
+    persistence(agentId: string): AgentPersistence;
+}
+//# sourceMappingURL=AgentStorage.d.ts.map

package/dist/AgentStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentStorage.d.ts","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kFAAkF;IAClF,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClE,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC/D;AAED,gEAAgE;AAChE,qBAAa,YAAY;;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAQrB,YAAY,OAAO,EAAE,mBAAmB,EAIvC;IAED;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmBzD;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAE7C;CACJ"}

package/dist/AgentStorage.js

@@ -0,0 +1,49 @@
+/** Storage roots shared by an `AgentSystemLocal` collection. */
+export class AgentStorage {
+    /** Shared key-value storage used for state spanning all agents. */
+    kv;
+    /** Acquires the database-backed exclusive lock for this store. */
+    #acquireLock;
+    /** Produces the isolated persistence used by one agent. */
+    #persistence;
+    /** Prevents two systems from sharing even one AgentStorage instance. */
+    #owned = false;
+    constructor(options) {
+        this.kv = options.kv;
+        this.#acquireLock = options.acquireLock;
+        this.#persistence = options.persistence;
+    }
+    /**
+     * Acquire exclusive ownership until the returned lock is released. The adapter's lock
+     * enforces this across processes; the local guard also rejects accidental reuse of this
+     * object.
+     */
+    async acquireLock(ctx) {
+        if (this.#owned)
+            throw new Error("The agent store is already owned by another system.");
+        this.#owned = true;
+        let lock;
+        try {
+            lock = await this.#acquireLock(ctx);
+        }
+        catch (error) {
+            this.#owned = false;
+            throw error;
+        }
+        let released = false;
+        return {
+            release: async (releaseCtx) => {
+                if (released)
+                    return;
+                await lock.release(releaseCtx);
+                released = true;
+                this.#owned = false;
+            },
+        };
+    }
+    /** The isolated persistence for the given agent. */
+    persistence(agentId) {
+        return this.#persistence(agentId);
+    }
+}
+//# sourceMappingURL=AgentStorage.js.map

package/dist/AgentStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentStorage.js","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AA2BA,gEAAgE;AAChE,MAAM,OAAO,YAAY;IACrB,mEAAmE;IAC1D,EAAE,CAAU;IACrB,kEAAkE;IACzD,YAAY,CAA8C;IACnE,2DAA2D;IAClD,YAAY,CAAwC;IAC7D,wEAAwE;IACxE,MAAM,GAAG,KAAK,CAAC;IAEf,YAAY,OAA4B;QACpC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,GAAY;QAC1B,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACxF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,IAAsB,CAAC;QAC3B,IAAI,CAAC;YACD,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACpB,MAAM,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO;YACH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE;gBAC1B,IAAI,QAAQ;oBAAE,OAAO;gBACrB,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC/B,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACxB,CAAC;SACJ,CAAC;IACN,CAAC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAe;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACJ"}

package/dist/AgentSystem.d.ts

@@ -0,0 +1,52 @@
+import type { SessionMessage, SessionUserMessage } from "@slopus/happy-providers";
+import type { Context } from "@steve.kite/stdlib";
+import type { Agent } from "./Agent.js";
+import type { AgentBaseAwaitOptions, AgentBaseMessageOptions } from "./AgentBase.js";
+import type { AgentConfig } from "./AgentConfig.js";
+import type { AgentModel } from "./AgentModel.js";
+/** Conversation state installed atomically before a newly created agent starts. */
+export interface AgentInitialContext {
+    /** The conversation installed as the agent's history before its first turn runs. */
+    readonly messages: readonly SessionMessage[];
+}
+/**
+ * A collection of agents addressed by ID: what an owner can ask of the agents it runs. An agent
+ * exists only once it has been created with its configuration, which is persisted and stays in
+ * effect for the agent's whole life; resolving one that was never created is an error.
+ *
+ * This is the full surface, including the operations that wait for an agent's run loop to reach a
+ * particular point — `delete`, and anything reached through the returned `Agent`. Those are for
+ * the caller that owns the agents' lifetime. Code running *inside* an agent, such as a feature
+ * hook or a tool, is waited for by that loop and must not wait for it in turn: it should hold an
+ * `AgentSystemRef`, whose every operation returns without waiting for a loop.
+ */
+export interface AgentSystem {
+    /** The models this collection offers its agents. */
+    readonly models: readonly AgentModel[];
+    /** Stop every agent and release this system's exclusive ownership of its durable store. */
+    close(ctx: Context): Promise<void>;
+    /**
+     * Create an agent with a new system-generated cuid2 identity and the configuration it keeps
+     * for its whole life. The configuration and optional initial context are persisted before
+     * the agent runs; a creation that fails to produce an agent leaves no identity behind.
+     */
+    create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
+    /** Close an agent and release its identity, so the same ID can be created again. */
+    delete(ctx: Context, agentId: string): Promise<void>;
+    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
+    /** The live agent for an ID, loading it if this process has not seen it yet. */
+    resolve(ctx: Context, agentId: string): Promise<Agent>;
+    /**
+     * Queue a user message for an agent, injected as soon as its current response and tool batch
+     * finish.
+     */
+    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    /** Queue a user message for an agent that injects only when the agent would otherwise stop. */
+    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
+    abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
+    /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
+    compact(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
+}
+//# sourceMappingURL=AgentSystem.d.ts.map

package/dist/AgentSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystem.d.ts","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAEvC,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhG,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,6FAA6F;IAC7F,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAExE,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEvD;;;OAGG;IACH,KAAK,CACD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,+FAA+F;IAC/F,IAAI,CACA,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF,wFAAwF;IACxF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F"}

package/dist/AgentSystem.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentSystem.js.map

package/dist/AgentSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystem.js","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":""}

package/dist/AgentSystemContext.d.ts

@@ -0,0 +1,15 @@
+import { type Context } from "@steve.kite/stdlib";
+import type { AgentSystemRef } from "./AgentSystemRef.js";
+/**
+ * Carry the collection that owns an agent and its features, as a reference.
+ *
+ * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
+ * is code some run loop is waiting for, while the owner's surface holds the operations that wait
+ * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
+ * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
+ * through a context can wait for the loop that is waiting for it.
+ */
+export declare function withAgentSystem(ctx: Context, value: AgentSystemRef): Context;
+/** The collection owning the current feature or agent operation. */
+export declare function agentSystem(ctx: Context): AgentSystemRef | undefined;
+//# sourceMappingURL=AgentSystemContext.d.ts.map

package/dist/AgentSystemContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystemContext.d.ts","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5E;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAEpE"}

package/dist/AgentSystemContext.js

@@ -0,0 +1,20 @@
+import { createContextNamespace } from "@steve.kite/stdlib";
+/** The context slot that carries the collection owning the current agent or feature operation. */
+const agentSystemNamespace = createContextNamespace("happyAgent.agentSystem", undefined);
+/**
+ * Carry the collection that owns an agent and its features, as a reference.
+ *
+ * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
+ * is code some run loop is waiting for, while the owner's surface holds the operations that wait
+ * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
+ * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
+ * through a context can wait for the loop that is waiting for it.
+ */
+export function withAgentSystem(ctx, value) {
+    return agentSystemNamespace.set(ctx, value);
+}
+/** The collection owning the current feature or agent operation. */
+export function agentSystem(ctx) {
+    return agentSystemNamespace.get(ctx);
+}
+//# sourceMappingURL=AgentSystemContext.js.map

package/dist/AgentSystemContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystemContext.js","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,kGAAkG;AAClG,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,wBAAwB,EACxB,SAAS,CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,KAAqB;IAC/D,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/AgentSystemLocal.d.ts

@@ -0,0 +1,104 @@
+import type { SessionUserMessage } from "@slopus/happy-providers";
+import { type Context } from "@steve.kite/stdlib";
+import { Agent } from "./Agent.js";
+import { type AgentBaseAwaitOptions, type AgentBaseMessageOptions } from "./AgentBase.js";
+import { type AgentConfig } from "./AgentConfig.js";
+import type { AgentFeature } from "./AgentFeature.js";
+import type { AgentModel } from "./AgentModel.js";
+import type { AgentProviders } from "./AgentProviders.js";
+import type { AgentStorage } from "./AgentStorage.js";
+import type { AgentInitialContext, AgentSystem } from "./AgentSystem.js";
+/** Everything `AgentSystemLocal` needs to build and run the agents in its collection. */
+export interface AgentSystemLocalOptions {
+    /**
+     * The features every agent in this collection runs with, given as instances the caller has
+     * already built and ready to serve. One instance serves the whole collection: a hook is told
+     * which agent it is running for by the scope it is handed, so any per-agent state a feature
+     * keeps in memory has to be keyed by that ID rather than held as a single value.
+     */
+    readonly features?: readonly AgentFeature[];
+    /** The registry providers are resolved from when an agent is built. */
+    readonly providers: AgentProviders;
+    /** The registry ID of the provider new agents are created with. */
+    readonly provider: string;
+    /** The models this collection offers its agents. */
+    readonly models: readonly AgentModel[];
+}
+/**
+ * The `AgentSystem` backed by this process: it lazily builds and owns the `Agent` instances for
+ * the identities its storage holds. Concurrent resolutions of the same ID share one load, while a
+ * failed load is forgotten so a later resolution can retry.
+ *
+ * Work serializes per agent rather than per collection: a collection-wide lock would make one
+ * agent's feature load block every other agent, including one that load itself resolves.
+ *
+ * This is the owner's handle, and some of what it offers waits for an agent to reach a point only
+ * that agent's run loop can bring it to. Hand an `AgentSystemRef` to anything running inside an
+ * agent instead.
+ */
+export declare class AgentSystemLocal implements AgentSystem {
+    #private;
+    /** The models this collection offers its agents. */
+    readonly models: readonly AgentModel[];
+    /**
+     * Bring up a collection over one storage and carry on where the last process left off.
+     *
+     * A collection is not a passive registry that happens to be asked for agents later: whatever
+     * was running when the previous process ended is still owed an answer, and this is what
+     * makes it happen. Every identity the storage holds is examined, and each one that owes work
+     * is resolved and resumed, so by the time this returns the collection is not merely built
+     * but running.
+     */
+    static create(ctx: Context, storage: AgentStorage, config: AgentSystemLocalOptions): Promise<AgentSystemLocal>;
+    /**
+     * Wire this collection to its storage, providers, and feature configuration, without reading
+     * any of it. Private: a collection is brought up by `create`, which also resumes the work
+     * the storage was left holding — building one without that is building half of it.
+     */
+    private constructor();
+    /**
+     * Stop every live agent, wait for operations already admitted by this owner, and only then
+     * release the database lock. Repeated callers join the same shutdown.
+     */
+    close(ctx: Context): Promise<void>;
+    /**
+     * Create an agent with the configuration it keeps for its whole life, and resolve it. The
+     * identity is allocated here and nowhere else: it is a cuid2, globally unique, so a new
+     * agent never lands on an identity that already exists or on a store something else wrote.
+     * The configuration is persisted before the agent runs, so every later process resolves the
+     * agent exactly as it was created.
+     *
+     * Nothing here is undone: an agent whose features refuse to load leaves an identity that
+     * exists, is resolvable, and will be built the next time something wants it. Taking a
+     * provisional identity back after a failed build would add a compensation that can itself
+     * fail.
+     */
+    create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
+    /**
+     * Close an agent and release its identity, so the same ID can be created again. Used to undo
+     * a creation whose follow-up work failed; an ID that was never created is left alone.
+     *
+     * What the agent wrote is left where it is. The close finishes first, so the store holds a
+     * whole conversation rather than a truncated one, and that record is worth more here than the
+     * space it takes: whoever deleted the agent may still want to know what it did. The next
+     * identity created under this ID starts from an empty store all the same, because creation is
+     * what clears it.
+     */
+    delete(ctx: Context, agentId: string): Promise<void>;
+    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
+    /**
+     * The live agent for an ID, loading and starting it if this process has not seen it yet.
+     * Concurrent resolutions of the same ID share one load.
+     */
+    resolve(ctx: Context, agentId: string): Promise<Agent>;
+    /** Queue a steered message for an agent. */
+    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    /** Queue a message for an agent. */
+    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
+    abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
+    /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
+    compact(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
+}
+//# sourceMappingURL=AgentSystemLocal.d.ts.map

package/dist/AgentSystemLocal.d.ts.map

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