rogerrat 1.4.1 → 1.19.0

package/dist/remote-control.js

@@ -0,0 +1,113 @@
+// One-shot bootstrap for the "let me drive the agent from my phone" flow.
+// Composes the existing primitives — create_account + create_identity + create_channel
+// + a /join for the agent itself — so an agent can do it in a single tool call
+// instead of stitching four together.
+//
+// Returns:
+//   - agent: callsign + identity_key the agent uses to enter the channel.
+//   - phone: callsign + identity_key the phone uses to enter the channel.
+//   - channel_id, channel_token, mobile_url
+//
+// Same function backs:
+//   - POST /api/remote-control                       (REST: human-friendly bootstrap)
+//   - MCP tool open_remote_control (in mcp.ts)       (one-call bootstrap for agents)
+import { randomBytes } from "node:crypto";
+import QRCode from "qrcode";
+import { createAccount, createIdentity, verifySession } from "./accounts.js";
+import { createChannel } from "./store.js";
+export async function createRemoteControl(opts) {
+    // 1. Resolve the account: either reuse the caller's, or mint a fresh anonymous one.
+    let accountId;
+    let recoveryToken = null;
+    if (opts.sessionToken) {
+        const id = verifySession(opts.sessionToken);
+        if (!id)
+            return { error: "invalid or expired session_token", code: "unauthorized" };
+        accountId = id;
+    }
+    else {
+        const acc = createAccount();
+        accountId = acc.account_id;
+        recoveryToken = acc.recovery_token;
+    }
+    // 2. Mint two identities on that account. Both need require_identity=true on
+    //    the channel, so each side authenticates with its own identity_key.
+    //    Callsigns are random hex slugs — opaque, collision-resistant, and not
+    //    advertised back to the user (they look at agent/phone roles, not names).
+    const randomCallsign = (prefix) => `${prefix}-${randomBytes(3).toString("hex")}`;
+    const agent = createIdentity(accountId, randomCallsign("agent"));
+    if ("error" in agent)
+        return { error: agent.error, code: "internal" };
+    const phone = createIdentity(accountId, randomCallsign("phone"));
+    if ("error" in phone)
+        return { error: phone.error, code: "internal" };
+    // 3. Mint a random owner_password and create the channel.
+    //    - require_identity=true: both sides authenticate by identity_key.
+    //    - trust_mode=trusted + owner_password set: when the agent joins with
+    //      identity_key + owner_password, the join handler stamps that session as
+    //      `human_authorized` → trust_posture becomes "trusted-authorized" →
+    //      operating instructions tell the agent to act on peer requests without
+    //      per-action confirmation (still refuses destructive ops).
+    //    - retention=metadata: join/leave log without storing message bodies.
+    //    - 24h TTL: sessions survive screen-off / app-switch without re-joining.
+    //    base64url for URL-safety; 16 bytes = 22 chars, well above the 6-char floor.
+    const ownerPassword = randomBytes(16).toString("base64url");
+    const ch = createChannel({
+        retention: "metadata",
+        require_identity: true,
+        trust_mode: "trusted",
+        session_ttl_seconds: 24 * 60 * 60,
+        creator_account_id: accountId,
+        owner_password: ownerPassword,
+    });
+    if ("error" in ch)
+        return { error: ch.error, code: "internal" };
+    // 4. Build the mobile URL with creds in the fragment (never on the wire).
+    //    The owner_password is DELIBERATELY NOT embedded — the user has to type it
+    //    manually on /remote. Rationale: if the URL leaks (screenshot, share-sheet,
+    //    browser sync), the leaker can still join the channel (identity_key is in
+    //    the URL), but their session is `human_authorized=false` — auditable as a
+    //    non-human join. Only someone who got the password through a separate
+    //    channel (the agent's MCP response, told to them by the human) can flip
+    //    their session to `trusted-authorized`.
+    const frag = new URLSearchParams();
+    frag.set("t", ch.token);
+    frag.set("k", phone.identity_key);
+    frag.set("cs", phone.callsign);
+    const mobileUrl = `${opts.publicOrigin}/remote/${ch.id}#${frag.toString()}`;
+    // 5. Render an ASCII (unicode-block) QR of mobile_url for terminal display.
+    //    `type:'terminal' small:true` outputs 2-row-per-cell using ▀ ▄ █ — most
+    //    terminals + camera apps handle it fine. errorCorrectionLevel 'L' keeps
+    //    the QR small (URL is ~110 chars, M/Q/H would balloon the size and choke
+    //    narrow terminal columns).
+    const qrAscii = await QRCode.toString(mobileUrl, {
+        type: "terminal",
+        small: true,
+        errorCorrectionLevel: "L",
+    });
+    // 6. Build the listen-here receiver command template. `<SID>` is a placeholder
+    //    the agent substitutes with the session_id it gets back from /join.
+    //    --format text + --inbox is the safe default — text format means each line
+    //    is a self-contained human-readable notification, so the agent's Monitor
+    //    tool can tail the file as bare `tail -F` with no parser in between
+    //    (adding jq/python in the Monitor cmd is a frequent source of silent
+    //    breakage from shell-escaping bugs). For programmatic consumers, swap to
+    //    --format jsonl downstream of this recipe.
+    const inboxPath = `/tmp/rr-${ch.id}.log`;
+    const receiverCommandTemplate = `nohup npx -y rogerrat listen-here --channel ${ch.id} --token ${ch.token} --session <SID> --origin ${opts.publicOrigin} --inbox ${inboxPath} --format text --quiet >/dev/null 2>&1 &`;
+    const monitorCommand = `stdbuf -oL tail -n 0 -F ${inboxPath}`;
+    return {
+        channel_id: ch.id,
+        channel_token: ch.token,
+        owner_password: ownerPassword,
+        agent: { callsign: agent.callsign, identity_key: agent.identity_key },
+        phone: { callsign: phone.callsign, identity_key: phone.identity_key },
+        mobile_url: mobileUrl,
+        qr_ascii: qrAscii,
+        account_id: accountId,
+        recovery_token: recoveryToken,
+        session_ttl_seconds: ch.session_ttl_seconds,
+        receiver_command_template: receiverCommandTemplate,
+        monitor_command_template: monitorCommand,
+    };
+}