@rubytech/create-realagent 1.0.621 → 1.0.622

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.621",
+  "version": "1.0.622",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/lib/device-url/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Device-bound URL emission helper.
+ *
+ * A device-bound URL is one whose intent is "the device running the Maxy
+ * platform needs to open this URL so its local state machine can progress"
+ * — as opposed to a generic external URL that opens wherever the operator
+ * is viewing the chat from.
+ *
+ * The contract: tool results that want a URL to open on the device
+ * embed a fenced markdown code block with language identifier
+ * `maxy-device-url`, containing a JSON payload { url, intent, hostname? }.
+ * The chat UI dispatches on the language identifier (alongside `mermaid`)
+ * and renders the block as a button that navigates the device's VNC
+ * browser via CDP.
+ *
+ * See `.docs/web-chat.md` § URL rendering contract for the full spec.
+ *
+ * This module is the single source of truth for the emit-side block
+ * format. Plugin MCP tools import it so every emitter produces an
+ * identical shape.
+ */
+export interface DeviceUrlOptions {
+    /** The actual URL the device should navigate to. Must be http(s). */
+    url: string;
+    /** Short human-readable label shown on the chat UI button (e.g. "Sign in to Cloudflare"). */
+    intent: string;
+    /** Optional hostname of the device — used in the fallback UI when VNC is unreachable. */
+    hostname?: string;
+}
+export declare const DEVICE_URL_LANGUAGE = "maxy-device-url";
+/**
+ * Build a fenced markdown code block that declares a device-bound URL.
+ *
+ * The returned string is meant to be concatenated into a tool-result
+ * `text` content block. The chat UI parses the fence and renders a button.
+ * When the chat UI is older than this contract (or rendering in a
+ * fallback environment), the block degrades to a readable JSON code
+ * block — no broken link, no silent swallow.
+ *
+ * Throws on invalid input so emit-side bugs surface at call time rather
+ * than producing a malformed block that the render side has to catch.
+ */
+export declare function deviceUrlBlock(opts: DeviceUrlOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/device-url/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAgC7D"}

package/payload/platform/lib/device-url/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Device-bound URL emission helper.
+ *
+ * A device-bound URL is one whose intent is "the device running the Maxy
+ * platform needs to open this URL so its local state machine can progress"
+ * — as opposed to a generic external URL that opens wherever the operator
+ * is viewing the chat from.
+ *
+ * The contract: tool results that want a URL to open on the device
+ * embed a fenced markdown code block with language identifier
+ * `maxy-device-url`, containing a JSON payload { url, intent, hostname? }.
+ * The chat UI dispatches on the language identifier (alongside `mermaid`)
+ * and renders the block as a button that navigates the device's VNC
+ * browser via CDP.
+ *
+ * See `.docs/web-chat.md` § URL rendering contract for the full spec.
+ *
+ * This module is the single source of truth for the emit-side block
+ * format. Plugin MCP tools import it so every emitter produces an
+ * identical shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEVICE_URL_LANGUAGE = void 0;
+exports.deviceUrlBlock = deviceUrlBlock;
+exports.DEVICE_URL_LANGUAGE = "maxy-device-url";
+/**
+ * Build a fenced markdown code block that declares a device-bound URL.
+ *
+ * The returned string is meant to be concatenated into a tool-result
+ * `text` content block. The chat UI parses the fence and renders a button.
+ * When the chat UI is older than this contract (or rendering in a
+ * fallback environment), the block degrades to a readable JSON code
+ * block — no broken link, no silent swallow.
+ *
+ * Throws on invalid input so emit-side bugs surface at call time rather
+ * than producing a malformed block that the render side has to catch.
+ */
+function deviceUrlBlock(opts) {
+    const { url, intent, hostname } = opts;
+    if (typeof url !== "string" || url.length === 0) {
+        throw new Error("[device-url] url is required");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`[device-url] url is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`[device-url] url scheme must be http or https (got ${parsed.protocol})`);
+    }
+    if (typeof intent !== "string" || intent.length === 0) {
+        throw new Error("[device-url] intent is required and must be a non-empty string");
+    }
+    if (intent.length > 100) {
+        throw new Error(`[device-url] intent exceeds 100 chars (got ${intent.length})`);
+    }
+    if (hostname !== undefined && typeof hostname !== "string") {
+        throw new Error("[device-url] hostname must be a string if provided");
+    }
+    const payload = hostname
+        ? { url, intent, hostname }
+        : { url, intent };
+    return "```" + exports.DEVICE_URL_LANGUAGE + "\n" + JSON.stringify(payload) + "\n```";
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/device-url/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAyBH,wCAgCC;AA9CY,QAAA,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,IAAsB;IACnD,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAEvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,sDAAsD,MAAM,CAAC,QAAQ,GAAG,CACzE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,8CAA8C,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAqB,QAAQ;QACxC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC3B,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAEpB,OAAO,KAAK,GAAG,2BAAmB,GAAG,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAChF,CAAC"}

package/payload/platform/lib/device-url/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Device-bound URL emission helper.
+ *
+ * A device-bound URL is one whose intent is "the device running the Maxy
+ * platform needs to open this URL so its local state machine can progress"
+ * — as opposed to a generic external URL that opens wherever the operator
+ * is viewing the chat from.
+ *
+ * The contract: tool results that want a URL to open on the device
+ * embed a fenced markdown code block with language identifier
+ * `maxy-device-url`, containing a JSON payload { url, intent, hostname? }.
+ * The chat UI dispatches on the language identifier (alongside `mermaid`)
+ * and renders the block as a button that navigates the device's VNC
+ * browser via CDP.
+ *
+ * See `.docs/web-chat.md` § URL rendering contract for the full spec.
+ *
+ * This module is the single source of truth for the emit-side block
+ * format. Plugin MCP tools import it so every emitter produces an
+ * identical shape.
+ */
+
+export interface DeviceUrlOptions {
+  /** The actual URL the device should navigate to. Must be http(s). */
+  url: string;
+  /** Short human-readable label shown on the chat UI button (e.g. "Sign in to Cloudflare"). */
+  intent: string;
+  /** Optional hostname of the device — used in the fallback UI when VNC is unreachable. */
+  hostname?: string;
+}
+
+export const DEVICE_URL_LANGUAGE = "maxy-device-url";
+
+/**
+ * Build a fenced markdown code block that declares a device-bound URL.
+ *
+ * The returned string is meant to be concatenated into a tool-result
+ * `text` content block. The chat UI parses the fence and renders a button.
+ * When the chat UI is older than this contract (or rendering in a
+ * fallback environment), the block degrades to a readable JSON code
+ * block — no broken link, no silent swallow.
+ *
+ * Throws on invalid input so emit-side bugs surface at call time rather
+ * than producing a malformed block that the render side has to catch.
+ */
+export function deviceUrlBlock(opts: DeviceUrlOptions): string {
+  const { url, intent, hostname } = opts;
+
+  if (typeof url !== "string" || url.length === 0) {
+    throw new Error("[device-url] url is required");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`[device-url] url is not a valid URL: ${url}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `[device-url] url scheme must be http or https (got ${parsed.protocol})`,
+    );
+  }
+  if (typeof intent !== "string" || intent.length === 0) {
+    throw new Error("[device-url] intent is required and must be a non-empty string");
+  }
+  if (intent.length > 100) {
+    throw new Error(`[device-url] intent exceeds 100 chars (got ${intent.length})`);
+  }
+  if (hostname !== undefined && typeof hostname !== "string") {
+    throw new Error("[device-url] hostname must be a string if provided");
+  }
+
+  const payload: DeviceUrlOptions = hostname
+    ? { url, intent, hostname }
+    : { url, intent };
+
+  return "```" + DEVICE_URL_LANGUAGE + "\n" + JSON.stringify(payload) + "\n```";
+}

package/payload/platform/lib/device-url/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -8,6 +8,7 @@ import { resolve, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { writeKey, validateKey, hasKey, keyFilePath } from "../../../../lib/anthropic-key/dist/index.js";
+import { deviceUrlBlock } from "../../../../lib/device-url/dist/index.js";
 import { createHash, randomInt, randomUUID } from "node:crypto";
 import { createConnection } from "node:net";
 import { homedir, hostname as osHostname } from "node:os";
@@ -333,7 +334,7 @@ server.tool("system-status", "Check health of all Maxy platform services: Neo4j,
         .join("\n");
     return { content: [{ type: "text", text: formatted }] };
 });
-server.tool("remote-auth-status", "Check whether the remote access password is configured. Returns configured (true/false) and the setupUrl for the user to set a password in their browser. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
+server.tool("remote-auth-status", "Check whether the remote access password is configured. When not configured, emits a device-bound URL affordance (maxy-device-url fenced block) pointing at the password setup page — this URL opens on the device's own screen when the operator clicks it. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
     const TAG = "[remote-auth-status]";
     const platformPort = parseInt(PLATFORM_PORT, 10);
     const setupUrl = `http://${osHostname()}.local:${platformPort}/__remote-auth/setup`;
@@ -344,11 +345,17 @@ server.tool("remote-auth-status", "Check whether the remote access password is c
         const body = await res.json();
         const configured = body.configured === true;
         console.error(`${TAG} configured=${configured} port=${platformPort}`);
+        // Shape the response for both the agent (deciding what to say) and
+        // the user (seeing the device-URL button when they need to act).
+        // Configured → plain status, no URL. Unconfigured → include the
+        // fenced block so the agent can surface the button verbatim.
+        const text = configured
+            ? `Remote access password is configured.`
+            : `Remote access password is not configured. The admin interface will refuse to expose over the tunnel until one is set.\n\n` +
+                `${deviceUrlBlock({ url: setupUrl, intent: "Set remote access password", hostname: osHostname() })}\n\n` +
+                `Click the button above to open the setup page on the device's browser. Do NOT collect the password in chat.`;
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({ configured, setupUrl }),
-                }],
+            content: [{ type: "text", text }],
         };
     }
     catch (err) {