keri-ts 2.1.0 → 2.2.1

package/esm/keri/npm/src/cli/identity/delegate.js

@@ -1,158 +1,16 @@
-/**
- * Delegator-side CLI approval for pending delegated events.
- *
- * KERIpy correspondence:
- * - this is the bounded command analogue of KLI's delegation approval flow
- * - pending work is discovered from durable `delegables.` escrow, not from
- *   controller notifications
- *
- * Maintainer rule:
- * - `/delegate/request` notifications are UI hints only
- * - approval ordering and event selection come from the delegated-event escrows
- *   and the delegator's own KEL state
- */
-import { Diger } from "cesr-ts";
-import { call, race, sleep, spawn } from "effection";
-import { runAgentRuntime } from "../../app/runtime/agent-runtime.js";
 import { ValidationError } from "../../core/errors.js";
-import { dgKey } from "../../db/core/keys.js";
-import { parseBooleanOption, parseStringListOption, parseStringOption } from "../common/parsing.js";
-import { createExchangeMessage } from "../../app/exchanges/exchange-messaging.js";
-import { groupSigningMembers, isLocalGroupHab, localGroupMember } from "../../app/identity/endpoint-roleing.js";
+import { parseBooleanOption, parseNumberOption, parseStringListOption, parseStringOption, } from "../common/parsing.js";
+import { approveDelegation, DELEGATION_APPROVAL_TIMEOUT_MS, proposeGroupDelegationApproval, requestDelegatedEvent, settleDelegationApproval, waitForDelegationAnchor, waitForDelegationApproval, waitForPendingDelegation, } from "../../app/identity/delegation-approval.js";
+import { isLocalGroupHab, localGroupMember } from "../../app/identity/endpoint-roleing.js";
 import { MULTISIG_IXN_ROUTE } from "../../app/multisig/grouping.js";
-import { SeqNoQuerier } from "../../app/queries/querying.js";
-import { runtimeTurn } from "../../app/runtime/runtime-turn.js";
-import { WitnessReceiptor } from "../../app/witness/receipting.js";
 import { withHabAndAgentRuntime } from "../common/context.js";
+import { withRuntimeWorkers } from "../common/runtime-workers.js";
 import { resolveWitnessAuths } from "../common/witness-auth.js";
-/** Return pending delegated events for one local delegator, oldest first. */
-function pendingDelegations(hby, delegatorPre) {
-    const pending = [];
-    for (const [keys, said] of hby.db.delegables.getTopItemIter()) {
-        const pre = keys[0];
-        if (!pre) {
-            continue;
-        }
-        const serder = hby.db.getEvtSerder(pre, said);
-        if (!serder) {
-            continue;
-        }
-        const sourcePrefix = delegationSourcePrefix(hby, serder, pre);
-        if (sourcePrefix !== delegatorPre) {
-            continue;
-        }
-        pending.push(serder);
-    }
-    return pending.sort((left, right) => (left.sn ?? 0) - (right.sn ?? 0));
-}
-/** Determine the delegator prefix for `dip` or `drt` escrow material. */
-function delegationSourcePrefix(hby, serder, pre) {
-    if (serder.delpre) {
-        return serder.delpre;
-    }
-    if (serder.ilk !== "drt") {
-        return undefined;
-    }
-    const delegatedPre = serder.pre ?? pre;
-    return hby.db.getKever(delegatedPre)?.delpre
-        ?? hby.db.getState(delegatedPre)?.di;
-}
-/** Project a delegated event into the seal embedded by the approving event. */
-function anchorData(serder) {
-    if (!serder.pre || !serder.snh || !serder.said) {
-        throw new ValidationError("Delegated event is missing pre, sn, or said.");
-    }
-    return { i: serder.pre, s: serder.snh, d: serder.said };
-}
-function approvingEvent(hby, serder, delegator) {
-    return hby.db.fetchLastSealingEventByEventSeal(delegator.pre, anchorData(serder));
-}
-/** Resolve delegate witnesses for either delegated inception or rotation. */
-function delegateWitnesses(hby, serder) {
-    if ((serder.sn ?? 0) === 0) {
-        return [...serder.backs];
-    }
-    if (!serder.pre) {
-        return [];
-    }
-    return [...(hby.db.getKever(serder.pre)?.wits ?? [])];
-}
-/** Return true once the delegated event has left escrow and reached local state. */
-function delegateCommitted(hby, serder) {
-    if (!serder.pre) {
-        return false;
-    }
-    const kever = hby.db.getKever(serder.pre);
-    return kever !== undefined && kever !== null && kever.sn >= (serder.sn ?? 0);
-}
-/** Build a witness log query used to pull delegate-side completion material. */
-function delegateWitnessLogsQuery(hab, serder, witness) {
-    if (!serder.pre || !serder.snh) {
-        throw new ValidationError("Delegated event is missing pre or sn for query.");
-    }
-    return {
-        pre: serder.pre,
-        signer: hab.pre,
-        src: witness,
-        route: "logs",
-        q: { fn: "0", s: serder.snh },
-        wits: [witness],
-    };
-}
-/**
- * Publish group delegation approval to remote signing members before advancing the workflow.
- *
- * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
- * @param hby Borrowed local identities and accepted-state stores.
- * @param groupHab Group approving habitat.
- * @param message Signed approving interaction to embed for remote members.
- * @returns Successful delivery URLs after each concrete Poster outcome.
- */
-function* publishGroupDelegationApproval(runtime, hby, groupHab, message) {
-    const member = localGroupMember(hby, groupHab.pre);
-    const smids = groupSigningMembers(hby, groupHab.pre);
-    const deliveries = [];
-    for (const recipient of smids) {
-        if (recipient === member.pre || hby.habs.has(recipient)) {
-            continue;
-        }
-        const { msg } = createExchangeMessage(member, {
-            dest: recipient,
-            route: MULTISIG_IXN_ROUTE,
-            payload: { gid: groupHab.pre, smids },
-            embeds: { ixn: message },
-        });
-        const postman = runtime.postman;
-        const evt = postman.send({ src: member.pre, dest: recipient, topic: "multisig", msg }, { notify: true });
-        const result = yield* postman.wait(evt);
-        if (result.kin === "failed")
-            throw result.error;
-        deliveries.push(...result.deliveries);
-    }
-    return deliveries;
-}
-function eventAccepted(hby, serder) {
-    return !!serder.pre && serder.said !== undefined
-        && hby.db.kels.getLast(serder.pre, serder.sn ?? 0) === serder.said;
-}
-function pinApprovalSeal(hby, hab, delegated, approving) {
-    if (!approving.sner || !approving.said || !delegated.pre || !delegated.said) {
-        throw new ValidationError("Approving event material is incomplete.");
-    }
-    hby.db.aess.pin(dgKey(delegated.pre, delegated.said), [
-        approving.sner,
-        new Diger({ qb64: approving.said }),
-    ]);
-    hab.kvy.processEscrowDelegables();
-}
-/** Observe approval state while the command's host workers own background progress. */
-function* waitForDelegation(done, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (!done()) {
-        if (Date.now() >= deadline)
-            throw new Error(`Runtime did not converge within ${timeoutMs}ms.`);
-        yield* runtimeTurn();
-    }
+/** Wall-clock budget for the request and anchor waits; `--timeout` seconds, else the library default. */
+function waitBudgetMs(confirmArgs) {
+    return confirmArgs.timeoutSeconds === undefined
+        ? DELEGATION_APPROVAL_TIMEOUT_MS
+        : confirmArgs.timeoutSeconds * 1000;
 }
 /**
  * Approve pending events without starting or serially driving background workers.
@@ -164,11 +22,12 @@ function* waitForDelegation(done, timeoutMs) {
  */
 function* performDelegationApproval(hby, hab, runtime, confirmArgs) {
     const interactionApproval = confirmArgs.interact ?? false;
-    yield* waitForDelegation(() => pendingDelegations(hby, hab.pre).length > 0, 15_000);
-    const pending = pendingDelegations(hby, hab.pre);
-    if (pending.length === 0) {
-        throw new ValidationError(`No delegated events are awaiting approval for ${hab.pre}.`);
+    const timeoutMs = waitBudgetMs(confirmArgs);
+    const waited = yield* waitForPendingDelegation(hby, { delegator: hab.pre }, { timeoutMs });
+    if (waited.outcome === "timed-out") {
+        throw new ValidationError(`No delegated events are awaiting approval for ${hab.pre} after ${timeoutMs}ms.`);
     }
+    const pending = waited.status;
     if (pending.length > 1 && !confirmArgs.auto) {
         throw new ValidationError(`Multiple delegated events are awaiting approval for ${hab.pre}. Re-run with --auto to approve them in order.`);
     }
@@ -177,109 +36,75 @@ function* performDelegationApproval(hby, hab, runtime, confirmArgs) {
         promptMissing: confirmArgs.authenticate ?? false,
     });
     const selected = confirmArgs.auto ? pending : [pending[0]];
-    for (const serder of selected) {
-        const anchor = anchorData(serder);
+    const deps = {
+        hby,
+        protocol: runtime.protocol,
+        http: runtime.http,
+        clock: runtime.clock,
+        querying: runtime.querying,
+    };
+    for (const request of selected) {
         if (isLocalGroupHab(hby, hab)) {
-            if (!interactionApproval) {
-                throw new ValidationError("Multisig delegated approval currently requires --interact.");
-            }
-            const approving = approvingEvent(hby, serder, hab);
-            if (!approving) {
-                const created = hby.interactGroupHab(confirmArgs.alias, undefined, { data: [anchor] });
-                const deliveries = yield* publishGroupDelegationApproval(runtime, hby, created.hab, created.message);
-                console.log(JSON.stringify({
-                    status: eventAccepted(hby, created.serder) ? "accepted" : "multisig-pending",
-                    route: MULTISIG_IXN_ROUTE,
-                    group: created.hab.pre,
-                    delegated: serder.pre,
-                    said: serder.said,
-                    anchor: created.serder.said,
-                    deliveries,
-                }));
-                continue;
-            }
-            const witnesses = delegateWitnesses(hby, serder).sort();
-            const selectedWitness = witnesses[0];
-            const member = localGroupMember(hby, hab.pre);
-            pinApprovalSeal(hby, hab, serder, approving);
-            if (!delegateCommitted(hby, serder) && selectedWitness) {
-                runtime.querying.enqueue(delegateWitnessLogsQuery(member, serder, selectedWitness));
-                yield* waitForDelegation(() => delegateCommitted(hby, serder), 30_000);
-            }
-            pinApprovalSeal(hby, hab, serder, approving);
-            if (serder.pre && serder.said) {
-                const stillPending = hby.db.delegables.get([serder.pre]).includes(serder.said);
-                if (stillPending) {
-                    throw new ValidationError(`Delegated event ${serder.said} remained in delegables escrow after approval.`);
-                }
-            }
-            console.log(`Approved delegated ${serder.ilk} ${serder.said ?? ""} for ${serder.pre ?? ""} using multisig ixn.`);
+            yield* approveGroupDelegation(hby, hab, runtime, confirmArgs, request, auths);
             continue;
         }
-        // KERIpy permits either interaction or rotation approval. Keep this
-        // explicit because the chosen approving event type affects later
-        // replay, but the embedded anchor seal is the same.
-        if (interactionApproval) {
-            hab.interact({ data: [anchor] });
-        }
-        else {
-            hab.rotate({ data: [anchor] });
-        }
-        if (hab.kever?.wits.length) {
-            const witDoer = new WitnessReceiptor(hby, runtime.protocol, runtime.http, runtime.clock);
-            yield* witDoer.submit(hab.pre, {
-                sn: hab.kever.sn,
-                auths,
-            });
-        }
-        const approving = hby.db.getEvtSerder(hab.pre, hab.kever.said);
-        if (!approving) {
-            throw new ValidationError("Approving event material is incomplete.");
-        }
-        const witnesses = delegateWitnesses(hby, serder).sort();
-        const selectedWitness = witnesses[0];
-        if (selectedWitness) {
-            // Witnessed delegates must prove the delegated event is committed
-            // locally before we pin `aess.` and retry delegated unescrow. Doing
-            // it earlier can make local state look approved but incomplete.
-            runtime.querying.enqueue(delegateWitnessLogsQuery(hab, serder, selectedWitness));
-            yield* waitForDelegation(() => delegateCommitted(hby, serder), 30_000);
-        }
-        else {
-            // No delegate witness exists to query. Process the local delegable
-            // after the delegator has anchored approval; the delegate still
-            // discovers approval through its own delegator-KEL query path.
-            pinApprovalSeal(hby, hab, serder, approving);
-            const observed = yield* race([
-                call(function* () {
-                    yield* new SeqNoQuerier(hby.db, runtime.querying, serder.pre, serder.sn ?? 0, {
-                        signer: hab.pre,
-                    }).queryDo();
-                    return true;
-                }),
-                call(function* () {
-                    yield* sleep(30_000);
-                    return false;
-                }),
-            ]);
-            if (!observed)
-                throw new Error("Runtime did not converge within 30000ms.");
-        }
-        // Match KERIpy sequencing: only record the approving seal and retry
-        // delegated unescrow after the delegate event has been observed as
-        // locally committed through the witness-backed query/replay path.
-        if (selectedWitness) {
-            pinApprovalSeal(hby, hab, serder, approving);
+        yield* approveDelegation(deps, request, {
+            event: interactionApproval ? "ixn" : "rot",
+            auths,
+        });
+        const result = yield* waitForDelegationApproval({ db: hby.db, settle: () => settleDelegationApproval(deps, request) }, request, { timeoutMs: 30_000 });
+        if (result.outcome === "timed-out") {
+            throw new Error(`Runtime did not converge within ${result.timeoutMs}ms.`);
         }
-        if (serder.pre && serder.said) {
-            const stillPending = hby.db.delegables.get([serder.pre]).includes(serder.said);
-            if (stillPending) {
-                throw new ValidationError(`Delegated event ${serder.said} remained in delegables escrow after approval.`);
-            }
+        if (hby.db.delegables.get([request.delegate]).includes(request.said)) {
+            throw new ValidationError(`Delegated event ${request.said} remained in delegables escrow after approval.`);
         }
-        console.log(`Approved delegated ${serder.ilk} ${serder.said ?? ""} for ${serder.pre ?? ""} using ${interactionApproval ? "ixn" : "rot"}.`);
+        console.log(`Approved delegated ${request.ilk} ${request.said} for ${request.delegate} using ${interactionApproval ? "ixn" : "rot"}.`);
     }
 }
+/**
+ * Group delegator approval: propose the anchoring interaction the first time; once the
+ * group's KEL holds the anchor (the other members approved it), ask for the delegate's event.
+ */
+function* approveGroupDelegation(hby, hab, runtime, confirmArgs, request, auths) {
+    if (!confirmArgs.interact) {
+        throw new ValidationError("Multisig delegated approval currently requires --interact.");
+    }
+    const deps = {
+        hby,
+        protocol: runtime.protocol,
+        http: runtime.http,
+        clock: runtime.clock,
+        querying: runtime.querying,
+    };
+    const timeoutMs = waitBudgetMs(confirmArgs);
+    const sent = yield* proposeGroupDelegationApproval({ hby, protocol: runtime.protocol, postman: runtime.postman, counselor: runtime.counselor }, request, { auths, fallbackAfterMs: 0 });
+    if (sent) {
+        console.log(JSON.stringify({
+            status: hby.db.kels.getLast(sent.group, sent.event.sn) === sent.event.said ? "accepted" : "multisig-pending",
+            route: MULTISIG_IXN_ROUTE,
+            group: sent.group,
+            delegated: request.delegate,
+            said: request.said,
+            anchor: sent.event.said,
+            deliveries: sent.deliveries,
+        }));
+        return;
+    }
+    const anchored = yield* waitForDelegationAnchor({ db: hby.db }, request, { timeoutMs });
+    if (anchored.outcome === "timed-out") {
+        throw new ValidationError(`The anchor for delegated ${request.ilk} ${request.said} was not accepted and receipted by ${hab.pre} within ${timeoutMs}ms. `
+            + "The other members must approve the proposal first.");
+    }
+    requestDelegatedEvent(deps, request, localGroupMember(hby, hab.pre).pre);
+    const result = yield* waitForDelegationApproval({ db: hby.db, settle: () => settleDelegationApproval(deps, request) }, request, { timeoutMs: 30_000 });
+    if (result.outcome === "timed-out")
+        throw new Error(`Runtime did not converge within ${result.timeoutMs}ms.`);
+    if (hby.db.delegables.get([request.delegate]).includes(request.said)) {
+        throw new ValidationError(`Delegated event ${request.said} remained in delegables escrow after approval.`);
+    }
+    console.log(`Approved delegated ${request.ilk} ${request.said} for ${request.delegate} using multisig ixn.`);
+}
 /** Approve pending delegated events for the selected local delegator habitat. */
 export function* delegateConfirmCommand(args) {
     const confirmArgs = {
@@ -294,7 +119,11 @@ export function* delegateConfirmCommand(args) {
         authenticate: parseBooleanOption(args.authenticate, "authenticate"),
         code: parseStringListOption(args.code, "code"),
         codeTime: parseStringOption(args.codeTime, "codeTime"),
+        timeoutSeconds: parseNumberOption(args.timeout, "timeout"),
     };
+    if (confirmArgs.timeoutSeconds !== undefined && !(confirmArgs.timeoutSeconds >= 0)) {
+        throw new ValidationError("timeout must not be negative");
+    }
     if (!confirmArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
     }
@@ -311,12 +140,6 @@ export function* delegateConfirmCommand(args) {
             throw new ValidationError(`Missing accepted key state for ${hab.pre}.`);
         }
         const signer = isLocalGroupHab(hby, hab) ? localGroupMember(hby, hab.pre) : hab;
-        const worker = yield* spawn(() => runAgentRuntime(runtime, { hab: signer }));
-        try {
-            yield* performDelegationApproval(hby, hab, runtime, confirmArgs);
-        }
-        finally {
-            yield* worker.halt();
-        }
+        yield* withRuntimeWorkers(runtime, { hab: signer }, () => performDelegationApproval(hby, hab, runtime, confirmArgs));
     });
 }

package/esm/keri/npm/src/cli/identity/incept.js

@@ -1,14 +1,11 @@
 import { call } from "effection";
 import { resolveBootstrap } from "../../app/bootstrap/bootstrapping.js";
-import { createProtocolProcessor } from "../../app/protocol/protocol-processing.js";
-import { createAgentRuntime, runAgentRuntimeUntil, } from "../../app/runtime/agent-runtime.js";
-import { systemClock } from "../../app/runtime/runtime-clock.js";
 import { NodeHttpClient } from "../../app/transport/node-http-client.js";
 import { ValidationError } from "../../core/errors.js";
 import { assertBootstrapComplete } from "../common/bootstrap.js";
 import { createConfiger } from "../../app/identity/configing.js";
 import { resolveDelegationCommunicationHab } from "../../app/identity/delegating.js";
-import { Receiptor, WitnessReceiptor } from "../../app/witness/receipting.js";
+import { cliEventCompletionDeps, completeEventOrThrow } from "../common/event-completion.js";
 import { setupHby } from "../common/existing.js";
 import { loadInceptFileOptions, parseBooleanOption, parseCountOption, parseDataItems, parseKeriVersionOption, parseStringListOption, parseStringOption, parseThresholdOption, } from "../common/parsing.js";
 /**
@@ -121,34 +118,20 @@ export function* inceptCommand(args) {
                 delpre: opts.delpre,
                 version: inceptArgs.version,
             });
-            if (hab.kever?.wits.length) {
-                if (inceptArgs.endpoint) {
-                    const receiptor = new Receiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                    yield* receiptor.receipt(hab.pre, { sn: 0 });
-                }
-                else {
-                    const witDoer = new WitnessReceiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                    yield* witDoer.submit(hab.pre, { sn: 0 });
-                }
-            }
-            let delegationPhase = null;
-            if (opts.delpre) {
-                const communicationHab = resolveDelegationCommunicationHab(hby, inceptArgs.proxy);
-                if (!communicationHab) {
-                    throw new ValidationError(`Delegated inception for ${hab.pre} requires --proxy <alias>.`);
-                }
-                const runtime = yield* createAgentRuntime(hby, http, systemClock);
-                try {
-                    runtime.delegating.beginLatest(hab.pre, 0, {
-                        communicationHab,
-                    });
-                    yield* runAgentRuntimeUntil(runtime, () => runtime.delegating.complete(hab.pre, 0), { hab, timeoutMs: 120_000, pollMailbox: true });
-                    delegationPhase = runtime.delegating.workflowStatus(hab.pre, "0").phase;
-                }
-                finally {
-                    yield* runtime.close();
-                }
-            }
+            const { delegationPhase } = yield* completeEventOrThrow(cliEventCompletionDeps(hby, http), hab, 0, {
+                endpoint: inceptArgs.endpoint,
+                delegation: opts.delpre
+                    ? {
+                        communicationHab: () => {
+                            const communicationHab = resolveDelegationCommunicationHab(hby, inceptArgs.proxy);
+                            if (!communicationHab) {
+                                throw new ValidationError(`Delegated inception for ${hab.pre} requires --proxy <alias>.`);
+                            }
+                            return communicationHab;
+                        },
+                    }
+                    : undefined,
+            });
             const state = hby.db.getState(hab.pre);
             return { prefix: hab.pre, keys: state?.k ?? [], delegationPhase };
         }

package/esm/keri/npm/src/cli/identity/interact.js

@@ -1,10 +1,8 @@
-import { createProtocolProcessor } from "../../app/protocol/protocol-processing.js";
-import { systemClock } from "../../app/runtime/runtime-clock.js";
 import { NodeHttpClient } from "../../app/transport/node-http-client.js";
 import { isLocalGroupHab } from "../../app/multisig/group-members.js";
-import { Receiptor, WitnessReceiptor } from "../../app/witness/receipting.js";
 import { ValidationError } from "../../core/errors.js";
 import { withExistingHab } from "../common/context.js";
+import { cliEventCompletionDeps, completeEventOrThrow } from "../common/event-completion.js";
 import { parseBooleanOption, parseDataItems, parseKeriVersionOption, parseStringListOption, parseStringOption, } from "../common/parsing.js";
 import { resolveWitnessAuths } from "../common/witness-auth.js";
 /**
@@ -59,20 +57,10 @@ export function* interactCommand(args) {
                 codeTime: interactArgs.codeTime,
                 promptMissing: interactArgs.authenticate ?? false,
             });
-            if (interactArgs.endpoint) {
-                const receiptor = new Receiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                yield* receiptor.receipt(hab.pre, {
-                    sn: hab.kever.sn,
-                    auths,
-                });
-            }
-            else {
-                const witDoer = new WitnessReceiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                yield* witDoer.submit(hab.pre, {
-                    sn: hab.kever.sn,
-                    auths,
-                });
-            }
+            yield* completeEventOrThrow(cliEventCompletionDeps(hby, http), hab, hab.kever.sn, {
+                auths,
+                endpoint: interactArgs.endpoint,
+            });
         }
         const state = hby.db.getState(hab.pre);
         console.log(`Prefix  ${hab.pre}`);

package/esm/keri/npm/src/cli/identity/rotate.js

@@ -1,12 +1,9 @@
-import { createProtocolProcessor } from "../../app/protocol/protocol-processing.js";
-import { systemClock } from "../../app/runtime/runtime-clock.js";
 import { NodeHttpClient } from "../../app/transport/node-http-client.js";
-import { createAgentRuntime, runAgentRuntimeUntil, } from "../../app/runtime/agent-runtime.js";
 import { ValidationError } from "../../core/errors.js";
 import { resolveDelegationCommunicationHab } from "../../app/identity/delegating.js";
 import { isLocalGroupHab } from "../../app/multisig/group-members.js";
-import { Receiptor, WitnessReceiptor } from "../../app/witness/receipting.js";
 import { withExistingHab } from "../common/context.js";
+import { cliEventCompletionDeps, completeEventOrThrow } from "../common/event-completion.js";
 import { loadRotateFileOptions, parseBooleanOption, parseCountOption, parseDataItems, parseKeriVersionOption, parseStringListOption, parseStringOption, parseThresholdOption, } from "../common/parsing.js";
 import { resolveWitnessAuths } from "../common/witness-auth.js";
 /** Empty baseline used before CLI/file precedence is applied. */
@@ -127,38 +124,13 @@ export function* rotateCommand(args, { witnessAuths } = {}) {
             data: options.data ?? [],
             version: rotateArgs.version,
         });
-        if (hab.kever?.wits.length) {
-            if (rotateArgs.endpoint) {
-                const receiptor = new Receiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                yield* receiptor.receipt(hab.pre, {
-                    sn: hab.kever.sn,
-                    auths,
-                });
-            }
-            else {
-                const witDoer = new WitnessReceiptor(hby, createProtocolProcessor(hby), http, systemClock);
-                yield* witDoer.submit(hab.pre, {
-                    sn: hab.kever.sn,
-                    auths,
-                });
-            }
-        }
-        let delegationPhase = null;
-        if (kever.delpre !== null && hab.kever) {
-            const communicationHab = resolveDelegationCommunicationHab(hby, rotateArgs.proxy);
-            const runtime = yield* createAgentRuntime(hby, http, systemClock);
-            try {
-                runtime.delegating.beginLatest(hab.pre, hab.kever.sn, {
-                    communicationHab,
-                });
-                const snh = hab.kever.sn.toString(16);
-                yield* runAgentRuntimeUntil(runtime, () => runtime.delegating.complete(hab.pre, hab.kever.sn), { hab, timeoutMs: 120_000, pollMailbox: true });
-                delegationPhase = runtime.delegating.workflowStatus(hab.pre, snh).phase;
-            }
-            finally {
-                yield* runtime.close();
-            }
-        }
+        const { delegationPhase } = yield* completeEventOrThrow(cliEventCompletionDeps(hby, http), hab, hab.kever.sn, {
+            auths,
+            endpoint: rotateArgs.endpoint,
+            delegation: kever.delpre !== null && hab.kever
+                ? { communicationHab: () => resolveDelegationCommunicationHab(hby, rotateArgs.proxy) }
+                : undefined,
+        });
         const state = hby.db.getState(hab.pre);
         console.log(`Prefix  ${hab.pre}`);
         console.log(`New Sequence No.  ${hab.kever?.sn ?? state?.s ?? ""}`);

package/esm/keri/npm/src/cli/index.js

@@ -8,8 +8,9 @@
 export { parseGvrsn } from "../core/attachment-countering.js";
 export { withAgentRuntime, withExistingHab, withExistingHabery, withHabAndAgentRuntime, } from "./common/context.js";
 export { ensureHby, setupHby } from "./common/existing.js";
-export { parseBooleanOption, parseCountOption, parseIntegerOption, parseNumberOption, parseStringListOption, parseStringOption, } from "./common/parsing.js";
+export { parseBooleanOption, parseCountOption, parseIntegerOption, parseKeriVersionOption, parseNumberOption, parseStringListOption, parseStringOption, } from "./common/parsing.js";
 export { writeJsonLine, writeTextLines } from "./common/rendering.js";
+export { withRuntimeWorkers } from "./common/runtime-workers.js";
 export { resolveWitnessAuths } from "./common/witness-auth.js";
 export { ipexAdmitCommand, ipexAgreeCommand, ipexApplyCommand, ipexGrantCommand, ipexJoinCommand, ipexListCommand, ipexOfferCommand, ipexPollCommand, ipexSpurnCommand, joinIpexProposal, } from "./credentials/ipex.js";
 export { vcCreateCommand, vcExportCommand, vcImportCommand, vcListCommand, vcRegistryInceptCommand, vcRegistryListCommand, vcRegistryStatusCommand, vcRevokeCommand, vcSchemaImportCommand, } from "./credentials/vc.js";
@@ -30,6 +31,7 @@ export { rotateCommand } from "./identity/rotate.js";
 export { exchangeSendCommand } from "./messaging/exchange.js";
 export { multisigInceptCommand, multisigInteractCommand, multisigJoinCommand, multisigRotateCommand, multisigRpyCommand, } from "./messaging/multisig.js";
 export { notificationsListCommand, notificationsMarkReadCommand, notificationsRemoveCommand, } from "./messaging/notifications.js";
+export { rootCopyLine, RootCopyRecoveryCommand, rootResealLine, } from "./messaging/root-copy-lines.js";
 export { annotateCommand } from "./tools/annotate.js";
 export { benchmarkCommand } from "./tools/benchmark.js";
 export { dumpEvts } from "./tools/db-dump.js";

package/esm/keri/npm/src/cli/messaging/group-join.js

@@ -0,0 +1,83 @@
+/**
+ * `tufa multisig join` proposal selection, as KERIpy `kli multisig join`.
+ *
+ * Join approves exactly one stored proposal, the first the user consents to:
+ * - an explicit `--said` names the proposal, otherwise the unapproved proposals
+ *   the notice store announces are offered in notice order; `--kind` restricts the
+ *   offer (and a `--said`) to one proposal kind, so a join never signs another kind;
+ * - without `--auto` every offered proposal is shown and approved only on a yes;
+ * - with `--auto` the first offered proposal is approved without a prompt. This is
+ *   the whole of auto consent: it exists only inside the `join` the user ran for
+ *   that purpose, and no other command signs a proposal it was not asked to sign.
+ *
+ * Signing, publication and the Counselor hand-off belong to `approveGroupProposal`.
+ */
+import { sleep } from "effection";
+import { approveGroupProposal, dismissGroupProposal, findGroupProposal, listGroupProposals, } from "../../app/multisig/proposals.js";
+import { ValidationError } from "../../core/errors.js";
+/** Group prefix for a joined group's prefix or alias; undefined for a name not yet used. */
+function joinedGroup(hby, group) {
+    return group === undefined ? undefined : (hby.habByName(group) ?? hby.habs.get(group))?.pre ?? undefined;
+}
+/** Candidates for one pass, oldest first. */
+function candidates(deps, { said, group, kind }) {
+    const wanted = joinedGroup(deps.hby, group);
+    if (said !== undefined) {
+        const proposal = findGroupProposal(deps, said);
+        if (proposal && kind !== undefined && proposal.kind !== kind) {
+            throw new ValidationError(`Multisig exchange ${said} is a ${proposal.kind} proposal, not ${kind}.`);
+        }
+        if (proposal && wanted !== undefined && proposal.group !== wanted) {
+            throw new ValidationError(`Multisig exchange ${said} belongs to group ${proposal.group}, not ${wanted}.`);
+        }
+        return proposal ? [proposal] : [];
+    }
+    return listGroupProposals(deps, wanted === undefined ? {} : { group: wanted })
+        .filter(proposal => proposal.local === "unapproved" && (kind === undefined || proposal.kind === kind));
+}
+/**
+ * Approve the first proposal the user consents to, polling stored proposals until
+ * the deadline. A declined proposal is not offered again by this call. Returns
+ * null when nothing was approved; the host owns the runtime that delivers new
+ * proposals while this waits.
+ */
+export function* joinProposal(deps, options) {
+    if (!deps.notifier && options.said === undefined) {
+        throw new ValidationError("Multisig join requires notification storage or an explicit exchange SAID.");
+    }
+    const skipped = new Set();
+    while (true) {
+        for (const proposal of candidates(deps, options)) {
+            if (skipped.has(proposal.said))
+                continue;
+            // An explicit proposal already approved here is replayed without asking again.
+            if (proposal.local !== "approved" && !options.confirm(proposal)) {
+                skipped.add(proposal.said);
+                continue;
+            }
+            const choices = { ...options.inputs(proposal) };
+            if (proposal.needs.groupAlias)
+                choices.groupAlias = options.groupAlias(proposal);
+            if (proposal.needs.registryName)
+                choices.registryName = options.registryName(proposal);
+            let result;
+            try {
+                result = yield* approveGroupProposal(deps, proposal.said, choices);
+            }
+            catch (error) {
+                // A proposal that cannot be approved never hides a later one; an explicit SAID reports why.
+                if (options.said === undefined && error instanceof ValidationError) {
+                    skipped.add(proposal.said);
+                    continue;
+                }
+                throw error;
+            }
+            dismissGroupProposal(deps, proposal.said);
+            return { proposal, result };
+        }
+        const remaining = options.deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        yield* sleep(Math.min(250, remaining));
+    }
+}