@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/store/memory.js

@@ -0,0 +1,645 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { encodeCursor } from "./cursor.js";
+import { OwnershipLostError } from "./ownership.js";
+import { DOC_TABLES, } from "./types.js";
+/** Schema version the fake reports; it has no migrations. */
+export const MEMORY_SCHEMA_VERSION = 1;
+function emptyState() {
+    return {
+        docs: Object.fromEntries(DOC_TABLES.map((table) => [table, new Map()])),
+        sessionMeta: new Map(),
+        outbox: new Map(),
+        executors: new Map(),
+        principals: new Map(),
+        vaults: new Map(),
+        credentials: new Map(),
+        audit: [],
+        idempotency: new Map(),
+        settings: new Map(),
+    };
+}
+const OWNERSHIP_KEYS = new Set(["owner", "epoch", "ownerExpiresAt"]);
+const OPEN_SESSION = new Set(["running", "runnable"]);
+const byId = (entries) => [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+const copy = (value) => structuredClone(value);
+/**
+ * The data behind in-memory Session Stores: what a database is to its connections. Several
+ * `MemorySessionStore`s on one `MemoryStoreData` see each other's commits and serialize their
+ * transactions together, as several processes on one Tenant schema would; it outlives them,
+ * so a test can close a Tenant and open it again.
+ */
+export class MemoryStoreData {
+    /** @internal */ state = emptyState();
+    /** @internal */ queue = Promise.resolve();
+}
+/**
+ * In-memory `SessionStore` for unit tests. Not a supported profile.
+ *
+ * Transactions are serialized (one at a time), each works on a copy of the
+ * state and replaces it on commit, so a throw rolls back everything: documents,
+ * sequences, outbox rows, `afterCommit` callbacks and `signalWork`. Commit listeners see
+ * only this store's commits, as with a Postgres connection.
+ */
+export class MemorySessionStore {
+    data;
+    tenantId;
+    active = new AsyncLocalStorage();
+    listeners = new Set();
+    now;
+    onError;
+    closed = false;
+    constructor(options, 
+    /** Shared with other stores on the same data; a fresh, private one by default. */
+    data = new MemoryStoreData()) {
+        this.data = data;
+        this.tenantId = options.tenantId;
+        this.now = options.now ?? (() => new Date());
+        this.onError =
+            options.onError ??
+                ((error) => queueMicrotask(() => {
+                    throw error;
+                }));
+    }
+    async tx(fn) {
+        if (this.closed)
+            throw new Error("SessionStore is closed");
+        if (this.active.getStore() === this)
+            throw new Error("Nested SessionStore.tx is not allowed");
+        const release = await this.acquire();
+        let t;
+        let result;
+        try {
+            const working = copy(this.data.state);
+            t = new MemoryTx(working, this.tenantId, this.now);
+            try {
+                result = await this.active.run(this, () => fn(t));
+            }
+            finally {
+                t.closed = true;
+            }
+            this.data.state = working;
+            if (t.events.length > 0 || t.workAvailable) {
+                const commit = {
+                    events: t.events,
+                    incarnations: t.incarnations,
+                    workAvailable: t.workAvailable,
+                };
+                for (const listener of this.listeners) {
+                    try {
+                        listener(commit);
+                    }
+                    catch (error) {
+                        this.onError(error);
+                    }
+                }
+            }
+        }
+        finally {
+            release();
+        }
+        for (const callback of t.callbacks) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                this.onError(error);
+            }
+        }
+        return result;
+    }
+    onCommit(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async health() {
+        return {
+            ok: !this.closed,
+            schemaVersion: MEMORY_SCHEMA_VERSION,
+            expectedSchemaVersion: MEMORY_SCHEMA_VERSION,
+        };
+    }
+    async close() {
+        this.closed = true;
+        await this.data.queue;
+    }
+    acquire() {
+        let release;
+        const next = new Promise((resolve) => (release = resolve));
+        const ready = this.data.queue.then(() => release);
+        this.data.queue = this.data.queue.then(() => next);
+        return ready;
+    }
+}
+class MemoryTx {
+    s;
+    tenantId;
+    now;
+    closed = false;
+    events = [];
+    incarnations = [];
+    callbacks = [];
+    workAvailable = false;
+    constructor(s, tenantId, now) {
+        this.s = s;
+        this.tenantId = tenantId;
+        this.now = now;
+    }
+    check() {
+        if (this.closed)
+            throw new Error("Tx used after its transaction ended");
+    }
+    // --- documents -----------------------------------------------------------
+    async get(table, id) {
+        this.check();
+        const raw = this.s.docs[table].get(id);
+        if (raw === undefined)
+            return undefined;
+        return (table === "sessions" ? this.session(id) : JSON.parse(raw));
+    }
+    async put(table, id, body) {
+        this.check();
+        let value = body;
+        if (table === "sessions" && body && typeof body === "object") {
+            value = Object.fromEntries(Object.entries(body).filter(([key]) => !OWNERSHIP_KEYS.has(key)));
+            if (!this.s.sessionMeta.has(id))
+                this.s.sessionMeta.set(id, {
+                    owner: null,
+                    epoch: 0,
+                    ownerExpiresAt: null,
+                    nextSeq: 0,
+                });
+        }
+        const json = JSON.stringify(value);
+        if (json === undefined)
+            throw new Error("Document body must be JSON");
+        this.s.docs[table].set(id, json);
+    }
+    async delete(table, id) {
+        this.check();
+        this.s.docs[table].delete(id);
+        if (table === "sessions") {
+            this.s.sessionMeta.delete(id);
+            this.s.outbox.delete(id);
+        }
+    }
+    session(id) {
+        const raw = this.s.docs.sessions.get(id);
+        const meta = this.s.sessionMeta.get(id);
+        if (raw === undefined || !meta)
+            return undefined;
+        return {
+            ...JSON.parse(raw),
+            owner: meta.owner,
+            epoch: meta.epoch,
+            ownerExpiresAt: meta.ownerExpiresAt,
+        };
+    }
+    docs(table) {
+        return byId(this.s.docs[table]).map(([id, raw]) => [
+            id,
+            JSON.parse(raw),
+        ]);
+    }
+    sessions() {
+        return byId(this.s.docs.sessions).map(([id]) => this.session(id));
+    }
+    // --- ordering ------------------------------------------------------------
+    async lockSession(id) {
+        this.check();
+        // Transactions are serialized, so the whole store is already locked.
+        return this.session(id);
+    }
+    async event(sessionId, turnId, type, payload) {
+        this.check();
+        const meta = this.s.sessionMeta.get(sessionId);
+        if (!meta)
+            throw new Error(`Session ${sessionId} not found`);
+        const seq = meta.nextSeq++;
+        const event = JSON.parse(JSON.stringify({
+            eventId: randomUUID(),
+            sessionId,
+            tenantId: this.tenantId,
+            turnId,
+            cursor: encodeCursor(sessionId, seq),
+            createdAt: this.now().toISOString(),
+            type,
+            payload,
+        }));
+        let rows = this.s.outbox.get(sessionId);
+        if (!rows)
+            this.s.outbox.set(sessionId, (rows = new Map()));
+        rows.set(seq, JSON.stringify(event));
+        this.events.push(event);
+        const doc = JSON.parse(this.s.docs.sessions.get(sessionId));
+        this.incarnations.push(doc.streamIncarnation ?? null);
+        return copy(event);
+    }
+    afterCommit(fn) {
+        this.check();
+        this.callbacks.push(fn);
+    }
+    signalWork() {
+        this.check();
+        this.workAvailable = true;
+    }
+    // --- ownership -----------------------------------------------------------
+    async takeOwnership(sessionId, claim) {
+        this.check();
+        const meta = this.s.sessionMeta.get(sessionId);
+        if (!meta)
+            return { status: "missing" };
+        if (meta.owner !== null &&
+            meta.ownerExpiresAt !== null &&
+            Date.parse(meta.ownerExpiresAt) > claim.now.getTime())
+            return {
+                status: "busy",
+                owner: meta.owner,
+                ownerExpiresAt: meta.ownerExpiresAt,
+            };
+        const previous = {
+            owner: meta.owner,
+            epoch: meta.epoch,
+            ownerExpiresAt: meta.ownerExpiresAt,
+        };
+        meta.epoch += 1;
+        meta.owner = claim.owner;
+        meta.ownerExpiresAt = new Date(claim.now.getTime() + claim.leaseMs).toISOString();
+        return {
+            status: "owned",
+            epoch: meta.epoch,
+            takeover: previous.owner !== null,
+            previous,
+        };
+    }
+    async renewOwnership(sessionId, owner, epoch, until) {
+        this.check();
+        const meta = this.s.sessionMeta.get(sessionId);
+        if (!meta || meta.owner !== owner || meta.epoch !== epoch)
+            return false;
+        meta.ownerExpiresAt = until.toISOString();
+        return true;
+    }
+    async releaseOwnership(sessionId, owner, epoch) {
+        this.check();
+        const meta = this.s.sessionMeta.get(sessionId);
+        if (!meta || meta.owner !== owner || meta.epoch !== epoch)
+            return false;
+        meta.owner = null;
+        meta.ownerExpiresAt = null;
+        return true;
+    }
+    async assertEpoch(sessionId, epoch) {
+        this.check();
+        const session = this.session(sessionId);
+        if (!session)
+            throw new OwnershipLostError(sessionId, epoch, undefined);
+        if (session.epoch !== epoch)
+            throw new OwnershipLostError(sessionId, epoch, session.epoch);
+        return session;
+    }
+    // --- typed queries -------------------------------------------------------
+    async sessionsWithStatus(statuses) {
+        this.check();
+        return this.sessions().filter((s) => statuses.includes(s.status));
+    }
+    async orphanedSessions(now, limit) {
+        this.check();
+        const lease = (s) => s.owner === null || s.ownerExpiresAt === null
+            ? -Infinity
+            : Date.parse(s.ownerExpiresAt);
+        return this.sessions()
+            .filter((s) => OPEN_SESSION.has(s.status) && lease(s) <= now.getTime())
+            .sort((a, b) => lease(a) - lease(b) || (a.id < b.id ? -1 : 1))
+            .slice(0, limit);
+    }
+    async listSessions(filter = {}) {
+        this.check();
+        return this.sessions().filter((s) => (filter.agentId === undefined || s.agentId === filter.agentId) &&
+            (filter.ownerUserId === undefined ||
+                s.ownerUserId === filter.ownerUserId));
+    }
+    async listDefinitions() {
+        this.check();
+        return this.docs("definitions").map(([, doc]) => doc);
+    }
+    async listSandboxes() {
+        this.check();
+        return this.docs("sandboxes").map(([, doc]) => doc);
+    }
+    actions() {
+        return this.docs("actions").map(([, doc]) => doc);
+    }
+    async expiredClaims(now, limit) {
+        this.check();
+        return this.actions()
+            .filter((a) => a.status === "claimed" &&
+            a.leaseExpiresAt !== null &&
+            Date.parse(a.leaseExpiresAt) <= now.getTime())
+            .sort((a, b) => Date.parse(a.leaseExpiresAt) - Date.parse(b.leaseExpiresAt) ||
+            (a.actionId < b.actionId ? -1 : 1))
+            .slice(0, limit);
+    }
+    async pendingActions(agentId) {
+        this.check();
+        return this.actions().filter((a) => a.status === "pending" && a.agentId === agentId);
+    }
+    async actionsForSession(sessionId, filter = {}) {
+        this.check();
+        return this.actions().filter((a) => a.sessionId === sessionId &&
+            (filter.turnId === undefined || a.turnId === filter.turnId) &&
+            (filter.statuses === undefined || filter.statuses.includes(a.status)));
+    }
+    async actionsWithStatus(statuses, filter = {}) {
+        this.check();
+        return this.actions().filter((a) => statuses.includes(a.status) &&
+            (filter.kinds === undefined || filter.kinds.includes(a.kind)));
+    }
+    effects() {
+        return this.docs("effects").map(([, doc]) => doc);
+    }
+    async invokingEffects(sessionId) {
+        return this.effectsForSession(sessionId, { statuses: ["invoking"] });
+    }
+    async effectsForSession(sessionId, filter = {}) {
+        this.check();
+        return this.effects().filter((e) => e.request?.sessionId === sessionId &&
+            (filter.turnId === undefined || e.request.turnId === filter.turnId) &&
+            (filter.statuses === undefined || filter.statuses.includes(e.status)));
+    }
+    async effectsForTurn(sessionId, turnId, statuses) {
+        return this.effectsForSession(sessionId, { turnId, statuses });
+    }
+    async effectsWithStatus(statuses, filter = {}) {
+        this.check();
+        return this.effects().filter((e) => statuses.includes(e.status) &&
+            (filter.kinds === undefined || filter.kinds.includes(e.request?.kind)));
+    }
+    async linkedSessions(workflowSessionId) {
+        this.check();
+        const out = [];
+        for (const [agentSessionId, link] of this.docs("links")) {
+            if (link.workflowSessionId !== workflowSessionId)
+                continue;
+            const session = this.session(agentSessionId);
+            if (session)
+                out.push({ agentSessionId, link, session });
+        }
+        return out;
+    }
+    async counts() {
+        this.check();
+        const sessions = this.sessions();
+        return {
+            sessions: sessions.length,
+            runningSessions: sessions.filter((s) => OPEN_SESSION.has(s.status))
+                .length,
+            pendingActions: this.actions().filter((a) => a.status === "pending" || a.status === "claimed").length,
+            uncertainEffects: this.effects().filter((e) => e.status === "uncertain")
+                .length,
+            sandboxes: this.s.docs.sandboxes.size,
+            definitions: this.s.docs.definitions.size,
+        };
+    }
+    // --- outbox --------------------------------------------------------------
+    async outbox(limit, filter = {}) {
+        this.check();
+        const rows = [];
+        for (const [sessionId, bySeq] of byId(this.s.outbox)) {
+            if (filter.sessionId !== undefined && filter.sessionId !== sessionId)
+                continue;
+            for (const seq of [...bySeq.keys()].sort((a, b) => a - b)) {
+                if (rows.length >= limit)
+                    return rows;
+                rows.push({ sessionId, seq, event: JSON.parse(bySeq.get(seq)) });
+            }
+        }
+        return rows;
+    }
+    async deleteOutbox(sessionId, throughSeq, incarnation) {
+        this.check();
+        const rows = this.s.outbox.get(sessionId);
+        if (!rows)
+            return 0;
+        if (incarnation !== undefined) {
+            const doc = this.s.docs.sessions.get(sessionId);
+            if (doc === undefined ||
+                (JSON.parse(doc).streamIncarnation ?? null) !== incarnation)
+                return 0;
+        }
+        let n = 0;
+        for (const seq of [...rows.keys()])
+            if (seq <= throughSeq) {
+                rows.delete(seq);
+                n += 1;
+            }
+        if (rows.size === 0)
+            this.s.outbox.delete(sessionId);
+        return n;
+    }
+    async outboxStats() {
+        this.check();
+        let depth = 0;
+        let oldestCreatedAt = null;
+        for (const rows of this.s.outbox.values())
+            for (const body of rows.values()) {
+                depth += 1;
+                const createdAt = JSON.parse(body).createdAt;
+                if (oldestCreatedAt === null || createdAt < oldestCreatedAt)
+                    oldestCreatedAt = createdAt;
+            }
+        return { depth, oldestCreatedAt };
+    }
+    // --- executors -----------------------------------------------------------
+    async listExecutors() {
+        this.check();
+        return byId(this.s.executors).map(([, row]) => copy(row));
+    }
+    async getExecutor(agentId) {
+        this.check();
+        const row = this.s.executors.get(agentId);
+        return row && copy(row);
+    }
+    async putExecutor(row) {
+        this.check();
+        for (const other of this.s.executors.values())
+            if (other.tokenHash === row.tokenHash && other.agentId !== row.agentId)
+                throw new Error("executors.token_hash must be unique");
+        const existing = this.s.executors.get(row.agentId);
+        this.s.executors.set(row.agentId, {
+            ...copy(row),
+            createdAt: existing?.createdAt ?? row.updatedAt,
+        });
+    }
+    async deleteExecutor(agentId) {
+        this.check();
+        this.s.executors.delete(agentId);
+    }
+    // --- principals ----------------------------------------------------------
+    async insertPrincipal(row) {
+        this.check();
+        if (this.s.principals.has(row.id))
+            throw new Error("principals.id must be unique");
+        for (const other of this.s.principals.values())
+            if (other.tokenHash === row.tokenHash)
+                throw new Error("principals.token_hash must be unique");
+        this.s.principals.set(row.id, copy(row));
+    }
+    async principalByTokenHash(tokenHash) {
+        this.check();
+        for (const row of this.s.principals.values())
+            if (row.tokenHash === tokenHash)
+                return copy(row);
+        return undefined;
+    }
+    async principalById(id) {
+        this.check();
+        const row = this.s.principals.get(id);
+        return row && copy(row);
+    }
+    async applicationTokenHashes() {
+        this.check();
+        return byId(this.s.principals)
+            .filter(([, row]) => row.role === "application")
+            .map(([, row]) => row.tokenHash);
+    }
+    // --- vault ---------------------------------------------------------------
+    async insertVault(row) {
+        this.check();
+        if (this.s.vaults.has(row.id))
+            throw new Error("vaults.id must be unique");
+        if (row.scope === "host" &&
+            [...this.s.vaults.values()].some((v) => v.scope === "host"))
+            throw new Error("Only one host vault is allowed");
+        this.s.vaults.set(row.id, copy(row));
+    }
+    async getVault(id) {
+        this.check();
+        const row = this.s.vaults.get(id);
+        return row && copy(row);
+    }
+    async vaultsByOwner(ownerUserId) {
+        this.check();
+        return [...this.s.vaults.values()]
+            .filter((v) => v.ownerUserId === ownerUserId && v.scope === "user")
+            .sort(byCreated)
+            .map(copy);
+    }
+    async updateVaultMetadata(id, metadataJson) {
+        this.check();
+        const row = this.s.vaults.get(id);
+        if (row)
+            row.metadataJson = metadataJson;
+    }
+    async deleteVault(id) {
+        this.check();
+        for (const [credentialId, row] of this.s.credentials)
+            if (row.vaultId === id)
+                this.s.credentials.delete(credentialId);
+        this.s.vaults.delete(id);
+    }
+    async insertCredential(row) {
+        this.check();
+        if (this.s.credentials.has(row.id))
+            throw new Error("vault_credentials.id must be unique");
+        if (!this.s.vaults.has(row.vaultId))
+            throw new Error("vault_credentials.vault_id references a missing vault");
+        this.s.credentials.set(row.id, copy(row));
+    }
+    async getCredential(id) {
+        this.check();
+        const row = this.s.credentials.get(id);
+        return row && copy(row);
+    }
+    async credentialsForVault(vaultId, filter = {}) {
+        this.check();
+        return [...this.s.credentials.values()]
+            .filter((c) => c.vaultId === vaultId &&
+            (filter.type === undefined || c.type === filter.type))
+            .sort(byCreated)
+            .map(copy);
+    }
+    async updateCredential(vaultId, id, patch) {
+        this.check();
+        const row = this.s.credentials.get(id);
+        if (!row || row.vaultId !== vaultId)
+            return false;
+        const defined = Object.fromEntries(Object.entries(copy(patch)).filter(([, value]) => value !== undefined));
+        this.s.credentials.set(id, { ...row, ...defined });
+        return true;
+    }
+    async deleteCredential(vaultId, id) {
+        this.check();
+        const row = this.s.credentials.get(id);
+        if (!row || row.vaultId !== vaultId)
+            return false;
+        this.s.credentials.delete(id);
+        return true;
+    }
+    async countCredentials() {
+        this.check();
+        return this.s.credentials.size;
+    }
+    async insertVaultAudit(row) {
+        this.check();
+        this.s.audit.push(copy(row));
+    }
+    async vaultAudit(filter = {}) {
+        this.check();
+        return this.s.audit
+            .filter((r) => filter.vaultId === undefined || r.vaultId === filter.vaultId)
+            .slice(0, filter.limit ?? Infinity)
+            .map(copy);
+    }
+    async getVaultIdempotency(id) {
+        this.check();
+        const row = this.s.idempotency.get(id);
+        return row && copy(row);
+    }
+    async insertVaultIdempotency(row) {
+        this.check();
+        if (this.s.idempotency.has(row.id))
+            throw new Error("vault_idempotency.id must be unique");
+        this.s.idempotency.set(row.id, copy(row));
+    }
+    // --- settings ------------------------------------------------------------
+    async getSetting(key) {
+        this.check();
+        return this.s.settings.get(key);
+    }
+    async putSetting(key, value) {
+        this.check();
+        this.s.settings.set(key, value);
+    }
+    // --- reset ---------------------------------------------------------------
+    async reset(scope) {
+        this.check();
+        if (scope === "sessions" || scope === "all") {
+            for (const table of [
+                "sessions",
+                "commands",
+                "checkpoints",
+                "effects",
+                "actions",
+                "links",
+            ])
+                this.s.docs[table].clear();
+            this.s.sessionMeta.clear();
+            this.s.outbox.clear();
+        }
+        if (scope === "sandboxes" || scope === "all")
+            this.s.docs.sandboxes.clear();
+        if (scope === "all") {
+            this.s.docs.definitions.clear();
+            this.s.executors.clear();
+            for (const vault of [...this.s.vaults.values()])
+                if (vault.scope !== "host")
+                    await this.deleteVault(vault.id);
+        }
+    }
+}
+function byCreated(a, b) {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}

package/dist/store/ownership.d.ts

@@ -0,0 +1,19 @@
+import type { SessionDoc, SessionStore, StoredSession, Tx } from "./types.js";
+/**
+ * An advance's transaction found the session's epoch changed: another Worker
+ * took ownership. The advance aborts with no write (§10.6).
+ */
+export declare class OwnershipLostError extends Error {
+    readonly sessionId: string;
+    readonly expectedEpoch: number;
+    readonly actualEpoch: number | undefined;
+    readonly code = "ownership.lost";
+    constructor(sessionId: string, expectedEpoch: number, actualEpoch: number | undefined);
+}
+export declare function isOwnershipLost(error: unknown): error is OwnershipLostError;
+/**
+ * An epoch-checked transaction: locks the session, checks `epoch`, then runs
+ * `fn` with the locked session. A mismatch rejects with `OwnershipLostError`
+ * before `fn` runs, so nothing is written.
+ */
+export declare function ownedTx<T, S extends SessionDoc = SessionDoc>(store: SessionStore, sessionId: string, epoch: number, fn: (t: Tx, session: StoredSession<S>) => Promise<T>): Promise<T>;

package/dist/store/ownership.js

@@ -0,0 +1,33 @@
+/**
+ * An advance's transaction found the session's epoch changed: another Worker
+ * took ownership. The advance aborts with no write (§10.6).
+ */
+export class OwnershipLostError extends Error {
+    sessionId;
+    expectedEpoch;
+    actualEpoch;
+    code = "ownership.lost";
+    constructor(sessionId, expectedEpoch, actualEpoch) {
+        super(actualEpoch === undefined
+            ? `Session ${sessionId} is gone; ownership lost`
+            : `Session ${sessionId} is at epoch ${actualEpoch}, not ${expectedEpoch}; ownership lost`);
+        this.sessionId = sessionId;
+        this.expectedEpoch = expectedEpoch;
+        this.actualEpoch = actualEpoch;
+        this.name = "OwnershipLostError";
+    }
+}
+export function isOwnershipLost(error) {
+    return (error instanceof OwnershipLostError ||
+        (typeof error === "object" &&
+            error !== null &&
+            error.code === "ownership.lost"));
+}
+/**
+ * An epoch-checked transaction: locks the session, checks `epoch`, then runs
+ * `fn` with the locked session. A mismatch rejects with `OwnershipLostError`
+ * before `fn` runs, so nothing is written.
+ */
+export function ownedTx(store, sessionId, epoch, fn) {
+    return store.tx(async (t) => fn(t, await t.assertEpoch(sessionId, epoch)));
+}