@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/runtime/runtime.js

@@ -0,0 +1,563 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StimulusQuarantine = void 0;
+exports.startRuntime = startRuntime;
+const types_js_1 = require("./drivers/types.js");
+/**
+ * Runtime — the one subject that opens and owns the action surface.
+ *
+ * §4.3: `runtime.start` alone opens the DB, native session, model and socket;
+ * `stop` closes only what it opened. Product assembly states the paths — core
+ * never guesses `~/.mama`. This module is the socket·credential half of that
+ * subject: it issues this boot's session credential, mounts the action socket
+ * on the shared catalog/dispatch, and on `stop` releases exactly those two
+ * things. The adapter, catalog and dispatcher stay product-owned — the daemon
+ * opens its one DB and builds the one action surface, and the runtime serves
+ * them rather than opening a second stack. There is never a second start
+ * subject per profile.
+ *
+ * It is also the loop's intake. `accept` is the one door a stimulus enters by —
+ * an owner's message, a connector delta, a scheduled time — and it does exactly
+ * two things: prove the stated principal is one this runtime serves, and make
+ * the stimulus durable. It returns a receipt of acceptance and nothing more.
+ * What the stimulus MEANS, and what to do about it, is the agent's; a host that
+ * classified it here would be choosing the model's work for it.
+ *
+ * The intake is opened before the socket, for the same reason the credential
+ * table is: a producer must never reach a runtime whose intake does not exist
+ * yet.
+ *
+ * And the runtime carries what it accepted through to the loop: the claim, the
+ * lease, the retry backoff and the ack are the runtime's, so no producer has to
+ * hold a stimulus while a turn runs and no producer has to remember one that
+ * failed. What runs inside a delivery is the native session the product already
+ * has — this is the delivery half of the mailbox, never a second turn loop.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ipc_js_1 = require("../client/ipc.js");
+const mailbox_js_1 = require("./mailbox.js");
+function writeCredential(path, credential) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const temporaryPath = `${path}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    try {
+        (0, node_fs_1.writeFileSync)(temporaryPath, credential, { mode: 0o600, flag: 'wx' });
+        (0, node_fs_1.renameSync)(temporaryPath, path);
+    }
+    catch (error) {
+        (0, node_fs_1.rmSync)(temporaryPath, { force: true });
+        throw error;
+    }
+}
+/**
+ * A delivery that must NOT be tried again.
+ *
+ * Retry is the runtime's default because most failures are transient. Some are
+ * not: an external effect whose outcome is unknown cannot be replayed on a
+ * guess (§4.3), and a stimulus whose delivery already spent one must park where
+ * a person can see it rather than repeat it. Throwing this from `deliver` says
+ * exactly that — park the row dead, spend no attempt, and name it through
+ * `onDead`.
+ */
+class StimulusQuarantine extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = 'StimulusQuarantine';
+    }
+}
+exports.StimulusQuarantine = StimulusQuarantine;
+/**
+ * Opens the action surface: issues the session credential and serves
+ * `catalog`/`dispatch` on the private socket. `stop` closes the socket and
+ * removes the credential file it wrote — nothing else.
+ */
+async function startRuntime(options) {
+    const maxPerTick = options.delivery?.maxPerTick ?? 8;
+    const maxPendingInputs = options.delivery?.maxPendingInputs ?? maxPerTick;
+    if (!Number.isSafeInteger(maxPendingInputs) || maxPendingInputs < 1) {
+        throw new Error('maxPendingInputs must be a positive integer');
+    }
+    const { socketPath } = options.paths;
+    if (options.principals.length === 0) {
+        throw new Error('startRuntime requires at least one principal');
+    }
+    const paths = options.principals.map((principal) => principal.credentialPath);
+    if (new Set(paths).size !== paths.length) {
+        throw new Error('each principal needs its own credential path');
+    }
+    const ids = options.principals.map((principal) => principal.access.principalId);
+    if (new Set(ids).size !== ids.length) {
+        throw new Error('each principal needs its own principal ID');
+    }
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(socketPath), { recursive: true });
+    // Opened before the socket, for the same reason the credential table is: a
+    // producer must never reach a runtime whose intake does not exist yet.
+    const mailbox = options.mailbox
+        ? new mailbox_js_1.Mailbox(options.mailbox.adapter, ...(options.mailbox.clock ? [options.mailbox.clock] : []))
+        : undefined;
+    // Prepare the credential table before the socket, but publish files only
+    // after the socket is ours. A second start must not rotate or remove the
+    // credentials of a live runtime whose socket it failed to acquire.
+    const byCredential = new Map();
+    const byPrincipalId = new Map();
+    const credentialsToPublish = [];
+    const credentialPaths = new Set(paths);
+    const written = new Set();
+    const removeCredentials = () => {
+        for (const path of written) {
+            (0, node_fs_1.rmSync)(path, { force: true });
+        }
+        written.clear();
+    };
+    for (const principal of options.principals) {
+        const credential = (0, node_crypto_1.randomUUID)();
+        credentialsToPublish.push({ path: principal.credentialPath, credential });
+        byCredential.set(credential, principal);
+        byPrincipalId.set(principal.access.principalId, { principal, credential });
+    }
+    const mounted = await (0, ipc_js_1.createActionIpcServer)({
+        socketPath,
+        catalog: options.catalog,
+        dispatch: options.dispatch,
+        // The principal's stated run rides with whatever the host states per
+        // call. The credential selects it, so one caller's run is never another's.
+        sessionFacts: (access, request) => {
+            const stated = options.sessionFacts?.(access, request);
+            const principal = request.credential === undefined ? undefined : byCredential.get(request.credential);
+            const runEvidenceScope = principal?.runEvidenceScope;
+            if (!runEvidenceScope) {
+                return stated;
+            }
+            return { ...(stated ?? {}), runEvidenceScope };
+        },
+        reclaimStaleSocket: options.reclaimStaleSocket,
+        resolveAccess: (presented) => {
+            const principal = presented === undefined ? undefined : byCredential.get(presented);
+            if (principal === undefined) {
+                throw new Error('unresolved session credential');
+            }
+            return principal.access;
+        },
+    });
+    try {
+        for (const entry of credentialsToPublish) {
+            writeCredential(entry.path, entry.credential);
+            written.add(entry.path);
+        }
+        const requeued = mailbox?.recoverOrphanedClaims() ?? 0;
+        if (requeued > 0) {
+            console.info(`[Runtime] requeued orphaned mailbox claims count=${requeued}`);
+        }
+    }
+    catch (error) {
+        try {
+            await mounted.close();
+        }
+        finally {
+            removeCredentials();
+        }
+        throw error;
+    }
+    const servedPrincipals = new Set(options.principals.map((principal) => principal.access.principalId));
+    const delivery = options.delivery;
+    const leaseMs = delivery?.leaseMs ?? 10 * 60_000;
+    // The replay's job is to return claims that outlived their lease, and the
+    // youngest thing it can find is `leaseMs` old - so running it on every drain
+    // (once per accept, plus every tick) spends a full scan and three prunes to
+    // find nothing. Half a lease is the most often it can report anything new.
+    // The floor paces WHEN the scan runs, never whether a loss is recorded: a
+    // row that spent its attempts is dead in the store and visible in `depth()`
+    // the moment it happens. What the pacing can delay is this drain REPORTING
+    // it, on a runtime configured with a lease under a minute.
+    const replayEveryMs = Math.max(leaseMs / 2, 30_000);
+    let lastReplayAt = 0;
+    let draining = false;
+    let currentScan;
+    let stopped = false;
+    const servePrincipal = (principal) => {
+        if (stopped)
+            throw new Error('Cannot serve a principal after runtime stop');
+        const principalId = principal.access.principalId;
+        if (!principalId.trim())
+            throw new Error('Runtime principal ID is required');
+        if (byPrincipalId.has(principalId))
+            throw new Error('Runtime principal is already served');
+        if (credentialPaths.has(principal.credentialPath)) {
+            throw new Error('Runtime credential path is already served');
+        }
+        const credential = (0, node_crypto_1.randomUUID)();
+        writeCredential(principal.credentialPath, credential);
+        written.add(principal.credentialPath);
+        credentialPaths.add(principal.credentialPath);
+        byCredential.set(credential, principal);
+        byPrincipalId.set(principalId, { principal, credential });
+        servedPrincipals.add(principalId);
+    };
+    const unservePrincipal = (principalId) => {
+        if (stopped)
+            throw new Error('Cannot unserve a principal after runtime stop');
+        const served = byPrincipalId.get(principalId);
+        if (!served)
+            return;
+        byCredential.delete(served.credential);
+        byPrincipalId.delete(principalId);
+        servedPrincipals.delete(principalId);
+        (0, node_fs_1.rmSync)(served.principal.credentialPath, { force: true });
+        credentialPaths.delete(served.principal.credentialPath);
+        written.delete(served.principal.credentialPath);
+    };
+    let reconciliationCursor = 0;
+    const activeDeliveries = new Map();
+    const reportedUncertain = new Set();
+    let drainScheduled = false;
+    const scheduleDrain = () => {
+        if (stopped || drainScheduled)
+            return;
+        drainScheduled = true;
+        setImmediate(() => {
+            drainScheduled = false;
+            void drainOnce().catch(() => { });
+        });
+    };
+    const activeNativeInputs = new Map();
+    const runNative = (nativeInputId, content, request) => {
+        const run = activeNativeInputs.get(nativeInputId);
+        if (stopped || !run)
+            return Promise.reject(new Error('Native execution requires a currently active input'));
+        return run(content, request);
+    };
+    const markUncertain = async (row, reason) => {
+        // The first recorded cause stays; a later reconcile pass only re-reports it.
+        if (mailbox.nativeInputs.get(row.id)?.state !== 'uncertain') {
+            mailbox.nativeInputs.uncertain(row.id, reason);
+        }
+        if (reportedUncertain.has(row.id))
+            return;
+        reportedUncertain.add(row.id);
+        try {
+            await delivery?.onUncertain?.(row, reason);
+        }
+        catch {
+            // The unresolved dispatch remains durable even if reporting fails.
+        }
+    };
+    // A loss is the runtime's to report, and reporting it may not break the
+    // drain: the next row is still owed delivery.
+    const announceDead = async (row, reason) => {
+        if (!delivery?.onDead)
+            return;
+        try {
+            await delivery.onDead(row, reason);
+        }
+        catch {
+            // The report failed; the death is already durable in the store.
+        }
+    };
+    const deliverClaim = async (row) => {
+        const result = { delivered: 0, failed: 0, dead: 0 };
+        try {
+            if (!servedPrincipals.has(row.principalId))
+                throw new StimulusQuarantine('Input principal is no longer served');
+            const nativeDelivery = mailbox.nativeInputs.prepare(row.id);
+            if (!nativeDelivery.invocationId)
+                throw new StimulusQuarantine('Native input identity is unresolved');
+            const inputId = nativeDelivery.invocationId;
+            let invoked = false;
+            let nativeRun = null;
+            let nativeSteer = null;
+            const context = {
+                nativeInputId: inputId,
+                resultForReceipt: (receipt) => mailbox.nativeInputs.resultForReceipt(receipt, row.principalId),
+                onInputDispatch: (input) => mailbox.nativeInputs.dispatch(row.id, input),
+                onAccepted: (receipt) => {
+                    const active = activeDeliveries.get(row.id);
+                    if (!active)
+                        throw new Error('Native acknowledgement requires an active input');
+                    mailbox.nativeInputs.accept(row.id, receipt);
+                    active.accepted = true;
+                    scheduleDrain();
+                },
+                wasDispatched: () => {
+                    const record = mailbox.nativeInputs.get(row.id);
+                    if (!record)
+                        throw new Error('Native input delivery record is missing');
+                    return record.state !== 'prepared';
+                },
+                run: (content, request) => {
+                    if (stopped || activeNativeInputs.get(inputId) !== context.run) {
+                        return Promise.reject(new Error('Native execution requires a currently active input'));
+                    }
+                    if (invoked)
+                        return Promise.reject(new Error('Native session already invoked for this input'));
+                    if (!options.nativeSession?.runTurn)
+                        return Promise.reject(new StimulusQuarantine('Native session execution is not configured'));
+                    invoked = true;
+                    const observer = request?.streamCallbacks;
+                    const invoke = options.nativeSession.runTurn.bind(options.nativeSession);
+                    nativeRun = Promise.resolve()
+                        .then(() => invoke(content, {
+                        ...request,
+                        nativeInputId: inputId,
+                        streamCallbacks: {
+                            ...observer,
+                            onInputDispatch: (input) => {
+                                context.onInputDispatch(input);
+                                observer?.onInputDispatch?.(input);
+                            },
+                            onAccepted: (receipt) => {
+                                context.onAccepted(receipt);
+                                observer?.onAccepted?.(receipt);
+                            },
+                        },
+                    }))
+                        .then((nativeResult) => {
+                        if (!mailbox.nativeInputs.get(row.id)?.receipt) {
+                            mailbox.nativeInputs.uncertain(row.id, 'Native result has no accepted receipt');
+                            throw new Error('Native result has no accepted receipt');
+                        }
+                        mailbox.nativeInputs.storeResult(row.id, nativeResult);
+                        return nativeResult;
+                    });
+                    // The drain observes this rejection even if its adapter forgot to await.
+                    void nativeRun.catch(() => { });
+                    return nativeRun;
+                },
+                steer: (content, target, sessionKey) => {
+                    if (stopped || activeNativeInputs.get(inputId) !== context.run) {
+                        return Promise.reject(new Error('Native steering requires a currently active input'));
+                    }
+                    if (invoked)
+                        return Promise.reject(new Error('Native session already invoked for this input'));
+                    if (!options.nativeSession?.steer)
+                        return Promise.reject(new StimulusQuarantine('Native steering is not configured'));
+                    if (target.backend !== 'codex' ||
+                        !target.sessionId.trim() ||
+                        !target.turnId.trim() ||
+                        !sessionKey.trim()) {
+                        return Promise.reject(new Error('Native steering requires an exact Codex turn'));
+                    }
+                    if (mailbox.nativeInputs.listByReceipt(target, row.principalId, { limit: 1 }).inputIds
+                        .length === 0) {
+                        return Promise.reject(new Error('Native steering target is not accepted for this principal'));
+                    }
+                    invoked = true;
+                    const invoke = options.nativeSession.steer.bind(options.nativeSession);
+                    nativeSteer = Promise.resolve()
+                        .then(async () => {
+                        if (stopped)
+                            throw new Error('Native runtime stopped before steering dispatch');
+                        const receipt = await invoke(content, target, sessionKey, () => context.onInputDispatch({
+                            backend: 'codex',
+                            sessionId: target.sessionId,
+                            inputId,
+                        }));
+                        if (receipt.backend !== 'codex' ||
+                            receipt.sessionId !== target.sessionId ||
+                            receipt.turnId !== target.turnId) {
+                            throw new Error('Native steer receipt does not match the target turn');
+                        }
+                        context.onAccepted(receipt);
+                        return receipt;
+                    })
+                        .catch((error) => {
+                        if (error instanceof types_js_1.NativeSteeringTargetUnavailableError &&
+                            !context.wasDispatched()) {
+                            // This attempt never reached the native transport. The same claimed
+                            // input may open a fresh turn without spending a retry or duplicating IO.
+                            invoked = false;
+                            nativeSteer = null;
+                        }
+                        throw error;
+                    });
+                    void nativeSteer.catch(() => { });
+                    return nativeSteer;
+                },
+            };
+            activeNativeInputs.set(inputId, context.run);
+            try {
+                await delivery.deliver({ ...row, nativeDelivery }, context);
+            }
+            finally {
+                try {
+                    if (nativeRun)
+                        await nativeRun;
+                    if (nativeSteer)
+                        await nativeSteer;
+                }
+                finally {
+                    activeNativeInputs.delete(inputId);
+                }
+            }
+            mailbox.nativeInputs.settle(row.id);
+            result.delivered += 1;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            const native = mailbox.nativeInputs.get(row.id);
+            if (native && native.state !== 'prepared') {
+                await markUncertain(row, reason);
+                result.failed += 1;
+                return result;
+            }
+            if (error instanceof StimulusQuarantine) {
+                // The host says this one must not be tried again. No attempt is
+                // spent and no backoff applies: it parks where it can be seen.
+                mailbox.quarantine(row.id, reason);
+                result.failed += 1;
+                result.dead += 1;
+                await announceDead(row, reason);
+                return result;
+            }
+            // The host did not take it. The row is owed again under the backoff,
+            // and a row that has spent its attempts parks dead and visible -
+            // a permanent loss is never silent.
+            const outcome = mailbox.retry(row.id, reason);
+            result.failed += 1;
+            if (outcome === 'dead') {
+                result.dead += 1;
+                await announceDead(row, reason);
+            }
+        }
+        return result;
+    };
+    const drainOnce = async () => {
+        const result = { delivered: 0, failed: 0, dead: 0 };
+        if (!mailbox || !delivery || draining || stopped || delivery.ready?.() === false)
+            return result;
+        const started = [];
+        draining = true;
+        let finishScan;
+        currentScan = new Promise((resolve) => {
+            finishScan = resolve;
+        });
+        try {
+            const now = Date.now();
+            if (now - lastReplayAt >= replayEveryMs) {
+                lastReplayAt = now;
+                // These claims are still owned by live adapters, including pre-dispatch waits.
+                for (const [id, active] of activeDeliveries) {
+                    if (!active.accepted)
+                        mailbox.renewClaim(id, now);
+                }
+                const replay = mailbox.replayStaleDetailed(leaseMs, now);
+                result.dead += replay.newlyDead.length;
+                for (const dead of replay.newlyDead)
+                    await announceDead(dead, 'lease expired repeatedly');
+            }
+            const unresolved = mailbox.unsettledNative(maxPerTick, reconciliationCursor);
+            reconciliationCursor =
+                unresolved.length === maxPerTick ? unresolved[unresolved.length - 1].id : 0;
+            for (const row of unresolved) {
+                if (activeDeliveries.has(row.id) || !servedPrincipals.has(row.principalId))
+                    continue;
+                try {
+                    if ((await delivery.reconcile?.(row)) === 'settled')
+                        mailbox.nativeInputs.settle(row.id, true);
+                }
+                catch (error) {
+                    await markUncertain(row, error instanceof Error ? error.message : String(error));
+                }
+            }
+            for (let count = 0; count < maxPerTick && !stopped; count++) {
+                const waiting = [...activeDeliveries.values()].filter((active) => !active.accepted).length;
+                if (waiting >= maxPendingInputs)
+                    break;
+                const row = mailbox.claimNext(delivery.prefer ? { prefer: delivery.prefer } : {});
+                if (!row)
+                    break;
+                const completion = Promise.resolve()
+                    .then(() => deliverClaim(row))
+                    .finally(() => {
+                    activeDeliveries.delete(row.id);
+                    scheduleDrain();
+                });
+                activeDeliveries.set(row.id, { accepted: false, result: completion });
+                started.push(completion);
+            }
+        }
+        finally {
+            // Scanning/claiming is serialized; an accepted native turn's result is not the next input's gate.
+            draining = false;
+            currentScan = undefined;
+            finishScan();
+        }
+        for (const outcome of await Promise.all(started)) {
+            result.delivered += outcome.delivered;
+            result.failed += outcome.failed;
+            result.dead += outcome.dead;
+        }
+        return result;
+    };
+    // Accepting is what usually has something to deliver, so the drain follows
+    // acceptance rather than waiting for the next tick. The interval is the
+    // floor underneath it: a retry's backoff expires on nobody's accept.
+    const intervalMs = delivery?.intervalMs ?? 5_000;
+    const timer = mailbox && delivery && intervalMs > 0
+        ? setInterval(() => {
+            void drainOnce().catch(() => { });
+        }, intervalMs)
+        : undefined;
+    timer?.unref?.();
+    return {
+        runNative,
+        socketPath: mounted.socketPath,
+        ...(options.runner ? { runner: options.runner } : {}),
+        ...(mailbox ? { mailbox } : {}),
+        accept: (stimulus) => {
+            if (!mailbox) {
+                throw new Error('runtime.accept requires a mailbox store stated at start');
+            }
+            if (!(0, mailbox_js_1.isStimulusKind)(stimulus.kind)) {
+                throw new Error(`runtime.accept: unknown stimulus kind "${String(stimulus.kind)}"`);
+            }
+            if (!servedPrincipals.has(stimulus.principalId)) {
+                throw new Error(`runtime.accept: principal "${stimulus.principalId}" is not served here`);
+            }
+            if (stimulus.channelKey.trim() === '') {
+                throw new Error('runtime.accept requires the stimulus channel identity');
+            }
+            const rowId = mailbox.enqueue(stimulus);
+            if (rowId !== null && delivery) {
+                // After the row is durable, never before: a producer's receipt must
+                // mean "kept", and a drain that ran first could ack what was never
+                // written.
+                scheduleDrain();
+            }
+            return rowId === null
+                ? { inputId: null, state: 'duplicate' }
+                : { inputId: String(rowId), state: 'accepted' };
+        },
+        drainOnce,
+        ...(options.nativeSession
+            ? {
+                nativeSession: {
+                    stop: () => options.nativeSession.stop(),
+                    resetSession: async (sessionKey) => {
+                        if (!options.nativeSession.resetSession)
+                            throw new Error('Native session reset is not configured');
+                        await options.nativeSession.resetSession(sessionKey);
+                    },
+                },
+            }
+            : {}),
+        principalFor: (credential) => credential === undefined ? undefined : byCredential.get(credential),
+        servesPrincipal: (principalId) => servedPrincipals.has(principalId),
+        servePrincipal,
+        unservePrincipal,
+        stop: async () => {
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            // The harness goes before the socket: a turn still running holds action
+            // calls, and closing the door under it would fail it on the way out.
+            await options.nativeSession?.stop();
+            await currentScan;
+            // Result/outbox writers still own their claims until their adapters finish.
+            await Promise.allSettled([...activeDeliveries.values()].map((active) => active.result));
+            await mounted.close();
+            removeCredentials();
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map