@sema-agent/server 7.109.0 → 7.111.0

package/dist/user-input-ledger.js

@@ -0,0 +1,354 @@
+import { USER_STEER_UNDRAINED_CAUSES } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { isHolderDeathVerdict } from "./plugins/store-contracts.js";
+import { defaultEngineNoticeRouter } from "./trace/engine-notice-wire.js";
+export const USER_INPUT_LEDGER_DIR = "user-input-ledger";
+export const USER_INPUT_KIND_WORDS = { steer: true };
+export const SETTLE_HOW_WORDS = { leg_end: true, not_applied: true };
+const UNDRAINED_CAUSE_MINTER = { leg_end: "engine", crashed: "server" };
+export const CRASHED_CAUSE = "crashed";
+export function isServingLayerUndrainedCause(v) {
+    if (typeof v !== "string" || !USER_STEER_UNDRAINED_CAUSES.includes(v))
+        return false;
+    return UNDRAINED_CAUSE_MINTER[v] === "server";
+}
+export class UserInputLedgerFold {
+    byId = new Map();
+    bySession = new Map();
+    has(acceptId) {
+        return this.byId.has(acceptId);
+    }
+    get(acceptId) {
+        return this.byId.get(acceptId);
+    }
+    sessionSize(sessionId) {
+        return this.bySession.get(sessionId)?.length ?? 0;
+    }
+    admits(rec) {
+        switch (rec.kind) {
+            case "accepted":
+                return !this.byId.has(rec.acceptId);
+            case "settled":
+            case "converged": {
+                const cur = this.byId.get(rec.acceptId);
+                return cur !== undefined && cur.state.kind === "open";
+            }
+            case "announced": {
+                const cur = this.byId.get(rec.acceptId);
+                return cur !== undefined && cur.state.kind === "converged" && cur.announced === undefined;
+            }
+            case "erased":
+                return this.sessionSize(rec.sessionId) > 0;
+            default: {
+                const unreachable = rec;
+                return unreachable;
+            }
+        }
+    }
+    apply(rec) {
+        if (!this.admits(rec))
+            return false;
+        switch (rec.kind) {
+            case "accepted": {
+                this.byId.set(rec.acceptId, {
+                    acceptId: rec.acceptId,
+                    input: rec.input,
+                    messageId: rec.messageId,
+                    sessionId: rec.sessionId,
+                    taskId: rec.taskId,
+                    writer: rec.writer,
+                    acceptedAtMs: rec.at,
+                    state: { kind: "open" },
+                });
+                const list = this.bySession.get(rec.sessionId);
+                if (list)
+                    list.push(rec.acceptId);
+                else
+                    this.bySession.set(rec.sessionId, [rec.acceptId]);
+                return true;
+            }
+            case "settled": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, state: { kind: "settled", how: rec.how, atMs: rec.at } });
+                return true;
+            }
+            case "converged": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, state: { kind: "converged", cause: rec.cause, atMs: rec.at } });
+                return true;
+            }
+            case "announced": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, announced: { atMs: rec.at, taskId: rec.taskId } });
+                return true;
+            }
+            case "erased": {
+                for (const acceptId of this.bySession.get(rec.sessionId))
+                    this.byId.delete(acceptId);
+                this.bySession.delete(rec.sessionId);
+                return true;
+            }
+            default: {
+                const unreachable = rec;
+                return unreachable;
+            }
+        }
+    }
+    listOpen(after, limit) {
+        assertPageLimit("listOpen", limit);
+        const open = sortAcceptances([...this.byId.values()].filter((a) => a.state.kind === "open"));
+        const rest = after === undefined ? open : open.filter((a) => a.acceptedAtMs > after.acceptedAtMs || (a.acceptedAtMs === after.acceptedAtMs && a.acceptId > after.acceptId));
+        const page = rest.slice(0, limit);
+        const last = page.length === limit ? page[page.length - 1] : undefined;
+        return last === undefined ? { open: page } : { open: page, next: { acceptedAtMs: last.acceptedAtMs, acceptId: last.acceptId } };
+    }
+    listCrashed(sessionId, limit) {
+        const ids = this.bySession.get(sessionId) ?? [];
+        const crashed = sortAcceptances(ids.map((id) => this.byId.get(id)).filter((a) => a.state.kind === "converged"));
+        return crashed.slice(Math.max(0, crashed.length - limit));
+    }
+    listUnannounced(sessionId, limit) {
+        assertPageLimit("listUnannounced", limit);
+        const ids = this.bySession.get(sessionId) ?? [];
+        return sortAcceptances(ids.map((id) => this.byId.get(id)).filter((a) => a.state.kind === "converged" && a.announced === undefined)).slice(0, limit);
+    }
+}
+export function assertPageLimit(op, limit) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error(`user-input ledger ${op}: limit must be a positive integer (got ${String(limit)})`);
+    return limit;
+}
+export function sortAcceptances(list) {
+    return list.sort((a, b) => a.acceptedAtMs - b.acceptedAtMs || (a.acceptId < b.acceptId ? -1 : a.acceptId > b.acceptId ? 1 : 0));
+}
+export const USER_INPUT_OPEN_SCAN_MAX = 1000;
+export const USER_INPUT_OPEN_SCAN_PAGES = 100;
+export const USER_INPUT_SESSION_READ_MAX = 500;
+const USER_STEER_UNDRAINED = "task.user_steer_undrained";
+export function buildCrashedSteerNotice(input) {
+    return {
+        code: USER_STEER_UNDRAINED,
+        message: `Check the earlier run's transcript and results before re-sending any of these steers to a live run. The server accepted ${input.steer} user steer(s) for run ${input.taskId} (each answered 200 applied or 202 queued-immediate), but the process running that run ended before the run settled; whether the run consumed them is not known. They are NOT redelivered.`,
+        detail: { steer: input.steer, cause: CRASHED_CAUSE, taskId: input.taskId, sessionId: input.sessionId },
+        sessionId: input.sessionId,
+    };
+}
+const errText = (e) => (e instanceof Error ? e.message : String(e));
+const LANE_FACTS = {
+    exclusive_data_root: { foreignHolderMayBeAlive: false, absentRunRow: "crashed" },
+    run_store_verdict: { foreignHolderMayBeAlive: true, absentRunRow: "leg_over" },
+};
+async function judgeOpen(a, me, liveHere, kind, getRun) {
+    if (a.writer === me)
+        return liveHere.has(a.acceptId) ? "live" : "leg_over";
+    const lane = LANE_FACTS[kind];
+    const run = await getRun(a.taskId);
+    if (!run)
+        return lane.absentRunRow;
+    if (run.instanceId === a.writer) {
+        if (run.status === "running")
+            return lane.foreignHolderMayBeAlive ? "live" : "crashed";
+        if (isHolderDeathVerdict(run))
+            return "crashed";
+    }
+    return "leg_over";
+}
+export function createUserInputLedger(opts) {
+    const { store, writer, evidence } = opts;
+    const now = opts.now ?? Date.now;
+    const legs = new WeakMap();
+    const liveHere = new Set();
+    const track = (leg, acceptId) => {
+        const set = legs.get(leg);
+        if (set)
+            set.add(acceptId);
+        else
+            legs.set(leg, new Set([acceptId]));
+    };
+    const pageSize = opts.scanBudget?.pageSize ?? USER_INPUT_OPEN_SCAN_MAX;
+    const maxPages = opts.scanBudget?.maxPages ?? USER_INPUT_OPEN_SCAN_PAGES;
+    let scanCursor;
+    let inFlight;
+    const convergePass = async () => {
+        const reads = new Map();
+        const getRun = (taskId) => {
+            let read = reads.get(taskId);
+            if (read === undefined)
+                reads.set(taskId, (read = evidence.runs.getRun(taskId)));
+            return read;
+        };
+        let n = 0;
+        for (let page = 0; page < maxPages; page++) {
+            let scanned;
+            try {
+                scanned = await store.listOpen(scanCursor, pageSize);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=converge ${errText(e)}`);
+                return n;
+            }
+            n += await convergePage(scanned.open, getRun);
+            scanCursor = scanned.next;
+            if (scanCursor === undefined)
+                return n;
+        }
+        return n;
+    };
+    const convergePage = async (open, getRun) => {
+        let n = 0;
+        for (const a of open) {
+            let verdict;
+            try {
+                verdict = await judgeOpen(a, writer, liveHere, evidence.kind, getRun);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=judge ${errText(e)}`);
+                continue;
+            }
+            try {
+                switch (verdict) {
+                    case "crashed":
+                        if (await store.converge(a.acceptId, now()))
+                            n += 1;
+                        break;
+                    case "leg_over":
+                        await store.settle(a.acceptId, "leg_end", now());
+                        break;
+                    case "live":
+                        break;
+                    default: {
+                        const unreachable = verdict;
+                        return unreachable;
+                    }
+                }
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.append-failed", `op=converge ${errText(e)}`);
+            }
+        }
+        return n;
+    };
+    return {
+        async accept(input) {
+            const acceptId = opts.newId();
+            liveHere.add(acceptId);
+            try {
+                await store.accept({ acceptId, input: input.input, messageId: input.messageId, sessionId: input.sessionId, taskId: input.taskId, writer, acceptedAtMs: now() });
+            }
+            catch (e) {
+                liveHere.delete(acceptId);
+                throw e;
+            }
+            track(input.leg, acceptId);
+            return { acceptId, leg: input.leg };
+        },
+        async withdraw(receipt) {
+            legs.get(receipt.leg)?.delete(receipt.acceptId);
+            try {
+                await store.settle(receipt.acceptId, "not_applied", now());
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.append-failed", `op=withdraw ${errText(e)}`);
+            }
+            finally {
+                liveHere.delete(receipt.acceptId);
+            }
+        },
+        async settleLeg(leg) {
+            const ids = legs.get(leg);
+            if (!ids)
+                return;
+            legs.delete(leg);
+            for (const acceptId of ids) {
+                try {
+                    await store.settle(acceptId, "leg_end", now());
+                }
+                catch (e) {
+                    recordFailOpen("server.user-input-ledger.append-failed", `op=settle ${errText(e)}`);
+                }
+                finally {
+                    liveHere.delete(acceptId);
+                }
+            }
+        },
+        converge() {
+            inFlight ??= convergePass().finally(() => {
+                inFlight = undefined;
+            });
+            return inFlight;
+        },
+        async announceUndrained(at, router = defaultEngineNoticeRouter) {
+            let rows;
+            try {
+                rows = await store.listUnannounced(at.sessionId, USER_INPUT_SESSION_READ_MAX);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=announce ${errText(e)}`);
+                return;
+            }
+            const groups = new Map();
+            for (const a of rows) {
+                const g = groups.get(a.taskId);
+                if (g)
+                    g.push(a);
+                else
+                    groups.set(a.taskId, [a]);
+            }
+            for (const [oldTaskId, group] of groups) {
+                const steer = new Set(group.map((a) => a.messageId)).size;
+                const delivered = await router.routeConfirmed(buildCrashedSteerNotice({ steer, taskId: oldTaskId, sessionId: at.sessionId }));
+                if (delivered === 0)
+                    continue;
+                for (const a of group) {
+                    try {
+                        await store.announce(a.acceptId, at.taskId, now());
+                    }
+                    catch (e) {
+                        recordFailOpen("server.user-input-ledger.append-failed", `op=announce ${errText(e)}`);
+                    }
+                }
+            }
+        },
+        async readSession(sessionId) {
+            const rows = await store.listCrashed(sessionId);
+            const seen = new Set();
+            const out = [];
+            for (const a of rows) {
+                if (a.state.kind !== "converged")
+                    continue;
+                const key = `${a.taskId}\u0000${a.messageId}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push({
+                    messageId: a.messageId,
+                    kind: a.input,
+                    taskId: a.taskId,
+                    acceptedAt: new Date(a.acceptedAtMs).toISOString(),
+                    cause: a.state.cause,
+                    ...(a.announced !== undefined ? { announced: { at: new Date(a.announced.atMs).toISOString(), taskId: a.announced.taskId } } : {}),
+                });
+            }
+            return out.length > 0 ? out : undefined;
+        },
+    };
+}
+export async function createUserInputLedgerAtBoot(opts) {
+    const ledger = createUserInputLedger(opts);
+    const converged = await ledger.converge();
+    return { ledger, converged };
+}
+export function writerGoneEvidenceFor(backendKind, runs) {
+    switch (backendKind) {
+        case "local":
+            return { kind: "exclusive_data_root", runs };
+        case "mysql":
+        case "pg":
+            return { kind: "run_store_verdict", runs };
+        default: {
+            const unreachable = backendKind;
+            return unreachable;
+        }
+    }
+}
+//# sourceMappingURL=user-input-ledger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.109.0",
+  "version": "7.111.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -61,7 +61,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.37.1",
+    "@sema-agent/core": "7.38.2",
     "@sema-agent/settings-schema": "6.4.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -77,7 +77,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "13.1.0",
+    "@sema-agent/sdk": "15.1.1",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",