@hiveku-apps/sync 0.5.14 → 0.5.17

package/README.md

@@ -185,9 +185,13 @@ them, to add the prompts.
 
 > **This vs. the plugin.** For a single account, you can instead install the
 > published [Hiveku Codex plugin](https://github.com/locus2012/hiveku-codex-plugin)
-> once (`codex plugin marketplace add locus2012/hiveku-codex-plugin` then
-> `codex plugin add hiveku@hiveku`) and set
-> `HIVEKU_TOKEN`. `hiveku-sync --codex` is the self-contained, per-account route —
+> once (`codex plugin marketplace add locus2012/hiveku-codex-plugin`, then
+> `codex plugin add hiveku@hiveku`, then `codex plugin add hiveku-hooks@hiveku`)
+> and set `HIVEKU_TOKEN`. Already have Hiveku in Codex? Run
+> `codex plugin marketplace upgrade hiveku` before these commands. The first
+> time, Codex asks you to approve Hiveku's hooks: type `/hooks` in Codex and
+> trust them.
+> `hiveku-sync --codex` is the self-contained, per-account route:
 > better for multi-account / CI / power-user setups, and it also brings the
 > account's own knowledge. Use one route per folder, not both.
 

package/bin/hiveku-sync.mjs

@@ -96,7 +96,13 @@ Memory/rules/skills:
                                     Hiveku Codex plugin (single-account users can
                                     instead run: codex plugin marketplace add
                                     locus2012/hiveku-codex-plugin, then:
-                                    codex plugin add hiveku@hiveku).
+                                    codex plugin add hiveku@hiveku, then:
+                                    codex plugin add hiveku-hooks@hiveku.
+                                    Already have Hiveku in Codex? Run
+                                    codex plugin marketplace upgrade hiveku
+                                    before these commands. The first time,
+                                    Codex asks you to approve Hiveku's hooks:
+                                    type /hooks in Codex and trust them).
 
 Coder projects:
   projects                          List the account's coder projects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.5.14",
+  "version": "0.5.17",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",

package/src/codex-prompt-tools.json

@@ -1,5 +1,5 @@
 {
-  "source": "locus2012/hiveku-codex-plugin 0.3.41 (3974fee, on main 616e72b), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
+  "source": "locus2012/hiveku-codex-plugin 0.3.44 (859caff, on main f588ca8), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
   "why": "hiveku-sync writes its own [mcp_servers.hiveku] into a Codex folder. Codex then uses that entry, not the plugin's, for the server's connection and for every tool's approval mode, so these prompts must be written here too. Refresh this list whenever the Codex plugin's prompt list changes.",
   "tools": [
     "deploy_site",
@@ -82,6 +82,13 @@
     "helpdesk_assistant_knowledge_sources_update",
     "helpdesk_contact_data_erase",
     "helpdesk_chat_retention_set",
+    "helpdesk_social_comments_settings_update",
+    "voice_site_create",
+    "voice_role_assign",
+    "voice_role_remove",
+    "voice_api_key_create",
+    "voice_api_key_revoke",
+    "voice_desk_phone_set",
     "marketing_report_send",
     "ppc_budget_update",
     "ppc_platform_budget_update",
@@ -177,6 +184,7 @@
     "voice_sms_toll_free_verification_submit",
     "voice_port_order_create",
     "voice_port_order_action",
+    "voice_port_order_document_upload",
     "voice_settings_update",
     "voice_number_update",
     "voice_blocked_numbers_remove",

package/src/mcp.mjs

@@ -1,10 +1,138 @@
 /**
  * Minimal MCP JSON-RPC client over Streamable HTTP.
  * Speaks just enough of the protocol to initialize + call tools.
+ *
+ * Every body goes gzip-compressed, and a refusal from the web edge in front of
+ * Hiveku fails only the request it refused (HK-847, below). This is the only
+ * place hiveku-sync posts to core.hiveku.com; it posts to nothing else.
  */
+import { gzipSync } from 'node:zlib';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
+/**
+ * ★ EVERY BODY TO CORE GOES GZIP-COMPRESSED (HK-847): Content-Encoding gzip,
+ * the Content-Type unchanged, and the JSON inside byte for byte what it was.
+ *
+ * The web edge in front of core.hiveku.com reads plain request bodies against
+ * content rules nobody at Hiveku can see or change. On 2026-10-28 it answered a
+ * pm_tasks_create from the Claude Code plugin with an HTML "Blocked" page
+ * because of a file path in the task's text (HK-838), and the same body sent
+ * gzip-compressed passed. A push carries whole files, code and file paths
+ * included, so this client needs it as much as the plugin (lib/upstream.mjs
+ * gzipBody, since 0.27.111) and the VS Code extension (src/mcpClient.ts).
+ *
+ * WHERE THE SERVER INFLATES IT (hiveku-mcp-api-server, checked 2026-10-29):
+ * src/middleware/json-body.ts is its one JSON body parser, mounted app-wide in
+ * src/index-unified-http.ts before every route. It inflates gzip and deflate
+ * (body-parser's default) and counts its 30 MB limit after inflating, so a
+ * compressed body has the ceiling a plain one had.
+ */
+export function gzipJsonBody(message) {
+  return gzipSync(Buffer.from(JSON.stringify(message), 'utf8'));
+}
+
+/**
+ * ★ WHO REFUSED: HIVEKU, OR THE WEB EDGE IN FRONT OF IT (HK-847).
+ *
+ * 401, 403 and 429 come from both. Hiveku's MCP server sends each one as a
+ * JSON-RPC error object: mcp-auth.ts for a revoked key (401) or a key used for
+ * another account (403), rate-limiter.ts for its 429. The edge sends a page of
+ * its own instead, and the request never reached Hiveku. So the BODY decides,
+ * never the status alone: Hiveku's own JSON-RPC error keeps the `MCP HTTP
+ * <status>: <body>` it always had, and anything else on those statuses (an
+ * HTML page, a "Blocked" title, plain text, an empty body, JSON that is not a
+ * JSON-RPC error) is the edge refusing THIS request: McpEdgeRefusalError, a
+ * plain message with the edge's ray id that never calls it a key problem.
+ * 503 is not one of them: the proxy in front of Hiveku also answers 503 when a
+ * deploy cuts a call it had already delivered, so it keeps the generic path.
+ * The words are exactly the VS Code extension's (src/mcpClient.ts
+ * coreEdgeRefusalMessage); the plugin (lib/upstream.mjs edgeRefusalError)
+ * says the same facts to a model, with the next steps a model has.
+ */
+const EDGE_REFUSAL_STATUSES = new Set([401, 403, 429]);
+
+/** True for Hiveku's own error answer: JSON-RPC 2.0 whose `error` has a whole-number code and a string message. */
+export function isHivekuErrorAnswer(text) {
+  if (typeof text !== 'string' || !text.trim()) return false;
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body) || body.jsonrpc !== '2.0') return false;
+  const { error } = body;
+  if (!error || typeof error !== 'object' || Array.isArray(error)) return false;
+  return Number.isInteger(error.code) && typeof error.message === 'string';
+}
+
+/** A ray id is an id: only an id-shaped value is passed on. */
+const RAY_HEADER_RE = /^[0-9a-f]{16}(?:-[a-z]{3,4})?$/i;
+/** "Ray ID: <strong>8f1c...</strong>" in a block page, or "ray_id":"8f1c..." in a JSON one. */
+const RAY_IN_PAGE_RE = /ray[\s_-]*id[\s\S]{0,80}?(?<![0-9a-z])([0-9a-f]{16})(?![0-9a-z])/i;
+
+/** The ray id the edge gave its refusal: the cf-ray header first, else one named in the page. null when neither holds one. */
+export function edgeRayId(headers, text) {
+  const header = String(headers?.get?.('cf-ray') ?? '').trim();
+  if (RAY_HEADER_RE.test(header)) return header;
+  const found = typeof text === 'string' ? text.slice(0, 64 * 1024).match(RAY_IN_PAGE_RE) : null;
+  return found ? found[1] : null;
+}
+
+/**
+ * The words for a refusal from the web edge in front of Hiveku. They claim only
+ * what this client knows: the edge refused this request, so it never reached
+ * Hiveku, and Hiveku did not refuse the key. Not why: a rule on a request's text
+ * is the usual cause, but a rule on where requests come from answers every
+ * request the same way, so a 401 or 403 says what to do then. The ray id comes
+ * first, so a message cut short still carries it. Plain words: no vendor names.
+ */
+export function edgeRefusalMessage(status, rayId) {
+  const byText = status === 401 || status === 403;
+  const label = rayId ? `HTTP ${status}, ray id ${rayId}` : `HTTP ${status}`;
+  const give = rayId ? `ray id ${rayId}` : 'the time it happened';
+  const what = byText
+    ? `The web edge in front of Hiveku refused this one request (${label}), most often because of something in its text.`
+    : `The web edge in front of Hiveku turned this one request away (${label}). It does that when it is busy, and also ` +
+      "because of something in a request's text.";
+  const next = byText
+    ? 'Try it again with the text shortened or rephrased: code and file paths are the usual cause. If every request ' +
+      'is refused this way, even a plain one, the block is on where the requests come from, not on their text: tell ' +
+      `Hiveku support and give them ${give}.`
+    : 'Wait a minute and try it once more. If it is turned away again, shorten or rephrase the text: code and file ' +
+      `paths are the usual cause. If it keeps happening, tell Hiveku support and give them ${give}.`;
+  return (
+    `${what} It never reached Hiveku and nothing was saved. Hiveku did not refuse your key, so there is no need to ` +
+    `reconnect: the next request is sent as usual. ${next}`
+  );
+}
+
+/** The words for a 401, 403 or 429 whose answer could not be read, so who refused it is not known. */
+export function refusalUnreadMessage(status) {
+  return (
+    `The answer to this request (HTTP ${status}) could not be read, so it is not known whether Hiveku or ` +
+    'the web edge in front of Hiveku refused it. It is not taken as a sign that your key stopped working: the next ' +
+    'request is sent as usual. Try it once more.'
+  );
+}
+
+/**
+ * A 401, 403 or 429 that was not Hiveku's own JSON-RPC error. `edge_blocked`:
+ * the edge's own page, so the request never reached Hiveku. `unreadable`: the
+ * answer could not be read, so who refused it is not known. Neither is a key
+ * problem.
+ */
+export class McpEdgeRefusalError extends Error {
+  constructor(kind, httpStatus, rayId = null) {
+    super(kind === 'edge_blocked' ? edgeRefusalMessage(httpStatus, rayId) : refusalUnreadMessage(httpStatus));
+    this.name = 'McpEdgeRefusalError';
+    this.kind = kind;
+    this.httpStatus = httpStatus;
+    this.rayId = kind === 'edge_blocked' ? rayId : null;
+  }
+}
+
 export class HivekuMcpClient {
   constructor({ baseUrl, apiKey, profile = 'full' }) {
     if (!baseUrl) throw new Error('baseUrl required');
@@ -30,6 +158,8 @@ export class HivekuMcpClient {
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
       'Content-Type': 'application/json',
+      // The body is gzip, so the edge's content rules never read it (gzipJsonBody).
+      'Content-Encoding': 'gzip',
       Accept: 'application/json',
     };
     if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
@@ -37,15 +167,20 @@ export class HivekuMcpClient {
     const res = await fetch(this.endpoint, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      body: gzipJsonBody({ jsonrpc: '2.0', id, method, params }),
     });
 
     const sessionHeader = res.headers.get('mcp-session-id');
     if (sessionHeader) this.sessionId = sessionHeader;
 
     if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      throw new Error(`MCP HTTP ${res.status}: ${text.slice(0, 500)}`);
+      const text = await res.text().catch(() => null);
+      // ★ A 401, 403 or 429 is classified by its body first (EDGE_REFUSAL_STATUSES).
+      if (EDGE_REFUSAL_STATUSES.has(res.status)) {
+        if (text === null) throw new McpEdgeRefusalError('unreadable', res.status);
+        if (!isHivekuErrorAnswer(text)) throw new McpEdgeRefusalError('edge_blocked', res.status, edgeRayId(res.headers, text));
+      }
+      throw new Error(`MCP HTTP ${res.status}: ${(text ?? '').slice(0, 500)}`);
     }
 
     if (res.status === 204) return null;

package/src/push.mjs

@@ -69,6 +69,7 @@ import {
   tryReadVersionStatus,
   versionAfterPush,
 } from './versions.mjs';
+import { McpEdgeRefusalError } from './mcp.mjs';
 import { saveCodeFiles } from './saveFiles.mjs';
 import {
   branchMovedSafeNote,
@@ -423,6 +424,11 @@ export async function pushProject({
     log: (line) => console.log(line),
   });
   const failedPaths = [...code.failed];
+  // The words of the last request the web edge in front of Hiveku refused
+  // (mcp.mjs McpEdgeRefusalError, HK-847), printed with the files it kept from
+  // saving so the person sees why, and the edge's ray id. Set only where that
+  // refusal left a file unsaved, never for one a retry got past.
+  let edgeRefusal = code.refusal ?? null;
   const codeSaved = code.saved;
   // The branch tree this push leaves behind (every branch write answers it).
   let branchEtag = code.workingTreeEtag;
@@ -444,7 +450,12 @@ export async function pushProject({
         }
         return;
       } catch (e) {
-        if (attempt >= 2) failedPaths.push(f.path);
+        if (attempt >= 2) {
+          failedPaths.push(f.path);
+          // Only the attempt that left the file unsaved says why: an edge
+          // refusal that a second attempt got past says nothing (HK-847).
+          if (e instanceof McpEdgeRefusalError) edgeRefusal = e.message;
+        }
       }
     }
   });
@@ -461,7 +472,8 @@ export async function pushProject({
       const etag = answer?.working_tree_etag ?? answer?.data?.working_tree_etag;
       if (typeof etag === 'string' && etag) branchEtag = etag;
       deleted += 1;
-    } catch {
+    } catch (e) {
+      if (e instanceof McpEdgeRefusalError) edgeRefusal = e.message;
       failedPaths.push(p);
     }
   }
@@ -478,6 +490,7 @@ export async function pushProject({
       `  ${failedPaths.length} file${failedPaths.length !== 1 ? 's' : ''} did NOT save: ` +
         `${failedPaths.slice(0, 10).join(', ')}${failedPaths.length > 10 ? '…' : ''}`,
     );
+    if (edgeRefusal) console.log(`  ${edgeRefusal}`);
     console.log('  Every other file IS saved. Push again to retry the ones that failed.');
   }
 

package/src/saveFiles.mjs

@@ -17,6 +17,7 @@
  * Builder contract: hiveku_builder feature/versions-core
  * src/app/api/olympus/builder/projects/[projectId]/files-bulk/route.ts (POST).
  */
+import { McpEdgeRefusalError } from './mcp.mjs';
 
 /** Batches of about 25 text files finish inside the route's time budget (the tool's own advice). */
 export const BATCH_FILES = 25;
@@ -71,16 +72,24 @@ export function readSaveAnswer(data, sentPaths) {
 
 /**
  * Save `files` ({ path, content, encoding }) to Your site (branch null) or a
- * branch. Returns { saved, failed: [paths], workingTreeEtag }. Never throws for
- * a refused or failed call: those files are reported in `failed`.
+ * branch. Returns { saved, failed: [paths], workingTreeEtag, refusal }. Never
+ * throws for a refused or failed call: those files are reported in `failed`.
+ * `refusal` is the web edge's words (mcp.mjs McpEdgeRefusalError, HK-847),
+ * with its ray id, when the edge refused the last attempt of a batch whose
+ * files are in `failed`, so the person is told why those did not save; else
+ * null. A refused attempt followed by one Hiveku answered says nothing about
+ * the batch any more, so its words are dropped.
  */
 export async function saveCodeFiles({ client, projectId, files, branch = null, note, log = () => {} }) {
   const savedPaths = new Set();
   const failed = [];
   let workingTreeEtag = null;
+  let refusal = null;
   const total = files.length;
   for (const batch of batchFiles(files)) {
     let pending = batch;
+    // The edge's words when it refused this batch's latest attempt, else null.
+    let batchRefusal = null;
     for (let attempt = 1; attempt <= ATTEMPTS && pending.length; attempt++) {
       const sentPaths = pending.map((f) => f.path);
       let data;
@@ -94,10 +103,14 @@ export async function saveCodeFiles({ client, projectId, files, branch = null, n
             ...(branch ? { branch } : {}),
           })
         )?.data;
-      } catch {
+      } catch (err) {
         // No answer: nothing is known about this batch, so all of it is sent again.
+        // The edge refusing it never reached Hiveku; its words are kept for the person.
+        batchRefusal = err instanceof McpEdgeRefusalError ? err.message : null;
         continue;
       }
+      // Hiveku answered, so it, not the edge, says what did not land.
+      batchRefusal = null;
       const answer = readSaveAnswer(data, sentPaths);
       for (const p of answer.landed) savedPaths.add(p);
       if (answer.etag) workingTreeEtag = answer.etag;
@@ -105,7 +118,9 @@ export async function saveCodeFiles({ client, projectId, files, branch = null, n
       pending = pending.filter((f) => again.has(f.path) && !savedPaths.has(f.path));
     }
     failed.push(...pending.map((f) => f.path));
+    // Set only by a refused last attempt, which leaves this batch's files in `failed`.
+    if (batchRefusal) refusal = batchRefusal;
     log(`  code ${savedPaths.size}/${total}`);
   }
-  return { saved: savedPaths.size, failed, workingTreeEtag };
+  return { saved: savedPaths.size, failed, workingTreeEtag, refusal };
 }