@slopus/happy-agent-base 0.0.0 → 0.0.2

package/dist/AgentSystemLocal.js

@@ -0,0 +1,282 @@
+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 { agentBaseWithStoreStill } from "./AgentBaseStoreLock.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.
+ *
+ * Identity is durable and shared, so more than one live collection can be working over one
+ * storage. Everything below therefore 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 — and treats storage, not memory, as the authority on who exists.
+ *
+ * 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;
+    /**
+     * 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;
+    /** 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();
+    /**
+     * 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. An identity another owner is still creating is left alone, since until that
+     * creation commits there is no agent to resume.
+     */
+    static async create(ctx, storage, config) {
+        const system = new AgentSystemLocal(storage, config);
+        await system.#start(ctx);
+        return system;
+    }
+    /**
+     * 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(storage, options) {
+        this.#features = options.features ?? [];
+        this.#storage = storage;
+        this.#providers = options.providers;
+        this.#provider = options.provider;
+        this.models = [...options.models];
+        this.#configs = storage.kv.scoped("config");
+        this.#sharedFeatureKV = storage.kv.scoped("features");
+    }
+    /**
+     * 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 ever 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. The
+     * alternative — writing a provisional identity and taking it back when the build fails —
+     * has to get the taking-back right in the presence of crashes and other owners, and a
+     * compensation that can itself fail is not a guarantee.
+     */
+    async create(ctx, config, initialContext) {
+        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.#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 agentBaseWithStoreStill(ctx, persistence, (storeCtx) => persistence.transaction(storeCtx, 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) {
+        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) {
+        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.`);
+            // Building an agent takes as long as its features do, and identity is not this
+            // collection's to hold still for that: another owner may have deleted the ID, or a
+            // creation this resolution overtook may have rolled it back. Handing back an agent
+            // for an identity that no longer exists strands its caller with a live object no
+            // restart would ever reproduce, so the answer is checked before it is given.
+            if ((await this.config(lockCtx, agentId)) === undefined) {
+                this.#agents.delete(agentId);
+                await agent.close();
+                throw new Error(`Agent "${agentId}" was deleted while it was being resolved.`);
+            }
+            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) {
+        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 = onlyIfActive
+            ? await Agent.loadActive(agentCtx, options)
+            : await Agent.load(agentCtx, options);
+        if (agent === undefined)
+            return undefined;
+        agent.start();
+        this.#agents.set(agentId, agent);
+        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);
+        await Promise.all(created.map(async ({ key: agentId, value }) => {
+            if (!Value.Check(agentConfigSchema, value))
+                return;
+            await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                if (this.#agents.has(agentId))
+                    return;
+                await this.#instantiate(lockCtx, agentId, value, true);
+            });
+        }));
+    }
+    /** 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) {
+        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) {
+        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 (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 (await this.resolve(ctx, agentId)).compact(ctx, options);
+    }
+}
+//# 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"}

package/dist/AgentTool.d.ts

@@ -0,0 +1,87 @@
+import type { SessionOutputBlock, SessionToolLarkGrammar } from "@slopus/happy-providers";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Context } from "@steve.kite/stdlib";
+/** A tool-owned decision about one invocation while the agent is in Auto mode. */
+export type AgentToolAutoPermissionPredicate<Args> = {
+    bivarianceHack(args: Args, ctx: Context): boolean | Promise<boolean>;
+}["bivarianceHack"];
+/** Human-readable description of the exact action an Auto reviewer is deciding on. */
+export type AgentToolAutoPermissionActionDescriber<Args> = {
+    bivarianceHack(args: Args, ctx: Context): string;
+}["bivarianceHack"];
+/**
+ * An executable tool with TypeBox-typed arguments and structured result. The descriptor fields
+ * mirror the provider session tool. The agent validates arguments against `parameters` before
+ * execute runs and the result against `returnType` after; `toLLM` renders the structured result
+ * into model-facing content. A thrown execute, an invalid result, or `isError` returning true
+ * becomes an error tool result for the model rather than failing the run.
+ */
+export interface AgentTool<Args extends TSchema = TSchema, Result extends TSchema = TSchema> {
+    /** The tool name the model calls. */
+    readonly name: string;
+    /** Optional grouping the tool is exposed under, such as an MCP server name. */
+    readonly namespace?: string;
+    /** Description of the containing namespace, when this tool is namespaced. */
+    readonly namespaceDescription?: string;
+    /**
+     * Exact native tool descriptor for a call the provider owns and settles inside its response.
+     * Absence means the agent owns execution.
+     */
+    readonly server?: {
+        readonly type: string;
+        readonly [key: string]: unknown;
+    };
+    /** Model-facing explanation of what the tool does and when to use it. */
+    readonly description?: string;
+    /** TypeBox schema the model's arguments are validated against before execute runs. */
+    readonly parameters?: Args;
+    /** TypeBox schema the structured result is validated against after execute runs. */
+    readonly returnType: Result;
+    /** Provider-neutral request to expose this tool through native tool discovery. */
+    readonly defer?: boolean;
+    /** Ignored by providers that do not support grammar-based tools. */
+    readonly grammar?: SessionToolLarkGrammar;
+    /**
+     * Provider-shaped guidance shown only in Auto mode. Use this for fields the model must set
+     * when it intentionally requests review or Full access.
+     */
+    readonly autoPermissionInstructions?: string;
+    /**
+     * Describes the exact action and boundary an Auto reviewer is deciding on. A tool whose
+     * `shouldReviewInAutoMode` can return true must provide this description.
+     */
+    readonly describeAutoPermissionAction?: AgentToolAutoPermissionActionDescriber<Static<Args>>;
+    /**
+     * The tool cannot be contained by Rig's local restricted modes, so it is available only in
+     * Auto or Full access. This does not itself approve an Auto invocation.
+     */
+    readonly requiresAutoOrFullAccess?: boolean;
+    /**
+     * Whether this exact invocation requires an Auto review. Every tool owns this decision;
+     * routine tools state that explicitly with a predicate that returns false.
+     */
+    readonly shouldReviewInAutoMode: AgentToolAutoPermissionPredicate<Static<Args>>;
+    /**
+     * Whether an approved invocation must temporarily run in Full access. Review and elevation
+     * are deliberately separate decisions; omission means the current sandbox remains active.
+     */
+    readonly shouldRunInFullAccessInAutoMode?: AgentToolAutoPermissionPredicate<Static<Args>>;
+    /**
+     * A durable tool is safe to execute again, so an interrupted call is retried when the agent
+     * restarts. A non-durable call interrupted by a restart becomes an error tool result instead.
+     */
+    readonly durable?: boolean;
+    /**
+     * The context's lifetime aborts when the turn is aborted, so a long-running tool can
+     * observe cancellation and stop its own work.
+     */
+    execute(ctx: Context, args: Static<Args>): Promise<Static<Result>>;
+    /** Renders a validated result into the content blocks the model actually sees. */
+    toLLM(result: Static<Result>): readonly SessionOutputBlock[];
+    /** Whether a structured result should be reported to the model as an error. */
+    isError?(result: Static<Result>): boolean;
+}
+export type AnyAgentTool = AgentTool<any, any>;
+/** Define a tool with TypeBox-inferred argument and result types. */
+export declare function defineAgentTool<const Args extends TSchema, const Result extends TSchema>(tool: AgentTool<Args, Result>): AgentTool<Args, Result>;
+//# sourceMappingURL=AgentTool.d.ts.map

package/dist/AgentTool.d.ts.map

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

package/dist/AgentTool.js

@@ -0,0 +1,5 @@
+/** Define a tool with TypeBox-inferred argument and result types. */
+export function defineAgentTool(tool) {
+    return tool;
+}
+//# sourceMappingURL=AgentTool.js.map

package/dist/AgentTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTool.js","sourceRoot":"","sources":["../sources/AgentTool.ts"],"names":[],"mappings":"AA0FA,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAC3B,IAA6B;IAE7B,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,25 @@
-export {};
+/** Public surface of `@slopus/happy-agent-base`, re-exported by concern. */
+export { Agent, type AgentOptions } from "./Agent.js";
+export { type AgentSystem } from "./AgentSystem.js";
+export { type AgentInitialContext } from "./AgentSystem.js";
+export { AgentSystemLocal, type AgentSystemLocalOptions } from "./AgentSystemLocal.js";
+export { AgentSystemRef } from "./AgentSystemRef.js";
+export { AgentRef } from "./AgentRef.js";
+export { agentSystem, withAgentSystem } from "./AgentSystemContext.js";
+export { agentConfig, agentConfigSchema, agentFeatureConfig, agentEnvironment, agentEnvironmentSchema, agentFeatureConfigSchema, agentPlatformSchema, currentAgentEnvironment, withAgentConfig, type AgentConfig, type AgentEnvironment, type AgentFeatureConfig, type AgentPlatform, } from "./AgentConfig.js";
+export { AgentStorage, type AgentStorageOptions } from "./AgentStorage.js";
+export { type AgentModel } from "./AgentModel.js";
+export { knownModels, type Model } from "./models.js";
+export { AgentBase, type AgentBaseAwaitOptions, type AgentBaseMessageOptions, type AgentBaseOptions, type AgentBaseQueueMode, } from "./AgentBase.js";
+export { agentEffort, agentId, agentKV, agentModel, agentProvider, agentRunKV, agentServiceTier, withAgentContext, withAgentKV, withAgentRunKV, } from "./AgentContexts.js";
+export { agentTaskContext, taskContextBeforeToolCall, withAgentTaskContext, } from "./AgentTaskContext.js";
+export { AgentKV } from "./AgentKV.js";
+export { type AgentBaseHooks, type AgentBaseInference, type AgentBaseModelChange, type AgentBaseToolExecution, type AgentBaseTurn, type AgentBaseTurnStart, type MaybePromise, } from "./AgentBaseHooks.js";
+export { type AgentPersistence, type AgentRecord } from "./AgentPersistence.js";
+export { agentBasePendingStateOf, agentBaseStoreOwesWork, AGENT_BASE_PENDING_KEY, type AgentBasePendingStage, type AgentBasePendingState, } from "./AgentBasePending.js";
+export { type AgentBaseState } from "./AgentBaseState.js";
+export { type AgentFeature, type AgentFeatureAgent, type AgentFeatureScope, } from "./AgentFeature.js";
+export { type AgentFeatureAction } from "./AgentFeatureAction.js";
+export { AgentProviders } from "./AgentProviders.js";
+export { defineAgentTool, type AgentTool, type AgentToolAutoPermissionActionDescriber, type AgentToolAutoPermissionPredicate, type AnyAgentTool, } from "./AgentTool.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../sources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../sources/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAG5E,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGvE,OAAO,EACH,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG3E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EACH,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,WAAW,EACX,OAAO,EACP,OAAO,EACP,UAAU,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,YAAY,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EACH,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EACH,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EACH,eAAe,EACf,KAAK,SAAS,EACd,KAAK,sCAAsC,EAC3C,KAAK,gCAAgC,EACrC,KAAK,YAAY,GACpB,MAAM,gBAAgB,CAAC"}