@sema-agent/core 2.2.0 → 2.4.0

package/dist/core/store-contracts/contract-harness.js

@@ -0,0 +1,16 @@
+export function defaultSequentialRunner(_name, fn) {
+    return fn();
+}
+export function beginContract(runAssertion = defaultSequentialRunner) {
+    const pending = [];
+    return {
+        run: (name, fn) => {
+            const result = runAssertion(name, fn);
+            if (result instanceof Promise)
+                pending.push(result);
+        },
+        settle: async () => {
+            await Promise.all(pending);
+        },
+    };
+}

package/dist/core/store-contracts/contract-kit-version.d.ts

@@ -0,0 +1 @@
+export declare const CONTRACT_KIT_ENGINE_VERSION: string;

package/dist/core/store-contracts/contract-kit-version.js

@@ -0,0 +1,2 @@
+import { engineVersion } from "../version.js";
+export const CONTRACT_KIT_ENGINE_VERSION = engineVersion();

package/dist/core/store-contracts/file-snapshot-store-contract.d.ts

@@ -0,0 +1,3 @@
+import type { FileSnapshotStore } from "../file-snapshot-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/file-snapshot-store-contract.js

@@ -0,0 +1,126 @@
+import { strict as assert } from "node:assert";
+import { createHash } from "node:crypto";
+import { beginContract } from "./contract-harness.js";
+const bytes = (s) => new TextEncoder().encode(s);
+const sha256 = (s) => createHash("sha256").update(bytes(s)).digest("hex");
+const srcBlob = async (hash) => hash === sha256("alpha") ? bytes("alpha") : hash === sha256("beta") ? bytes("beta") : undefined;
+export async function fileSnapshotStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("kit prerequisites: exportManifest/getBlob/putBlob/importManifest are implemented (REQUIRED by this kit)", async () => {
+        const probe = make();
+        const missing = ["exportManifest", "getBlob", "putBlob", "importManifest"].filter((m) => typeof probe[m] !== "function");
+        assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the FileSnapshotStore contract kit`);
+    });
+    run("absent everything: has=false, listKeys=[], exportManifest=null, getBlob=undefined", async () => {
+        const store = make();
+        assert.equal(await store.has("sc", "k1"), false);
+        assert.deepEqual(await store.listKeys("sc"), []);
+        assert.equal(await store.exportManifest("sc", "k1"), null);
+        assert.equal(await store.getBlob(sha256("alpha")), undefined);
+    });
+    run("putBlob verifies content-address integrity: mismatched bytes → read_failed, nothing stored", async () => {
+        const store = make();
+        const r = await store.putBlob(sha256("beta"), bytes("alpha"));
+        assert.equal(r.ok, false);
+        if (!r.ok)
+            assert.equal(r.error.code, "read_failed");
+        assert.equal(await store.getBlob(sha256("beta")), undefined);
+    });
+    run("putBlob ok; a repeat putBlob for the same hash is an idempotent no-op; getBlob round-trips the bytes", async () => {
+        const store = make();
+        assert.deepEqual(await store.putBlob(sha256("alpha"), bytes("alpha")), { ok: true });
+        assert.deepEqual(await store.putBlob(sha256("alpha"), bytes("alpha")), { ok: true });
+        assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
+    });
+    run("importManifest commits only after every blob verifies: has=true, exportManifest round-trips", async () => {
+        const store = make();
+        const manifest = new Map([["a.txt", sha256("alpha")], ["b.txt", sha256("beta")]]);
+        assert.deepEqual(await store.importManifest("sc", "k1", manifest, srcBlob), { ok: true });
+        assert.equal(await store.has("sc", "k1"), true);
+        const exported = await store.exportManifest("sc", "k1");
+        assert.deepEqual([...exported.entries()].sort(), [...manifest.entries()].sort());
+    });
+    run("importManifest is create-once: a second import for an existing key is a no-op (ok, zero fetches, manifest unchanged)", async () => {
+        const store = make();
+        const manifest = new Map([["a.txt", sha256("alpha")]]);
+        assert.deepEqual(await store.importManifest("sc", "k1", manifest, srcBlob), { ok: true });
+        const refetched = [];
+        const second = await store.importManifest("sc", "k1", new Map([["z.txt", sha256("beta")]]), async (h) => {
+            refetched.push(h);
+            return srcBlob(h);
+        });
+        assert.deepEqual(second, { ok: true });
+        assert.deepEqual(refetched, []);
+        assert.deepEqual([...(await store.exportManifest("sc", "k1")).entries()], [...manifest.entries()]);
+    });
+    run("importManifest is FAIL-CLOSED: a missing or hash-mismatched source blob → read_failed, no manifest committed", async () => {
+        const store = make();
+        const manifest = new Map([["c.txt", "0".repeat(64)]]);
+        const miss = await store.importManifest("sc", "k2", manifest, async () => undefined);
+        assert.equal(miss.ok, false);
+        if (!miss.ok)
+            assert.equal(miss.error.code, "read_failed");
+        assert.equal(await store.has("sc", "k2"), false);
+        const mism = await store.importManifest("sc", "k2", manifest, async () => bytes("wrong-bytes"));
+        assert.equal(mism.ok, false);
+        if (!mism.ok)
+            assert.equal(mism.error.code, "read_failed");
+        assert.equal(await store.has("sc", "k2"), false);
+    });
+    run("RB-361 a throwing source fetch → read_failed NAMING the blob hash, byte-identical wording (since 2.2.0)", async () => {
+        const store = make();
+        const hash = sha256("x");
+        const r = await store.importManifest("sc", "k3", new Map([["d.txt", hash]]), () => Promise.reject(new Error("transport down")));
+        assert.equal(r.ok, false);
+        if (!r.ok) {
+            assert.equal(r.error.code, "read_failed");
+            assert.equal(r.error.message, `source blob ${hash} fetch failed: transport down`);
+        }
+        assert.equal(await store.has("sc", "k3"), false);
+    });
+    run("RB-361 a path-escaping hash is refused as UNSAFE before any fetch, byte-identical wording (since 2.2.0)", async () => {
+        const store = make();
+        const fetched = [];
+        const r = await store.importManifest("sc", "k4", new Map([["e.txt", "../../escape"]]), async (h) => {
+            fetched.push(h);
+            return undefined;
+        });
+        assert.equal(r.ok, false);
+        if (!r.ok) {
+            assert.equal(r.error.code, "read_failed");
+            assert.equal(r.error.message, `unsafe blob hash "../../escape"`);
+        }
+        assert.deepEqual(fetched, []);
+        assert.equal(await store.has("sc", "k4"), false);
+    });
+    run("restore of a missing key → not_found (never a throw out of the seam)", async () => {
+        const store = make();
+        const stubEnv = {};
+        const r = await store.restore("sc", "nope", stubEnv, "/nonexistent-root");
+        assert.equal(r.ok, false);
+        if (!r.ok)
+            assert.equal(r.error.code, "not_found");
+    });
+    run("listKeys reflects only committed keys and is scope-isolated", async () => {
+        const store = make();
+        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
+        await store.importManifest("sc", "k2", new Map([["c.txt", "0".repeat(64)]]), async () => undefined);
+        assert.deepEqual(((await store.listKeys("sc")) ?? []).slice().sort(), ["k1"]);
+        assert.deepEqual(await store.listKeys("other"), []);
+    });
+    run("reap keeps listed keys and their blobs", async () => {
+        const store = make();
+        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
+        assert.equal(await store.reap("sc", ["k1"]), 0);
+        assert.deepEqual(await store.listKeys("sc"), ["k1"]);
+        assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
+    });
+    run("reap keep-nothing drops the key and GCs the now-unreferenced blobs", async () => {
+        const store = make();
+        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
+        assert.equal(await store.reap("sc", []), 1);
+        assert.equal(await store.has("sc", "k1"), false);
+        assert.equal(await store.getBlob(sha256("alpha")), undefined);
+    });
+    await settle();
+}

package/dist/core/store-contracts/mailbox-store-contract.d.ts

@@ -0,0 +1,6 @@
+import type { MailboxStore } from "../mailbox-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare const MAILBOX_CONTRACT_SCOPE = "default";
+export declare function mailboxStoreContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function mailboxAckOwnershipContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function mailboxBundledOnlyContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -0,0 +1,193 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export const MAILBOX_CONTRACT_SCOPE = "default";
+const msg = (content, sentAt = 1000) => ({ content, sentAt });
+async function withStores(mk, fn) {
+    const live = [];
+    const make = () => {
+        const s = mk();
+        live.push(s);
+        return s;
+    };
+    try {
+        await fn(make);
+    }
+    finally {
+        for (const s of live.splice(0))
+            s.close?.();
+    }
+}
+export async function mailboxStoreContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("append 铸单调 seq;claimLease 取全部可见消息(不删);ack 才删;活租约=单消费者", async (make) => {
+        const s = make();
+        assert.equal(await s.append(S, "a1", msg("m1")), 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.content), ["m1", "m2"]);
+        assert.equal(lease.maxSeq, 2);
+        assert.equal(await s.claimLease(S, "a1", "w2", 60_000, 20_000), null);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        await s.ack(S, "a1", "w1", 2);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("X-1 无损:lease 过期/release 后消息按原 seq 回可见;seq 在箱的一生中永不复用", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l1 = await s.claimLease(S, "a1", "w1", 1_000, 10_000);
+        assert.equal(l1.maxSeq, 1);
+        const l2 = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
+        assert.deepEqual(l2.messages.map((m) => m.seq), [1]);
+        await s.releaseLease(S, "a1", "w2");
+        const l3 = await s.claimLease(S, "a1", "w3", 1_000, 20_500);
+        assert.deepEqual(l3.messages.map((m) => m.seq), [1]);
+        await s.ack(S, "a1", "w3", 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+    });
+    run("lease 窗内 append:后到消息在下次 claim 时可见(lease 只覆盖 claim 时刻快照)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.equal(l.maxSeq, 1);
+        await s.append(S, "a1", msg("m2"));
+        await s.ack(S, "a1", "w1", l.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+        const next = await s.claimLease(S, "a1", "w2", 60_000, 20_000);
+        assert.deepEqual(next.messages.map((m) => m.content), ["m2"]);
+    });
+    run("drop 清整箱;reap 按最新消息龄整箱老化", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("old", 1_000));
+        await s.append(S, "a2", msg("fresh", 90_000));
+        assert.equal(await s.reap(S, 100_000, { maxAgeMs: 50_000 }), 1);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.peekCount(S, "a2"), 1);
+        await s.drop(S, "a2");
+        assert.equal(await s.peekCount(S, "a2"), 0);
+    });
+    run("RB-86 空箱 ⇒ null:没消息就不发租约(既不假装投递,也不 fence 掉后来真正的消费者)", async (make) => {
+        const s = make();
+        assert.equal(await s.claimLease(S, "never-written", "o1", 60_000, 1_000), null, "从未写过的箱");
+        await s.append(S, "a1", msg("m1"));
+        const first = await s.claimLease(S, "a1", "o1", 60_000, 1_000);
+        await s.ack(S, "a1", "o1", first.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.claimLease(S, "a1", "o1", 60_000, 2_000), null, "全部 ack 后箱内零可见消息");
+        assert.equal(await s.claimLease(S, "a2", "ghost", 60_000, 3_000), null);
+        await s.append(S, "a2", msg("real", 4_000));
+        const real = await s.claimLease(S, "a2", "o2", 60_000, 4_000);
+        assert.deepEqual(real?.messages.map((m) => m.content), ["real"], "空取不该留下 fence 后来者的幽灵租约");
+    });
+    run("RB-261 守恒律:一条消息在被 ack 消费之前必须至少投递过一次(maxSeq 不得覆盖未投递项)", async (make) => {
+        const s = make();
+        const appended = ["m1", "m2", "m3"];
+        for (const [i, c] of appended.entries())
+            await s.append(S, "a1", msg(c, 1_000 + i));
+        const delivered = new Set();
+        let round = 0;
+        while ((await s.peekCount(S, "a1")) > 0) {
+            round += 1;
+            assert.ok(round < 10, "要么有限轮内收敛,要么就是投递不动了");
+            const owner = `w${round}`;
+            const lease = await s.claimLease(S, "a1", owner, 60_000, 10_000 + round);
+            assert.notEqual(lease, null, "还有可见消息时 claimLease 不得返回 null");
+            for (const m of lease.messages)
+                delivered.add(m.content);
+            await s.ack(S, "a1", owner, lease.maxSeq);
+        }
+        assert.deepEqual([...delivered].sort(), [...appended].sort(), "每条被消费掉的消息都必须先被投递过");
+    });
+    run("releaseLease owner-fenced:非持有者的 release 是 no-op(活租约的单消费者窗口不被外人撬开)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const held = await s.claimLease(S, "a1", "owner-A", 60_000, 10_000);
+        assert.equal(held.messages.length, 1);
+        await s.releaseLease(S, "a1", "not-the-owner");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "A 的活租约必须仍然 fence 住 rival");
+        await s.releaseLease(S, "a1", "owner-A");
+        const after = await s.claimLease(S, "a1", "rival", 60_000, 12_000);
+        assert.deepEqual(after?.messages.map((m) => m.seq), [1], "归还后同一条按原 seq 回可见");
+    });
+    await settle();
+}
+export async function mailboxAckOwnershipContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("a non-holder's ack does not delete messages held under another owner's LIVE lease", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        assert.equal(lease?.messages.length, 2);
+        await s.ack(S, "a1", "stale-actor", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "the messages must survive — this caller never held the lease");
+    });
+    run("angle 4 — internal consistency: releaseLease and ack now apply the SAME owner fence (was the asymmetry that proved this was an oversight)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.claimLease(S, "a1", "real-owner", 60_000, 10_000);
+        await s.releaseLease(S, "a1", "wrong-owner");
+        await s.ack(S, "a1", "wrong-owner", 1);
+        assert.equal(await s.peekCount(S, "a1"), 1, "neither operation should have touched anything");
+    });
+    run("angle 5 — ack with no lease EVER claimed is a no-op, not a silent wipe", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.ack(S, "a1", "nobody", Number.MAX_SAFE_INTEGER);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+    });
+    run("the legitimate holder's own ack still works (regression check — the fix must not break the happy path)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        await s.ack(S, "a1", "consumer-A", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("angle 3 in detail — the real loss sequence (stale owner outlives its own expired lease, a NEW owner has since taken over): the new owner's custody survives", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "ship-the-release", sentAt: 1 });
+        await s.append(S, "a1", { content: "notify-oncall", sentAt: 2 });
+        const leaseA = await s.claimLease(S, "a1", "consumer-A", 1_000, 1_000);
+        assert.equal(leaseA?.messages.length, 2);
+        const leaseB = await s.claimLease(S, "a1", "consumer-B", 60_000, 5_000);
+        assert.equal(leaseB?.messages.length, 2);
+        await s.ack(S, "a1", "consumer-A", leaseA.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "B's live custody must survive A's stale ack");
+        await s.ack(S, "a1", "consumer-B", leaseB.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    await settle();
+}
+export async function mailboxBundledOnlyContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    run("RB-251(黑板 [1937]):handle 含 NUL 被两个后端一致拒绝,且不得跨 (scope,handle) 串箱", async (make) => {
+        const s = make();
+        const NUL = String.fromCharCode(0);
+        await assert.rejects(s.append("s", `a${NUL}b`, msg("secret")));
+        assert.equal(await s.peekCount(`s${NUL}a`, "b"), 0, "歧义键下不得出现串箱可读");
+        await s.append("s", "plain", msg("ok"));
+        assert.equal(await s.peekCount("s", "plain"), 1);
+    });
+    run("多租户:同名 handle 在不同 scope 下是两个互不可见的箱(各自独立铸 seq)", async (make) => {
+        const s = make();
+        assert.equal(await s.append("tenant-a", "shared-handle", msg("for-a")), 1);
+        assert.equal(await s.append("tenant-b", "shared-handle", msg("for-b")), 1, "另一个 scope 的箱独立铸号");
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 1);
+        const a = await s.claimLease("tenant-a", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(a.messages.map((m) => m.content), ["for-a"]);
+        const b = await s.claimLease("tenant-b", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(b.messages.map((m) => m.content), ["for-b"]);
+        await s.ack("tenant-a", "shared-handle", "w", a.maxSeq);
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 0);
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 1, "跨 scope 的 ack 不得越界");
+        await s.drop("tenant-b", "shared-handle");
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 0);
+    });
+    await settle();
+}

package/dist/core/store-contracts/session-repo-contract.d.ts

@@ -0,0 +1,3 @@
+import type { SessionRepo } from "../../internal/harness-types.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function sessionRepoContract(make: () => SessionRepo, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/session-repo-contract.js

@@ -0,0 +1,36 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+const SESSION_ENTRY = (id, parentId) => ({
+    id,
+    parentId,
+    type: "message",
+    timestamp: "2026-07-30T00:00:00.000Z",
+    message: { role: "user", content: [{ type: "text", text: `t-${id}` }], timestamp: 1785340800000 },
+});
+export async function sessionRepoContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    const A = "0198fa00-0000-7000-8000-00000000000a";
+    run("RB-360 create({id}) on an id that ALREADY has history is an idempotent REOPEN — never a wipe", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+        const again = await repo.create({ id: A });
+        const entries = await again.getStorage().getEntries();
+        assert.deepEqual(entries.map((e) => e.id), ["e1", "e2"]);
+        const exported = (await repo.exportEntries?.(A)) ?? [];
+        assert.deepEqual(exported.map((e) => e.id), ["e1", "e2"]);
+    });
+    run("create({id}) fresh → open() sees appended entries (round-trip floor)", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const opened = await repo.open({ id: A, createdAt: "" });
+        assert.deepEqual((await opened.getStorage().getEntries()).map((e) => e.id), ["e1"]);
+    });
+    run("open(missing) throws not_found — never a silent create", async () => {
+        const repo = make();
+        await assert.rejects(repo.open({ id: "0198fa00-0000-7000-8000-0000000000ff", createdAt: "" }), /not.?found/i);
+    });
+    await settle();
+}

package/dist/core/store-contracts/tool-result-store-contract.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResultStore } from "../tool-result-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/tool-result-store-contract.js

@@ -0,0 +1,35 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export async function toolResultStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("put/get full + sliced; write-once no-op; unknown → undefined", async () => {
+        const store = make();
+        const ref = "tr_s_c";
+        await store.put(ref, "0123456789");
+        assert.deepEqual(await store.get(ref), { content: "0123456789", offset: 0, totalChars: 10 });
+        assert.deepEqual(await store.get(ref, { offset: 2, limit: 3 }), { content: "234", offset: 2, totalChars: 10 });
+        await store.put(ref, "IGNORED");
+        assert.equal((await store.get(ref)).content, "0123456789");
+        assert.equal(await store.get("tr_unknown"), undefined);
+    });
+    run("RB-266 unsafe refs are rejected at the WRITE by every backend; the read face degrades instead", async () => {
+        const store = make();
+        const NUL = String.fromCharCode(0);
+        const unsafe = ["", ".", "..", "a/b", "../escape", "dir\\ref", `tr_x${NUL}y`];
+        for (const ref of unsafe) {
+            await assert.rejects((async () => store.put(ref, "payload"))(), `put(${JSON.stringify(ref)}) must reject — a durable backend cannot key it`);
+            assert.equal(await store.get(ref), undefined, "get of an unsafe ref degrades to undefined");
+        }
+        await store.put("tr_sess-1_call.7", "ok");
+        assert.equal((await store.get("tr_sess-1_call.7")).content, "ok");
+    });
+    run("RB-273 a ref the contract ACCEPTS round-trips on every backend (no backend is stricter than the rule)", async () => {
+        const store = make();
+        for (const ref of ["tr_sess_call:1", "tr_sess_call%2F1", "tr_sess_call 1", "tr_sess_日本語"]) {
+            await store.put(ref, `payload-${ref}`);
+            assert.equal((await store.get(ref))?.content, `payload-${ref}`, `put(${JSON.stringify(ref)}) must round-trip here`);
+        }
+        assert.equal((await store.get("tr_sess_call:1")).content, "payload-tr_sess_call:1");
+    });
+    await settle();
+}

package/dist/core/task-notification.d.ts

@@ -10,6 +10,8 @@ export interface TaskNotificationPayload {
     source?: string;
     stoppedBy?: "user" | "parent" | "system" | (string & {});
     summary: string;
+    error?: string;
+    errorCode?: string;
     exitCode?: number;
     result?: string;
     partial?: boolean;

package/dist/core/task-registry-agent.d.ts

@@ -1,5 +1,6 @@
 import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
 import { type StopSource, type TaskAccess, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
+import { type ToolResultStore } from "./tool-result-store.js";
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
 export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: (keyof BackgroundAgentRecord)[]): void;
 export declare function durableAgentArmedLane(core: DurableAgentCore, id: string): boolean;
@@ -65,6 +66,8 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
     stoppedBy?: StopSource;
     seq?: number;
 }): "completed" | "failed" | "killed" | undefined;
@@ -97,6 +100,8 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function unmarkRetainedContinuationLane(core: DurableAgentCore, id: string): void;
 export declare function attachAgentNotifyLane(core: DurableAgentCore, id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;
@@ -119,5 +124,6 @@ export declare function notFoundRunningAgentsTail(footer: {
     background: string[];
 }): string;
 export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): UnifiedTaskResult;
-export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, oneShot?: boolean): Promise<UnifiedTaskResult>;
+export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
+export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, oneShot?: boolean, store?: ToolResultStore, sessionId?: string): Promise<UnifiedTaskResult>;
 export declare function stopBackgroundAgentLane(core: DurableAgentCore, handle: BackgroundAgentTaskHandle): Promise<UnifiedTaskResult>;

package/dist/core/task-registry-agent.js

@@ -3,7 +3,9 @@ import { uuidv7 } from "../internal/harness.js";
 import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
+import { boundedRedactedSummary } from "./untrusted-egress.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function ensureDurableHeartbeatLane(core) {
     if (core.durableHeartbeatTimer !== undefined)
         return;
@@ -635,6 +637,7 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
     handle.resolveParkedStop = undefined;
     handle.updatedAt = Date.now();
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     if (flipped.seq !== undefined)
         handle.cycleSeq = flipped.seq;
     return true;
@@ -680,6 +683,7 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     handle.status = outcome.status;
     mintCompletionId(handle);
     handle.notify = undefined;
+    handle.onReapTerminal = undefined;
     for (const [, , qResolve] of handle.preAttachQueue ?? [])
         qResolve?.({ ok: false, reason: "not_running" });
     handle.preAttachQueue = undefined;
@@ -698,6 +702,10 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     }
     if (outcome.error !== undefined && !(outcome.status === "killed" && outcome.error === BG_AGENT_REAP_STOP_ERROR)) {
         handle.error = outcome.error;
+        if (outcome.errorCode !== undefined)
+            handle.errorCode = outcome.errorCode;
+        if (outcome.retryable !== undefined)
+            handle.errorRetryable = outcome.retryable;
     }
     handle.updatedAt = Date.now();
     if (outcome.seq !== undefined)
@@ -834,10 +842,12 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
         handle.abort = abort;
     handle.result = undefined;
     handle.resultFull = undefined;
+    handle.spillRef = undefined;
     handle.error = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
@@ -1022,7 +1032,19 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
         },
     };
 }
-export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot) {
+export async function spillClippedAgentResult(handle, full, clipped, store, sessionId) {
+    if (clipped === full)
+        return clipped;
+    if (store === undefined)
+        return clipped;
+    if (handle.spillRef === undefined) {
+        const ref = buildToolResultRef(sessionId ?? "no-session", `${handle.id}_c${handle.reviveCycle ?? 0}`);
+        await store.put(ref, full);
+        handle.spillRef = ref;
+    }
+    return `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${handle.spillRef}" to read it back.]`;
+}
+export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId) {
     while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
         await sleepPollStep(deadline, signal);
     }
@@ -1041,6 +1063,8 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             },
         };
     }
+    const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
+    const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
     const body = running
         ? oneShot === true
             ? `status: running
@@ -1050,7 +1074,7 @@ The agent is still working — you will be notified when it completes.`
         : `status: ${handle.status}
 ${handle.error ? `error: ${handle.error}
 ` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
-${clipTaskOutput(handle.resultFull ?? handle.result, handle.outputFile)}` : "(no result text)"}`;
+${resultText}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
         details: {
@@ -1060,6 +1084,11 @@ ${clipTaskOutput(handle.resultFull ?? handle.result, handle.outputFile)}` : "(no
             retrieval_status: retrieval,
             ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
             ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.status === "failed" && handle.error !== undefined
+                ? { error: delimitUntrusted("agent error", boundedRedactedSummary(handle.error, 300)) }
+                : {}),
+            ...(handle.status === "failed" && handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+            ...(handle.status === "failed" && handle.errorRetryable !== undefined ? { retryable: handle.errorRetryable } : {}),
             ...(handle.resultIsPartial ? { partial_result: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         },