keri-ts 0.10.0 → 0.10.2

package/esm/keri/npm/src/app/agent-runtime.js

@@ -0,0 +1,430 @@
+import { spawn } from "effection";
+import { Deck } from "../core/deck.js";
+import { CREDENTIAL_MAILBOX_TOPIC, DELEGATE_MAILBOX_TOPIC, RECEIPT_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC, REPLY_MAILBOX_TOPIC, } from "../core/mailbox-topics.js";
+import { createReger, Reger } from "../db/reger.js";
+import { Regery } from "../vdr/credentialing.js";
+import { Tevery } from "../vdr/eventing.js";
+import { Authenticator } from "./authenticating.js";
+import { loadChallengeHandlers } from "./challenging.js";
+import { cueDo, processCuesOnce } from "./cue-runtime.js";
+import { Anchorer, loadDelegationHandlers } from "./delegating.js";
+import { ForwardHandler, MailboxPoller, mailboxTopicForRoute, Poster, } from "./forwarding.js";
+import { loadMultisigHandlers } from "./grouping.js";
+import { loadIpexHandlers } from "./ipexing.js";
+import { MailboxDirector } from "./mailbox-director.js";
+import { openMailboxerForHabery } from "./mailboxing.js";
+import { Notifier, openNoterForHabery } from "./notifying.js";
+import { isWellKnownOobiUrl, loadOobiHandlers, Oobiery, parseOobiUrl } from "./oobiery.js";
+import { QueryCoordinator } from "./querying.js";
+import { Reactor } from "./reactor.js";
+import { Respondant } from "./respondant.js";
+import { resolveRuntimeServices } from "./runtime-services.js";
+import { runtimeTurn } from "./runtime-turn.js";
+import { Signaler } from "./signaling.js";
+import { Verifier } from "./verifying.js";
+/**
+ * Create the shared runtime composition root used by CLI commands and
+ * `tufa agent`.
+ *
+ * Construction rule:
+ * - every host mode uses the same shared cue deck and the same component
+ *   classes
+ * - hosting style changes where the runtime is run, not what it is
+ */
+export function* createAgentRuntime(hby, options = {}) {
+    const mode = options.mode ?? "local";
+    const services = resolveRuntimeServices(options.services);
+    const enableMailboxStore = options.enableMailboxStore ?? mode === "indirect";
+    const mailboxer = options.mailboxer
+        ?? (enableMailboxStore ? (yield* openMailboxerForHabery(hby)) : null);
+    const ownsMailboxer = options.mailboxer === undefined && mailboxer !== null;
+    const signaler = options.signaler
+        ?? options.notifier?.signaler
+        ?? (hby.signator ? new Signaler() : null);
+    const noter = options.noter
+        ?? options.notifier?.noter
+        ?? (!hby.readonly && hby.signator ? (yield* openNoterForHabery(hby)) : null);
+    const ownsNoter = options.noter === undefined
+        && options.notifier === undefined
+        && noter !== null;
+    const notifier = options.notifier
+        ?? (noter && signaler ? new Notifier(hby, { noter, signaler }) : null);
+    const cues = new Deck();
+    const vdr = { ...(options.vdr ?? {}) };
+    let ownsReger = false;
+    if (!vdr.reger && !hby.readonly) {
+        vdr.reger = yield* createReger({
+            name: hby.name,
+            base: hby.base,
+            temp: hby.temp,
+            headDirPath: hby.headDirPath,
+            compat: hby.compat,
+        });
+        ownsReger = true;
+    }
+    const reger = vdr.reger instanceof Reger ? vdr.reger : null;
+    if (reger && !vdr.tvy) {
+        vdr.tvy = new Tevery({ db: hby.db, reger, cues });
+    }
+    if (reger && !vdr.vry) {
+        vdr.vry = new Verifier(hby, { reger, cues });
+    }
+    if (reger && vdr.tvy instanceof Tevery && vdr.vry instanceof Verifier && !vdr.rgy) {
+        vdr.rgy = new Regery(hby, {
+            reger,
+            tvy: vdr.tvy,
+            vry: vdr.vry,
+            cues,
+        });
+    }
+    const reactor = new Reactor(hby, { cues, vdr });
+    loadChallengeHandlers(hby.db, reactor.exchanger);
+    loadDelegationHandlers(hby, reactor.exchanger, notifier);
+    loadOobiHandlers(hby, reactor.exchanger, notifier);
+    loadMultisigHandlers(hby, reactor.exchanger, { notifier });
+    loadIpexHandlers(hby, reactor.exchanger, { notifier });
+    const mailboxDirector = new MailboxDirector(hby, mailboxer ? { mailboxer } : {});
+    const poster = new Poster(hby, { mailboxer, services });
+    const respondant = new Respondant(hby, { poster, mailboxDirector });
+    if (mailboxer) {
+        reactor.exchanger.addHandler(new ForwardHandler(mailboxDirector));
+    }
+    for (const route of reactor.exchanger.routes.keys()) {
+        if (route === ForwardHandler.resource) {
+            continue;
+        }
+        const topic = mailboxTopicForRoute(route);
+        if (topic.length > 0) {
+            mailboxDirector.registerTopic(topic);
+        }
+    }
+    const mailboxPoller = new MailboxPoller(hby, mailboxDirector, {
+        services,
+        pollTransport: options.mailboxPollTransport,
+        mailboxAdmission: options.mailboxAdmission,
+    });
+    for (const topic of [
+        DELEGATE_MAILBOX_TOPIC,
+        CREDENTIAL_MAILBOX_TOPIC,
+        RECEIPT_MAILBOX_TOPIC,
+        REPLAY_MAILBOX_TOPIC,
+        REPLY_MAILBOX_TOPIC,
+    ]) {
+        mailboxDirector.registerTopic(topic);
+    }
+    const querying = new QueryCoordinator(hby);
+    const delegating = new Anchorer(hby, { poster, querying });
+    const oobiery = new Oobiery(hby, reactor, { cues, services });
+    oobiery.registerReplyRoutes(reactor.router);
+    const authenticator = new Authenticator(hby, { services });
+    return {
+        hby,
+        mode,
+        mailboxer,
+        noter,
+        notifier,
+        signaler,
+        cues,
+        reactor,
+        oobiery,
+        authenticator,
+        mailboxDirector,
+        respondant,
+        mailboxPoller,
+        poster,
+        delegating,
+        querying,
+        vdr,
+        services,
+        *close() {
+            if (ownsNoter && noter?.opened) {
+                yield* noter.close();
+            }
+            if (ownsMailboxer && mailboxer?.opened) {
+                yield* mailboxer.close();
+            }
+            if (ownsReger && reger?.opened) {
+                yield* reger.close(hby.temp);
+            }
+        },
+    };
+}
+/**
+ * Queue one CESR/KERI message byte sequence for runtime parsing.
+ *
+ * This is the supported ingress seam for both local synthetic messages and
+ * remotely fetched OOBI material.
+ */
+export function ingestKeriBytes(runtime, bytes) {
+    runtime.reactor.ingest(bytes);
+}
+/**
+ * Queue one OOBI resolution job through the durable OOBI component.
+ *
+ * Unlike the older bootstrap runtime, this no longer stages jobs on a root
+ * in-memory deck. The authoritative queue is the `oobis.` database family.
+ */
+export function enqueueOobi(runtime, job) {
+    runtime.oobiery.resolve(job.url, job.alias);
+}
+/**
+ * Parse and settle one or more newly arrived KERI/CESR messages immediately.
+ *
+ * This is the shared ingress-settlement seam for mailbox-delivered batches and
+ * HTTP request payloads that should advance parser and escrow state together.
+ *
+ * Maintainer mental model:
+ * - this helper is intentionally route-policy-free
+ * - callers decide whether a message should be treated as `local` or ordinary
+ *   remote ingress before calling it
+ * - once called, it always does the same two things: feed the parser and run
+ *   one escrow replay turn
+ *
+ * Why `local` matters:
+ * - `local` is not an HTTP transport detail
+ * - it is a parser/runtime semantic switch used when the host is acting as the
+ *   local controller or local witness for the received message
+ * - witness hosting relies on that distinction so accepted witness-targeted
+ *   events emit witness cues rather than ordinary remote receipt cues
+ */
+export function settleRuntimeIngress(runtime, messages, { local, } = {}) {
+    for (const message of messages) {
+        runtime.reactor.processChunk(message, { local });
+    }
+    runtime.reactor.processEscrowsOnce();
+}
+/**
+ * Settle one mailbox retrieval batch while preserving per-source boundaries.
+ *
+ * Local and remote poll results are intentionally processed batch-by-batch so
+ * follow-on escrow progress can occur before the next source is consumed.
+ */
+export function settleMailboxPollBatch(runtime, batch) {
+    for (const message of batch.messages) {
+        runtime.reactor.processCompleteChunk(message);
+    }
+    runtime.reactor.processEscrowsOnce();
+}
+/**
+ * Drain one bounded mailbox polling turn and settle each returned batch.
+ *
+ * This keeps mailbox polling ownership inside the shared runtime surface so
+ * commands do not need to know how mailbox ingress is parsed and escrowed.
+ */
+export function* processMailboxTurn(runtime, options = {}) {
+    runtime.mailboxPoller.configure({ hab: options.hab });
+    const batches = yield* runtime.mailboxPoller.processOnce({
+        budgetMs: options.budgetMs,
+    });
+    for (const batch of batches) {
+        settleMailboxPollBatch(runtime, batch);
+    }
+    return batches;
+}
+/**
+ * Drain one bounded runtime turn by delegating to component-owned flows.
+ *
+ * Turn order:
+ * 1. `Reactor.processOnce()` drains queued ingress
+ * 2. `Oobiery.processOnce()` resolves at most one durable OOBI record
+ * 3. `Authenticator.processOnce()` advances one well-known auth step
+ * 4. `processCuesOnce()` emits cues from fresh ingress/OOBI work into
+ *    `QueryCoordinator`
+ * 5. `QueryCoordinator.processPending()` resolves any newly correspondence-ready
+ *    query work
+ * 6. `Reactor.processEscrowsOnce()` runs KEL and reply escrow passes
+ * 7. `processCuesOnce()` emits cues created during escrow progress
+ * 8. `QueryCoordinator.processPending()` resolves any follow-on query work
+ *
+ * This helper remains because command-local CLI flows and focused tests need a
+ * single deterministic step without having to spawn the long-lived doers.
+ */
+export function* processRuntimeTurn(runtime, options = {}) {
+    runtime.querying.configure({ hab: options.hab, sink: options.sink });
+    runtime.reactor.processOnce();
+    yield* runtime.oobiery.processOnce();
+    yield* runtime.authenticator.processOnce();
+    yield* runtime.poster.processPending();
+    yield* runtime.delegating.processAllOnce();
+    runtime.signaler?.processOnce();
+    if (options.pollMailbox ?? true) {
+        yield* processMailboxTurn(runtime, { hab: options.hab });
+    }
+    yield* processCuesOnce(runtime, { ...options, sink: runtime.querying });
+    yield* runtime.querying.processPending();
+    runtime.reactor.processEscrowsOnce();
+    yield* runtime.delegating.processAllOnce();
+    yield* processCuesOnce(runtime, { ...options, sink: runtime.querying });
+    yield* runtime.querying.processPending();
+}
+/**
+ * Return the current pending-work summary for bounded command-local hosts.
+ *
+ * `queriesPending` is part of convergence because query continuations may still
+ * owe a follow-on `logs` query or local catch-up wait after normal cue decks
+ * and ingress have drained.
+ */
+export function runtimePendingState(runtime) {
+    return {
+        ingress: !runtime.reactor.ingress.empty,
+        cues: !runtime.cues.empty,
+        replyEscrow: runtime.hby.db.rpes.cnt() > 0,
+        oobiQueued: runtime.hby.db.oobis.cnt() > 0,
+        oobiInFlight: runtime.hby.db.coobi.cnt() > 0,
+        multiPending: runtime.hby.db.moobi.cnt() > 0,
+        authQueued: runtime.hby.db.woobi.cnt() > 0,
+        authInFlight: runtime.hby.db.mfa.cnt() > 0,
+        outboxPending: runtime.poster.hasPendingWork(),
+        delegationPending: runtime.hby.db.dpwe.cnt() > 0
+            || runtime.hby.db.dune.cnt() > 0
+            || runtime.hby.db.dpub.cnt() > 0,
+        queriesPending: runtime.querying.hasPendingWork(),
+    };
+}
+/** Return true when any command-local runtime work remains in flight. */
+export function runtimeHasPendingWork(runtime) {
+    const state = runtimePendingState(runtime);
+    return state.ingress || state.cues || state.replyEscrow
+        || state.oobiQueued || state.oobiInFlight || state.multiPending
+        || state.authQueued || state.authInFlight || state.outboxPending
+        || state.delegationPending
+        || state.queriesPending;
+}
+/** Return true when a well-known URL has been authorized into `wkas.`. */
+export function runtimeHasWellKnownAuth(runtime, url) {
+    const cid = parseOobiUrl(url).cid;
+    if (!cid) {
+        return false;
+    }
+    return runtime.hby.db.wkas.get(cid).some((record) => record.url === url);
+}
+/** Return the current terminal state projection for one requested OOBI URL. */
+export function runtimeOobiTerminalState(runtime, url) {
+    if (isWellKnownOobiUrl(url)) {
+        const record = runtime.hby.db.rmfa.get(url);
+        if (!record) {
+            return { status: "pending", via: "none", record: null };
+        }
+        return {
+            status: record.state === "resolved" ? "resolved" : "failed",
+            via: "rmfa",
+            record,
+        };
+    }
+    const failed = runtime.hby.db.eoobi.get(url);
+    if (failed) {
+        return { status: "failed", via: "eoobi", record: failed };
+    }
+    const resolved = runtime.hby.db.roobi.get(url);
+    if (resolved) {
+        return { status: "resolved", via: "roobi", record: resolved };
+    }
+    return { status: "pending", via: "none", record: null };
+}
+/**
+ * Return true once one requested OOBI has reached a terminal state and all
+ * related runtime work has drained.
+ */
+export function runtimeOobiConverged(runtime, url) {
+    return runtimeOobiTerminalState(runtime, url).status !== "pending"
+        && !runtimeHasPendingWork(runtime);
+}
+/**
+ * Drive the shared runtime until the caller-provided completion predicate
+ * succeeds or the bounded turn budget is exhausted.
+ */
+export function* processRuntimeUntil(runtime, done, options = {}) {
+    const maxTurns = options.maxTurns ?? 64;
+    for (let turn = 0; turn < maxTurns; turn++) {
+        if (done()) {
+            return;
+        }
+        yield* processRuntimeTurn(runtime, options);
+        if (done()) {
+            return;
+        }
+        if (!runtimeHasPendingWork(runtime)) {
+            yield* runtimeTurn();
+        }
+    }
+    throw new Error(`Runtime did not converge within ${maxTurns} turns.`);
+}
+/**
+ * Yield cooperatively back to the host scheduler between runtime turns.
+ *
+ * Re-exported here because earlier Gate E helpers imported the scheduler
+ * boundary from `agent-runtime.ts`, and the boundary still conceptually belongs
+ * to the shared runtime surface even though components use it internally too.
+ */
+export { runtimeTurn } from "./runtime-turn.js";
+/**
+ * Run the shared runtime continuously until the surrounding host halts it.
+ *
+ * Component/doer model:
+ * - `Reactor.msgDo()` owns continuous ingress draining
+ * - `Reactor.escrowDo()` owns continuous escrow reprocessing
+ * - `Oobiery.oobiDo()` owns durable OOBI resolution
+ * - `Authenticator.authDo()` owns well-known auth convergence
+ * - `QueryCoordinator.queryDo()` owns deferred query correspondence work
+ *
+ * The root itself now acts as a composition host: it starts the component
+ * doers and stays alive until the surrounding Effection scope halts.
+ */
+export function* runAgentRuntime(runtime, options = {}) {
+    runtime.querying.configure({ hab: options.hab, sink: options.sink });
+    runtime.mailboxPoller.configure({ hab: options.hab });
+    const tasks = [
+        yield* spawn(function* () {
+            yield* runtime.reactor.msgDo();
+        }),
+        yield* spawn(function* () {
+            yield* cueDo(runtime, { ...options, sink: runtime.querying });
+        }),
+        yield* spawn(function* () {
+            yield* runtime.reactor.escrowDo();
+        }),
+        yield* spawn(function* () {
+            yield* runtime.oobiery.oobiDo();
+        }),
+        yield* spawn(function* () {
+            yield* runtime.authenticator.authDo();
+        }),
+        ...(runtime.signaler
+            ? [
+                yield* spawn(function* () {
+                    yield* runtime.signaler.signalDo();
+                }),
+            ]
+            : []),
+        yield* spawn(function* () {
+            while (true) {
+                yield* runtime.poster.processPending();
+                yield* runtimeTurn();
+            }
+        }),
+        yield* spawn(function* () {
+            yield* runtime.mailboxPoller.pollDo((batch) => {
+                settleMailboxPollBatch(runtime, batch);
+            });
+        }),
+        yield* spawn(function* () {
+            while (true) {
+                yield* runtime.delegating.processAllOnce();
+                yield* runtimeTurn();
+            }
+        }),
+        yield* spawn(function* () {
+            yield* runtime.querying.queryDo();
+        }),
+    ];
+    try {
+        while (true) {
+            yield* runtimeTurn();
+        }
+    }
+    finally {
+        for (const task of tasks.reverse()) {
+            yield* task.halt();
+        }
+    }
+}