keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/cli/ipex.js

@@ -1,519 +0,0 @@
-import * as dntShim from "../../_dnt.shims.js";
-import { concatBytes, Counter, parse, SerderKERI } from "cesr-ts";
-import { action, spawn } from "effection";
-import { parseGvrsn } from "../../core/attachment-countering.js";
-import { ValidationError } from "../../core/errors.js";
-import { CREDENTIAL_MAILBOX_TOPIC } from "../../core/mailbox-topics.js";
-import { abortable } from "../abortable.js";
-import { runAgentRuntime, settleMailboxPollBatch } from "../agent-runtime.js";
-import { fileBytes } from "../byte-source.js";
-import { requireRegery } from "../credential-workflows.js";
-import { isLocalGroupHab, localGroupMember } from "../group-members.js";
-import { embeddedBusinessExnSAD, MULTISIG_EXN_ROUTE } from "../grouping.js";
-import { credentialSaidFromGrant, ipexCredentialAdmit, ipexCredentialGrant, processCredentialPresentationArtifacts, storedGrantArtifacts, } from "../ipex-credentialing.js";
-import { approveMultisigIpex, approveStoredMultisigIpexWrappers, findPendingMultisigIpex, groupIpexPartial, publishGroupIpexProposal, requireStoredExchange, sendCredentialBytes, storedExchangeMessage, } from "../ipex-grouping.js";
-import { IPEX_AGREE_ROUTE, IPEX_APPLY_ROUTE, IPEX_GRANT_ROUTE, IPEX_OFFER_ROUTE, IPEX_SPURN_ROUTE, } from "../ipexing.js";
-import { withAgentRuntime } from "./common/context.js";
-/** Implement `tufa ipex apply` by sending a schema/attribute request EXN. */
-export function* ipexApplyCommand(args) {
-    const ipexArgs = ipexBaseArgs(args);
-    const schema = args.schema;
-    requireNonEmpty(schema, "Schema");
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime }) {
-        const hab = requireHab(hby, ipexArgs.alias);
-        const recipient = runtime.poster.resolveRecipient(requireString(ipexArgs.recipient, "Recipient"));
-        const result = yield* runtime.poster.sendExchange(hab, {
-            recipient,
-            route: IPEX_APPLY_ROUTE,
-            payload: {
-                m: ipexArgs.message ?? "",
-                s: schema,
-                a: parseJsonArg(args.attrs) ?? {},
-                i: recipient,
-            },
-            topic: CREDENTIAL_MAILBOX_TOPIC,
-            delivery: ipexArgs.delivery,
-        });
-        console.log(JSON.stringify({ said: result.serder.said, deliveries: result.deliveries }));
-    });
-}
-/** Implement `tufa ipex offer` with one embedded ACDC stream reference. */
-export function* ipexOfferCommand(args) {
-    const ipexArgs = ipexBaseArgs(args);
-    const acdcFile = args.acdc;
-    requireNonEmpty(acdcFile, "ACDC file");
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime }) {
-        const hab = requireHab(hby, ipexArgs.alias);
-        const recipient = runtime.poster.resolveRecipient(requireString(ipexArgs.recipient, "Recipient"));
-        const result = yield* runtime.poster.sendExchange(hab, {
-            recipient,
-            route: IPEX_OFFER_ROUTE,
-            payload: { m: ipexArgs.message ?? "" },
-            dig: args.apply,
-            embeds: { acdc: dntShim.Deno.readFileSync(acdcFile) },
-            topic: CREDENTIAL_MAILBOX_TOPIC,
-            delivery: ipexArgs.delivery,
-        });
-        console.log(JSON.stringify({ said: result.serder.said, deliveries: result.deliveries }));
-    });
-}
-/** Implement `tufa ipex agree` as a response to an accepted offer EXN. */
-export function* ipexAgreeCommand(args) {
-    yield* sendPriorResponse(args, IPEX_AGREE_ROUTE, "offer");
-}
-/** Implement `tufa ipex spurn` as a rejection response in an IPEX thread. */
-export function* ipexSpurnCommand(args) {
-    yield* sendPriorResponse(args, IPEX_SPURN_ROUTE, "prior");
-}
-/** Implement `tufa ipex grant` and optional grant artifact export/delivery. */
-export function* ipexGrantCommand(args) {
-    const ipexArgs = {
-        ...ipexBaseArgs(args),
-        said: args.said,
-        agree: args.agree,
-        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 120, "approval timeout seconds"),
-    };
-    requireNonEmpty(ipexArgs.said, "Credential SAID");
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime, reger }) {
-        const hab = requireHab(hby, ipexArgs.alias);
-        const recipient = ipexArgs.out
-            ? resolveAid(hby, requireString(ipexArgs.recipient, "Recipient"))
-            : runtime.poster.resolveRecipient(requireString(ipexArgs.recipient, "Recipient"));
-        const grant = ipexCredentialGrant({
-            hby,
-            hab,
-            reger,
-            recipient,
-            credentialSaid: ipexArgs.said,
-            message: ipexArgs.message ?? "",
-            options: {
-                agree: ipexArgs.agree ? hby.db.exns.get([ipexArgs.agree]) : null,
-                gvrsn: ipexArgs.gvrsn,
-            },
-            sign: !isLocalGroupHab(hby, hab),
-        });
-        const group = isLocalGroupHab(hby, hab);
-        if (group) {
-            const genus = grant.grant.gvrsn ?? ipexArgs.gvrsn ?? grant.grant.pvrsn;
-            const partialGrant = groupIpexPartial(hby, hab, grant.grant, grant.attachments, genus);
-            yield* runtime.reactor.processBytes(concatBytes(Counter.makeGVC(genus), partialGrant), { local: true });
-            yield* runtime.reactor.processEscrowsOnce();
-            const deliveries = yield* publishGroupIpexProposal(runtime, hab, partialGrant, undefined, genus);
-            const complete = ipexArgs.approvalTimeoutSeconds > 0
-                ? yield* waitForMultisigIpexCompletion(hby, runtime, hab, grant.grant.said, ipexArgs.approvalTimeoutSeconds)
-                : runtime.reactor.exchanger.complete(grant.grant.said);
-            if (!complete) {
-                console.log(JSON.stringify({
-                    said: grant.grant.said,
-                    credential: ipexArgs.said,
-                    support: grant.support.length,
-                    status: "multisig-pending",
-                    deliveries,
-                }));
-                return;
-            }
-            const completedGrant = requireStoredExchange(hby, grant.grant.said);
-            const completedGrantWire = storedExchangeMessage(hby, completedGrant, ipexArgs.gvrsn);
-            const stream = concatBytes(...grant.support, completedGrantWire);
-            if (ipexArgs.out) {
-                dntShim.Deno.writeFileSync(ipexArgs.out, stream);
-            }
-            else if (runtime.reactor.exchanger.lead(hab, completedGrant.said)) {
-                yield* sendCredentialBytes(runtime, localGroupMember(hby, hab.pre), recipient, [
-                    ...grant.support,
-                    completedGrantWire,
-                ], ipexArgs.delivery);
-            }
-            console.log(JSON.stringify({
-                said: completedGrant.said,
-                credential: ipexArgs.said,
-                support: grant.support.length,
-                status: "multisig-complete",
-                lead: runtime.reactor.exchanger.lead(hab, completedGrant.said),
-                deliveries,
-            }));
-            return;
-        }
-        const stream = concatBytes(...grant.support, grant.wire);
-        if (ipexArgs.out) {
-            dntShim.Deno.writeFileSync(ipexArgs.out, stream);
-        }
-        else {
-            yield* sendCredentialBytes(runtime, hab, recipient, [...grant.support, grant.wire], ipexArgs.delivery);
-        }
-        console.log(JSON.stringify({ said: grant.grant.said, credential: ipexArgs.said, support: grant.support.length }));
-    });
-}
-/** Implement `tufa ipex admit` and holder-side grant artifact processing. */
-export function* ipexAdmitCommand(args) {
-    const ipexArgs = {
-        ...ipexBaseArgs(args),
-        said: args.said,
-        grantFile: args.grantFile,
-        noWait: args.noWait,
-    };
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime, reger }) {
-        const hab = requireHab(hby, ipexArgs.alias);
-        const grant = yield* loadGrant(hby, ipexArgs);
-        const admit = ipexCredentialAdmit({
-            hab,
-            reger,
-            grant,
-            message: ipexArgs.message ?? "",
-            options: { requireSaved: !(ipexArgs.noWait ?? false) },
-        });
-        const recipient = grantSender(grant);
-        if (ipexArgs.out) {
-            dntShim.Deno.writeFileSync(ipexArgs.out, admit.wire);
-        }
-        else {
-            yield* sendCredentialBytes(runtime, hab, recipient, [admit.wire], ipexArgs.delivery);
-        }
-        console.log(JSON.stringify({ said: admit.admit.said, grant: grant.said }));
-    });
-}
-/** Implement `tufa ipex list` by printing locally accepted IPEX EXNs. */
-export function* ipexListCommand(args) {
-    const ipexArgs = ipexBaseArgs(args);
-    yield* withIpexRuntime(ipexArgs, function* ({ hby }) {
-        for (const [, exn] of hby.db.exns.getTopItemIter()) {
-            const route = exn.route ?? "";
-            if (!route.startsWith("/ipex/")) {
-                continue;
-            }
-            console.log(JSON.stringify({
-                said: exn.said,
-                route,
-                sender: exn.ked?.i,
-                prior: exn.ked?.p,
-            }));
-        }
-    });
-}
-/** Observe settled mailbox input and stored grant replay until new IPEX state or an elapsed deadline. */
-export function* ipexPollCommand(args) {
-    const ipexArgs = ipexBaseArgs(args);
-    const timeoutMs = nonNegativeNumber(args.timeout, 40, "poll timeout seconds") * 1000;
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime, reger }) {
-        const hab = ipexArgs.alias ? requireHab(hby, ipexArgs.alias) : undefined;
-        const beforeExns = new Set([...hby.db.exns.getTopItemIter()]
-            .map(([, exn]) => exn.said)
-            .filter((said) => typeof said === "string"));
-        const beforeSaved = savedCredentials(reger);
-        let batchesSeen = 0;
-        let messagesSeen = 0;
-        const signer = hab && isLocalGroupHab(hby, hab) ? localGroupMember(hby, hab.pre) : hab;
-        const deadline = Date.now() + timeoutMs;
-        let receiving = 0;
-        const host = yield* spawn(() => runAgentRuntime(runtime, { hab: signer, pollMailbox: false }));
-        try {
-            const mailbox = yield* spawn(function* () {
-                yield* runtime.mailboxPoller.pollDo(function* (batch) {
-                    receiving++;
-                    try {
-                        yield* settleMailboxPollBatch(runtime, batch);
-                        batchesSeen++;
-                        messagesSeen += batch.messages.length;
-                    }
-                    finally {
-                        receiving--;
-                    }
-                });
-            });
-            try {
-                while (true) {
-                    yield* processStoredCredentialGrants(hby, runtime, reger, ipexArgs.gvrsn);
-                    // State may become visible before the rest of a delivered batch settles.
-                    if (receiving === 0
-                        && (newIpexMessages(hby, beforeExns).length > 0 || newSavedCredentials(reger, beforeSaved).length > 0)) {
-                        break;
-                    }
-                    if (Date.now() >= deadline)
-                        break;
-                    yield* sleep(Math.min(250, deadline - Date.now()));
-                }
-            }
-            finally {
-                yield* mailbox.halt();
-            }
-        }
-        finally {
-            yield* host.halt();
-        }
-        console.log(JSON.stringify({
-            batches: batchesSeen,
-            messages: messagesSeen,
-            ipex: newIpexMessages(hby, beforeExns),
-            saved: newSavedCredentials(reger, beforeSaved),
-        }));
-    });
-}
-/** Implement multisig IPEX approval over a pending `/multisig/exn` wrapper. */
-export function* ipexJoinCommand(args) {
-    const ipexArgs = {
-        ...ipexBaseArgs(args),
-        said: args.said,
-        auto: args.auto,
-        approvalTimeoutSeconds: nonNegativeNumber(args.approvalTimeoutSeconds, 60, "approval timeout seconds"),
-    };
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime }) {
-        const pollHab = ipexArgs.alias ? requireHab(hby, ipexArgs.alias) : undefined;
-        const exn = ipexArgs.said
-            ? hby.db.exns.get([ipexArgs.said])
-            : yield* nextPendingMultisigIpex(hby, runtime, {
-                hab: pollHab,
-                timeoutMs: ipexArgs.approvalTimeoutSeconds * 1000,
-            });
-        if (!exn) {
-            throw new ValidationError(ipexArgs.said
-                ? `IPEX message ${ipexArgs.said} not found.`
-                : "No pending multisig IPEX proposal was available to join.");
-        }
-        if (exn.route?.startsWith("/ipex/")) {
-            console.log(JSON.stringify({ said: exn.said, route: exn.route, status: "single-sig" }));
-            return;
-        }
-        if (exn.route !== MULTISIG_EXN_ROUTE) {
-            throw new ValidationError(`EXN ${ipexArgs.said} is not an IPEX or multisig IPEX message.`);
-        }
-        const embeddedSad = embeddedBusinessExnSAD(exn);
-        if (!embeddedSad || typeof embeddedSad.r !== "string" || !embeddedSad.r.startsWith("/ipex/")) {
-            throw new ValidationError(`Multisig EXN ${ipexArgs.said} does not wrap an IPEX message.`);
-        }
-        const embedded = new SerderKERI({ sad: embeddedSad });
-        const group = embedded.pre;
-        if (!group || !hby.habs.has(group)) {
-            throw new ValidationError(`Multisig IPEX sender ${group ?? "<missing>"} is not a local group AID.`);
-        }
-        if (!ipexArgs.auto) {
-            console.log(JSON.stringify({
-                said: ipexArgs.said,
-                route: exn.route,
-                status: "multisig-pending",
-                embedded: embedded.said,
-                embeddedRoute: embedded.route,
-                group,
-            }));
-            return;
-        }
-        const approval = yield* approveMultisigIpex(hby, runtime, exn, {
-            publish: true,
-            delivery: ipexArgs.delivery,
-            gvrsn: ipexArgs.gvrsn,
-        });
-        console.log(JSON.stringify({
-            said: ipexArgs.said,
-            route: exn.route,
-            status: approval.accepted ? "multisig-approved" : "multisig-escrowed",
-            embedded: embedded.said,
-            embeddedRoute: embedded.route,
-            group,
-            lead: runtime.reactor.exchanger.lead(hby.habs.get(group), embedded.said),
-            deliveries: approval.deliveries,
-        }));
-    });
-}
-function* sendPriorResponse(args, route, priorLabel) {
-    const ipexArgs = ipexBaseArgs(args);
-    const prior = args[priorLabel];
-    requireNonEmpty(prior, priorLabel);
-    yield* withIpexRuntime(ipexArgs, function* ({ hby, runtime }) {
-        const hab = requireHab(hby, ipexArgs.alias);
-        const recipient = runtime.poster.resolveRecipient(requireString(ipexArgs.recipient, "Recipient"));
-        const result = yield* runtime.poster.sendExchange(hab, {
-            recipient,
-            route,
-            payload: { m: ipexArgs.message ?? "" },
-            dig: prior,
-            topic: CREDENTIAL_MAILBOX_TOPIC,
-            delivery: ipexArgs.delivery,
-        });
-        console.log(JSON.stringify({ said: result.serder.said, deliveries: result.deliveries }));
-    });
-}
-function ipexBaseArgs(args) {
-    return {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        compat: args.compat,
-        alias: args.alias,
-        recipient: args.recipient,
-        message: args.message,
-        out: args.out,
-        delivery: args.delivery,
-        gvrsn: parseGvrsn(args.gvrsn),
-    };
-}
-function* withIpexRuntime(args, use) {
-    requireNonEmpty(args.name, "Name");
-    return yield* withAgentRuntime(args, {
-        compat: args.compat ?? false,
-        skipConfig: true,
-    }, function* ({ hby, runtime }) {
-        const reger = requireRegery(runtime).reger;
-        return yield* use({ hby, runtime, reger });
-    });
-}
-function requireHab(hby, alias) {
-    requireNonEmpty(alias, "Alias");
-    const hab = hby.habByName(alias);
-    if (!hab?.pre) {
-        throw new ValidationError(`No local AID found for alias ${alias}.`);
-    }
-    return hab;
-}
-function resolveAid(hby, value) {
-    return hby.habByName(value)?.pre ?? value;
-}
-function requireString(value, label) {
-    requireNonEmpty(value, label);
-    return value;
-}
-function nonNegativeNumber(value, fallback, label) {
-    if (value === undefined || value === null || value === "") {
-        return fallback;
-    }
-    const parsed = Number(value);
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        throw new ValidationError(`${label} must be a finite nonnegative number.`);
-    }
-    return parsed;
-}
-function requireNonEmpty(value, label) {
-    if (!value) {
-        throw new ValidationError(`${label} is required and cannot be empty.`);
-    }
-}
-function newIpexMessages(hby, before) {
-    const messages = [];
-    for (const [, exn] of hby.db.exns.getTopItemIter()) {
-        const said = exn.said;
-        const route = exn.route ?? "";
-        if (!said || before.has(said) || !route.startsWith("/ipex/")) {
-            continue;
-        }
-        messages.push({
-            said,
-            route,
-            sender: exn.ked?.i,
-            prior: exn.ked?.p,
-        });
-    }
-    return messages;
-}
-function savedCredentials(reger) {
-    return new Set([...reger.saved.getTopItemIter()].map(([keys]) => keys[0]).filter((key) => !!key));
-}
-function newSavedCredentials(reger, before) {
-    return [...savedCredentials(reger)].filter((said) => !before.has(said));
-}
-/** Settle accepted grant artifacts before the poll command reports newly saved credentials. */
-function* processStoredCredentialGrants(hby, runtime, reger, gvrsn) {
-    for (const [, grant] of hby.db.exns.getTopItemIter()) {
-        if (grant.route !== IPEX_GRANT_ROUTE) {
-            continue;
-        }
-        const credentialSaid = credentialSaidFromGrant(grant);
-        if (!credentialSaid || reger.saved.get([credentialSaid])) {
-            continue;
-        }
-        yield* processCredentialPresentationArtifacts(runtime.reactor, storedGrantArtifacts(hby, grant, gvrsn));
-    }
-}
-function parseJsonArg(value) {
-    if (!value) {
-        return undefined;
-    }
-    const text = value.startsWith("@") ? dntShim.Deno.readTextFileSync(value.slice(1)) : value;
-    return JSON.parse(text);
-}
-/** Scan a file through valid EOF before choosing a grant, or use its persisted exchange record. */
-function* loadGrant(hby, args) {
-    if (args.grantFile) {
-        const path = args.grantFile;
-        return yield* abortable(async (signal) => {
-            let grant;
-            const frames = parse(fileBytes(path, { signal }));
-            try {
-                while (true) {
-                    signal.throwIfAborted();
-                    const result = await frames.next();
-                    signal.throwIfAborted();
-                    if (result.done)
-                        break;
-                    const frame = result.value;
-                    if (!grant && frame.body instanceof SerderKERI && frame.body.route === IPEX_GRANT_ROUTE)
-                        grant = frame.body;
-                }
-            }
-            finally {
-                await frames.return();
-            }
-            if (grant)
-                return grant;
-            throw new ValidationError(`Grant file ${path} does not contain an IPEX grant.`);
-        });
-    }
-    requireNonEmpty(args.said, "Grant SAID");
-    const grant = hby.db.exns.get([args.said]);
-    if (!grant || grant.route !== IPEX_GRANT_ROUTE) {
-        throw new ValidationError(`Grant ${args.said} not found.`);
-    }
-    return grant;
-}
-function grantSender(grant) {
-    const sender = grant.ked?.i;
-    if (typeof sender !== "string" || sender.length === 0) {
-        throw new ValidationError("Grant is missing sender AID.");
-    }
-    return sender;
-}
-/** Await group approval while the ordinary host owns mailbox, query and escrow progress. */
-function* waitForMultisigIpexCompletion(hby, runtime, groupHab, embeddedSaid, approvalTimeoutSeconds) {
-    const member = localGroupMember(hby, groupHab.pre);
-    const deadline = Date.now() + approvalTimeoutSeconds * 1000;
-    const host = yield* spawn(() => runAgentRuntime(runtime, { hab: member }));
-    try {
-        while (true) {
-            yield* approveStoredMultisigIpexWrappers(hby, runtime, embeddedSaid);
-            if (runtime.reactor.exchanger.complete(embeddedSaid))
-                return true;
-            if (Date.now() >= deadline)
-                return false;
-            yield* sleep(Math.min(250, deadline - Date.now()));
-        }
-    }
-    finally {
-        yield* host.halt();
-    }
-}
-/** Observe stored proposals while the host progresses input, then join before approval. */
-function* nextPendingMultisigIpex(hby, runtime, { hab, timeoutMs }) {
-    const found = findPendingMultisigIpex(hby, runtime);
-    if (found || timeoutMs === 0)
-        return found;
-    const signer = hab && isLocalGroupHab(hby, hab) ? localGroupMember(hby, hab.pre) : hab;
-    const deadline = Date.now() + timeoutMs;
-    const host = yield* spawn(() => runAgentRuntime(runtime, { hab: signer }));
-    try {
-        while (true) {
-            const pending = findPendingMultisigIpex(hby, runtime);
-            if (pending)
-                return pending;
-            if (Date.now() >= deadline)
-                return null;
-            yield* sleep(Math.min(250, deadline - Date.now()));
-        }
-    }
-    finally {
-        yield* host.halt();
-    }
-}
-function* sleep(ms) {
-    yield* action((resolve) => {
-        const timeout = setTimeout(resolve, ms);
-        return () => clearTimeout(timeout);
-    });
-}

package/esm/keri/npm/src/app/cli/query.js

@@ -1,142 +0,0 @@
-/**
- * `tufa query` command implementation.
- *
- * KERIpy correspondence:
- * - mirrors the bounded "launch query, poll for replies, print external state"
- *   behavior of `keri.cli.commands.query`
- * - builds on the `QueryCoordinator`/querier helpers that correspond to
- *   KERIpy's query/noticer doers
- *
- * `keri-ts` difference:
- * - transport, mailbox polling, and parser ingress are composed explicitly for
- *   one bounded command lifetime instead of being spread across long-lived HIO
- *   doers
- */
-import * as dntShim from "../../_dnt.shims.js";
-import { SealEvent } from "cesr-ts";
-import { spawn } from "effection";
-import { ValidationError } from "../../core/errors.js";
-import { Roles } from "../../core/roles.js";
-import { runAgentRuntime, runtimeHasPendingWork, runtimeTurn, } from "../agent-runtime.js";
-import { flattenRoleUrls } from "../mailboxing.js";
-import { withHabAndAgentRuntime } from "./common/context.js";
-import { printExternal } from "./common/displaying.js";
-/**
- * Bounded runtime window for the primary query/watch pass.
- *
- * KLI compatibility:
- * - KERIpy's CLI query flow waits for roughly ten seconds before printing the
- *   best available external state
- */
-const QueryTimeoutMs = 10_000;
-/** Decode one concrete event seal before opening state or scheduling an anchor query. */
-function loadAnchor(path) {
-    const text = dntShim.Deno.readTextFileSync(path);
-    const anchor = JSON.parse(text);
-    if (!SealEvent.isSad(anchor)) {
-        throw new ValidationError("Anchor file must contain only string i, s and d event-seal fields.");
-    }
-    // Reuse CESR primitive validation without rewriting the supplied seal representation.
-    SealEvent.fromSad(anchor);
-    return anchor;
-}
-/**
- * Build the controller OOBI URL used for query catch-up fallback.
- *
- * Why this exists:
- * - a successful `ksn` reply can prove a remote controller is ahead of local
- *   accepted state without carrying the whole log replay
- * - when that happens, the CLI falls back to controller OOBI replay so local
- *   verification state can converge within the command's bounded lifetime
- */
-function controllerCatchupUrl(hab, queriedPre) {
-    const ends = hab.endsFor(queriedPre);
-    const controller = flattenRoleUrls(ends[Roles.controller])[0]
-        ?? flattenRoleUrls(ends[Roles.agent])[0];
-    if (!controller) {
-        return null;
-    }
-    const url = new URL(controller.url);
-    url.pathname = `/oobi/${queriedPre}/controller`;
-    url.search = "";
-    url.hash = "";
-    return url.toString();
-}
-/**
- * Query remote key state or anchored logs and then print KLI-style external state.
- *
- * Behavioral shape:
- * - start a bounded local runtime
- * - register either a key-state or anchor continuation
- * - poll transport/mailbox work until convergence or timeout
- * - optionally fall back to controller catch-up replay before printing
- */
-export function* queryCommand(args) {
-    const queryArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        compat: args.compat,
-        prefix: args.prefix,
-        anchor: args.anchor,
-    };
-    if (!queryArgs.name) {
-        throw new ValidationError("Name is required and cannot be empty");
-    }
-    if (!queryArgs.alias) {
-        throw new ValidationError("Alias is required and cannot be empty");
-    }
-    if (!queryArgs.prefix) {
-        throw new ValidationError("Prefix is required and cannot be empty");
-    }
-    const prefix = queryArgs.prefix;
-    const anchor = queryArgs.anchor ? loadAnchor(queryArgs.anchor) : undefined;
-    yield* withHabAndAgentRuntime(queryArgs, queryArgs.alias, {
-        compat: queryArgs.compat ?? false,
-        readonly: false,
-        skipConfig: true,
-        skipSignator: true,
-    }, function* ({ hby, runtime, hab }) {
-        let watchDone = () => false;
-        if (anchor) {
-            console.log(`Checking for anchor ${JSON.stringify(anchor)}...`);
-            const querier = runtime.querying.watchAnchor(prefix, anchor, {
-                signer: hab.pre,
-            });
-            watchDone = () => querier.done;
-        }
-        else {
-            console.log("Checking for updates...");
-            const noticer = runtime.querying.watchKeyState(prefix, {
-                signer: hab.pre,
-            });
-            watchDone = () => noticer.done;
-        }
-        const worker = yield* spawn(() => runAgentRuntime(runtime, { hab }));
-        try {
-            const deadline = Date.now() + QueryTimeoutMs;
-            while (!watchDone() && Date.now() < deadline) {
-                yield* runtimeTurn();
-            }
-            if (!watchDone() && !queryArgs.anchor) {
-                const catchupUrl = controllerCatchupUrl(hab, prefix);
-                if (catchupUrl) {
-                    runtime.oobiery.resolve(catchupUrl);
-                    const catchupDeadline = Date.now() + 5_000;
-                    while (!watchDone() && Date.now() < catchupDeadline) {
-                        if (!runtimeHasPendingWork(runtime))
-                            break;
-                        yield* runtimeTurn();
-                    }
-                }
-            }
-        }
-        finally {
-            yield* worker.halt();
-        }
-        console.log("");
-        printExternal(hby, prefix);
-    });
-}