forge-memory 0.2.111 → 0.2.113

package/README.md

@@ -40,8 +40,9 @@ show up as a tool result instead of a closed MCP transport.
 `pair-ios` prefers the Iroh QR. Forge starts a Rust Iroh host, prints a QR payload
 with the desktop node id, pairing token, optional relay hint, and ALPN
 `forge-companion/1`, and the iPhone app connects through its native Rust bridge. The
-CLI renders a compact QR and saves the same compact payload under
-`~/.forge/pairing/` so you can paste it into the iPhone app if the camera cannot scan.
+CLI renders a short-schema QR to keep the terminal code scannable and saves the
+full manual payload under `~/.forge/pairing/` so you can paste it into the iPhone
+app if the camera cannot scan.
 Use `--manual-http` only when you intentionally want a LAN, Tailscale, or direct
 HTTP/TCP route. For a real iPhone, pass a phone-reachable URL:
 
@@ -54,7 +55,11 @@ the iOS Simulator but not for a physical phone.
 
 The base install stays one command on purpose. The detailed companion transport
 reference lives in the Forge repo at `docs/companion-iroh.md` and in the published
-docs at `https://albertbuchard.github.io/forge/companion-transport.html`.
+docs at `https://albertbuchard.github.io/forge/companion-transport.html`. Forge
+Memory ships prebuilt Iroh host binaries for common desktop platforms and a bundled
+Rust source fallback for other machines. If neither a prebuilt host nor Cargo is
+available, `pair-ios` stops with transport-specific repair guidance instead of
+printing a localhost QR that a physical iPhone cannot use.
 
 `configure` reruns the full guided flow using the current config as defaults.
 Install and configure run Forge doctor before finishing. `doctor --repair` creates

package/bin/forge-memory.mjs

@@ -1616,6 +1616,22 @@ class PairingRequestError extends Error {
   }
 }
 
+class PairingTransportUnavailableError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = "PairingTransportUnavailableError";
+    this.code = "pairing_transport_unavailable";
+    this.detail = detail;
+    this.guidance = [
+      "Run npx forge-memory doctor --repair so Forge Memory refreshes the packaged runtime and companion transport files.",
+      "Then rerun npx forge-memory pair-ios.",
+      "On unsupported platforms, install Rust/Cargo so Forge can build the bundled companion Iroh source fallback.",
+      "For an explicit Tailscale or LAN fallback, rerun with npx forge-memory pair-ios --manual-http --public-url <phone-reachable Forge URL>.",
+      "Do not scan a QR whose API URL is 127.0.0.1 on a physical iPhone; that address only works in the iOS Simulator."
+    ];
+  }
+}
+
 async function bootstrapLocalOperatorSession(config) {
   const sessionUrl = forgeApiUrl(config, "/api/v1/auth/operator-session");
   let response;
@@ -1706,7 +1722,39 @@ async function createPairing(config, options = {}) {
       { url: pairingUrl.toString(), status: response.status }
     );
   }
-  return response.json();
+  const pairing = await response.json();
+  assertPairingTransportUsable(pairing, { requestedTransportMode: transportMode });
+  return pairing;
+}
+
+function assertPairingTransportUsable(pairing, { requestedTransportMode }) {
+  const payload = pairing?.qrPayload;
+  if (!payload || requestedTransportMode !== "iroh") {
+    return;
+  }
+  const resolvedTransportMode = payload.transportMode ?? payload.transport?.protocol;
+  const resolvedProtocol = payload.transport?.protocol;
+  if (resolvedTransportMode === "iroh" || resolvedProtocol === "iroh") {
+    return;
+  }
+  const apiBaseUrl = payload.apiBaseUrl ?? "";
+  const lastError = payload.transport?.lastError;
+  const notes = Array.isArray(payload.transport?.notes) ? payload.transport.notes : [];
+  throw new PairingTransportUnavailableError(
+    [
+      "Forge created a direct HTTP pairing while default iOS pairing requested Iroh.",
+      isLoopbackPairingUrl(apiBaseUrl)
+        ? `The generated API URL is ${apiBaseUrl}, which a physical iPhone cannot reach.`
+        : apiBaseUrl
+          ? `The generated API URL is ${apiBaseUrl}, but this was not an Iroh pairing.`
+          : "The response did not include a usable Iroh API URL.",
+      lastError ? `Iroh error: ${lastError}` : "",
+      notes.length ? `Notes: ${notes.join(" ")}` : ""
+    ]
+      .filter(Boolean)
+      .join(" "),
+    { apiBaseUrl, transportMode: resolvedTransportMode, protocol: resolvedProtocol }
+  );
 }
 
 function validatePairingOptions({ transportMode, publicUrl }) {
@@ -1766,6 +1814,48 @@ function compactPairingPayload(payload) {
   });
 }
 
+function compactQrPairingPayload(payload) {
+  const manualPayload = compactPairingPayload(payload);
+  const transport = manualPayload.transport
+    ? compactObject({
+        p: manualPayload.transport.protocol,
+        d: manualPayload.transport.provider,
+        s: manualPayload.transport.status,
+        pb: manualPayload.transport.publicBaseUrl,
+        lb: manualPayload.transport.localBaseUrl,
+        n: manualPayload.transport.nodeId,
+        r: manualPayload.transport.relay,
+        a: manualPayload.transport.alpn,
+        g: manualPayload.transport.agent,
+        pp: manualPayload.transport.pairPayload
+          ? compactObject({
+              v: manualPayload.transport.pairPayload.v,
+              n:
+                manualPayload.transport.pairPayload.node_id ??
+                manualPayload.transport.pairPayload.nodeId,
+              t: manualPayload.transport.pairPayload.token,
+              h:
+                manualPayload.transport.pairPayload.host_name ??
+                manualPayload.transport.pairPayload.hostName,
+              r: manualPayload.transport.pairPayload.relay
+            })
+          : undefined,
+        le: manualPayload.transport.lastError
+      })
+    : undefined;
+  return compactObject({
+    k: "fcp1",
+    a: manualPayload.apiBaseUrl,
+    u: manualPayload.uiBaseUrl,
+    m: manualPayload.transportMode,
+    t: transport,
+    s: manualPayload.sessionId,
+    pt: manualPayload.pairingToken,
+    e: manualPayload.expiresAt,
+    c: manualPayload.capabilities
+  });
+}
+
 function compactObject(value) {
   if (Array.isArray(value)) {
     const compacted = value.map((entry) => compactObject(entry)).filter((entry) => entry !== undefined);
@@ -1805,27 +1895,28 @@ function isLoopbackPairingUrl(value) {
 }
 
 async function printPairing(pairing) {
-  const payload = compactPairingPayload(pairing.qrPayload);
-  const payloadText = JSON.stringify(payload);
+  const manualPayload = compactPairingPayload(pairing.qrPayload);
+  const qrPayload = compactQrPairingPayload(pairing.qrPayload);
+  const qrPayloadText = JSON.stringify(qrPayload);
   const terminalColumns = process.stdout.columns ?? 120;
-  if (terminalColumns >= 72 && payloadText.length <= 2_950) {
+  if (terminalColumns >= 72 && qrPayloadText.length <= 1_500) {
     console.log("\nScan this compact QR in Forge Companion:\n");
-    qrcode.generate(payloadText, { small: true });
+    qrcode.generate(qrPayloadText, { small: true });
   } else {
     console.log("");
     console.log(color.yellow("QR skipped because the terminal is too narrow or the payload is too large to scan reliably."));
     console.log("Use Manual connection in the iPhone app and paste the saved payload below.");
   }
-  const transport = payload.transport;
+  const transport = manualPayload.transport;
   if (transport?.provider) {
     const label =
-      payload.transport?.protocol === "iroh"
+      manualPayload.transport?.protocol === "iroh"
         ? "Iroh"
-        : payload.transportMode === "iroh"
+        : manualPayload.transportMode === "iroh"
           ? "Iroh"
           : "Manual HTTP";
-    console.log(`${color.cyan(label)}: ${payload.apiBaseUrl}`);
-    if (label === "Manual HTTP" && isLoopbackPairingUrl(payload.apiBaseUrl)) {
+    console.log(`${color.cyan(label)}: ${manualPayload.apiBaseUrl}`);
+    if (label === "Manual HTTP" && isLoopbackPairingUrl(manualPayload.apiBaseUrl)) {
       console.log(
         color.yellow(
           "Manual HTTP points at this machine's loopback address. That is only useful for the iOS Simulator; a real iPhone needs Iroh, Tailscale, or a LAN URL passed with --public-url."
@@ -1837,7 +1928,7 @@ async function printPairing(pairing) {
     }
   }
   try {
-    const filePath = await writePairingPayloadFile(payload);
+    const filePath = await writePairingPayloadFile(manualPayload);
     console.log("");
     console.log(color.bold("If the QR is too large or the camera will not scan:"));
     console.log("1. Open Manual connection in the iPhone app.");
@@ -1845,14 +1936,18 @@ async function printPairing(pairing) {
     console.log(`3. Paste the payload saved at: ${filePath}`);
     console.log(color.dim(`   cat ${filePath}`));
     console.log("");
-    console.log(color.dim(`Compact payload bytes: ${payloadText.length}`));
+    console.log(
+      color.dim(
+        `QR payload bytes: ${qrPayloadText.length}; manual payload bytes: ${JSON.stringify(manualPayload).length}`
+      )
+    );
   } catch (error) {
     console.log(
       color.yellow(
         `Could not save pairing payload file: ${error instanceof Error ? error.message : String(error)}`
       )
     );
-    console.log(payloadText);
+    console.log(JSON.stringify(manualPayload));
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-memory",
-  "version": "0.2.111",
+  "version": "0.2.113",
   "description": "Guided Forge installer and local runtime manager for the Forge UI, OpenClaw, Hermes, Codex, and iOS pairing.",
   "type": "module",
   "license": "Apache-2.0",