@slopus/happy-agent-base 0.0.1 → 0.0.3

package/dist/AgentSystemLocal.js

@@ -0,0 +1,401 @@
+import { createId } from "@paralleldrive/cuid2";
+import { Value } from "@sinclair/typebox/value";
+import { asyncLock } from "@steve.kite/stdlib";
+import { Agent } from "./Agent.js";
+import {} from "./AgentBase.js";
+import { agentId as agentIdOf } from "./AgentContexts.js";
+import { agentConfigSchema, withAgentConfig } from "./AgentConfig.js";
+import { withAgentSystem } from "./AgentSystemContext.js";
+import { AgentSystemRef } from "./AgentSystemRef.js";
+/**
+ * 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 class AgentSystemLocal {
+    /** The models this collection offers its agents. */
+    models;
+    /** The lifetime context retained by this system and its storage lock. */
+    #ctx;
+    /**
+     * What this collection looks like from inside one of its agents, and the only form of it a
+     * derived context ever carries.
+     */
+    #ref = new AgentSystemRef(this);
+    /** The collection's feature instances, every one of them serving every agent it builds. */
+    #features;
+    /** Where the collection's identities, configuration, and per-agent state are durable. */
+    #storage;
+    /** The registry providers are resolved from when an agent is built. */
+    #providers;
+    /** The registry ID of the provider new agents are created with. */
+    #provider;
+    /** Exclusive database-backed ownership of this collection's whole durable store. */
+    #storageLock;
+    /** The configuration each identity was created with. */
+    #configs;
+    /**
+     * The root of the store features share across the collection. Each feature works under its
+     * own scope of it, which is where anything outliving one agent's conversation belongs.
+     */
+    #sharedFeatureKV;
+    /** The live `Agent` instances this process has built, keyed by identity. */
+    #agents = new Map();
+    // One agent has one store for the life of the collection, so inspecting an agent's durable
+    // work and running that agent never end up looking at two different stores.
+    #persistences = new Map();
+    /** Per-agent locks handed out by `#lockFor`, created lazily the first time an ID is touched. */
+    #locks = new Map();
+    /** Public operations admitted before shutdown and therefore allowed to finish. */
+    #admitted = new Set();
+    /** No agent operation is admitted until every feature has finished its beforeStart hook. */
+    #lifecycle = "initializing";
+    /** The shared shutdown, including release of the hard storage lock. */
+    #closePromise;
+    /**
+     * 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 async create(ctx, storage, config) {
+        const systemCtx = ctx;
+        const storageLock = await storage.acquireLock(systemCtx);
+        const system = new AgentSystemLocal(systemCtx, storage, storageLock, config);
+        try {
+            await system.#beforeStart(systemCtx);
+            const active = await system.#start(systemCtx);
+            system.#lifecycle = "open";
+            for (const agent of active)
+                agent.start();
+            await system.#afterStart(systemCtx);
+            return system;
+        }
+        catch (error) {
+            await system.close(systemCtx).catch(() => undefined);
+            throw error;
+        }
+    }
+    /**
+     * 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.
+     */
+    constructor(ctx, storage, storageLock, options) {
+        this.#ctx = ctx;
+        this.#features = options.features ?? [];
+        this.#storage = storage;
+        this.#storageLock = storageLock;
+        this.#providers = options.providers;
+        this.#provider = options.provider;
+        this.models = [...options.models];
+        this.#configs = storage.kv.scoped("config");
+        this.#sharedFeatureKV = storage.kv.scoped("features");
+    }
+    /**
+     * 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.
+     */
+    async close(ctx) {
+        if (this.#closePromise === undefined) {
+            this.#lifecycle = "closing";
+            this.#closePromise = this.#shutdown();
+        }
+        const closing = this.#closePromise;
+        const caller = agentIdOf(ctx);
+        if (caller !== undefined && this.#agents.has(caller)) {
+            void closing.catch(() => undefined);
+            throw new Error("Closing the agent system from inside one of its own agents would wait for " +
+                "that agent's turn. Shutdown will finish and release the store after this " +
+                "caller returns.");
+        }
+        await closing;
+    }
+    /** The real shutdown barrier, which keeps the hard store lock until every agent is closed. */
+    async #shutdown() {
+        try {
+            while (this.#admitted.size > 0) {
+                await Promise.allSettled(this.#admitted);
+            }
+            const closed = [...this.#agents.values()].map((agent) => {
+                void agent.close().catch(() => undefined);
+                return agent.waitForClosed();
+            });
+            await Promise.allSettled(closed);
+            this.#agents.clear();
+            this.#persistences.clear();
+            this.#locks.clear();
+        }
+        finally {
+            try {
+                await this.#storageLock.release(this.#ctx);
+            }
+            finally {
+                this.#lifecycle = "closed";
+            }
+        }
+    }
+    /**
+     * Admit one public operation while this system still owns the store. Shutdown rejects new
+     * admissions and waits for every earlier one before releasing the hard lock.
+     */
+    #admit(operation) {
+        if (this.#lifecycle !== "open") {
+            return Promise.reject(new Error(this.#lifecycle === "initializing"
+                ? "The agent system is not ready."
+                : "The agent system is closed."));
+        }
+        let running;
+        try {
+            // Begin synchronously so ownership-transfer boundaries such as create(config) copy
+            // caller-owned input before the caller can mutate it after receiving the promise.
+            running = operation();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const settled = running.then(() => undefined, () => undefined);
+        this.#admitted.add(settled);
+        void settled.finally(() => this.#admitted.delete(settled));
+        return running;
+    }
+    /**
+     * 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.
+     */
+    async create(ctx, config, initialContext) {
+        return await this.#admit(async () => {
+            const agentId = createId();
+            if (!Value.Check(agentConfigSchema, config)) {
+                throw new Error(`The configuration for agent "${agentId}" is not valid.`);
+            }
+            // The caller keeps its own object, and may go on editing it. What was created is what
+            // was passed at this moment, so storage and this agent's context both get a copy.
+            const owned = structuredClone(config);
+            return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                await this.#configs.write(lockCtx, agentId, owned);
+                if (initialContext !== undefined) {
+                    await this.#seedInitialContext(lockCtx, agentId, initialContext.messages);
+                }
+                const agent = await this.#instantiate(lockCtx, agentId, owned);
+                if (agent === undefined)
+                    throw new Error(`Agent "${agentId}" could not be built.`);
+                return 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.
+     */
+    async delete(ctx, agentId) {
+        await this.#admit(async () => {
+            await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                const agent = this.#agents.get(agentId);
+                this.#agents.delete(agentId);
+                await agent?.close();
+                await this.#configs.delete(lockCtx, agentId);
+                this.#persistences.delete(agentId);
+            });
+        });
+    }
+    /** Install a projected conversation before the new agent is started. */
+    async #seedInitialContext(ctx, agentId, messages) {
+        if (messages.length === 0)
+            return;
+        const persistence = this.#persistenceFor(agentId);
+        await persistence.transaction(ctx, async (txCtx) => {
+            await persistence.append(txCtx, {
+                type: "compaction",
+                messages: structuredClone(messages),
+            });
+        });
+    }
+    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    async config(ctx, agentId) {
+        return await this.#admit(async () => await this.#config(ctx, agentId));
+    }
+    /** Read one stored configuration while its owning operation is already admitted. */
+    async #config(ctx, agentId) {
+        const stored = await this.#configs.read(ctx, agentId);
+        if (stored === undefined)
+            return undefined;
+        if (!Value.Check(agentConfigSchema, stored)) {
+            throw new Error(`The stored configuration of agent "${agentId}" is not valid.`);
+        }
+        return stored;
+    }
+    /**
+     * 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.
+     */
+    async resolve(ctx, agentId) {
+        return await this.#admit(async () => await this.#resolve(ctx, agentId));
+    }
+    /** Resolve one agent while its owning public operation is already admitted. */
+    async #resolve(ctx, agentId) {
+        const existing = this.#agents.get(agentId);
+        if (existing !== undefined)
+            return existing;
+        return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+            const resolved = this.#agents.get(agentId);
+            if (resolved !== undefined)
+                return resolved;
+            const config = await this.#config(lockCtx, agentId);
+            if (config === undefined) {
+                throw new Error(`Agent "${agentId}" has not been created.`);
+            }
+            const agent = await this.#instantiate(lockCtx, agentId, config);
+            if (agent === undefined)
+                throw new Error(`Agent "${agentId}" could not be built.`);
+            return agent;
+        });
+    }
+    /**
+     * Build one agent and put it to work. Called with the agent's lock held, and only for an ID
+     * that has no live instance yet.
+     */
+    async #instantiate(ctx, agentId, config, onlyIfActive = false, start = true) {
+        const agentCtx = withAgentConfig(withAgentSystem(ctx, this.#ref), config);
+        const options = {
+            id: agentId,
+            providers: this.#providers,
+            provider: this.#provider,
+            persistence: this.#persistenceFor(agentId),
+            sharedKV: this.#sharedFeatureKV,
+            // The collection's features come first, so the instructions they contribute — the
+            // system prompt above all — open every agent's prompt.
+            features: this.#features,
+        };
+        // An identity built here may already have durable state — this is the path a restart
+        // resolves through — so the agent is loaded rather than created, and knows whether it
+        // has work left before anything asks it. Bringing a collection up asks only for the
+        // agents that do; anything else resolving an agent wants it whether it owes work or not.
+        const agent = await Agent.load(agentCtx, options);
+        if (onlyIfActive && !agent.active) {
+            await agent.close();
+            return undefined;
+        }
+        this.#agents.set(agentId, agent);
+        if (start)
+            agent.start();
+        return agent;
+    }
+    /**
+     * Resolve and resume every agent that has work left from before this process started.
+     *
+     * The active index is a fast answer, not the authority. It is written by a live run and can
+     * Every identity the storage holds is asked whether it has work left, and the ones that do
+     * are built and set going. The question is one key in the agent's own store, and only the
+     * agent answers it: the collection keeps no index of its own to go stale, and an identity is
+     * never dismissed on the strength of something written about it elsewhere.
+     *
+     * Building the agent is all this does. An agent picks its own work back up when it is
+     * loaded, so the collection has only to bring the right ones into existence.
+     */
+    async #start(ctx) {
+        const created = await this.#configs.list(ctx);
+        const results = await Promise.allSettled(created.map(async ({ key: agentId, value }) => {
+            if (!Value.Check(agentConfigSchema, value))
+                return undefined;
+            return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                if (this.#agents.has(agentId))
+                    return undefined;
+                return await this.#instantiate(lockCtx, agentId, value, true, false);
+            });
+        }));
+        throwFirstStartFailure(results);
+        return results.flatMap((result) => result.status === "fulfilled" && result.value !== undefined ? [result.value] : []);
+    }
+    /** Initialize every feature before any active agent is restored or started. */
+    async #beforeStart(ctx) {
+        const startCtx = withAgentSystem(ctx, this.#ref);
+        const results = await Promise.allSettled(this.#features.map(async (feature) => await feature.beforeStart?.(startCtx, this.#ref)));
+        throwFirstStartFailure(results);
+    }
+    /** Notify every feature after all active agents have been restored and started. */
+    async #afterStart(ctx) {
+        const startCtx = withAgentSystem(ctx, this.#ref);
+        const results = await Promise.allSettled(this.#features.map(async (feature) => await feature.afterStart?.(startCtx, this.#ref)));
+        throwFirstStartFailure(results);
+    }
+    /** The durable store for one agent, created once and reused for the life of the collection. */
+    #persistenceFor(agentId) {
+        const existing = this.#persistences.get(agentId);
+        if (existing !== undefined)
+            return existing;
+        const created = this.#storage.persistence(agentId);
+        this.#persistences.set(agentId, created);
+        return created;
+    }
+    /**
+     * The lock serializing this collection's work on one identity. It is per agent because the
+     * work it guards — building an agent, which loads every feature — may itself resolve another
+     * agent from this same collection, and a collection-wide lock would deadlock on it.
+     */
+    #lockFor(agentId) {
+        const existing = this.#locks.get(agentId);
+        if (existing !== undefined)
+            return existing;
+        const created = asyncLock({ reentry: "block" });
+        this.#locks.set(agentId, created);
+        return created;
+    }
+    /** Queue a steered message for an agent. */
+    async steer(ctx, agentId, message, options) {
+        await this.#admit(async () => {
+            const agent = await this.#resolve(ctx, agentId);
+            await agent.steer(ctx, message, options);
+        });
+    }
+    /** Queue a message for an agent. */
+    async send(ctx, agentId, message, options) {
+        await this.#admit(async () => {
+            const agent = await this.#resolve(ctx, agentId);
+            await agent.send(ctx, message, options);
+        });
+    }
+    /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
+    async abort(ctx, agentId, options) {
+        await this.#admit(async () => {
+            await (await this.#resolve(ctx, agentId)).abort(ctx, options);
+        });
+    }
+    /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
+    async compact(ctx, agentId, options) {
+        await this.#admit(async () => {
+            await (await this.#resolve(ctx, agentId)).compact(ctx, options);
+        });
+    }
+}
+/** Start every feature even when one fails, then surface the first failure in feature order. */
+function throwFirstStartFailure(results) {
+    const failure = results.find((result) => result.status === "rejected");
+    if (failure !== undefined)
+        throw failure.reason;
+}
+//# sourceMappingURL=AgentSystemLocal.js.map

package/dist/AgentSystemLocal.js.map

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

package/dist/AgentSystemRef.d.ts

@@ -0,0 +1,56 @@
+import type { SessionUserMessage } from "@slopus/happy-providers";
+import type { Context } from "@steve.kite/stdlib";
+import type { AgentBaseMessageOptions } from "./AgentBase.js";
+import type { AgentConfig } from "./AgentConfig.js";
+import type { AgentModel } from "./AgentModel.js";
+import { AgentRef } from "./AgentRef.js";
+import type { AgentInitialContext, AgentSystem } from "./AgentSystem.js";
+/**
+ * A reference to a collection of agents that cannot deadlock, for code that runs inside an agent
+ * — a feature hook, or a tool the run loop is waiting on. Every operation returns without
+ * waiting for any agent's loop to reach a particular point.
+ *
+ * What is missing is missing on purpose. `delete` closes an agent and `start` resumes whole
+ * agents; both are the owning caller's business, and both would wait for a loop that may be
+ * waiting for the very code asking. Agents come back as `AgentRef` for the same reason — handing
+ * out the real `Agent` would hand back `close` and `waitForIdle` along with the `await: true`
+ * that waits for a compaction or an unwound turn.
+ *
+ * A message is the one thing a caller here may be told about, because accepting one is a durable
+ * queue write rather than a turn: `steer` and `send` resolve once the message is safely part of
+ * the target agent's conversation, and reject when that write fails, so a caller routing work to
+ * another agent knows whether it arrived. The exception is the caller's own agent, whose loop is
+ * what would have to perform that write — asked for itself, the message is queued and not waited
+ * for. That is decided from the context, which names the agent the caller is running inside; a
+ * context that names none proves nothing, so nothing is waited for there either.
+ */
+export declare class AgentSystemRef {
+    #private;
+    /** Wrap a collection as the deadlock-free reference given to code running inside it. */
+    constructor(system: AgentSystem);
+    /** The models this collection offers its agents. */
+    get models(): readonly AgentModel[];
+    /** Create an agent with a new system-generated cuid2 identity. */
+    create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<AgentRef>;
+    /** A reference to an existing agent; resolving one that was never created is an error. */
+    resolve(ctx: Context, agentId: string): Promise<AgentRef>;
+    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
+    /**
+     * Queue a steered message. For another agent this resolves once the message is durably
+     * accepted and rejects when that write fails; for the caller's own agent it resolves as soon
+     * as the agent has taken the request on.
+     */
+    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /**
+     * Queue a sent message. For another agent this resolves once the message is durably accepted
+     * and rejects when that write fails; for the caller's own agent it resolves as soon as the
+     * agent has taken the request on.
+     */
+    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /** Ask an agent to compact, and resolve once it has been asked. */
+    compact(ctx: Context, agentId: string): Promise<void>;
+    /** Cancel an agent's active turn, and resolve once the cancellation has been signalled. */
+    abort(ctx: Context, agentId: string): Promise<void>;
+}
+//# sourceMappingURL=AgentSystemRef.d.ts.map

package/dist/AgentSystemRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystemRef.d.ts","sourceRoot":"","sources":["../sources/AgentSystemRef.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,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAwB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAc;;IAIvB,wFAAwF;IACxF,YAAY,MAAM,EAAE,WAAW,EAE9B;IAED,oDAAoD;IACpD,IAAI,MAAM,IAAI,SAAS,UAAU,EAAE,CAElC;IAED,kEAAkE;IAC5D,MAAM,CACR,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,mBAAmB,GACrC,OAAO,CAAC,QAAQ,CAAC,CAEnB;IAED,0FAA0F;IACpF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE9D;IAED,6FAA6F;IACvF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAE5E;IAED;;;;OAIG;IACG,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED;;;;OAIG;IACG,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,mEAAmE;IAC7D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAED,2FAA2F;IACrF,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExD;CACJ"}

package/dist/AgentSystemRef.js

@@ -0,0 +1,75 @@
+import { acceptanceIsWaitable, AgentRef } from "./AgentRef.js";
+/**
+ * A reference to a collection of agents that cannot deadlock, for code that runs inside an agent
+ * — a feature hook, or a tool the run loop is waiting on. Every operation returns without
+ * waiting for any agent's loop to reach a particular point.
+ *
+ * What is missing is missing on purpose. `delete` closes an agent and `start` resumes whole
+ * agents; both are the owning caller's business, and both would wait for a loop that may be
+ * waiting for the very code asking. Agents come back as `AgentRef` for the same reason — handing
+ * out the real `Agent` would hand back `close` and `waitForIdle` along with the `await: true`
+ * that waits for a compaction or an unwound turn.
+ *
+ * A message is the one thing a caller here may be told about, because accepting one is a durable
+ * queue write rather than a turn: `steer` and `send` resolve once the message is safely part of
+ * the target agent's conversation, and reject when that write fails, so a caller routing work to
+ * another agent knows whether it arrived. The exception is the caller's own agent, whose loop is
+ * what would have to perform that write — asked for itself, the message is queued and not waited
+ * for. That is decided from the context, which names the agent the caller is running inside; a
+ * context that names none proves nothing, so nothing is waited for there either.
+ */
+export class AgentSystemRef {
+    /** The collection this reference forwards every operation to without waiting on its loops. */
+    #system;
+    /** Wrap a collection as the deadlock-free reference given to code running inside it. */
+    constructor(system) {
+        this.#system = system;
+    }
+    /** The models this collection offers its agents. */
+    get models() {
+        return this.#system.models;
+    }
+    /** Create an agent with a new system-generated cuid2 identity. */
+    async create(ctx, config, initialContext) {
+        return new AgentRef(await this.#system.create(ctx, config, initialContext));
+    }
+    /** A reference to an existing agent; resolving one that was never created is an error. */
+    async resolve(ctx, agentId) {
+        return new AgentRef(await this.#system.resolve(ctx, agentId));
+    }
+    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    async config(ctx, agentId) {
+        return await this.#system.config(ctx, agentId);
+    }
+    /**
+     * Queue a steered message. For another agent this resolves once the message is durably
+     * accepted and rejects when that write fails; for the caller's own agent it resolves as soon
+     * as the agent has taken the request on.
+     */
+    async steer(ctx, agentId, message, options) {
+        await this.#system.steer(ctx, agentId, message, {
+            ...options,
+            await: acceptanceIsWaitable(ctx, agentId),
+        });
+    }
+    /**
+     * Queue a sent message. For another agent this resolves once the message is durably accepted
+     * and rejects when that write fails; for the caller's own agent it resolves as soon as the
+     * agent has taken the request on.
+     */
+    async send(ctx, agentId, message, options) {
+        await this.#system.send(ctx, agentId, message, {
+            ...options,
+            await: acceptanceIsWaitable(ctx, agentId),
+        });
+    }
+    /** Ask an agent to compact, and resolve once it has been asked. */
+    async compact(ctx, agentId) {
+        await (await this.resolve(ctx, agentId)).compact(ctx);
+    }
+    /** Cancel an agent's active turn, and resolve once the cancellation has been signalled. */
+    async abort(ctx, agentId) {
+        await (await this.resolve(ctx, agentId)).abort(ctx);
+    }
+}
+//# sourceMappingURL=AgentSystemRef.js.map

package/dist/AgentSystemRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSystemRef.js","sourceRoot":"","sources":["../sources/AgentSystemRef.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,cAAc;IACvB,8FAA8F;IACrF,OAAO,CAAc;IAE9B,wFAAwF;IACxF,YAAY,MAAmB;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IAED,oDAAoD;IACpD,IAAI,MAAM;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,MAAM,CACR,GAAY,EACZ,MAAmB,EACnB,cAAoC;QAEpC,OAAO,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,OAAO,CAAC,GAAY,EAAE,OAAe;QACvC,OAAO,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,6FAA6F;IAC7F,KAAK,CAAC,MAAM,CAAC,GAAY,EAAE,OAAe;QACtC,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CACP,GAAY,EACZ,OAAe,EACf,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;YAC5C,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC;SAC5C,CAAC,CAAC;IACP,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,OAAe,EACf,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;YAC3C,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC;SAC5C,CAAC,CAAC;IACP,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,OAAO,CAAC,GAAY,EAAE,OAAe;QACvC,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;IAED,2FAA2F;IAC3F,KAAK,CAAC,KAAK,CAAC,GAAY,EAAE,OAAe;QACrC,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;CACJ"}

package/dist/AgentTaskContext.d.ts

@@ -0,0 +1,17 @@
+import type { SessionMessage } from "@slopus/happy-providers";
+import { type Context } from "@steve.kite/stdlib";
+/**
+ * Carry the parent conversation that existed before the assistant response containing the
+ * current tool call. The snapshot is immutable caller context: collaboration can fork it without
+ * gaining a general-purpose history-reading capability.
+ */
+export declare function withAgentTaskContext(ctx: Context, messages: readonly SessionMessage[]): Context;
+/** The pre-tool-call parent conversation available to the current tool execution. */
+export declare function agentTaskContext(ctx: Context): readonly SessionMessage[];
+/**
+ * Select everything before the assistant response that issued `callId`. Removing the complete
+ * response follows Codex's fork boundary and prevents sibling calls, reasoning, or prefatory
+ * assistant text from leaking into a child while that response is still being settled.
+ */
+export declare function taskContextBeforeToolCall(messages: readonly SessionMessage[], callId: string): readonly SessionMessage[];
+//# sourceMappingURL=AgentTaskContext.d.ts.map

package/dist/AgentTaskContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTaskContext.d.ts","sourceRoot":"","sources":["../sources/AgentTaskContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAQ1E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAE/F;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,cAAc,EAAE,CAExE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,MAAM,EAAE,MAAM,GACf,SAAS,cAAc,EAAE,CAO3B"}

package/dist/AgentTaskContext.js

@@ -0,0 +1,26 @@
+import { createContextNamespace } from "@steve.kite/stdlib";
+/** Backing storage for `agentTaskContext`: the parent conversation before a tool call. */
+const taskContextNamespace = createContextNamespace("happyAgent.taskContext", undefined);
+/**
+ * Carry the parent conversation that existed before the assistant response containing the
+ * current tool call. The snapshot is immutable caller context: collaboration can fork it without
+ * gaining a general-purpose history-reading capability.
+ */
+export function withAgentTaskContext(ctx, messages) {
+    return taskContextNamespace.set(ctx, structuredClone(messages));
+}
+/** The pre-tool-call parent conversation available to the current tool execution. */
+export function agentTaskContext(ctx) {
+    return structuredClone(taskContextNamespace.get(ctx) ?? []);
+}
+/**
+ * Select everything before the assistant response that issued `callId`. Removing the complete
+ * response follows Codex's fork boundary and prevents sibling calls, reasoning, or prefatory
+ * assistant text from leaking into a child while that response is still being settled.
+ */
+export function taskContextBeforeToolCall(messages, callId) {
+    const boundary = messages.findIndex((message) => message.role === "assistant" &&
+        message.content.some((block) => block.type === "tool_call" && block.callId === callId));
+    return structuredClone(boundary < 0 ? messages : messages.slice(0, boundary));
+}
+//# sourceMappingURL=AgentTaskContext.js.map

package/dist/AgentTaskContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTaskContext.js","sourceRoot":"","sources":["../sources/AgentTaskContext.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAE1E,0FAA0F;AAC1F,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,wBAAwB,EACxB,SAAS,CACZ,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,QAAmC;IAClF,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,GAAY;IACzC,OAAO,eAAe,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACrC,QAAmC,EACnC,MAAc;IAEd,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAC/B,CAAC,OAAO,EAAE,EAAE,CACR,OAAO,CAAC,IAAI,KAAK,WAAW;QAC5B,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAC7F,CAAC;IACF,OAAO,eAAe,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClF,CAAC"}