@slopus/happy-agent-base 0.0.13 → 0.0.15

package/README.md

@@ -25,10 +25,17 @@ active Drizzle facade as `ctx.db`; `ctx.inTx(work)` and the exported `inTx(ctx,
 an outer transaction or reuse the one already carried by the context. Outside a transaction,
 stdlib starts post-commit callbacks on the next microtask.
 
-Storage, KV, migrations, and transactional module hooks compose with a context's outer transaction.
-Live `Agent` and `AgentSystem` commands do not: creating, resolving, messaging,
-mutating, archiving, or closing a live agent from inside an outer storage transaction is rejected
-because the corresponding in-memory lifetime cannot be published until that transaction commits.
+Storage, KV, migrations, transactional module hooks, and message delivery compose with a context's
+outer transaction. `send` and `steer` persist their queue entry and pending-work marker inside that
+transaction, then publish the in-memory queue and start the run only through `afterCommit`; rollback
+therefore leaves no live effect. Delivery inside a transaction never waits on the agent's internal
+persistence lock — the caller holds the database writer while its transaction stays open, and a
+running turn takes that lock before touching the database, so waiting here could deadlock against a
+live turn; the open transaction supplies the atomicity the lock otherwise guarantees.
+Transactional routing through `AgentSystem.send` or `steer`
+requires a target that is already live; loading an idle target remains a separate lifetime
+operation. Other live `Agent` and `AgentSystem` lifetime commands—creating, resolving, mutating,
+archiving, or closing—remain rejected inside an outer transaction.
 
 An agent runs in one of four permission modes — `read_only`, `workspace_write`, `auto`, and
 `full_access` — carried on every context it derives and read back with `agentPermissionMode`. A
@@ -75,9 +82,11 @@ Messages receive a generated cuid2 identity, or accept one through `{ id }` for
 delivery. A repeated ID is an ignored persistence conflict while its message remains in the
 durable conversation; deliberate conversation replacement releases identities for the records it
 removes. `send` and `steer` return the effective ID, delivery mode, and whether durable acceptance
-created the identity or found it already present. Optional immutable metadata travels beside the
-provider message and reaches both message-accepted hooks; module-generated send and steer actions
-accept the same fields.
+created the identity or found it already present. Inside an outer transaction, even an operation
+requested with `await: false` completes its durable queue write before returning, because work may
+not retain a transaction context after the transaction body ends. Optional immutable metadata
+travels beside the provider message and reaches both message-accepted hooks; module-generated send
+and steer actions accept the same fields.
 
 Base allocates cuid2 identities for every settled-to-settled loop, turn, inference, and settlement.
 The IDs are persisted with outstanding work before their first lifecycle hook, survive restart,

package/dist/AgentBase.d.ts.map

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

package/dist/AgentBase.js

@@ -289,6 +289,8 @@ export class AgentBase {
     #steering = [];
     /** The durable send queue, in the order its keys sort. */
     #sends = [];
+    /** A committed queue write that the next turn still has to reload from storage. */
+    #committedQueueDirty = false;
     /** Hook notices waiting to join history after tool settlement and compaction. */
     #injections = [];
     /** A consumed notice that still needs one provider response. */
@@ -706,7 +708,13 @@ export class AgentBase {
      * the agent's own close still drains it, so nothing is dropped by not looking.
      */
     async #offer(ctx, kind, message, options) {
-        this.#assertOutsideStorageTransaction(ctx, "message delivery");
+        const outerTransaction = agentStorageTransaction(ctx);
+        if (outerTransaction?.lifetime.aborted === true) {
+            throw new Error("The agent storage transaction carried by this context has ended.");
+        }
+        if (outerTransaction !== undefined && this.#insideOwnPersistenceLock()) {
+            throw new Error("Agent message delivery cannot reenter its own persistence operation inside a transaction.");
+        }
         const { await: requestedWait, id = createId(), metadata: suppliedMetadata, ...settings } = options ?? {};
         if (!Value.Check(cuid2Schema, id)) {
             throw new Error("The message ID must be a cuid2 identity.");
@@ -719,7 +727,9 @@ export class AgentBase {
         if (this.#closed)
             throw new Error("The agent has been closed.");
         const knownInProcess = this.#offeredMessageIds.has(id);
-        this.#offeredMessageIds.add(id);
+        if (outerTransaction === undefined) {
+            this.#offeredMessageIds.add(id);
+        }
         const accepted = this.#enqueue(ctx, [
             {
                 kind,
@@ -729,6 +739,16 @@ export class AgentBase {
                 options: settings,
             },
         ]);
+        // Work using an outer transaction must finish its durable writes before that transaction
+        // body can return. The caller may still choose not to wait for an ordinary independent
+        // acceptance, but a carried transaction cannot safely outlive unfinished work using it.
+        if (outerTransaction !== undefined) {
+            const [result] = await accepted;
+            if (result === undefined) {
+                throw new Error("The message acceptance result was lost.");
+            }
+            return result;
+        }
         if (wait) {
             try {
                 const [result] = await accepted;
@@ -808,7 +828,20 @@ export class AgentBase {
             throw new Error("The agent has been closed.");
         // Admitted: from here on the messages are the agent's responsibility, and a close that
         // begins now waits for them rather than resolving over the top of them.
-        const admitted = this.#runInPersistenceLock(ctx, async (lockCtx) => {
+        const admitted = agentStorageTransaction(ctx) === undefined
+            ? this.#enqueueIndependently(ctx, batch)
+            : this.#enqueueInTransaction(ctx, batch);
+        this.#admitted.add(admitted);
+        try {
+            return await admitted;
+        }
+        finally {
+            this.#admitted.delete(admitted);
+        }
+    }
+    /** Accept a batch under the persistence lock, in a transaction of the acceptance's own. */
+    async #enqueueIndependently(ctx, batch) {
+        return await this.#runInPersistenceLock(ctx, async (lockCtx) => {
             const accepted = [];
             const results = [];
             await this.#recordTransaction(lockCtx, async (txCtx) => {
@@ -862,13 +895,106 @@ export class AgentBase {
             }
             return results;
         });
-        this.#admitted.add(admitted);
-        try {
-            return await admitted;
-        }
-        finally {
-            this.#admitted.delete(admitted);
+    }
+    /**
+     * Accept a batch inside the caller's own open transaction. This path must not take the
+     * agent's persistence lock: the caller holds the database writer for as long as its
+     * transaction stays open, while a running turn takes the lock first and the database second,
+     * so waiting for the lock here would close a cycle nothing could break. The outer transaction
+     * supplies the atomicity the lock otherwise guarantees, queue keys are claimed with
+     * absent-only writes so a racing independent enqueue cannot be overwritten, and no heap
+     * state changes until the commit publishes the batch.
+     */
+    async #enqueueInTransaction(ctx, batch) {
+        const results = [];
+        let acceptedAny = false;
+        for (const request of batch) {
+            const identityKey = `message.${request.id}`;
+            if (!(await this.#persistence.writeValueIfAbsent(ctx, identityKey, true))) {
+                results.push({
+                    id: request.id,
+                    delivery: request.kind === "steering" ? "steer" : "send",
+                    accepted: "existing",
+                });
+                continue;
+            }
+            await this.#claimQueueKey(ctx, `${request.kind}.`, {
+                id: request.id,
+                message: request.message,
+                ...(request.metadata === undefined ? {} : { metadata: request.metadata }),
+                options: request.options,
+            });
+            acceptedAny = true;
+            results.push({
+                id: request.id,
+                delivery: request.kind === "steering" ? "steer" : "send",
+                accepted: "created",
+            });
         }
+        // Accepting a message is what makes the work owed, so the same transaction that admits
+        // it records that the agent owes an answer; here that record is staged durably and made
+        // live only once the outermost commit publishes the whole batch.
+        const stagedPending = acceptedAny
+            ? await this.#stagePendingMessageWork(ctx)
+            : undefined;
+        const offeredIds = batch.map(({ id }) => id);
+        afterCommit(ctx, async () => {
+            await this.#activateCommittedMessages(offeredIds, stagedPending);
+        });
+        return results;
+    }
+    /**
+     * Persist the pending inference an outer transaction will make live after commit, without
+     * changing any heap state that would survive a rollback. Reading the transaction's current
+     * value also makes multiple sends in one outer transaction reuse the same lifecycle IDs.
+     */
+    async #stagePendingMessageWork(ctx) {
+        const stored = await agentBasePendingStateOf(ctx, this.#persistence);
+        const pending = stored === undefined
+            ? { stage: "inference", loopId: createId() }
+            : { ...stored, stage: "inference" };
+        await this.#persistence.writeValue(ctx, AGENT_BASE_PENDING_KEY, pending);
+        return pending;
+    }
+    /**
+     * Publish a transactionally accepted message only after the outermost commit. The next turn
+     * reloads the durable queue instead of copying staged entries into memory; the dirty marker
+     * prevents a turn already in flight from clearing the request before that reload happens.
+     */
+    async #activateCommittedMessages(offeredIds, stagedPending) {
+        for (const id of offeredIds)
+            this.#offeredMessageIds.add(id);
+        if (stagedPending === undefined)
+            return;
+        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            let pending = stagedPending;
+            try {
+                pending =
+                    (await agentBasePendingStateOf(lockCtx, this.#persistence)) ?? stagedPending;
+            }
+            catch {
+                // The committed staged value is enough to start; a turn reload retries storage.
+            }
+            // A run in flight holds its lifecycle IDs across many lock acquisitions, so adopting
+            // over it would tear the identities out from under a live turn. That run reaches the
+            // committed batch through the dirty marker instead; adoption is for an idle agent
+            // whose next run should continue exactly what the commit recorded.
+            if (this.#runPromise === undefined) {
+                this.#adoptPendingState(pending);
+            }
+            this.#committedQueueDirty = true;
+        });
+        this.#turnRequested = true;
+        this.#startRun();
+    }
+    /** Make one committed pending record the exact in-memory lifecycle state. */
+    #adoptPendingState(pending) {
+        this.#pending = pending;
+        this.#pendingWritten = deterministicStringify(pending);
+        this.#loopId = pending.loopId;
+        this.#turnId = pending.turnId;
+        this.#inferenceId = pending.inferenceId;
+        this.#settlementId = pending.settlementId;
     }
     /** Durably queue hook notices until history reaches a safe append boundary. */
     async #enqueueInjections(ctx, batch) {
@@ -2060,6 +2186,7 @@ export class AgentBase {
     #clearTurnRequestIfNoPendingInput() {
         if (this.#steering.length === 0 &&
             this.#sends.length === 0 &&
+            !this.#committedQueueDirty &&
             this.#injections.length === 0 &&
             !this.#noticeAwaitingResponse &&
             this.#compaction === undefined) {
@@ -2399,6 +2526,7 @@ export class AgentBase {
                     this.#pendingToolsUndispatched = true;
                 }
             }
+            this.#committedQueueDirty = false;
         });
     }
     /**
@@ -2675,11 +2803,19 @@ export class AgentBase {
             return failure("The tool call was incomplete and was not executed.");
         }
         let args;
-        try {
-            args = call.arguments.trim().length === 0 ? {} : JSON.parse(call.arguments);
+        if (tool.grammar !== undefined) {
+            // A grammar tool is freeform: its own syntax constrained the model, so what arrives is
+            // the text that grammar produced and never JSON. Reading it as JSON would refuse every
+            // call a correct patch or query makes, so it is handed over as written.
+            args = { input: call.arguments };
         }
-        catch {
-            return failure(`The arguments for "${call.name}" were not valid JSON.`);
+        else {
+            try {
+                args = call.arguments.trim().length === 0 ? {} : JSON.parse(call.arguments);
+            }
+            catch {
+                return failure(`The arguments for "${call.name}" were not valid JSON.`);
+            }
         }
         if (tool.parameters !== undefined && !Value.Check(tool.parameters, args)) {
             return failure(`The arguments for "${call.name}" did not match its schema.`);
@@ -2888,6 +3024,22 @@ export class AgentBase {
         // a clock that went backwards: continue the sequence rather than starting it again.
         return key(lastSlot, Number(lastSequence) + 1);
     }
+    /**
+     * Write a queue entry under a key nothing else holds. An enqueue running outside the
+     * persistence lock can race an independent one for the tail position, so the key is claimed
+     * with an absent-only write and a taken key moves one sequence further rather than
+     * overwriting whatever claimed it first.
+     */
+    async #claimQueueKey(ctx, prefix, envelope) {
+        let key = await this.#queueKey(ctx, prefix);
+        for (let attempt = 0; attempt < 1000; attempt += 1) {
+            if (await this.#persistence.writeValueIfAbsent(ctx, key, envelope))
+                return key;
+            const [slot, sequence] = key.slice(prefix.length).split(".");
+            key = `${prefix}${slot}.${String(Number(sequence) + 1).padStart(6, "0")}`;
+        }
+        throw new Error("A queue key could not be claimed after repeated collisions.");
+    }
     /**
      * Consume one response stream into the assistant message it spells out, appending each block
      * to the store as it finishes and reporting every event to the hooks. What comes back is what