@slopus/happy-agent-base 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rig Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,251 @@
 # @slopus/happy-agent-base
 
-Shared foundations for Happy coding agents.
+The minimal core of a Happy coding agent.
 
-The package is bootstrapped with an empty public API. Future agent-base behavior belongs in
-`sources` and is exported through `sources/index.ts`.
+`AgentBase` is one agent session over one `@slopus/happy-providers` provider. Messages arrive
+through two FIFO queues — steering and send — the loop replays the full conversation to the
+provider session, and the streamed events are forwarded to the optional hooks while the
+assistant reply joins the history. When the model stops for tool calls, the agent executes them
+and feeds the results back. The conversation is observable only through hooks; there is no
+external transcript or status surface.
 
-```text
-sources/index.ts
-       |
-       v
-  dist/index.js
+## Core API
+
+```ts
+class AgentBase {
+    constructor(ctx: Context, options: AgentBaseOptions);
+
+    readonly id: string;
+    readonly state: AgentBaseState; // the agent's own copy, mutable directly
+
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    start(): void;
+    abort(): Promise<void>;
+    compact(ctx: Context): Promise<void>;
+    waitForIdle(): Promise<void>;
+    close(): Promise<void>;
+}
+
+interface AgentBaseOptions {
+    id: string;
+    providers: AgentProviders;
+    provider: string; // registry ID; serializable alongside model and effort
+    persistence: AgentBasePersistence;
+    hooks?: AgentBaseHooks;
+    initialState?: Partial<AgentBaseState>; // copied into the agent's own state
+    model?: string;
+    effort?: SessionReasoningEffort;
+    serviceTier?: SessionServiceTier;
+    steeringMode?: "one-at-a-time" | "all"; // default "one-at-a-time"
+    sendMode?: "one-at-a-time" | "all"; // default "one-at-a-time"
+}
+
+interface AgentBaseState {
+    instructions: string;
+    tools: AnyAgentTool[];
+}
+
+interface AgentBaseHooks {
+    onEvent?: (ctx: Context, event: SessionEvent) => void;
+    instructions?: (ctx: Context) => string;
+    tools?: (ctx: Context) => readonly AnyAgentTool[];
+    modelChanged?: (ctx: Context, change: AgentBaseModelChange) => SessionSystemMessage | undefined;
+    beforeAgentLoop?: (ctx: Context) => void;
+    beforeTurn?: (ctx: Context) => void;
+    beforeInference?: (ctx: Context) => void;
+    afterInference?: (ctx: Context) => void;
+    afterTurn?: (ctx: Context) => readonly AgentFeatureAction[] | undefined;
+    afterAgentLoop?: (ctx: Context) => readonly AgentFeatureAction[] | undefined;
+}
+
+interface AgentBaseModelChange {
+    previousModel: string | undefined;
+    model: string;
+    previousProvider: string;
+    provider: string;
+    providers: AgentProviders;
+    previousProviderInstance: BaseProvider | null;
+    providerInstance: BaseProvider | null;
+    wasReset: boolean; // the change was incompatible and the history was erased
+}
+
+interface AgentBaseMessageOptions {
+    provider?: string; // registry ID to switch to
+    model?: string;
+    effort?: SessionReasoningEffort;
+    serviceTier?: SessionServiceTier;
+}
+
+type AgentFeatureAction =
+    | { type: "steer"; message: SessionUserMessage }
+    | { type: "send"; message: SessionUserMessage }
+    | { type: "compact" };
+
+interface AgentTool<Args extends TSchema = TSchema, Result extends TSchema = TSchema> {
+    // The provider-facing descriptor fields of SessionTool, with parameters typed as Args, plus:
+    durable?: boolean;
+    returnType: Result;
+    execute(ctx: Context, args: Static<Args>): Promise<Static<Result>>;
+    toLLM(result: Static<Result>): readonly SessionOutputBlock[];
+    isError?(result: Static<Result>): boolean;
+}
+
+function defineAgentTool<const Args extends TSchema, const Result extends TSchema>(
+    tool: AgentTool<Args, Result>,
+): AgentTool<Args, Result>;
+
+interface AgentBasePersistence {
+    transaction<Result>(ctx: Context, work: (ctx: Context) => Promise<Result>): Promise<Result>;
+    load(ctx: Context): Promise<readonly AgentBaseRecord[]>;
+    append(ctx: Context, record: AgentBaseRecord): Promise<void>;
+    clearRecords(ctx: Context): Promise<void>; // physical delete, used inside the compaction transaction
+    readValues(ctx: Context, prefix: string): Promise<readonly { key: string; value: unknown }[]>;
+    writeValue(ctx: Context, key: string, value: unknown): Promise<void>;
+    deleteValue(ctx: Context, key: string): Promise<void>;
+}
 ```
 
-## Releasing
+Persistence is an append-only main context store plus a sorted key-value store alongside it. The
+agent serializes every operation through one internal lock (configured to crash on re-entry), so
+implementations never see concurrent calls and need no locking of their own.
+
+A queued message is written under a `steering.` or `send.` key ordered by append time;
+nothing that is not yet part of the context reaches the main store. When a queue drains, each
+consumed message is appended as a user record and its queue key deleted, all inside one
+`transaction` so a crash or failure can never leave a message in both stores or neither, and
+only then does inference run on the resulting context. Transactions are completely transparent
+to the agent: the implementation opens one, hands work a derived context its own operations
+recognize, and carries the transaction on that context however it likes; work resolving
+commits, a thrown error rolls back. Assistant output is appended one finished block at a time as
+it streams, so main-store records always arrive in context order and consecutive block records
+reassemble into one assistant message on load. The agent loop loads everything once, on the first
+inference attempt; the load result replaces the in-memory state, including leftover queued
+messages from an earlier process, which join the next turn. A failed load is reported as an
+`internal_error` done event and is not sticky: the next requested turn retries it, with every
+queued message still safely waiting.
+
+The two queues give four delivery strategies, mirroring Pi:
 
-From a clean `main` worktree whose `HEAD` matches `origin/main`, run:
+| Strategy | Behavior |
+|---|---|
+| Steering + one-at-a-time | `steer` queues FIFO. After the current assistant response and all its tool calls finish, the oldest message injects, gets a response, then the next is handled. |
+| Steering + all | After the current response and tool batch finish, every queued steering message injects together before one response. |
+| Send + one-at-a-time | `send` waits until the agent would otherwise stop — no tool calls or steering remain — then injects one message and waits for its response before draining another. |
+| Send + all | Once the agent would otherwise stop, every queued sent message injects together before one response. |
+
+Both modes default to `"one-at-a-time"`, and steering always takes precedence over sent messages.
+Queue consumption happens only between inferences — never mid-stream and never during a tool
+batch — so an injected message can never interleave with an active response's block records.
+
+`steer` and `send` resolve once the durable queue write lands, so a failed write keeps the
+message out of the conversation; they wait neither for the history load nor for the turn. Each
+message may carry its own inference settings — provider, model, effort, and service tier —
+which take effect when the message is consumed and stay effective for every later message that does not
+override them, surviving restarts through a durable settings entry. A message without settings
+uses the previously effective values, or the constructor defaults when nothing was ever carried;
+relying on those defaults is discouraged — prefer sending settings with the message.
+
+A provider or model change is checked against the provider-model compatibility matrix from
+`@slopus/happy-providers`, using the compatibility types the providers were registered with. A
+compatible change keeps the conversation; a compatible provider change still gets a fresh
+session on the new provider, since a session is bound to the provider that created it. An
+incompatible change — including a switch to a different provider of the same type, or to an
+unregistered ID — resets the conversation: the durable history is erased completely, the old
+provider session is destroyed, and a fresh session serves the new selection. The `modelChanged`
+hook fires on every selection change with the old and new model, both provider IDs and live
+instances, the registry, and the `wasReset` flag; on a reset the handoff system message it
+returns is injected at the very beginning of the fresh context — without one the context starts
+completely empty. The consumed message that carried the new selection follows the handoff. A
+thrown provider or load failure is reported to the `onEvent` hook as an `internal_error` done
+event instead of rejecting the loop. The agent never retries inference itself — providers own
+retry semantics and surface them as `retrying` events. A provider-reported error response ends
+that response but not the turn: messages still queued drain into a fresh inference, each drain
+consuming from a finite queue, so a persistently failing provider cannot loop.
+
+A turn that ends failed surfaces its error to the context as a durable system message
+(`The last turn failed: <message>`), so the next inference sees what went wrong. Only
+unrecovered failures leave this trace: a provider-reported error followed by a successful
+response in the same turn recovers silently, and a failed history load appends nothing since
+there is no loaded context to append to.
+
+When a turn stops for tool calls, every call in the batch runs in parallel. Arguments are
+validated against the tool's TypeBox `parameters` schema before `execute` runs, so `execute`
+receives them as `Static<Args>` rather than unknown. `execute` returns a structured result that
+is validated against `returnType` and then rendered into output blocks for the model with
+`toLLM`; an optional `isError` predicate marks a structured result as an error. A missing tool,
+invalid JSON arguments, arguments that fail the schema, an incomplete call, a thrown `execute`,
+or a result that fails `returnType` becomes an error tool result
+(`isError: true`) for the model instead of failing the run; provider-settled server calls are
+never executed by the agent, and their streamed `toolcall_result_*` events are simply ignored —
+the server call block stays in the history, the events reach the hooks, and no tool result
+message is stored or owed.
+
+Before any call in a batch executes, the whole batch is committed to the sorted store under
+`tool.` keys ordered by position, so a crash mid-batch leaves a durable record of the calls still
+owed a result. Calls run in parallel, but results land strictly in call order: a finished result
+waits until every earlier call in the batch has committed, and each commit appends the `tool`
+record and deletes the pending entry in one transaction. Once the batch is complete the loop runs
+inference again with the full context.
+
+`start` begins the loop without a new message: it loads the durable state and continues a turn
+that was cut off by a crash — leftover queued messages are consumed, a dispatched `tool.`
+batch is settled, and an unanswered user or tool message gets its inference. When an interrupted
+batch resumes, only tools marked `durable: true` execute again; every other interrupted call
+becomes an error tool result, since the agent cannot know whether its side effects already
+happened. On an idle history `start` loads and does nothing more.
+
+`compact` compacts the conversation through the provider session. It waits for the active turn
+to end — including queued messages already draining — or runs right away when idle, snapshots
+the history, and asks the provider to compact it. The completed replacement context supersedes
+the compacted history while any message that joined after the snapshot is kept. In one atomic
+transaction the superseded records are physically deleted and the replacement — the messages
+that stay — is appended as a `compaction` record, which then opens the store while later
+records append as usual. Calls made while a compaction is pending or running
+await that same shared compaction; it resolves on completion and rejects when the provider
+reports failure, leaving the history untouched.
+
+Hooks receive the agent's context first. That context — shared by tool executions — is derived
+once at construction and carries the agent's provider registry ID, model, effort, and
+service tier — all serializable values — readable through the exported `agentBaseProvider`,
+`agentBaseModel`, `agentBaseEffort`, and `agentBaseServiceTier` accessors. The
+`instructions` and `tools` hooks, when provided, answer for the session: they are consulted for
+session creation, every inference request, compaction, and tool lookup, superseding
+`state.instructions` and `state.tools`. A hook that throws falls back to the state and never
+fails the run.
+
+The lifecycle hooks bracket the loop's own structure. `beforeAgentLoop` fires when the loop
+leaves the settled state and begins working, and `afterAgentLoop` fires when it would settle
+back to idle; between them, each turn is bracketed by `beforeTurn` and `afterTurn`, and each
+inference request inside a turn by `beforeInference` and `afterInference`. `afterTurn` and
+`afterAgentLoop` may return an array of `AgentFeatureAction`s, all applied together before the
+loop continues: `steer` and `send` queue a message through the ordinary durable queues exactly
+as the public methods do, and `compact` triggers the shared compaction. Actions from `afterTurn`
+drive the loop into another turn within the same loop span; actions from `afterAgentLoop` reopen
+the loop instead of settling. Like every hook, a thrown lifecycle hook — or a failing action —
+never fails the run.
+
+`abort` cancels the active turn and resolves once the loop has stopped; when idle it is a no-op.
+The inference stream is abandoned and asked to close, a `done` event with state `cancelled` is
+emitted, blocks that already finished stay in the history while an unfinished block is dropped
+everywhere, and each still-running tool call settles as an error tool result saying it was
+aborted — consuming its pending `tool.` entry so the batch leaves a complete context behind.
+The queued turn request is dropped too, but messages still waiting in the steering and
+send queues stay durable and join the next requested turn.
+
+`AgentProviders` is a mutable registry of provider instances keyed by caller-supplied IDs, so the
+same provider class can be registered under several IDs. `add(id, provider, type)` registers an
+instance together with its compatibility type (`"claude"`, `"codex"`, `"grok"`, `"bedrock"`, or
+`"gym"`), `get(id)` returns the provider or null, and `typeOf(id)` returns the registered type
+or null. The agent is configured entirely with serializable values — a
+provider registry ID, a model name, an effort level, and a service tier — and resolves the live provider from
+the registry when the session is first created; an ID that is not registered at that moment
+fails the turn like any thrown error.
+
+## Validation
 
 ```sh
-pnpm release:happy-agent-base:patch
+pnpm --filter @slopus/happy-agent-base check
+pnpm --filter @slopus/happy-agent-base test
+pnpm --filter @slopus/happy-agent-base build
 ```
-
-The local release validates, tests, and builds only `@slopus/happy-agent-base`, then creates and
-pushes a `happy-agent-base-vX.Y.Z` tag. The shared GitHub publish workflow again validates, tests,
-and builds only this package before publishing it through npm trusted publishing. The npm trusted
-publisher must identify `slopus/rig`, `publish.yml`, and the `npm` GitHub environment.

package/dist/Agent.d.ts

@@ -0,0 +1,31 @@
+import type { SessionUserMessage } from "@slopus/happy-providers";
+import type { Context } from "@steve.kite/stdlib";
+import { type AgentBaseMessageOptions, type AgentBaseOptions } from "./AgentBase.js";
+import type { AgentBaseState } from "./AgentBaseState.js";
+import type { AgentFeature } from "./AgentFeature.js";
+import type { AnyAgentTool } from "./AgentTool.js";
+export interface AgentOptions<Tool extends AnyAgentTool = AnyAgentTool> extends Omit<AgentBaseOptions, "hooks"> {
+    /** Independent capabilities whose hook implementations are merged, in array order. */
+    readonly features?: readonly AgentFeature<Tool>[];
+}
+/**
+ * A thin wrapper around `AgentBase` that assembles its behavior from features. Each feature
+ * implements any subset of the agent hooks on its own; the agent merges them into the singular
+ * private hooks its internal base runs with. Observing hooks fan out to every feature in array
+ * order, instructions concatenate, tools concatenate, lifecycle actions concatenate, and the
+ * first feature to answer a reset injection wins.
+ */
+export declare class Agent<Tool extends AnyAgentTool = AnyAgentTool> {
+    #private;
+    constructor(ctx: Context, options: AgentOptions<Tool>);
+    get id(): string;
+    get state(): AgentBaseState;
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    start(): void;
+    waitForIdle(): Promise<void>;
+    compact(ctx: Context): Promise<void>;
+    abort(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/dist/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../sources/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAa,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,YAAY,GAAG,YAAY,CAClE,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACvC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;CACrD;AAED;;;;;;GAMG;AACH,qBAAa,KAAK,CAAC,IAAI,SAAS,YAAY,GAAG,YAAY;;IAGvD,YAAY,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAMpD;IAED,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,KAAK,IAAI,cAAc,CAE1B;IAEK,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAEf;IAEK,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAEf;IAED,KAAK,IAAI,IAAI,CAEZ;IAEK,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjC;IAEK,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;CACJ"}

package/dist/Agent.js

@@ -0,0 +1,119 @@
+import { AgentBase } from "./AgentBase.js";
+/**
+ * A thin wrapper around `AgentBase` that assembles its behavior from features. Each feature
+ * implements any subset of the agent hooks on its own; the agent merges them into the singular
+ * private hooks its internal base runs with. Observing hooks fan out to every feature in array
+ * order, instructions concatenate, tools concatenate, lifecycle actions concatenate, and the
+ * first feature to answer a reset injection wins.
+ */
+export class Agent {
+    #base;
+    constructor(ctx, options) {
+        const { features, ...base } = options;
+        this.#base = new AgentBase(ctx, {
+            ...base,
+            hooks: mergeFeatures(features ?? []),
+        });
+    }
+    get id() {
+        return this.#base.id;
+    }
+    get state() {
+        return this.#base.state;
+    }
+    async steer(ctx, message, options) {
+        await this.#base.steer(ctx, message, options);
+    }
+    async send(ctx, message, options) {
+        await this.#base.send(ctx, message, options);
+    }
+    start() {
+        this.#base.start();
+    }
+    async waitForIdle() {
+        await this.#base.waitForIdle();
+    }
+    async compact(ctx) {
+        await this.#base.compact(ctx);
+    }
+    async abort() {
+        await this.#base.abort();
+    }
+    async close() {
+        await this.#base.close();
+    }
+}
+/**
+ * Merge every feature's hook implementations into one `AgentBaseHooks`. A hook is provided only
+ * when at least one feature implements it, so the base's own fallbacks — such as the mutable
+ * state for instructions and tools — stay in effect otherwise.
+ */
+function mergeFeatures(features) {
+    const withInstructions = features.filter((feature) => feature.instructions !== undefined);
+    const withTools = features.filter((feature) => feature.tools !== undefined);
+    const withModelChanged = features.filter((feature) => feature.modelChanged !== undefined);
+    const fanOut = (pick) => {
+        const implemented = features.filter((feature) => pick(feature) !== undefined);
+        if (implemented.length === 0)
+            return undefined;
+        return (ctx) => {
+            for (const feature of implemented)
+                pick(feature)?.(ctx);
+        };
+    };
+    const collect = (pick) => {
+        const implemented = features.filter((feature) => pick(feature) !== undefined);
+        if (implemented.length === 0)
+            return undefined;
+        return (ctx) => implemented.flatMap((feature) => pick(feature)?.(ctx) ?? []);
+    };
+    const onEvent = fanOutEvent(features);
+    return {
+        ...(onEvent === undefined ? {} : { onEvent }),
+        ...(withInstructions.length === 0
+            ? {}
+            : {
+                instructions: (ctx) => withInstructions
+                    .map((feature) => feature.instructions?.(ctx) ?? "")
+                    .filter((text) => text.length > 0)
+                    .join("\n\n"),
+            }),
+        ...(withTools.length === 0
+            ? {}
+            : {
+                tools: (ctx) => withTools.flatMap((feature) => [...(feature.tools?.(ctx) ?? [])]),
+            }),
+        ...(withModelChanged.length === 0
+            ? {}
+            : {
+                modelChanged: (ctx, change) => {
+                    let injected;
+                    // Every feature observes the change; the first returned message wins.
+                    for (const feature of withModelChanged) {
+                        const message = feature.modelChanged?.(ctx, change);
+                        injected ??= message;
+                    }
+                    return injected;
+                },
+            }),
+        ...spread("beforeAgentLoop", fanOut((feature) => feature.beforeAgentLoop)),
+        ...spread("beforeTurn", fanOut((feature) => feature.beforeTurn)),
+        ...spread("beforeInference", fanOut((feature) => feature.beforeInference)),
+        ...spread("afterInference", fanOut((feature) => feature.afterInference)),
+        ...spread("afterTurn", collect((feature) => feature.afterTurn)),
+        ...spread("afterAgentLoop", collect((feature) => feature.afterAgentLoop)),
+    };
+}
+function fanOutEvent(features) {
+    const implemented = features.filter((feature) => feature.onEvent !== undefined);
+    if (implemented.length === 0)
+        return undefined;
+    return (ctx, event) => {
+        for (const feature of implemented)
+            feature.onEvent?.(ctx, event);
+    };
+}
+function spread(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+//# sourceMappingURL=Agent.js.map

package/dist/Agent.js.map

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

package/dist/AgentBase.d.ts

@@ -0,0 +1,93 @@
+import type { SessionReasoningEffort, SessionServiceTier, SessionUserMessage } from "@slopus/happy-providers";
+import { type Context } from "@steve.kite/stdlib";
+import type { AgentBaseHooks } from "./AgentBaseHooks.js";
+import type { AgentBasePersistence } from "./AgentBasePersistence.js";
+import type { AgentBaseState } from "./AgentBaseState.js";
+import { AgentProviders } from "./AgentProviders.js";
+/** How a message queue drains: one message per model response, or every queued message at once. */
+export type AgentBaseQueueMode = "one-at-a-time" | "all";
+/**
+ * Inference settings carried by a queued message. An omitted field keeps the previously
+ * effective value; the first message without a value falls back to the constructor default,
+ * though relying on that default is discouraged — prefer sending settings with the message.
+ */
+export interface AgentBaseMessageOptions {
+    /** The registry ID of the provider to switch to. */
+    readonly provider?: string;
+    readonly model?: string;
+    readonly effort?: SessionReasoningEffort;
+    readonly serviceTier?: SessionServiceTier;
+}
+export interface AgentBaseOptions {
+    /** Stable session identity supplied by the caller. */
+    readonly id: string;
+    /** The registry providers are resolved from, at session creation time. */
+    readonly providers: AgentProviders;
+    /** The registry ID of the provider to use; serializable alongside model and effort. */
+    readonly provider: string;
+    readonly persistence: AgentBasePersistence;
+    readonly hooks?: AgentBaseHooks;
+    /** Copied into the agent's own mutable `state`. */
+    readonly initialState?: Partial<AgentBaseState>;
+    readonly model?: string;
+    readonly effort?: SessionReasoningEffort;
+    readonly serviceTier?: SessionServiceTier;
+    readonly steeringMode?: AgentBaseQueueMode;
+    readonly sendMode?: AgentBaseQueueMode;
+}
+/**
+ * A single agent session over one provider. Messages arrive through two FIFO queues: steering
+ * messages inject as soon as the current assistant response and its tool batch finish, while
+ * sent messages wait until the agent would otherwise stop — no tool calls or steering remain.
+ * Each queue drains per its configured mode, and the conversation is durable through
+ * append-only persistence loaded on the first inference attempt.
+ */
+export declare class AgentBase {
+    #private;
+    readonly id: string;
+    /**
+     * The agent's own copy of the initial state, mutable directly; every inference reads the
+     * current values.
+     */
+    readonly state: AgentBaseState;
+    constructor(ctx: Context, options: AgentBaseOptions);
+    /**
+     * Queue a user message that injects as soon as the current assistant response and its tool
+     * batch finish; steering always takes precedence over sent messages. The returned promise
+     * resolves once the durable write lands; it waits neither for the history load nor for the
+     * turn, and a failed write keeps the message out of the conversation entirely.
+     */
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /**
+     * Queue a user message that waits until the agent would otherwise stop — no tool calls or
+     * steering remain — before injecting. The returned promise resolves once the durable write
+     * lands; it waits neither for the history load nor for the turn, and a failed write keeps
+     * the message out of the conversation entirely.
+     */
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    /**
+     * Start the loop without a new message: load the durable state and, if a turn was cut off —
+     * queued messages, a dispatched tool batch without results, or an unanswered user or tool
+     * message — continue it to completion. On an idle history this loads and does nothing more.
+     */
+    start(): void;
+    waitForIdle(): Promise<void>;
+    /**
+     * Compact the conversation. The compaction waits for the active turn to end — or runs right
+     * away when idle — and replaces the compacted history with the provider's replacement
+     * context while keeping every message that joined the history after the snapshot. Calls made
+     * while a compaction is pending or running await that same compaction; the shared promise
+     * resolves when it completes and rejects when the provider reports failure.
+     */
+    compact(ctx: Context): Promise<void>;
+    /**
+     * Cancel the active turn: stop consuming the inference stream, settle still-running tool
+     * calls as aborted error results, and drop the queued turn request. Blocks that already
+     * finished stay in the history; an unfinished block is dropped. Messages still waiting in
+     * the steering and send queues stay durable and join the next requested turn. Resolves
+     * once the loop has stopped; a no-op when the agent is idle.
+     */
+    abort(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=AgentBase.d.ts.map

package/dist/AgentBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentBase.d.ts","sourceRoot":"","sources":["../sources/AgentBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAMR,sBAAsB,EACtB,kBAAkB,EAIlB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAA2C,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrD,mGAAmG;AACnG,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,KAAK,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC7C;AASD,MAAM,WAAW,gBAAgB;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAwC/B,YAAY,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAmBlD;IAWD;;;;;OAKG;IACG,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAEf;IAED;;;;;OAKG;IACG,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAEf;IAmBD;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAGZ;IAEK,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAIjC;IAED;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzC;IAyCD;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAM3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAM3B;CAqvBJ"}