@nac3/forge-cli 0.2.1-alpha.60 → 1.0.0

package/dist/relay/board_snapshot.js

@@ -0,0 +1,149 @@
+/**
+ * Compact "board" snapshot for the P2 relay -- what the phone's Pizarron
+ * tab mirrors. The desktop's canonical boards (semantic graph, BPMN,
+ * etc.) are large; this is a small, high-signal digest that fits the
+ * relay payload budget (<32KB): the workflow phases/progress + the open
+ * pendings. Best-effort -- a missing source just drops that section.
+ *
+ * ASCII-only.
+ */
+import { readWorkflow } from '../workflow/state.js';
+import { computeWorkflowView } from '../workflow/view.js';
+import { readPending } from '../pending/store.js';
+export const NODE_GROUPS = [
+    'backend', 'frontend', 'mobile', 'tests', 'tools', 'scripts', 'libs', 'protocol',
+];
+/** Deterministic high-level grouping of a graph node from its id + kind.
+ *  Tool/script/lib are exact by id prefix; module/component fall back to
+ *  path/name heuristics (best-effort -- coarse module nodes are fuzzy). */
+export function nodeGroup(id, name, kind) {
+    if (id.startsWith('tool.ci.'))
+        return 'tools';
+    if (id.startsWith('tool.npm.') || id.startsWith('tool.script.'))
+        return 'scripts';
+    if (kind === 'library' || id.startsWith('lib.'))
+        return 'libs';
+    const s = (id + ' ' + name).toLowerCase();
+    if (/(^|[._-])(test|tests|spec|vitest|playwright|qa)([._-]|$)|test_agent|\.test\b/.test(s))
+        return 'tests';
+    if (/forge-mobile|nac3-rn|expo|metro|apps[._-]forge|(^|[._-])mobile([._-]|$)/.test(s))
+        return 'mobile';
+    if (/panel|pizarron|chat|reader|design|figma|(^|[._-])ui([._-]|$)|component|webview|board|view/.test(s))
+        return 'frontend';
+    if (kind === 'protocol' || id.startsWith('proto'))
+        return 'protocol';
+    return 'backend';
+}
+/** Build a compact board snapshot. Never throws. */
+export async function buildBoardSnapshot(projectRoot, slug) {
+    const snap = { ts: new Date().toISOString() };
+    try {
+        const wf = await readWorkflow(projectRoot);
+        const v = computeWorkflowView(wf);
+        snap.workflow = {
+            title: v.title,
+            done: v.done_steps,
+            total: v.total_steps,
+            stages: v.stages.slice(0, 12).map((s) => ({
+                title: s.title, status: s.status, done: s.done, total: s.total,
+            })),
+        };
+    }
+    catch { /* no workflow yet -> omit */ }
+    if (slug) {
+        try {
+            const pf = await readPending(slug);
+            const open = pf.items.filter((i) => !i.closed_at);
+            open.sort((a, b) => a.priority - b.priority);
+            snap.pendings = {
+                open: open.length,
+                /* Pablo 2026-06-15: 6 was too few -- the phone's list looked
+                 * truncated. Send up to 40 (the mobile scrolls). */
+                top: open.slice(0, 40).map((i) => ({
+                    id: i.id, title: i.title, priority: i.priority,
+                    category: i.category,
+                    /* functional detail for the phone's pending-detail view (#4),
+                     * bounded so the snapshot stays compact. */
+                    body: typeof i.body === 'string'
+                        ? i.body.slice(0, 500) : undefined,
+                })),
+            };
+        }
+        catch { /* no pendings -> omit */ }
+        /* PND-094 ext -- the coexisting workflows + tasks-by-stage. Compact:
+         * task id/title/closed only (the phone cross-refs `pendings` for the
+         * full detail). Capped so the board stays small. */
+        try {
+            const { computeWorkflowsView } = await import('../workflow/multi_view.js');
+            const cards = await computeWorkflowsView(slug, 'open');
+            if (cards.length) {
+                snap.workflows = cards.slice(0, 8).map((c) => ({
+                    code: c.code, name: c.name, kind: c.kind, status: c.status,
+                    done: c.done, total: c.total,
+                    stages: c.stages.map((s) => ({
+                        id: s.id, title: s.title,
+                        tasks: s.tasks.slice(0, 60).map((t) => ({
+                            id: t.id, title: t.title.slice(0, 90), closed: t.closed,
+                            ...(t.ad_hoc ? { ad_hoc: true } : {}),
+                        })),
+                    })),
+                }));
+            }
+        }
+        catch { /* no workflows -> omit */ }
+    }
+    return snap;
+}
+/* The semantic graph for the phone's "Grafo" tab travels in its OWN
+ * relay event (kind 'graph') so it does not share the board's 32KB
+ * budget -- that is what let the old code cap nodes at 60 and drop most
+ * edges. With its own budget we send the whole connected subgraph (all
+ * edges + their nodes) plus a generous fill of relevant isolated nodes.
+ *
+ * Same edge-fidelity rule: pick the EDGE-CONNECTED nodes first so no
+ * edge is orphaned, then fill with the most relevant nodes. */
+export async function buildGraphSnapshot(slug) {
+    try {
+        const { listRelevant, listAllEdges } = await import('../semantic_graph/store.js');
+        const NODE_CAP = 300; /* own event budget -- far above the old 60 */
+        const EDGE_CAP = 600;
+        /* Exclude `comp.*` (function-level) nodes -- too granular + their long
+         * ids blow the payload past 32KB. Same level the desktop graph shows
+         * (modules / libs / tooling / protocol). */
+        const pool = (await listRelevant(slug, { limit: 2000, min_confidence: 'claimed' }))
+            .filter((n) => !n.id.startsWith('comp.'));
+        if (!pool.length)
+            return null;
+        const byId = new Map(pool.map((n) => [n.id, n]));
+        const allEdges = (await listAllEdges(slug)).slice(0, EDGE_CAP);
+        const chosen = new Map();
+        for (const e of allEdges) {
+            if (chosen.size >= NODE_CAP)
+                break;
+            const a = byId.get(e.from_id);
+            if (a)
+                chosen.set(a.id, a);
+            const b = byId.get(e.to_id);
+            if (b)
+                chosen.set(b.id, b);
+        }
+        for (const n of pool) {
+            if (chosen.size >= NODE_CAP)
+                break;
+            if (!chosen.has(n.id))
+                chosen.set(n.id, n);
+        }
+        const nodeIds = new Set(chosen.keys());
+        const edges = allEdges.filter((e) => nodeIds.has(e.from_id) && nodeIds.has(e.to_id));
+        return {
+            nodes: [...chosen.values()].map((n) => ({
+                id: n.id, label: n.name, kind: n.kind, group: nodeGroup(n.id, n.name, n.kind),
+            })),
+            edges: edges.map((e) => ({ from: e.from_id, to: e.to_id, kind: e.kind })),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=board_snapshot.js.map

package/dist/relay/board_snapshot.js.map

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

package/dist/relay/command_consumer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Desktop relay command consumer (P2, Fase 2).
+ *
+ * The mirror of RelayPublisher: where the publisher pushes the desktop's
+ * activity OUT to the phone, this pulls the phone's chat commands IN.
+ * It polls the relay for `command` events, runs each through the chat
+ * turn pipeline, and publishes the assistant reply back as `chat_reply`
+ * (correlated by the command id the phone generated).
+ *
+ * This is what makes "command your laptop from your phone" real: the
+ * phone is a thin remote; the desktop session (with the user's BYOK
+ * brain + project context) does the actual work and answers.
+ *
+ * Best-effort + gated (YF_RELAY=1 + paired). A relay outage or a failed
+ * turn never crashes the desktop; the failure is reported back to the
+ * phone as a reply so the user is never left hanging.
+ *
+ * Deps are injected so the loop is unit-tested without a network or the
+ * full HTTP server (tests/relay-command-consumer.test.ts).
+ *
+ * ASCII-only.
+ */
+export interface ConsumerCommand {
+    /** command id generated by the phone (correlates the reply). */
+    id: string;
+    /** the user's message text (empty for control commands). */
+    text: string;
+    /** command type (default 'chat'). */
+    type?: string;
+    /** conversation thread the phone wants this to run in. Absent = the
+     *  unified desktop thread ('Sesion de la notebook'). */
+    sessionId?: string;
+    /** Control commands (type='control') carry an action instead of text:
+     *  e.g. switch_project (args.slug) or interrupt. They do NOT run a
+     *  chat turn -- they go through deps.onControl. (tasks #33, #29) */
+    control?: {
+        action: string;
+        args: Record<string, unknown>;
+    };
+}
+export interface CommandConsumerDeps {
+    /** Poll the relay for command events with seq > since. `ts` is the
+     *  event's ISO timestamp (used for the freshness window). */
+    pollCommands: (since: number) => Promise<{
+        ok: boolean;
+        events: Array<{
+            seq: number;
+            payload: Record<string, unknown>;
+            ts?: string;
+        }>;
+        cursor: number;
+    }>;
+    /** Run a chat turn (in the given thread) and resolve the reply text. */
+    runTurn: (text: string, sessionId?: string) => Promise<string>;
+    /** Handle a control command (switch_project, interrupt, ...) and
+     *  resolve a short status string to send back. Optional: when absent,
+     *  control commands are reported as unsupported. (tasks #33, #29) */
+    onControl?: (action: string, args: Record<string, unknown>) => Promise<string>;
+    /** Publish the reply for a command (chat_reply). */
+    reply: (commandId: string, text: string, done: boolean) => void;
+    /** Gate -- only runs when true (YF_RELAY flag + paired). */
+    enabled: () => boolean;
+    /** Optional filter -- process only commands this returns true for.
+     *  Lets the desktop run TWO consumers over the same stream: a chat
+     *  consumer (skips control) and a fast control consumer (skips chat),
+     *  so an interrupt is handled mid-turn while the chat consumer is
+     *  blocked running the turn. (task #29) */
+    accept?: (cmd: ConsumerCommand) => boolean;
+    /** Poll interval ms. Default 3000. */
+    intervalMs?: number;
+    /** Freshness window (Pablo 2026-06-15): a phone command is a REAL-TIME
+     *  request. On (re)connect the consumer polls the relay from cursor 0
+     *  and would otherwise replay the ENTIRE backlog -- executing every old
+     *  pending request one by one. Commands whose event ts is older than
+     *  this are skipped (cursor still advances). Default 120000 (2 min);
+     *  0/undefined disables the window. */
+    maxCommandAgeMs?: number;
+    /** Injectable clock for the freshness window (tests). Default Date.now. */
+    now?: () => number;
+    /** Optional error sink (diagnostics). */
+    onError?: (e: unknown) => void;
+}
+export interface CommandConsumerHandle {
+    stop(): void;
+    /** Run one poll+dispatch cycle now (used by tests). */
+    tickOnce(): Promise<void>;
+}
+/** Pull a usable command out of an event payload, or null to skip. */
+export declare function parseCommand(payload: Record<string, unknown>): ConsumerCommand | null;
+export declare function startCommandConsumer(deps: CommandConsumerDeps): CommandConsumerHandle;
+//# sourceMappingURL=command_consumer.d.ts.map

package/dist/relay/command_consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command_consumer.d.ts","sourceRoot":"","sources":["../../src/relay/command_consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;4DACwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;wEAEoE;IACpE,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC;iEAC6D;IAC7D,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QACvC,EAAE,EAAE,OAAO,CAAC;QACZ,MAAM,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9E,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,wEAAwE;IACxE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D;;yEAEqE;IACrE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,oDAAoD;IACpD,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAChE,4DAA4D;IAC5D,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB;;;;+CAI2C;IAC3C,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC;IAC3C,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;2CAKuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,IAAI,IAAI,CAAC;IACb,uDAAuD;IACvD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAMD,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,GAAG,IAAI,CAoBrF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAmErF"}

package/dist/relay/command_consumer.js

@@ -0,0 +1,129 @@
+/**
+ * Desktop relay command consumer (P2, Fase 2).
+ *
+ * The mirror of RelayPublisher: where the publisher pushes the desktop's
+ * activity OUT to the phone, this pulls the phone's chat commands IN.
+ * It polls the relay for `command` events, runs each through the chat
+ * turn pipeline, and publishes the assistant reply back as `chat_reply`
+ * (correlated by the command id the phone generated).
+ *
+ * This is what makes "command your laptop from your phone" real: the
+ * phone is a thin remote; the desktop session (with the user's BYOK
+ * brain + project context) does the actual work and answers.
+ *
+ * Best-effort + gated (YF_RELAY=1 + paired). A relay outage or a failed
+ * turn never crashes the desktop; the failure is reported back to the
+ * phone as a reply so the user is never left hanging.
+ *
+ * Deps are injected so the loop is unit-tested without a network or the
+ * full HTTP server (tests/relay-command-consumer.test.ts).
+ *
+ * ASCII-only.
+ */
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Pull a usable command out of an event payload, or null to skip. */
+export function parseCommand(payload) {
+    const type = typeof payload.type === 'string' ? payload.type : 'chat';
+    const id = typeof payload.id === 'string' && payload.id ? payload.id : '';
+    if (!id)
+        return null;
+    /* Control commands (switch_project, interrupt) carry an action and
+     * never run a chat turn (tasks #33, #29). */
+    if (type === 'control') {
+        const action = typeof payload.action === 'string' && payload.action ? payload.action : '';
+        if (!action)
+            return null;
+        const args = (payload.args && typeof payload.args === 'object')
+            ? payload.args : {};
+        return { id, text: '', type, control: { action, args } };
+    }
+    /* Only chat-style commands run a turn. */
+    if (type !== 'chat' && type !== 'command' && type !== '')
+        return null;
+    const text = typeof payload.text === 'string' ? payload.text.trim() : '';
+    if (!text)
+        return null;
+    const sessionId = typeof payload.session_id === 'string' && payload.session_id
+        ? payload.session_id : undefined;
+    return { id, text, type, ...(sessionId ? { sessionId } : {}) };
+}
+export function startCommandConsumer(deps) {
+    let stopped = false;
+    let cursor = 0;
+    let inflight = false;
+    let timer = null;
+    const interval = deps.intervalMs ?? 3000;
+    const tickOnce = async () => {
+        if (inflight || !deps.enabled())
+            return;
+        inflight = true;
+        try {
+            const r = await deps.pollCommands(cursor);
+            if (r && r.ok) {
+                if (typeof r.cursor === 'number')
+                    cursor = r.cursor;
+                const maxAge = deps.maxCommandAgeMs ?? 120_000;
+                const nowMs = (deps.now ?? Date.now)();
+                for (const ev of r.events) {
+                    /* Freshness window -- never replay a stale backlog of phone
+                     * commands on (re)connect. The cursor already advanced above,
+                     * so a skipped command is dropped for good. */
+                    if (maxAge > 0 && ev.ts) {
+                        const age = nowMs - Date.parse(ev.ts);
+                        if (Number.isFinite(age) && age > maxAge)
+                            continue;
+                    }
+                    const cmd = parseCommand(ev.payload || {});
+                    if (!cmd)
+                        continue;
+                    /* When two consumers share the stream, each takes its subset
+                     * (the other still advances its own cursor past skipped
+                     * events). (task #29) */
+                    if (deps.accept && !deps.accept(cmd))
+                        continue;
+                    try {
+                        if (cmd.control) {
+                            const status = deps.onControl
+                                ? await deps.onControl(cmd.control.action, cmd.control.args)
+                                : 'Accion no soportada: ' + cmd.control.action;
+                            deps.reply(cmd.id, status, true);
+                        }
+                        else {
+                            const replyText = await deps.runTurn(cmd.text, cmd.sessionId);
+                            deps.reply(cmd.id, replyText, true);
+                        }
+                    }
+                    catch (e) {
+                        deps.onError?.(e);
+                        deps.reply(cmd.id, 'No pude completar tu pedido: ' + errMsg(e), true);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            deps.onError?.(e);
+        }
+        finally {
+            inflight = false;
+        }
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        timer = setTimeout(() => { void tickOnce().finally(schedule); }, interval);
+        if (timer && typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    };
+    schedule();
+    return {
+        stop() { stopped = true; if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        } },
+        tickOnce,
+    };
+}
+//# sourceMappingURL=command_consumer.js.map

package/dist/relay/command_consumer.js.map

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

package/dist/relay/mock_relay.d.ts

@@ -0,0 +1,34 @@
+/**
+ * In-memory mock of the remote-relay worker (P2). Implements the
+ * contract (docs/MOBILE_REMOTE_RELAY_CONTRACT.md) so the desktop +
+ * mobile relay clients can be built + tested WITHOUT the real
+ * Cloudflare worker. Also handy for `yf chat` local dev.
+ *
+ * It exposes a `fetch`-compatible method the clients use as their
+ * fetchImpl. No auth check (the real worker validates the bearer);
+ * the mock trusts the handle in the path.
+ *
+ * ASCII-only.
+ */
+import { type RelayAppendEvent, type RelayFrom, type RelayAppendResult, type RelayPollResult } from './types.js';
+export declare class MockRelay {
+    private channels;
+    private now;
+    constructor(opts?: {
+        now?: () => string;
+    });
+    private chan;
+    append(handle: string, from: RelayFrom, deviceId: string, events: RelayAppendEvent[]): RelayAppendResult;
+    poll(handle: string, since: number, kinds?: string[]): RelayPollResult;
+    /** fetch-compatible impl. Routes POST/GET /v1/relay/<handle>. */
+    fetch: (input: string | URL | {
+        url: string;
+    }, init?: {
+        method?: string;
+        body?: string;
+    }) => Promise<Response>;
+    private json;
+    /** Test helper: total events stored for a handle. */
+    size(handle: string): number;
+}
+//# sourceMappingURL=mock_relay.d.ts.map

package/dist/relay/mock_relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock_relay.d.ts","sourceRoot":"","sources":["../../src/relay/mock_relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACY,KAAK,gBAAgB,EAAE,KAAK,SAAS,EACtD,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAC7C,MAAM,YAAY,CAAC;AAIpB,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,GAAG,CAAe;gBAEd,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAI7C,OAAO,CAAC,IAAI;IAMZ,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,iBAAiB;IAuBxG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,eAAe;IAUtE,iEAAiE;IACjE,KAAK,UAAiB,MAAM,GAAG,GAAG,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,SAAS;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,QAAQ,CAAC,CAiBjH;IAEF,OAAO,CAAC,IAAI;IAIZ,qDAAqD;IACrD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAC7B"}

package/dist/relay/mock_relay.js

@@ -0,0 +1,93 @@
+/**
+ * In-memory mock of the remote-relay worker (P2). Implements the
+ * contract (docs/MOBILE_REMOTE_RELAY_CONTRACT.md) so the desktop +
+ * mobile relay clients can be built + tested WITHOUT the real
+ * Cloudflare worker. Also handy for `yf chat` local dev.
+ *
+ * It exposes a `fetch`-compatible method the clients use as their
+ * fetchImpl. No auth check (the real worker validates the bearer);
+ * the mock trusts the handle in the path.
+ *
+ * ASCII-only.
+ */
+import { RELAY_LIMITS, } from './types.js';
+export class MockRelay {
+    channels = new Map();
+    now;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => new Date().toISOString());
+    }
+    chan(handle) {
+        let c = this.channels.get(handle);
+        if (!c) {
+            c = { seq: 0, log: [], firstSeq: 1 };
+            this.channels.set(handle, c);
+        }
+        return c;
+    }
+    append(handle, from, deviceId, events) {
+        if (!Array.isArray(events) || events.length === 0)
+            return { ok: false, error: 'no_events' };
+        if (events.length > RELAY_LIMITS.maxEventsPerAppend)
+            return { ok: false, error: 'payload_too_large' };
+        for (const e of events) {
+            if (Buffer.byteLength(JSON.stringify(e.payload ?? {}), 'utf-8') > RELAY_LIMITS.maxPayloadBytes) {
+                return { ok: false, error: 'payload_too_large' };
+            }
+        }
+        const c = this.chan(handle);
+        const ts = this.now();
+        const seqFrom = c.seq + 1;
+        for (const e of events) {
+            c.seq += 1;
+            c.log.push({ seq: c.seq, ts, from, device_id: deviceId, kind: e.kind, payload: e.payload ?? {} });
+        }
+        /* retencion: ultimos N */
+        if (c.log.length > RELAY_LIMITS.retainEvents) {
+            c.log.splice(0, c.log.length - RELAY_LIMITS.retainEvents);
+            c.firstSeq = c.log[0].seq;
+        }
+        return { ok: true, seq_from: seqFrom, seq_to: c.seq, server_ts: ts };
+    }
+    poll(handle, since, kinds) {
+        const c = this.chan(handle);
+        const sinceN = Number.isFinite(since) ? since : 0;
+        const truncated = sinceN > 0 && sinceN < c.firstSeq - 1;
+        let events = c.log.filter((e) => e.seq > sinceN);
+        if (kinds && kinds.length)
+            events = events.filter((e) => kinds.indexOf(e.kind) >= 0);
+        const cursor = events.length ? events[events.length - 1].seq : sinceN;
+        return { ok: true, events, cursor, truncated };
+    }
+    /** fetch-compatible impl. Routes POST/GET /v1/relay/<handle>. */
+    fetch = async (input, init) => {
+        const urlStr = typeof input === 'string' ? input : ('url' in input ? input.url : String(input));
+        const url = new URL(urlStr, 'http://mock');
+        const m = url.pathname.match(/\/v1\/relay\/([^/]+)/);
+        if (!m)
+            return this.json(404, { ok: false, error: 'no_channel' });
+        const handle = decodeURIComponent(m[1]);
+        const method = (init?.method ?? 'GET').toUpperCase();
+        if (method === 'POST') {
+            let body = {};
+            try {
+                body = JSON.parse(init?.body ?? '{}');
+            }
+            catch {
+                return this.json(400, { ok: false, error: 'bad_json' });
+            }
+            const r = this.append(handle, body.from === 'mobile' ? 'mobile' : 'desktop', String(body.device_id ?? ''), body.events ?? []);
+            return this.json(r.ok ? 200 : (r.error === 'payload_too_large' ? 413 : 400), r);
+        }
+        const since = Number(url.searchParams.get('since') ?? '0');
+        const kindsParam = url.searchParams.get('kinds');
+        const kinds = kindsParam ? kindsParam.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        return this.json(200, this.poll(handle, since, kinds));
+    };
+    json(status, body) {
+        return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+    }
+    /** Test helper: total events stored for a handle. */
+    size(handle) { return this.chan(handle).log.length; }
+}
+//# sourceMappingURL=mock_relay.js.map

package/dist/relay/mock_relay.js.map

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

package/dist/relay/relay_client.d.ts

@@ -0,0 +1,28 @@
+import type { RelayFrom, RelayAppendEvent, RelayAppendResult, RelayPollResult } from './types.js';
+/** Minimal fetch shape we depend on (lets the MockRelay + RN fetch
+ *  satisfy it without matching the full `typeof fetch` overloads). */
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface RelayDeps {
+    /** Stable device id (lets the other side ignore our echoes). */
+    deviceId: string;
+    baseUrl?: string;
+    fetchImpl?: FetchLike;
+    /** Test/override: returns the bearer + handle. Defaults to vault +
+     *  license. */
+    getAuth?: () => Promise<{
+        bearer: string;
+        handle: string;
+    }>;
+}
+/** Append events to this handle's relay log. */
+export declare function relayAppend(deps: RelayDeps, from: RelayFrom, events: RelayAppendEvent[]): Promise<RelayAppendResult>;
+/** Poll for events with seq > since (optionally filtered by kind). */
+export declare function relayPoll(deps: RelayDeps, since: number, kinds?: string[]): Promise<RelayPollResult>;
+//# sourceMappingURL=relay_client.d.ts.map

package/dist/relay/relay_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay_client.d.ts","sourceRoot":"","sources":["../../src/relay/relay_client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAChE,MAAM,YAAY,CAAC;AAIpB;sEACsE;AACtE,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACxE,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC;AAE/D,MAAM,WAAW,SAAS;IACxB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;mBACe;IACf,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAkCD,gDAAgD;AAChD,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU1H;AAED,sEAAsE;AACtE,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAa1G"}