@chatlychat/cli 0.1.7 → 0.3.0

package/dist/commands/listen-core.js

@@ -0,0 +1,334 @@
+/**
+ * What `chatly listen` does the same way for every surface it tails.
+ *
+ * ═══ WHY THIS FILE EXISTS ═════════════════════════════════════════════════
+ *
+ * `listen` tails two ledgers now — webhook subscriptions
+ * (`/v1/webhooks/deliveries`) and an external agent's push deliveries
+ * (`/v1/bots/{id}/deliveries`) — and will tail more. The poll loop differs
+ * per ledger; the flags, the seen-set, the signing and the forward leg do
+ * not. They are here so there is one of each, and so `listen.ts` stays under
+ * this repo's 650-line ceiling.
+ *
+ * ═══ THE SIGNATURE IT MINTS, AND THE SELF-CHECK ═══════════════════════════
+ *
+ * Neither ledger stores the signature Chatly sent — `webhook_deliveries` and
+ * `agent_deliveries` both store the PAYLOAD as `jsonb` and nothing else, and
+ * `jsonb` does not preserve key order, so the exact signed bytes are
+ * unreconstructable by construction rather than by omission. So a forwarded
+ * request is re-signed here, from `--secret`, and every forward carries TWO
+ * headers:
+ *
+ *   - the surface's own legacy header (`x-livechat-signature` for an event
+ *     webhook, `x-chatly-signature` for an agent delivery), `t=…,v1=…` over
+ *     `<t>.<rawBody>` — what the platform sends today;
+ *   - `x-chatly-signature-v2`, `t=…,v1=…` over
+ *     `<t>.<METHOD>.<path>.<rawBody>` — the unified construction every
+ *     surface is moving to (C-02). The platform does not send this on either
+ *     surface yet, which is exactly why minting it locally is useful: a
+ *     developer can write and test the verifier they will need before the
+ *     sender moves.
+ *
+ * `path` in that base string is the path of the request being signed — the
+ * local `--forward-to` path, because that is the request the receiver
+ * verifies. Both headers are verified with the SDK's own
+ * `verifyChatlySignature` BEFORE the request goes out, and a forward whose
+ * own signature does not verify is refused rather than sent. That self-check
+ * is not ceremony: it is the one thing that catches a signer and a verifier
+ * drifting on construction or on timestamp unit, which is a bug this product
+ * has actually shipped — the scheme once emitted milliseconds in the header
+ * while signing a seconds value, and every correct handler rejected us.
+ */
+import { createHmac } from 'node:crypto';
+import { chatlyV2SigningPath, signChatlyV2, verifyChatlySignature } from '@chatlychat/sdk-node';
+import { bool, num, str } from '../args.js';
+export const WEBHOOK_SIGN_PLAN = {
+    surface: 'event_webhook',
+    legacyHeader: 'x-livechat-signature',
+    timestampHeader: 'x-livechat-timestamp',
+};
+export const AGENT_SIGN_PLAN = {
+    surface: 'agent_delivery',
+    legacyHeader: 'x-chatly-signature',
+    timestampHeader: null,
+};
+/** Deliveries remembered before the oldest id is dropped. */
+const SEEN_CAP = 5_000;
+const DEFAULT_INTERVAL_SECONDS = 2;
+const MIN_INTERVAL_SECONDS = 1;
+const DEFAULT_PAGE_LIMIT = 50;
+/**
+ * The four words both ledgers use, with the same meanings: `failed` will be
+ * retried and `dead` will not. Validated here because the bot ledger answers
+ * a **400** on a word outside the four rather than an empty page.
+ */
+export const DELIVERY_STATUSES = ['pending', 'delivered', 'failed', 'dead'];
+/** Drop the oldest ids once the set is at its cap. Sets iterate in insertion order. */
+export function remember(seen, id) {
+    seen.add(id);
+    if (seen.size > SEEN_CAP) {
+        for (const old of seen) {
+            seen.delete(old);
+            if (seen.size <= SEEN_CAP) {
+                break;
+            }
+        }
+    }
+}
+/** `t=<unix seconds>,v1=<hex>` over `<t>.<body>`, the way the worker signs. */
+function tv1(body, secret, t, prefix = '') {
+    const v1 = createHmac('sha256', secret).update(`${t}.${prefix}${body}`).digest('hex');
+    return `t=${t},v1=${v1}`;
+}
+/**
+ * The signature headers for one forwarded request, self-checked.
+ *
+ * Returns the headers to merge, or a message naming what went wrong — which
+ * can only be a bug in this CLI, since it signed the bytes itself moments
+ * earlier. See this file's header for why both headers are minted.
+ */
+export function signedForwardHeaders(input) {
+    const t = Math.floor(input.nowMs / 1000).toString();
+    const { plan, body, secret, nowMs } = input;
+    const legacy = tv1(body, secret, t);
+    const legacyCheck = verifyChatlySignature({
+        surface: plan.surface,
+        body,
+        headers: { [plan.legacyHeader]: legacy },
+        secret,
+        nowMs,
+        // The v2 header is minted below and lives in the same bag on the wire;
+        // this check is specifically of the LEGACY construction, so the policy
+        // that would prefer v2 has to be off.
+        v2: 'ignore',
+    });
+    if (!legacyCheck.ok) {
+        return { ok: false, message: `${legacyCheck.reason}: ${legacyCheck.message}` };
+    }
+    const headers = { [plan.legacyHeader]: legacy };
+    if (plan.timestampHeader !== null) {
+        headers[plan.timestampHeader] = t;
+    }
+    /*
+     * The unified v2 header. `method` is POST because that is what this
+     * forwards, and `path` is the target's own path — the receiver verifies
+     * the request IT received, so the path in the digest has to be the one on
+     * that request line.
+     */
+    const path = chatlyV2SigningPath(input.targetUrl);
+    if (path === null) {
+        return { ok: false, message: `--forward-to "${input.targetUrl}" is not a URL` };
+    }
+    /*
+     * Through the shared signer, so this emits the `b=t` base marker.
+     *
+     * It used to build the value by hand, and its own docblock said "the
+     * platform does not send this on either surface yet" — which is now false
+     * for both. Worse, a hand-rolled value carries no marker, and an absent
+     * marker means the LEGACY `<t>.<rawBody>` construction: a receiver reading
+     * `b=` to decide what to verify would have been told, by the one tool whose
+     * job is to rehearse production, that the unified base is the body base.
+     *
+     * From `@chatlychat/sdk-node`, NOT from `@livechat/shared`. This package
+     * builds with plain `tsc` and publishes `dist` declaring only the SDK, so
+     * an import of the internal scope would emit a reference to a package that
+     * is not on npm and `npm i -g @chatlychat/cli` would fail at run time with
+     * MODULE_NOT_FOUND — a break no test here would see, because in the
+     * monorepo the import resolves. The SDK's copy is held byte-for-byte
+     * against the one the API and worker send with by
+     * `packages/shared/src/webhook-signature/v2.parity.spec.ts`, so this still
+     * teaches exactly the shape production sends.
+     */
+    const v2 = signChatlyV2({
+        base: 'target',
+        secret,
+        timestampSeconds: Number(t),
+        method: 'POST',
+        path,
+        body,
+    });
+    const v2Check = verifyChatlySignature({
+        surface: 'unified_v2',
+        body,
+        headers: { 'x-chatly-signature-v2': v2 },
+        secret,
+        method: 'POST',
+        path,
+        nowMs,
+    });
+    if (!v2Check.ok) {
+        return { ok: false, message: `${v2Check.reason}: ${v2Check.message}` };
+    }
+    headers['x-chatly-signature-v2'] = v2;
+    return { ok: true, headers };
+}
+/** POST one event on, verifying the headers we just minted before sending. */
+export async function forward(opts, deps, req) {
+    if (opts.forwardTo === null) {
+        return false;
+    }
+    const headers = {
+        'content-type': 'application/json',
+        ...req.headers,
+        // Not a header Chatly sends. A handler that logs it can tell a replayed
+        // local forward from a real delivery, which matters the first time
+        // somebody points this at a staging environment.
+        'x-chatly-cli-forwarded': '1',
+    };
+    if (opts.secret !== null) {
+        const signed = signedForwardHeaders({
+            plan: req.plan,
+            body: req.body,
+            secret: opts.secret,
+            nowMs: deps.now(),
+            targetUrl: opts.forwardTo,
+        });
+        if (!signed.ok) {
+            deps.err(`refusing to forward ${req.id}: the signature this CLI minted does not verify ` +
+                `(${signed.message}). This is a bug in chatly listen, not in your handler — ` +
+                'please report it.\n');
+            return false;
+        }
+        Object.assign(headers, signed.headers);
+    }
+    try {
+        const res = await deps.fetchFn(opts.forwardTo, {
+            method: 'POST',
+            headers,
+            body: req.body,
+            signal: deps.signal,
+        });
+        if (!res.ok) {
+            deps.err(`   ↳ ${opts.forwardTo} answered ${String(res.status)}. ` +
+                (res.status === 401 || res.status === 403
+                    ? 'That is usually signature verification — check --secret matches the endpoint.\n'
+                    : '\n'));
+            return false;
+        }
+        deps.out(`   ↳ ${String(res.status)} from ${opts.forwardTo}`);
+        return true;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        deps.err(`   ↳ ${opts.forwardTo} unreachable: ${reason}. Is your server running on that port?\n`);
+        return false;
+    }
+}
+function parseEventFilter(args) {
+    const raw = args.flags['event'];
+    if (raw === undefined) {
+        return null;
+    }
+    const list = (Array.isArray(raw) ? raw : [String(raw)]).flatMap((v) => v
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0));
+    return list.length === 0 ? null : new Set(list);
+}
+/**
+ * Read the flags, refusing anything that cannot work, with the fix named.
+ *
+ * The two secret prefixes are the one refusal worth reading twice: a webhook
+ * endpoint's secret is `whsec_` and an external agent's is `chsec_`, they are
+ * minted by different routes, and neither verifies the other's traffic. The
+ * symptom of crossing them is a 401 from your own handler, which looks
+ * exactly like a verifier bug.
+ */
+export function parseListenOptions(args) {
+    const forwardTo = str(args.flags, 'forward-to') ?? null;
+    if (forwardTo !== null) {
+        let parsed = null;
+        try {
+            parsed = new URL(forwardTo);
+        }
+        catch {
+            parsed = null;
+        }
+        /*
+         * One message for both failures, because `localhost:3000` — the mistake
+         * everyone makes — hits the SECOND branch, not the first: the WHATWG
+         * parser reads `localhost:` as a SCHEME and succeeds. A test caught this
+         * command telling a developer who typed `localhost:3000` that the scheme
+         * `"localhost:"` was unsupported, which is true and useless.
+         */
+        if (parsed === null || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+            throw new Error(`--forward-to "${forwardTo}" is not an http(s) URL${parsed === null ? '' : ` (it parsed as the scheme "${parsed.protocol}")`}. Include the scheme:\n` + '  chatly listen --forward-to http://localhost:3000/webhooks');
+        }
+    }
+    const botId = str(args.flags, 'bot') ?? null;
+    const endpointId = str(args.flags, 'endpoint') ?? null;
+    if (botId !== null && endpointId !== null) {
+        throw new Error('--bot and --endpoint tail different ledgers and cannot be combined. --bot <id> tails one ' +
+            "external agent's push deliveries; --endpoint <id> tails one webhook subscription's.");
+    }
+    const intervalSeconds = num(args.flags, 'interval') ?? DEFAULT_INTERVAL_SECONDS;
+    if (intervalSeconds < MIN_INTERVAL_SECONDS) {
+        throw new Error(`--interval ${String(intervalSeconds)} is below the ${String(MIN_INTERVAL_SECONDS)}s floor. ` +
+            'This polls a real API on your own rate limit; a tighter loop buys nothing, because the ' +
+            'delivery row is written after the attempt completes.');
+    }
+    const pageLimit = num(args.flags, 'limit') ?? DEFAULT_PAGE_LIMIT;
+    if (pageLimit < 1) {
+        throw new Error(`--limit ${String(pageLimit)} must be at least 1.`);
+    }
+    const replay = num(args.flags, 'replay') ?? 0;
+    if (replay < 0) {
+        throw new Error(`--replay ${String(replay)} cannot be negative.`);
+    }
+    if (replay > pageLimit) {
+        throw new Error(`--replay ${String(replay)} is more than --limit ${String(pageLimit)}, and this command ` +
+            'only ever reads one page per poll. Raise --limit to match.');
+    }
+    const status = str(args.flags, 'status') ?? null;
+    if (botId !== null && status !== null && !DELIVERY_STATUSES.includes(status)) {
+        // The route validates this against a zod enum and answers 400, not an
+        // empty page. Refusing here names the four words.
+        throw new Error(`--status "${status}" is not one of ${DELIVERY_STATUSES.join(', ')}. ` +
+            '`failed` will be retried; `dead` will not.');
+    }
+    const secret = str(args.flags, 'secret') ?? null;
+    if (secret !== null && botId === null && !secret.startsWith('whsec_')) {
+        throw new Error(`--secret should be the endpoint's whsec_ signing secret (got "${secret.slice(0, 6)}…").\n` +
+            'It is returned exactly once, by `chatly webhooks create`, and by no other route — if ' +
+            'you no longer have it, create another endpoint.\n' +
+            "With --bot, pass the AGENT's chsec_ secret instead; the two do not verify each other's " +
+            'traffic.');
+    }
+    if (secret !== null && botId !== null && !secret.startsWith('chsec_')) {
+        throw new Error(`--secret should be the external agent's chsec_ signing secret (got "${secret.slice(0, 6)}…").\n` +
+            'It is shown once by `chatly bots create` and once by `chatly bots rotate-secret <id>`, ' +
+            'and no read route returns it.\n' +
+            "A webhook endpoint's whsec_ secret signs a different surface and will not verify here.");
+    }
+    return {
+        forwardTo,
+        botId,
+        endpointId,
+        events: parseEventFilter(args),
+        status,
+        secret,
+        intervalMs: intervalSeconds * 1000,
+        replay,
+        pageLimit,
+        json: bool(args.flags, 'json'),
+    };
+}
+/** An abortable sleep, so Ctrl-C does not wait out the poll interval. */
+export function sleepUntilAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=listen-core.js.map

package/dist/commands/listen-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-core.js","sourceRoot":"","sources":["../../src/commands/listen-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEhG,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAmB,MAAM,YAAY,CAAC;AAe7D,MAAM,CAAC,MAAM,iBAAiB,GAAa;IACzC,OAAO,EAAE,eAAe;IACxB,YAAY,EAAE,sBAAsB;IACpC,eAAe,EAAE,sBAAsB;CACxC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,OAAO,EAAE,gBAAgB;IACzB,YAAY,EAAE,oBAAoB;IAClC,eAAe,EAAE,IAAI;CACtB,CAAC;AA4CF,6DAA6D;AAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB,MAAM,wBAAwB,GAAG,CAAC,CAAC;AACnC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAC/B,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAErF,uFAAuF;AACvF,MAAM,UAAU,QAAQ,CAAC,IAAiB,EAAE,EAAU;IACpD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACb,IAAI,IAAI,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,IAAI,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAC1B,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,GAAG,CAAC,IAAY,EAAE,MAAc,EAAE,CAAS,EAAE,MAAM,GAAG,EAAE;IAC/D,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAOpC;IACC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IACpD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAE5C,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,qBAAqB,CAAC;QACxC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI;QACJ,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE;QACxC,MAAM;QACN,KAAK;QACL,uEAAuE;QACvE,uEAAuE;QACvE,sCAAsC;QACtC,EAAE,EAAE,QAAQ;KACb,CAAC,CAAC;IACH,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;IACjF,CAAC;IAED,MAAM,OAAO,GAA2B,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxE,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,KAAK,CAAC,SAAS,gBAAgB,EAAE,CAAC;IAClF,CAAC;IACD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,EAAE,GAAG,YAAY,CAAC;QACtB,IAAI,EAAE,QAAQ;QACd,MAAM;QACN,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;QAC3B,MAAM,EAAE,MAAM;QACd,IAAI;QACJ,IAAI;KACL,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,qBAAqB,CAAC;QACpC,OAAO,EAAE,YAAY;QACrB,IAAI;QACJ,OAAO,EAAE,EAAE,uBAAuB,EAAE,EAAE,EAAE;QACxC,MAAM;QACN,MAAM,EAAE,MAAM;QACd,IAAI;QACJ,KAAK;KACN,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,uBAAuB,CAAC,GAAG,EAAE,CAAC;IAEtC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAYD,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAmB,EACnB,IAAgB,EAChB,GAAmB;IAEnB,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;QAClC,GAAG,GAAG,CAAC,OAAO;QACd,wEAAwE;QACxE,mEAAmE;QACnE,iDAAiD;QACjD,wBAAwB,EAAE,GAAG;KAC9B,CAAC;IAEF,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,oBAAoB,CAAC;YAClC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,CAAC,GAAG,CACN,uBAAuB,GAAG,CAAC,EAAE,kDAAkD;gBAC7E,IAAI,MAAM,CAAC,OAAO,2DAA2D;gBAC7E,qBAAqB,CACxB,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE;YAC7C,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,CAAC,GAAG,CACN,QAAQ,IAAI,CAAC,SAAS,aAAa,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI;gBACvD,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;oBACvC,CAAC,CAAC,iFAAiF;oBACnF,CAAC,CAAC,IAAI,CAAC,CACZ,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,IAAI,CAAC,GAAG,CACN,QAAQ,IAAI,CAAC,SAAS,iBAAiB,MAAM,0CAA0C,CACxF,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAgB;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CACpE,CAAC;SACE,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC/B,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,IAAI,CAAC;IACxD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,GAAe,IAAI,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD;;;;;;WAMG;QACH,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;YACrF,MAAM,IAAI,KAAK,CACb,iBAAiB,SAAS,0BACxB,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,8BAA8B,MAAM,CAAC,QAAQ,IACtE,yBAAyB,GAAG,6DAA6D,CAC1F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC;IAC7C,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,2FAA2F;YACzF,qFAAqF,CACxF,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,wBAAwB,CAAC;IAChF,IAAI,eAAe,GAAG,oBAAoB,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,cAAc,MAAM,CAAC,eAAe,CAAC,iBAAiB,MAAM,CAAC,oBAAoB,CAAC,WAAW;YAC3F,yFAAyF;YACzF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,kBAAkB,CAAC;IACjE,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,YAAY,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,GAAG,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,YAAY,MAAM,CAAC,MAAM,CAAC,yBAAyB,MAAM,CAAC,SAAS,CAAC,qBAAqB;YACvF,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,MAAe,CAAC,EAAE,CAAC;QACtF,sEAAsE;QACtE,kDAAkD;QAClD,MAAM,IAAI,KAAK,CACb,aAAa,MAAM,mBAAmB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACpE,4CAA4C,CAC/C,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC;IACjD,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,iEAAiE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ;YACzF,uFAAuF;YACvF,mDAAmD;YACnD,yFAAyF;YACzF,UAAU,CACb,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,uEAAuE,MAAM,CAAC,KAAK,CACjF,CAAC,EACD,CAAC,CACF,QAAQ;YACP,yFAAyF;YACzF,iCAAiC;YACjC,wFAAwF,CAC3F,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS;QACT,KAAK;QACL,UAAU;QACV,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC;QAC9B,MAAM;QACN,MAAM;QACN,UAAU,EAAE,eAAe,GAAG,IAAI;QAClC,MAAM;QACN,SAAS;QACT,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,EAAU,EAAE,MAAmB;IAC/D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,SAAS,OAAO;YACd,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/listen-relay-options.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The flags and the wire shapes of `chatly listen --relay`.
+ *
+ * Split out of `listen-relay.ts` for the 650-line ceiling. What is parsed
+ * here, and why each refusal exists, is documented on each function; the
+ * protocol the shapes belong to is `apps/cli/RELAY-SERVER-SPEC.md`.
+ */
+import { type RelayKind } from './listen-relay-sign.js';
+import { type ParsedArgs } from '../args.js';
+export interface RelaySecrets {
+    /** `--secret <value>`: for every target without its own. */
+    readonly fallback: string | null;
+    /** `--secret <targetId>=<value>`. */
+    readonly byTarget: ReadonlyMap<string, string>;
+}
+export interface RelayOptions {
+    readonly forwardTo: string;
+    readonly tools: readonly string[];
+    readonly cards: readonly string[];
+    readonly canvases: readonly string[];
+    readonly secrets: RelaySecrets;
+    readonly json: boolean;
+}
+/** One relayed call, as `GET /v1/relay-sessions/{id}/frames` renders it. */
+export interface RelayFrame {
+    readonly id: string;
+    readonly kind: RelayKind;
+    readonly targetId: string;
+    readonly method: string;
+    /** `pathname + search` of the CONFIGURED url. */
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Exactly the bytes the configured url would have received. `''` for none. */
+    readonly body: string;
+    /** When the waiting caller gives up. The CLI aborts the forward then. */
+    readonly deadlineAt: string;
+}
+/** What the CLI posts back. Exactly one of the two arms. */
+export type RelayAnswer = {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly durationMs: number;
+} | {
+    readonly error: 'unreachable' | 'timeout' | 'too_large' | 'not_selected' | 'signing_failed' | 'interrupted';
+    readonly message: string;
+    readonly durationMs: number;
+};
+/** `--tool`, `--card` or `--canvas` on a command that is not `--relay`. */
+export declare function relayOnlyFlagWithoutRelay(args: ParsedArgs): string | null;
+/** Read the relay flags, refusing anything that cannot work, with the fix named. */
+export declare function parseRelayOptions(args: ParsedArgs): RelayOptions;
+/**
+ * Where one frame goes: `--forward-to`'s origin and path prefix, then the
+ * CONFIGURED url's path and query.
+ *
+ * The path is preserved because for a tool call it IS the request —
+ * `GET /orders/{{order_id}}` renders to `/orders/42`, and a handler that
+ * cannot see the 42 cannot answer. Cards and canvases are kept the same way
+ * so there is one rule, and a local server mounted under a prefix still works.
+ */
+export declare function relayTargetUrl(forwardTo: string, framePath: string): string;
+/**
+ * The frames on one poll, and how many were unreadable.
+ *
+ * Hand-checked rather than zod, because this package declares the SDK as its
+ * only dependency (CLAUDE.md §2: no new dependency without approval). An
+ * unreadable frame is COUNTED, not silently dropped — the server is waiting
+ * on it, and a relay that loses frames quietly reads as a slow handler.
+ */
+export declare function readFrames(value: unknown): {
+    frames: RelayFrame[];
+    unreadable: number;
+};
+/** Which selected set a frame's kind is checked against. */
+export declare function selectedFor(opts: RelayOptions, kind: RelayKind): readonly string[];
+export declare function secretFor(opts: RelayOptions, targetId: string): string | null;
+//# sourceMappingURL=listen-relay-options.d.ts.map

package/dist/commands/listen-relay-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-relay-options.d.ts","sourceRoot":"","sources":["../../src/commands/listen-relay-options.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAIxD,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,GACD;IACE,QAAQ,CAAC,KAAK,EACV,aAAa,GACb,SAAS,GACT,WAAW,GACX,cAAc,GACd,gBAAgB,GAChB,aAAa,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAaN,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAOzE;AAqDD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CA6DhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ3E;AAWD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA8BvF;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,CAMlF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7E"}

package/dist/commands/listen-relay-options.js

@@ -0,0 +1,195 @@
+/**
+ * The flags and the wire shapes of `chatly listen --relay`.
+ *
+ * Split out of `listen-relay.ts` for the 650-line ceiling. What is parsed
+ * here, and why each refusal exists, is documented on each function; the
+ * protocol the shapes belong to is `apps/cli/RELAY-SERVER-SPEC.md`.
+ */
+import { RELAY_KINDS } from './listen-relay-sign.js';
+import { bool, str } from '../args.js';
+const ID_FLAGS = ['tool', 'card', 'canvas'];
+function listFlag(args, name) {
+    const raw = args.flags[name];
+    if (raw === undefined || raw === true || raw === false) {
+        return [];
+    }
+    return (Array.isArray(raw) ? raw : [String(raw)])
+        .flatMap((v) => String(v).split(','))
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** `--tool`, `--card` or `--canvas` on a command that is not `--relay`. */
+export function relayOnlyFlagWithoutRelay(args) {
+    for (const name of ID_FLAGS) {
+        if (args.flags[name] !== undefined) {
+            return name;
+        }
+    }
+    return null;
+}
+/** The ledger-tail flags, none of which mean anything on a relay. */
+const LEDGER_ONLY_FLAGS = ['bot', 'endpoint', 'event', 'status', 'replay', 'interval', 'limit'];
+function parseSecrets(args, ids) {
+    const raw = args.flags['secret'];
+    const values = raw === undefined || typeof raw === 'boolean' ? [] : Array.isArray(raw) ? raw : [raw];
+    let fallback = null;
+    const byTarget = new Map();
+    for (const value of values.map(String)) {
+        /*
+         * `<id>=<secret>` only when the left side IS one of the selected ids. A
+         * secret is operator-chosen on a tool, so it may itself contain `=`
+         * (standard base64 padding), and splitting every value on the first one
+         * would turn that secret into a target id nobody asked for.
+         */
+        const eq = value.indexOf('=');
+        const left = eq > 0 ? value.slice(0, eq) : '';
+        if (left.length > 0 && ids.has(left)) {
+            byTarget.set(left, value.slice(eq + 1));
+            continue;
+        }
+        if (fallback !== null) {
+            throw new Error('Two bare --secret values. With more than one target, name which secret is whose:\n' +
+                '  --secret <id>=<secret>   (repeatable)');
+        }
+        fallback = value;
+    }
+    for (const secret of [fallback, ...byTarget.values()]) {
+        if (secret === null) {
+            continue;
+        }
+        /*
+         * The two prefixes this product mints for OTHER surfaces. Neither signs
+         * a tool call, a card fetch or a canvas step, and the symptom of passing
+         * one is a 401 from your own handler that looks like a verifier bug.
+         */
+        if (secret.startsWith('whsec_') || secret.startsWith('chsec_')) {
+            throw new Error(`--secret "${secret.slice(0, 6)}…" is a ${secret.startsWith('whsec_') ? 'webhook endpoint' : 'external agent'} secret, and it signs a different surface. A relay needs the secret configured on ` +
+                "the tool, the customer card (or its endpoint), or the channel's canvas.");
+        }
+    }
+    return { fallback, byTarget };
+}
+/** Read the relay flags, refusing anything that cannot work, with the fix named. */
+export function parseRelayOptions(args) {
+    for (const name of LEDGER_ONLY_FLAGS) {
+        if (args.flags[name] !== undefined) {
+            throw new Error(`--${name} tails a delivery ledger and means nothing on --relay, which receives live ` +
+                'calls instead of replaying logged ones.');
+        }
+    }
+    const tools = listFlag(args, 'tool');
+    const cards = listFlag(args, 'card');
+    const canvases = listFlag(args, 'canvas');
+    if (tools.length + cards.length + canvases.length === 0) {
+        throw new Error('--relay needs at least one explicit target, because it takes PRODUCTION traffic:\n' +
+            '  --tool <id>          an AI tool (chatly ai tools list)\n' +
+            '  --card <id>          a customer card (chatly customer-cards list)\n' +
+            "  --canvas <channelId> a channel's canvas endpoint\n" +
+            'There is deliberately no form that relays everything.');
+    }
+    const forwardTo = str(args.flags, 'forward-to') ?? null;
+    if (forwardTo === null) {
+        throw new Error('--relay needs --forward-to. A relayed call is waiting for an answer, so there is no ' +
+            'print-only mode:\n  chatly listen --relay --tool <id> --forward-to http://localhost:3000');
+    }
+    let parsed;
+    try {
+        parsed = new URL(forwardTo);
+    }
+    catch {
+        parsed = null;
+    }
+    // `localhost:3000` parses, as the scheme `localhost:` — see listen-core.ts.
+    if (parsed === null || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+        throw new Error(`--forward-to "${forwardTo}" is not an http(s) URL. Include the scheme:\n` +
+            '  --forward-to http://localhost:3000');
+    }
+    if (parsed.search !== '' || parsed.hash !== '') {
+        // The configured url's own query is appended (see relayTargetUrl), and
+        // merging two query strings would sign one the handler does not receive.
+        throw new Error(`--forward-to "${forwardTo}" has a query or fragment. Give an origin, optionally with a ` +
+            "path prefix; each call's own path and query are appended to it.");
+    }
+    const ids = new Set([...tools, ...cards, ...canvases]);
+    return {
+        forwardTo,
+        tools,
+        cards,
+        canvases,
+        secrets: parseSecrets(args, ids),
+        json: bool(args.flags, 'json'),
+    };
+}
+/**
+ * Where one frame goes: `--forward-to`'s origin and path prefix, then the
+ * CONFIGURED url's path and query.
+ *
+ * The path is preserved because for a tool call it IS the request —
+ * `GET /orders/{{order_id}}` renders to `/orders/42`, and a handler that
+ * cannot see the 42 cannot answer. Cards and canvases are kept the same way
+ * so there is one rule, and a local server mounted under a prefix still works.
+ */
+export function relayTargetUrl(forwardTo, framePath) {
+    const base = new URL(forwardTo);
+    const prefix = base.pathname.replace(/\/+$/, '');
+    const rel = framePath.startsWith('/') ? framePath : `/${framePath}`;
+    const q = rel.indexOf('?');
+    const pathname = q === -1 ? rel : rel.slice(0, q);
+    const search = q === -1 ? '' : rel.slice(q);
+    return `${base.origin}${prefix}${pathname}${search}`;
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === 'string'));
+}
+/**
+ * The frames on one poll, and how many were unreadable.
+ *
+ * Hand-checked rather than zod, because this package declares the SDK as its
+ * only dependency (CLAUDE.md §2: no new dependency without approval). An
+ * unreadable frame is COUNTED, not silently dropped — the server is waiting
+ * on it, and a relay that loses frames quietly reads as a slow handler.
+ */
+export function readFrames(value) {
+    const list = typeof value === 'object' && value !== null
+        ? value.frames
+        : undefined;
+    if (!Array.isArray(list)) {
+        return { frames: [], unreadable: 0 };
+    }
+    const frames = [];
+    let unreadable = 0;
+    for (const f of list) {
+        const r = (typeof f === 'object' && f !== null ? f : {});
+        if (typeof r['id'] === 'string' &&
+            typeof r['kind'] === 'string' &&
+            RELAY_KINDS.includes(r['kind']) &&
+            typeof r['targetId'] === 'string' &&
+            typeof r['method'] === 'string' &&
+            typeof r['path'] === 'string' &&
+            isStringRecord(r['headers']) &&
+            typeof r['body'] === 'string' &&
+            typeof r['deadlineAt'] === 'string' &&
+            !Number.isNaN(Date.parse(r['deadlineAt']))) {
+            frames.push(r);
+        }
+        else {
+            unreadable += 1;
+        }
+    }
+    return { frames, unreadable };
+}
+/** Which selected set a frame's kind is checked against. */
+export function selectedFor(opts, kind) {
+    return kind === 'ai_tool_call'
+        ? opts.tools
+        : kind === 'customer_card'
+            ? opts.cards
+            : opts.canvases;
+}
+export function secretFor(opts, targetId) {
+    return opts.secrets.byTarget.get(targetId) ?? opts.secrets.fallback;
+}
+//# sourceMappingURL=listen-relay-options.js.map

package/dist/commands/listen-relay-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-relay-options.js","sourceRoot":"","sources":["../../src/commands/listen-relay-options.ts"],"names":[],"mappings":"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"}