@slopus/happy-agent-base 0.0.0 → 0.0.2

package/dist/AgentBase.d.ts

@@ -0,0 +1,340 @@
+import type { SessionReasoningEffort, SessionServiceTier, SessionUserMessage } from "@slopus/happy-providers";
+import { type Context } from "@steve.kite/stdlib";
+import type { AgentBaseHooks } from "./AgentBaseHooks.js";
+import type { AgentPersistence } from "./AgentPersistence.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;
+    /** The model to switch to; an incompatible one resets the conversation. */
+    readonly model?: string;
+    /** How hard the model should think about the request. */
+    readonly effort?: SessionReasoningEffort;
+    /** Which of the provider's service tiers to bill and schedule the request on. */
+    readonly serviceTier?: SessionServiceTier;
+}
+/**
+ * Whether an operation resolves once the agent has taken the request on, or once the agent has
+ * carried it out. Every operation that asks something of an agent accepts this, and every one of
+ * them defaults to the first: asking is the operation, and waiting is opt-in.
+ *
+ * The reason is re-entrancy. An agent does its work in one run loop, and while a hook or a tool
+ * runs, that loop is waiting for it — so code in that position that waits for its own agent waits
+ * for itself. Rather than offer some operations in a waiting form and others not, every operation
+ * returns as soon as the request is registered, and `await: true` asks for the rest. That flag is
+ * refused, loudly, when the caller's context says it is running inside the loop of the very agent
+ * it is asking, which is the only case where the wait could never end.
+ */
+export interface AgentBaseAwaitOptions {
+    /**
+     * Wait for the operation to finish rather than for it to be accepted. Refused from inside the
+     * agent's own run loop.
+     */
+    readonly await?: boolean;
+}
+/** Everything an agent session is constructed with; only the identity and store are required. */
+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;
+    /** The append-only store the conversation, the queues, and the settings live in. */
+    readonly persistence: AgentPersistence;
+    /** Observers and correctness hooks the run is assembled from; `Agent` merges features here. */
+    readonly hooks?: AgentBaseHooks;
+    /** Copied into the agent's own mutable `state`. */
+    readonly initialState?: Partial<AgentBaseState>;
+    /** The initial model, superseded by the first message that carries one. */
+    readonly model?: string;
+    /** The initial reasoning effort, superseded by the first message that carries one. */
+    readonly effort?: SessionReasoningEffort;
+    /** The initial service tier, superseded by the first message that carries one. */
+    readonly serviceTier?: SessionServiceTier;
+    /** How the steering queue drains; one message per response by default. */
+    readonly steeringMode?: AgentBaseQueueMode;
+    /** How the send queue drains; one message per response by default. */
+    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 reloaded at the start of every turn.
+ *
+ * The rest of this comment is the list of promises the implementation has to keep. They are
+ * written down because most of them are invisible in ordinary use and only show themselves when
+ * a process dies, two owners share a store, or a caller races the loop — every one of them was
+ * bought with a bug found by `tests/chaos/`, and each has a focused test that fails without it.
+ *
+ * ## Serialization
+ *
+ * One lock serializes every persistence operation together with its in-memory effect, so storage
+ * order always matches history order and a load never overlaps an append. Anything that decides
+ * from durable state resolves that state inside the lock rather than capturing it beforehand; a
+ * reference taken before a wait can belong to a history that has since been replaced.
+ *
+ * ## Accepting a message
+ *
+ * A message is accepted exactly once, or not at all. Its durable write and the writes of every
+ * other message in the same batch commit in one transaction under one hold of the lock. So:
+ *
+ * - `steer` and `send` with `await: true` resolve only once the message is durable; a failed
+ *   write keeps it out of the conversation entirely. Without the flag they return early, but the
+ *   acceptance is the same one, and a close still waits for it.
+ * - Messages a hook returns from one decision are accepted as one batch. A caller arriving while
+ *   that batch is being written lands after all of it, never between two halves of one thought.
+ * - Queue keys order by what the store already holds and end in a segment identifying their
+ *   writer, so two owners accepting in the same millisecond may order arbitrarily but can never
+ *   overwrite one another.
+ * - An agent holding a durable message never describes itself as settled.
+ *
+ * ## Consuming a message
+ *
+ * A consumption claims each entry with an atomic delete inside its own transaction, so one
+ * durable message is answered exactly once however many live owners hold it in memory. A batch
+ * that claims nothing rolls back having changed nothing. A message is never durable in both the
+ * queue and the context, or in neither, and memory changes only after the commit.
+ *
+ * ## Turns
+ *
+ * A turn answers the durable conversation, not the one this instance remembers: it reloads
+ * before it decides anything, so an appended message or a model switch from another owner is in
+ * force by the next turn. A turn that consumes the last queued work clears the request it just
+ * answered, rather than buying an extra turn with an empty queue and a full set of hooks.
+ *
+ * ## Tool calls
+ *
+ * A batch runs its calls at the same time, each in its own persistence scope, and commits their
+ * results in batch order. Results are matched back by call ID, so a response that used one ID
+ * twice has no answer the model could tell apart: that ID is kept once and refused before
+ * anything runs, since a refusal after the fact would not undo the side effect.
+ *
+ * The conversation never keeps a tool call the model will not get an answer for:
+ *
+ * - A batch is committed before any call in it runs, so a batch found uncommitted after a crash
+ *   has certainly not run and is dispatched as the fresh batch it never became.
+ * - A response that emits a call but does not end in one, and a turn that fails while owing
+ *   results, settle their own calls with error results before appending anything behind them.
+ * - A conversation loaded with a call stranded under later messages is repaired atomically at
+ *   load, since the answer belongs beside its call rather than at the end.
+ * - A non-durable tool never runs twice; a durable one may.
+ *
+ * ## Compaction
+ *
+ * A compaction runs before a turn's first inference, so the model always receives a settled
+ * conversation. It replaces the history whole or not at all, and the suffix it preserves is
+ * rebuilt from the store inside the commit — from a record count taken at the snapshot, so work
+ * another owner committed while the provider was summarizing survives. A compaction nobody will
+ * carry out is rejected rather than left waiting.
+ *
+ * ## Model changes
+ *
+ * An incompatible provider or model change resets the conversation; a compatible one keeps it.
+ * Either way the change lands on one side or the other, never the old history under the new
+ * model. `modelChanged` runs inside the lock and is lent a store bound to that hold — a
+ * capability released when the hook returns, so it cannot be retained to bypass the lock later.
+ * A failing handoff rejects an incompatible switch outright rather than costing the history.
+ *
+ * ## Recovery
+ *
+ * Whether a restart owes a response is decided by the last durable record: a consumed message, a
+ * tool result, or a failure note is owed an answer, while a replacement written by a compaction
+ * is not a question and gets none.
+ *
+ * ## Abort
+ *
+ * An abort owns the whole turn. Its scope opens before any of the turn's work — its hooks and its
+ * loading as much as its inference — so a turn cancelled while it is still starting up never
+ * reaches the model at all, rather than being cancelled only once it was already talking.
+ *
+ * What a cancelled turn leaves behind is fixed:
+ *
+ * - Assistant blocks that finished stay in the history; a block still being streamed is dropped,
+ *   because half a block is not something the model said.
+ * - Tool calls still running are settled in the conversation as aborted error results, so the
+ *   history owes nothing, and the turn ends without waiting for the tools themselves. A tool that
+ *   never notices cancellation therefore cannot hold the cancellation open — but it is still
+ *   running, so the *next* provider request waits for it before reusing the stateful session.
+ * - Messages already queued stay durable and join the next requested turn. An abort cancels the
+ *   turn, not the work waiting for one.
+ * - A compaction requested during the turn is rejected rather than left pending, because dropping
+ *   the turn request drops the only thing that would have carried it out.
+ * - Exactly one terminal event is reported. A cancellation seen after a response already reported
+ *   its own outcome adds nothing, since that response is over.
+ *
+ * `abort` signals and returns, because the cancellation is complete once it is signalled.
+ * `abort(ctx, { await: true })` additionally waits for the loop to stop, which is what an owner
+ * outside the agent usually wants and what code inside it must not ask for — see below.
+ *
+ * ## Close
+ *
+ * Close is a barrier, published before any of the shutdown runs. Nothing new is admitted from
+ * the moment it is called; everything already admitted is written and answered, and only then is
+ * the provider session destroyed. Every caller shares that one shutdown, including one
+ * reentering from inside session destruction, so a session is never destroyed twice.
+ *
+ * ## Hooks
+ *
+ * Hooks observe the run and never fail it. Neither a throwing hook nor a failing hook-driven
+ * action ends a turn.
+ *
+ * ## Re-entrancy
+ *
+ * A hook or a tool runs while the loop is waiting for it, so anything it asks of its own agent
+ * that only the loop can deliver would wait for itself. Rather than leave that to be remembered
+ * per operation, asking and waiting are separated everywhere:
+ *
+ * - `steer`, `send`, `abort` and `compact` are safe from anywhere in their asking form, which is
+ *   the default. Each registers what it registers and returns; the loop acts on it afterwards.
+ * - `await: true` asks for the part only the loop can give. Contexts handed to hooks and tools
+ *   record which agents' loops the execution is inside, so the flag is refused with an error that
+ *   names the problem instead of hanging. The check is per agent: work inside one agent's loop
+ *   may still wait on another's, which is what makes a subagent's report to its parent safe.
+ * - The refusal is uniform even where a particular wait would have happened to work. A tool that
+ *   waits for its own abort, for instance, does unwind — the batch races each execution against
+ *   cancellation — but that is a property of tool batches rather than of abort, and a rule that
+ *   holds only in one position is worse than no rule.
+ * - A hook that wants a compaction has a better option than requesting one: the
+ *   `{ type: "compact" }` action it returns lands exactly where the loop can act on it, in order
+ *   with the rest of that decision.
+ * - `close` and `waitForIdle` take no context, so they cannot be checked and will simply hang.
+ *   Both are nothing but a wait for the run to finish. Close the agent from the caller that owns
+ *   its lifetime.
+ *
+ * `AgentRef` and `AgentSystemRef` drop the two unguarded waits, and are what code running inside
+ * an agent should be handed.
+ */
+export declare class AgentBase {
+    #private;
+    /** The caller-supplied session identity: the name of this agent's store and of its loop. */
+    readonly id: string;
+    /**
+     * The agent's own copy of the initial state, mutable directly; every inference reads the
+     * current values.
+     */
+    readonly state: AgentBaseState;
+    /**
+     * A new agent, wired to its options and touching no storage at all. Use this for an identity
+     * with no durable state yet; whatever the agent needs from the store is read by its first
+     * turn.
+     */
+    static create(ctx: Context, options: AgentBaseOptions): Promise<AgentBase>;
+    /**
+     * An agent for an identity that may already have durable state, with the one externally
+     * meaningful fact about that state — whether it has work left — read before it is handed
+     * back, so `active` is answerable straight away.
+     *
+     * Only the flag is read. The conversation, the queues and the settings are deliberately not:
+     * they are needed by the first turn and by nothing before it, so an owner resuming a hundred
+     * identities at startup pays for a hundred small reads rather than a hundred transcripts.
+     * The rest loads on the way into the turn that actually needs it.
+     */
+    static load(ctx: Context, options: AgentBaseOptions): Promise<AgentBase>;
+    /**
+     * Load the agent and set it going again if it has work left, or answer with nothing when it
+     * has none. This is how an owner coming up carries on whatever an earlier process was in the
+     * middle of: the whole question is one key, and an agent told to go picks its own work back
+     * up, so the caller has only to bring it into existence.
+     *
+     * An agent owing nothing is not handed back, because there is nothing to do with it that
+     * resolving it when something is actually wanted of it would not do better.
+     */
+    static loadActive(ctx: Context, options: AgentBaseOptions): Promise<AgentBase | undefined>;
+    /**
+     * Build the agent from its options, without touching the store. Nothing is loaded here: the
+     * durable state is read by the first turn, so constructing one stays cheap even for a session
+     * nobody goes on to run. Private, because an agent is made by `create` or by `load`, and
+     * which of the two the caller means is worth saying.
+     */
+    private constructor();
+    /**
+     * Whether the agent has anything left to do. This is the only thing about an agent's state
+     * anyone outside it may read: the queues and the stage behind this answer are the run's own
+     * business, and can be cleared but never inspected. Even this is rarely wanted — it is here
+     * for the owner deciding which agents a restarted process has to resume.
+     */
+    get active(): boolean;
+    /**
+     * 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. Returns once the message
+     * has been handed to the agent, which never waits for the turn that answers it; with
+     * `await: true` it returns once the durable write has landed instead, and a failed write both
+     * rejects and keeps the message out of the conversation entirely.
+     */
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    /**
+     * Queue a user message that waits until the agent would otherwise stop — no tool calls or
+     * steering remain — before injecting. Returns once the message has been handed to the agent,
+     * which never waits for the turn that answers it; with `await: true` it returns once the
+     * durable write has landed instead, and a failed write both rejects and keeps the message out
+     * of the conversation entirely.
+     */
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): 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;
+    /**
+     * Wait until the agent has nothing left to do. That includes work it has taken on but not yet
+     * started: an operation whose caller did not wait for it is registered from the moment it is
+     * called, so a message asked for and abandoned is still something this waits for, rather than
+     * a race between the caller's next line and the agent's own lock.
+     */
+    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.
+     *
+     * Returns once the compaction has been asked for; with `await: true` it returns once the
+     * compaction has run, rejecting when the provider reports failure or when nothing will carry
+     * it out. Callers that wait while a compaction is pending or running all wait for that same
+     * compaction rather than queueing another.
+     */
+    compact(ctx: Context, options?: AgentBaseAwaitOptions): 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. A no-op when the agent is
+     * idle.
+     *
+     * Returns once the cancellation has been signalled, which is the point from which nothing
+     * more of that turn happens; with `await: true` it returns once the loop has actually
+     * unwound. The cancellation is identical either way — waiting only buys the answer about
+     * when it finished.
+     */
+    abort(ctx: Context, options?: AgentBaseAwaitOptions): Promise<void>;
+    /**
+     * Stop the agent, without abandoning anything it had already taken on. Nothing new is
+     * admitted from the moment close is called, but a message accepted just before it is still
+     * written, still answered, and only then is the provider session destroyed — so a caller
+     * whose send resolved never has to wonder whether the close raced it. Closing twice awaits
+     * the same shutdown.
+     *
+     * A close is nothing but a wait, so it is refused from inside the agent's own run loop, where
+     * the wait could never end. It is the one operation with no context to check, so it asks the
+     * runtime instead.
+     *
+     * Running tool calls are the exception to finishing what was accepted. From the moment close
+     * begins, the batch stops waiting for them and settles them in the conversation as error
+     * results. A tool can perfectly well be blocked on this very close — that is how two agents
+     * closing each other through their tools would otherwise wedge — and no tool is worth
+     * letting the shutdown never finish.
+     */
+    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":"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"}