@rubytech/create-realagent 1.0.867 → 1.0.869

package/payload/platform/lib/graph-mcp/src/__tests__/warnings-envelope.test.ts

@@ -0,0 +1,151 @@
+// Task 970 — Neo4j envelope-warning passthrough.
+//
+// Pure-function tests for the helpers in cypher-shim-read.ts:
+//   - filterEnvelopeNotifications: keeps only ^0[12]N5\d$ GQL status codes
+//   - stitchWarningsIntoResponse:  prepends a warnings content block
+//   - runReadProbe:                runs cypher through a shim-side session
+//                                  and returns notifications from the summary
+//
+// Failure mode this closes: the agent ran `RETURN h.hostname` against a node
+// whose property is `hostnameValue`, Neo4j emitted gql_status=01N52
+// "property does not exist", but the warning was dropped by the upstream
+// envelope and the agent saw `[]`. Without these warnings reaching the tool
+// result, the same recurrence will hit other property names too.
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  filterEnvelopeNotifications,
+  stitchWarningsIntoResponse,
+  runReadProbe,
+  type DriverNotification,
+} from "../cypher-shim-read.js";
+
+test("filterEnvelopeNotifications keeps 01N5x and 02N5x, drops everything else", () => {
+  const input: DriverNotification[] = [
+    { gqlStatus: "01N52", title: "...", description: "property does not exist (foo)", position: { offset: 0, line: 1, column: 1 } },
+    { gqlStatus: "02N50", title: "...", description: "label does not exist (Foo)", position: null },
+    { gqlStatus: "01N40", title: "...", description: "wrong family", position: null },
+    { gqlStatus: "03N42", title: "...", description: "unrelated", position: null },
+    { gqlStatus: "00N00", title: "...", description: "neutral status", position: null },
+  ];
+  const filtered = filterEnvelopeNotifications(input);
+  assert.equal(filtered.length, 2);
+  assert.equal(filtered[0].gql_status, "01N52");
+  assert.equal(filtered[0].description, "property does not exist (foo)");
+  assert.deepEqual(filtered[0].position, { offset: 0, line: 1, column: 1 });
+  assert.equal(filtered[1].gql_status, "02N50");
+  assert.equal(filtered[1].position, null);
+});
+
+test("filterEnvelopeNotifications on an empty or all-irrelevant list returns []", () => {
+  assert.deepEqual(filterEnvelopeNotifications([]), []);
+  assert.deepEqual(
+    filterEnvelopeNotifications([
+      { gqlStatus: "03N42", title: "", description: "", position: null },
+      { gqlStatus: "01N40", title: "", description: "", position: null },
+    ]),
+    [],
+  );
+});
+
+test("stitchWarningsIntoResponse prepends a warnings content block when warnings exist", () => {
+  const original = {
+    jsonrpc: "2.0",
+    id: 42,
+    result: { content: [{ type: "text", text: "[]" }] },
+  };
+  const warnings = [
+    { gql_status: "01N52", description: "property hostname does not exist", position: null },
+  ];
+  const out = stitchWarningsIntoResponse(original, warnings);
+  assert.notEqual(out, null);
+  const parsed = JSON.parse(out!);
+  assert.equal(parsed.id, 42);
+  assert.equal(parsed.result.content.length, 2);
+  assert.equal(parsed.result.content[0].type, "text");
+  assert.match(parsed.result.content[0].text, /Neo4j envelope warnings/);
+  assert.match(parsed.result.content[0].text, /01N52/);
+  assert.match(parsed.result.content[0].text, /property hostname does not exist/);
+  // Original row block preserved verbatim, after the warnings prefix.
+  assert.equal(parsed.result.content[1].text, "[]");
+});
+
+test("stitchWarningsIntoResponse returns null when no warnings (no envelope rewrite)", () => {
+  const original = { jsonrpc: "2.0", id: 1, result: { content: [{ type: "text", text: "[]" }] } };
+  assert.equal(stitchWarningsIntoResponse(original, []), null);
+});
+
+test("stitchWarningsIntoResponse handles missing result.content defensively", () => {
+  const original = { jsonrpc: "2.0", id: 1, result: {} };
+  const warnings = [{ gql_status: "01N52", description: "x", position: null }];
+  const out = stitchWarningsIntoResponse(original as never, warnings);
+  assert.notEqual(out, null);
+  const parsed = JSON.parse(out!);
+  assert.equal(parsed.result.content.length, 1);
+  assert.match(parsed.result.content[0].text, /01N52/);
+});
+
+test("runReadProbe returns notifications captured from the driver summary", async () => {
+  const session = {
+    run: async () => ({
+      summary: {
+        notifications: [
+          { gqlStatus: "01N52", title: "", description: "missing prop", position: null },
+        ] as DriverNotification[],
+      },
+    }),
+    close: async () => {},
+  };
+  const driver = { session: () => session };
+  const notifs = await runReadProbe(driver, "MATCH (n) RETURN n.foo", {});
+  assert.equal(notifs.length, 1);
+  assert.equal(notifs[0].gqlStatus, "01N52");
+});
+
+test("runReadProbe returns [] when driver summary has no notifications", async () => {
+  const session = {
+    run: async () => ({ summary: {} }),
+    close: async () => {},
+  };
+  const driver = { session: () => session };
+  assert.deepEqual(await runReadProbe(driver, "RETURN 1", {}), []);
+});
+
+test("runReadProbe closes the session even when run() throws", async () => {
+  let closed = false;
+  const session = {
+    run: async () => {
+      throw new Error("boom");
+    },
+    close: async () => {
+      closed = true;
+    },
+  };
+  const driver = { session: () => session };
+  await assert.rejects(() => runReadProbe(driver, "RETURN 1", {}));
+  assert.equal(closed, true, "session must be closed on error");
+});
+
+test("end-to-end: filter + stitch on a real-shape upstream response surfaces 01N52", () => {
+  // Models the failure mode in the original log: upstream returned an empty
+  // row list; Neo4j attached an 01N52 notification that the upstream Python
+  // server dropped.
+  const upstreamResponse = {
+    jsonrpc: "2.0",
+    id: 99,
+    result: { content: [{ type: "text", text: "[]" }] },
+  };
+  const driverNotifications: DriverNotification[] = [
+    {
+      gqlStatus: "01N52",
+      title: "Property does not exist",
+      description: "The property 'hostname' does not exist on the node",
+      position: { offset: 38, line: 1, column: 39 },
+    },
+  ];
+  const warnings = filterEnvelopeNotifications(driverNotifications);
+  const stitched = stitchWarningsIntoResponse(upstreamResponse, warnings);
+  const parsed = JSON.parse(stitched!);
+  assert.match(parsed.result.content[0].text, /01N52/);
+  assert.match(parsed.result.content[0].text, /hostname/);
+});

package/payload/platform/lib/graph-mcp/src/cypher-shim-read.ts

@@ -0,0 +1,141 @@
+/**
+ * Pure helpers for the shim-side read-warning probe (Task 970).
+ *
+ * The upstream `mcp-neo4j-cypher@0.6.0` server runs the cypher against Neo4j
+ * itself and returns rendered text; it drops `result.summary.notifications`
+ * before serialising the JSON-RPC response. That is the dropped-envelope leg
+ * of failure mode `676504f1`: the agent ran `RETURN h.hostname` against a
+ * node whose property is `hostnameValue`, Neo4j emitted `gql_status=01N52
+ * "property does not exist"`, the upstream surfaced it to its stderr but
+ * NOT to the tool result, and the agent saw `[]` with no actionable signal.
+ *
+ * The shim now runs the same cypher in a second, lightweight pass against
+ * its own Neo4j driver — only to read `summary.notifications` and stitch
+ * codes matching `^0[12]N5\d$` into a warnings prefix block on the
+ * upstream's response. The probe is sequential (after the upstream has
+ * returned) so concurrent ordering and error-handling stay simple. The
+ * upstream's rendered row text is left byte-for-byte untouched as
+ * `content[1]`, so existing callers that read the rows do not see a format
+ * change.
+ *
+ * Extracted from index.ts so the filter/stitch logic is testable as pure
+ * functions without booting the shim's stdin/stdout pipe.
+ */
+
+/** GQL status codes Neo4j 5.x emits for missing / unrecognised schema tokens.
+ *  Covers 01N5x ("property does not exist", "type does not exist", etc.) and
+ *  02N5x (label / type missing in pattern). These are the codes whose loss
+ *  most often manifests as an empty-rows result the agent cannot diagnose. */
+const ENVELOPE_GQL_RE = /^0[12]N5\d$/;
+
+/** Shape of a notification as returned by neo4j-driver 5.x's `summary.notifications`. */
+export interface DriverNotification {
+  gqlStatus: string;
+  title: string;
+  description: string;
+  position: { offset: number; line: number; column: number } | null;
+}
+
+/** Stitched envelope warning shape — what the agent sees in the tool result. */
+export interface EnvelopeWarning {
+  gql_status: string;
+  description: string;
+  position: { offset: number; line: number; column: number } | null;
+}
+
+/** Keep only notifications whose gql_status matches the envelope-passthrough set. */
+export function filterEnvelopeNotifications(
+  notifications: DriverNotification[],
+): EnvelopeWarning[] {
+  const out: EnvelopeWarning[] = [];
+  for (const n of notifications) {
+    if (typeof n.gqlStatus === "string" && ENVELOPE_GQL_RE.test(n.gqlStatus)) {
+      out.push({
+        gql_status: n.gqlStatus,
+        description: n.description,
+        position: n.position ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+/** JSON-RPC response shape — just enough to clone + prepend a content block. */
+export interface ResponseEnvelope {
+  jsonrpc?: string;
+  id?: string | number;
+  result?: {
+    content?: Array<{ type?: string; text?: string }>;
+    isError?: boolean;
+  };
+}
+
+/**
+ * Prepend a warnings content block to a JSON-RPC read response.
+ * Returns the rewritten JSON string, or `null` if there are no warnings to
+ * surface (caller forwards the original line unchanged in that case).
+ */
+export function stitchWarningsIntoResponse(
+  msg: ResponseEnvelope,
+  warnings: EnvelopeWarning[],
+): string | null {
+  if (warnings.length === 0) return null;
+  const lines = warnings.map(
+    (w) =>
+      `  - gql_status=${w.gql_status} ${w.description}` +
+      (w.position
+        ? ` (line ${w.position.line}, column ${w.position.column})`
+        : ""),
+  );
+  const text =
+    "Neo4j envelope warnings — these were emitted by the driver but " +
+    "dropped by the upstream server. Treat them as schema feedback on " +
+    "the cypher you just ran:\n" +
+    lines.join("\n") +
+    "\n\n--- results below ---";
+  const original = msg.result?.content ?? [];
+  const wrapped: ResponseEnvelope = {
+    ...msg,
+    result: {
+      ...(msg.result ?? {}),
+      content: [{ type: "text", text }, ...original],
+    },
+  };
+  return JSON.stringify(wrapped);
+}
+
+/** Minimal session / driver interfaces for the probe — defined here so the
+ *  probe is testable without importing `neo4j-driver` types at test time. */
+export interface ProbeSession {
+  run(
+    cypher: string,
+    params?: Record<string, unknown>,
+  ): Promise<{ summary: { notifications?: DriverNotification[] } }>;
+  close(): Promise<void>;
+}
+
+export interface ProbeDriver {
+  session(): ProbeSession;
+}
+
+/**
+ * Run cypher through the shim's driver purely to capture
+ * `result.summary.notifications`. The probe is best-effort: any error closes
+ * the session and rethrows so the caller can decide to forward the
+ * upstream's response unchanged.
+ */
+export async function runReadProbe(
+  driver: ProbeDriver,
+  cypher: string,
+  params: Record<string, unknown>,
+): Promise<DriverNotification[]> {
+  const session = driver.session();
+  try {
+    const result = await session.run(cypher, params);
+    return result.summary.notifications ?? [];
+  } finally {
+    await session.close().catch(() => {
+      /* session already closed on error path — swallow */
+    });
+  }
+}

package/payload/platform/lib/graph-mcp/src/index.ts

@@ -48,6 +48,13 @@ import {
   synthesiseWriteResponse,
   type GraphDriver,
 } from "./cypher-shim-write.js";
+import {
+  filterEnvelopeNotifications,
+  runReadProbe,
+  stitchWarningsIntoResponse,
+  type ProbeDriver,
+} from "./cypher-shim-read.js";
+import { createHash } from "node:crypto";
 
 const SERVER_NAME = "graph";
 const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
@@ -301,6 +308,10 @@ interface PendingCall {
    *  upstream commits (the validator only detected them; emission waits for
    *  the post-write line family). */
   writeUnknownTokens: UnknownToken[];
+  /** Task 970: full operator-supplied params (e.g. for $-bound names), kept so
+   *  the post-response envelope-warning probe runs the same cypher with the
+   *  same params as the upstream call. Reads only. */
+  cypherParams: Record<string, unknown> | null;
 }
 const pending = new Map<string | number, PendingCall>();
 
@@ -641,6 +652,13 @@ function handleRequestLine(line: string): RequestDecision {
     ? extractSessionIdParam(msg.params?.arguments)
     : null;
 
+  const operatorArgs = msg.params?.arguments ?? {};
+  const paramsArg = operatorArgs["params"];
+  const cypherParams: Record<string, unknown> | null =
+    paramsArg && typeof paramsArg === "object" && !Array.isArray(paramsArg)
+      ? (paramsArg as Record<string, unknown>)
+      : null;
+
   const entry: PendingCall = {
     method: methodName,
     cypherPrefix,
@@ -651,6 +669,7 @@ function handleRequestLine(line: string): RequestDecision {
     validated: false,
     readWarnings: [],
     writeUnknownTokens: [],
+    cypherParams: isWriteCall ? null : cypherParams,
   };
 
   if (!isCypherCall || !cypherFull) {
@@ -759,7 +778,7 @@ function handleRequestLine(line: string): RequestDecision {
   return "forward";
 }
 
-function handleResponseLine(line: string): string | null {
+async function handleResponseLine(line: string): Promise<string | null> {
   let msg: JsonRpcMessage;
   try {
     msg = JSON.parse(line) as JsonRpcMessage;
@@ -853,18 +872,83 @@ function handleResponseLine(line: string): string | null {
     }
   }
 
+  // Task 970 — envelope-warning probe. Reads only, after upstream succeeds.
+  // Runs the same cypher through the shim's own driver to harvest
+  // `summary.notifications` matching ^0[12]N5\d$ (property/label-missing
+  // codes the upstream Python server drops before serialising). Best-effort:
+  // any probe failure leaves the upstream response untouched.
+  let envelopeStitched: string | null = null;
+  if (
+    !p.isWrite &&
+    p.cypherFull &&
+    msg.result &&
+    !msg.result.isError &&
+    p.method === READ_CYPHER_TOOL
+  ) {
+    try {
+      const driver = (await getSharedDriver(
+        resolvedNeo4jUri,
+        neo4jUser,
+        neo4jPassword,
+      )) as ProbeDriver;
+      const notifications = await runReadProbe(
+        driver,
+        p.cypherFull,
+        p.cypherParams ?? {},
+      );
+      const envelopeWarnings = filterEnvelopeNotifications(notifications);
+      if (envelopeWarnings.length > 0) {
+        const queryHash = createHash("sha1")
+          .update(p.cypherFull)
+          .digest("hex")
+          .slice(0, 12);
+        for (const w of envelopeWarnings) {
+          console.error(
+            `[mcp:graph] envelope-warning gql_status=${w.gql_status} query_hash=${queryHash} description="${w.description.replace(/"/g, "'")}"`,
+          );
+        }
+        envelopeStitched = stitchWarningsIntoResponse(msg, envelopeWarnings);
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[mcp:graph] probe-error op=${p.method} error="${errMsg.replace(/"/g, "'")}" — forwarding response without envelope stitch`,
+      );
+    }
+  }
+
+  // Compose with the existing cypher-validate warning prefix (Task 654). If
+  // both are present, the envelope warnings appear first (outermost prepend),
+  // then the validation warnings, then the upstream's rendered rows.
   if (p.readWarnings.length > 0) {
     try {
-      return wrapReadWarnings(msg, p.readWarnings);
+      const validationWrapped = wrapReadWarnings(msg, p.readWarnings);
+      if (envelopeStitched) {
+        // Re-stitch envelope warnings ONTO the validation-wrapped message.
+        const parsed = JSON.parse(envelopeStitched) as JsonRpcMessage;
+        const valParsed = JSON.parse(validationWrapped) as JsonRpcMessage;
+        const merged: JsonRpcMessage = {
+          ...valParsed,
+          result: {
+            ...(valParsed.result ?? {}),
+            content: [
+              ...(parsed.result?.content ?? []).slice(0, 1),
+              ...(valParsed.result?.content ?? []),
+            ],
+          },
+        };
+        return JSON.stringify(merged);
+      }
+      return validationWrapped;
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       console.error(
         `[cypher-validate] warning-wrap failed op=${p.method} error="${errMsg.replace(/"/g, "'")}" — forwarding response unwrapped`,
       );
-      return null;
+      return envelopeStitched;
     }
   }
-  return null;
+  return envelopeStitched;
 }
 
 /**
@@ -911,18 +995,30 @@ process.stdin.on("end", () => {
 });
 
 const responseBuffer = makeLineBuffer();
+// Task 970 — handleResponseLine is now async (envelope-warning probe). The
+// per-line work is serialised through a write-chain so multi-line chunks
+// preserve their original byte order on the way to stdout. The chain only
+// adds latency when the probe actually runs (reads with a result); other
+// lines resolve synchronously and append immediately.
+let responseWriteChain: Promise<void> = Promise.resolve();
 child.stdout.on("data", (chunk: Buffer) => {
   for (const line of responseBuffer.push(chunk)) {
-    if (line.length === 0) {
-      process.stdout.write("\n");
-      continue;
-    }
-    const rewritten = handleResponseLine(line);
-    process.stdout.write(`${rewritten ?? line}\n`);
+    responseWriteChain = responseWriteChain.then(async () => {
+      if (line.length === 0) {
+        process.stdout.write("\n");
+        return;
+      }
+      const rewritten = await handleResponseLine(line);
+      process.stdout.write(`${rewritten ?? line}\n`);
+    });
   }
 });
 child.stdout.on("end", () => {
-  process.stdout.end();
+  // Task 970 — handleResponseLine is async; if a probe is still in flight when
+  // upstream closes its stdout, ending process.stdout synchronously would drop
+  // the final response (Node's Writable silently discards writes after end()).
+  // Await the write-chain so every queued line reaches stdout first.
+  responseWriteChain.then(() => process.stdout.end());
 });
 
 for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {

package/payload/platform/plugins/admin/PLUGIN.md

@@ -1,8 +1,9 @@
 ---
 name: admin
-description: "Platform administration plugin. Provides system-status, brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), render-component, session-reset, session-resume, file-attach, wifi, adherence-read (attention-weighted adherence ledger), and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver — single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), render-component, session-reset, session-resume, file-attach, wifi, adherence-read (attention-weighted adherence ledger), and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
 tools:
   - system-status
+  - public-hostname
   - brand-settings
   - account-manage
   - account-update

package/payload/platform/plugins/admin/mcp/dist/__tests__/public-hostname.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=public-hostname.test.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/__tests__/public-hostname.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-hostname.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/public-hostname.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/admin/mcp/dist/__tests__/public-hostname.test.js

@@ -0,0 +1,106 @@
+// Task 970 — public-hostname deterministic resolver.
+//
+// Locks in the contract for `resolvePublicHostname` (the helper backing the
+// new `public-hostname` MCP tool). The tool exists so an agent following
+// publish-site never has to guess the property name on `CloudflareHostname`
+// nodes (the Task 970 root cause: `RETURN h.hostname` instead of
+// `h.hostnameValue`, returning `[]` and exhausting the turn budget).
+//
+// Tests stub a session-shaped object and assert exact cypher text, params,
+// and return shape — no driver, no neo4j-driver dependency at test time.
+import { describe, it, expect, vi } from "vitest";
+import { resolvePublicHostname, } from "../lib/public-hostname.js";
+function assertMiss(r) {
+    if (r.hostname !== null)
+        throw new Error("expected miss, got hit");
+}
+function record(fields) {
+    return { get: (k) => fields[k] };
+}
+function mockSession(results) {
+    let i = 0;
+    const run = vi.fn((_cypher, _params) => {
+        if (i >= results.length)
+            throw new Error(`unexpected session.run call #${i + 1}`);
+        return Promise.resolve(results[i++]);
+    });
+    const close = vi.fn(() => Promise.resolve());
+    return { run, close };
+}
+describe("resolvePublicHostname", () => {
+    it("returns hostname/isApex/tunnelId on hit, after one cypher call against CloudflareHostname", async () => {
+        const session = mockSession([
+            {
+                records: [
+                    record({ hostname: "test.maxy.bot", isApex: false, tunnelId: "tun-abc" }),
+                ],
+            },
+        ]);
+        const r = await resolvePublicHostname(session, "acc-1");
+        expect(r).toEqual({
+            hostname: "test.maxy.bot",
+            isApex: false,
+            tunnelId: "tun-abc",
+        });
+        expect(session.run).toHaveBeenCalledTimes(1);
+        const [cypher, params] = session.run.mock.calls[0];
+        expect(cypher).toContain("CloudflareHostname");
+        expect(cypher).toContain("h.hostnameValue");
+        expect(cypher).toContain("h.isApex");
+        expect(cypher).toContain("h.tunnelId");
+        expect(cypher).toContain("ORDER BY h.isApex DESC");
+        expect(cypher).toContain("LIMIT 1");
+        expect(params).toEqual({ accountId: "acc-1" });
+    });
+    it("returns reason=no-hostname when hostname missing but a tunnel exists", async () => {
+        const session = mockSession([
+            { records: [] },
+            { records: [record({ n: 1 })] },
+        ]);
+        const r = await resolvePublicHostname(session, "acc-1");
+        expect(r).toEqual({
+            hostname: null,
+            isApex: null,
+            tunnelId: null,
+            reason: "no-hostname",
+        });
+        expect(session.run).toHaveBeenCalledTimes(2);
+        const [tunnelCypher] = session.run.mock.calls[1];
+        expect(tunnelCypher).toContain("CloudflareTunnel");
+    });
+    it("returns reason=no-tunnel when neither hostname nor tunnel exists", async () => {
+        const session = mockSession([
+            { records: [] },
+            { records: [record({ n: 0 })] },
+        ]);
+        const r = await resolvePublicHostname(session, "acc-1");
+        expect(r).toEqual({
+            hostname: null,
+            isApex: null,
+            tunnelId: null,
+            reason: "no-tunnel",
+        });
+    });
+    it("handles Neo4j Integer return for the tunnel count", async () => {
+        // neo4j-driver returns count() as an Integer object with low/high fields
+        // and a toNumber() method. The resolver must unwrap it.
+        const integerLike = { low: 3, high: 0, toNumber: () => 3 };
+        const session = mockSession([
+            { records: [] },
+            { records: [record({ n: integerLike })] },
+        ]);
+        const r = await resolvePublicHostname(session, "acc-1");
+        assertMiss(r);
+        expect(r.reason).toBe("no-hostname");
+    });
+    it("scopes the query to accountId — no cross-account leakage", async () => {
+        const session = mockSession([
+            { records: [] },
+            { records: [record({ n: 0 })] },
+        ]);
+        await resolvePublicHostname(session, "acc-X");
+        expect(session.run.mock.calls[0][1]).toEqual({ accountId: "acc-X" });
+        expect(session.run.mock.calls[1][1]).toEqual({ accountId: "acc-X" });
+    });
+});
+//# sourceMappingURL=public-hostname.test.js.map

package/payload/platform/plugins/admin/mcp/dist/__tests__/public-hostname.test.js.map

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

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

@@ -20,6 +20,7 @@ import QRCode from "qrcode";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { getOnboardingState, completeOnboardingStep } from "./lib/onboarding.js";
 import { findSkillOwners, computePluginReadHint } from "./skill-resolution.js";
+import { resolvePublicHostname } from "./lib/public-hostname.js";
 const server = new McpServer({
     name: "admin",
     version: "0.1.0",
@@ -402,6 +403,39 @@ server.tool("system-status", "Check health of all Maxy platform services: Neo4j,
         .join("\n");
     return { content: [{ type: "text", text: formatted }] };
 });
+server.tool("public-hostname", "Resolve this account's canonical public hostname from the CloudflareHostname graph. Returns a single deterministic answer; never guess the property name on hostname nodes (Task 970 — the third recurrence of `RETURN h.hostname` instead of `h.hostnameValue` exhausting the agent's turn budget). Use this immediately after publish-site to construct the full URL.", {}, async () => {
+    const TAG = "[admin:public-hostname]";
+    const session = getSession();
+    try {
+        const result = await resolvePublicHostname(session, ACCOUNT_ID);
+        if (result.hostname !== null) {
+            console.error(`${TAG} resolved accountId=${ACCOUNT_ID} hostname=${result.hostname} isApex=${result.isApex}`);
+            const body = `hostname: ${result.hostname}\n` +
+                `isApex: ${result.isApex}\n` +
+                `tunnelId: ${result.tunnelId}\n` +
+                `usage: paste \`https://${result.hostname}<path-slug>\` to the operator — the <path-slug> comes from publish-site.`;
+            return { content: [{ type: "text", text: body }] };
+        }
+        console.error(`${TAG} empty accountId=${ACCOUNT_ID} reason=${result.reason}`);
+        const remediation = result.reason === "no-tunnel"
+            ? "No Cloudflare tunnel is configured for this account. Run the cloudflare setup-tunnel skill before publishing externally."
+            : "A Cloudflare tunnel exists but no public hostname is bound to it. Run the cloudflare setup-hostname skill before publishing externally.";
+        return {
+            content: [{
+                    type: "text",
+                    text: `hostname: (none)\nreason: ${result.reason}\n${remediation}`,
+                }],
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} error accountId=${ACCOUNT_ID} message="${errMsg.replace(/"/g, "'")}"`);
+        return {
+            content: [{ type: "text", text: `error resolving public hostname: ${errMsg}` }],
+            isError: true,
+        };
+    }
+});
 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);