@huynle/hub 0.8.1 → 0.8.3

package/packages/cli/dist/hub-cli.js

@@ -7,7 +7,7 @@ import { createInterface } from "readline";
 // packages/cli/package.json
 var package_default = {
   name: "@huynle/hub-cli",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   license: "MIT",
@@ -863,7 +863,7 @@ class HubClient {
     return this.call("POST", `/api/decisions/${segment(id)}/answer`, { body, ...signalOf(answer) });
   }
   approve(addr, requestID, options = {}) {
-    const body = { requestID, ...options.always ? { always: true } : {}, ...whyField(options) };
+    const body = { requestID, ...options.always ? { always: true } : {}, ...options.recommend ? { recommend: true } : {}, ...whyField(options) };
     return this.call("POST", `${AGENT}/sessions/${segment(addr)}/approve`, { body, ...signalOf(options) });
   }
   deny(addr, requestID, options = {}) {
@@ -3826,6 +3826,33 @@ var GRAPH_LIMITS = {
   defaultWindowMs: 24 * 60 * 60000
 };
 var WATCHTOWER_CHUNK_BUDGET = 700 * 1024;
+// packages/protocol/src/voice-recording.ts
+var RECORDING_LIMITS = {
+  retentionMs: 7 * 24 * 3600000,
+  userBytes: 500 * 1024 * 1024,
+  recordingBytes: 150 * 1024 * 1024,
+  segmentBytes: 2 * 1024 * 1024,
+  segmentsPerRecording: 5000,
+  eventsPerBatch: 200,
+  batchBytes: 256 * 1024,
+  keepaliveBatchBytes: 60 * 1024,
+  eventsPerRecording: 50000,
+  eventBytesPerRecording: 32 * 1024 * 1024,
+  recordingsStored: 200,
+  activePerUser: 4,
+  maxDurationMs: 4 * 3600000,
+  idleEndMs: 10 * 60000,
+  sweepMs: 15 * 60000,
+  textChars: 2000,
+  utteranceChars: 4000,
+  replyChars: 32000,
+  messageChars: 300,
+  consoleBufferEvents: 2000,
+  flushMs: 5000,
+  flushEvents: 100,
+  hubFlushMs: 2000,
+  hubFlushEvents: 100
+};
 // packages/protocol/src/index.ts
 var PROTOCOL_VERSION = 1;
 var FORM_ANSWER_MAX_KEYS = 50;
@@ -3852,6 +3879,9 @@ function formAnswerProblem(v) {
 }
 var REVERT_FILES_MAX = 50;
 var REVERT_FILE_MAX_CHARS = 1000;
+function isRevertCommitted(v) {
+  return isObj(v) && nonEmpty(v.messageID) && v.messageID.length <= 300 && (v.from === undefined || num(v.from)) && num(v.until) && num(v.at);
+}
 var FORWARDED_EVENTS = new Set([
   "session.created",
   "session.renamed",
@@ -3906,7 +3936,7 @@ var IMPLIED_OPENCODE_FEATURES = [
   "expose",
   "create"
 ];
-var OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert"];
+var OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError"];
 var CORE_OPS = ["turn", "steer", "interrupt", "stop", "permission", "form"];
 var KNOWN_SPOKE_FEATURES = [...CORE_OPS, ...OPTIONAL_SPOKE_FEATURES, "turnEvents", PROFILE_APPLY_FEATURE, SESSION_CONTEXT_FEATURE];
 var SPOKE_FEATURES = [...OPTIONAL_SPOKE_FEATURES, PROFILE_APPLY_FEATURE, SESSION_CONTEXT_FEATURE];
@@ -3943,13 +3973,14 @@ function isLaunchCreate(req) {
 }
 var AGENT_NAME_MAX = 100;
 var PERMISSION_MESSAGE_MAX = 1000;
+var RES_CODE_MAX = 40;
 var isModelSelection = (v) => isObj(v) && typeof v.providerID === "string" && ID.test(v.providerID) && typeof v.modelID === "string" && ID.test(v.modelID) && (v.variant === undefined || typeof v.variant === "string" && ID.test(v.variant));
 var SESSION_TOKEN_TEXT = new RegExp(`^[\\x21-\\x7e]{1,${SESSION_TOKEN_MAX_CHARS}}$`);
 function isSessionToken(v) {
   return isObj(v) && nonEmpty(v.sessionID) && v.sessionID.length <= 300 && str2(v.token) && SESSION_TOKEN_TEXT.test(v.token) && num(v.exp);
 }
 function isSession(v) {
-  return isObj(v) && nonEmpty(v.id) && str2(v.title) && str2(v.directory) && num(v.updated) && typeof v.owned === "boolean" && (v.parentID === undefined || str2(v.parentID)) && (v.exposed === undefined || typeof v.exposed === "boolean") && (v.project === undefined || str2(v.project)) && (v.projectName === undefined || str2(v.projectName)) && (v.archived === undefined || typeof v.archived === "boolean") && (v.open === undefined || typeof v.open === "boolean") && (v.terminal === undefined || isTerminal(v.terminal)) && (v.revert === undefined || isSessionRevert(v.revert)) && (v.agent === undefined || nonEmpty(v.agent) && v.agent.length <= AGENT_NAME_MAX) && (v.contextRevision === undefined || Number.isSafeInteger(v.contextRevision) && v.contextRevision >= 0) && (v.locked === undefined || v.locked === true);
+  return isObj(v) && nonEmpty(v.id) && str2(v.title) && str2(v.directory) && num(v.updated) && typeof v.owned === "boolean" && (v.parentID === undefined || str2(v.parentID)) && (v.exposed === undefined || typeof v.exposed === "boolean") && (v.project === undefined || str2(v.project)) && (v.projectName === undefined || str2(v.projectName)) && (v.archived === undefined || typeof v.archived === "boolean") && (v.open === undefined || typeof v.open === "boolean") && (v.terminal === undefined || isTerminal(v.terminal)) && (v.revert === undefined || isSessionRevert(v.revert)) && (v.revertCommitted === undefined || isRevertCommitted(v.revertCommitted)) && (v.agent === undefined || nonEmpty(v.agent) && v.agent.length <= AGENT_NAME_MAX) && (v.contextRevision === undefined || Number.isSafeInteger(v.contextRevision) && v.contextRevision >= 0) && (v.locked === undefined || v.locked === true);
 }
 var REVERT_STATUS = new Set(["added", "deleted", "modified"]);
 var count = (v) => Number.isSafeInteger(v) && v >= 0;
@@ -3957,7 +3988,7 @@ function isRevertFile(v) {
   return isObj(v) && nonEmpty(v.file) && v.file.length <= REVERT_FILE_MAX_CHARS && (v.status === undefined || REVERT_STATUS.has(v.status)) && (v.additions === undefined || count(v.additions)) && (v.deletions === undefined || count(v.deletions));
 }
 function isSessionRevert(v) {
-  return isObj(v) && nonEmpty(v.messageID) && v.messageID.length <= 300 && count(v.hidden) && (v.at === undefined || num(v.at)) && Array.isArray(v.files) && v.files.length <= REVERT_FILES_MAX && v.files.every(isRevertFile) && count(v.filesTotal) && v.filesTotal >= v.files.length;
+  return isObj(v) && nonEmpty(v.messageID) && v.messageID.length <= 300 && count(v.hidden) && (v.at === undefined || num(v.at)) && Array.isArray(v.files) && v.files.length <= REVERT_FILES_MAX && v.files.every(isRevertFile) && count(v.filesTotal) && v.filesTotal >= v.files.length && (v.stagedAt === undefined || num(v.stagedAt));
 }
 var TERMINAL_STATUS = new Set(["idle", "working", "blocked", "done", "unknown"]);
 function isTerminal(v) {
@@ -4129,6 +4160,7 @@ function isServerRequest(v) {
       return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300 && typeof v.files === "boolean";
     case "revertRestore":
     case "revertCommit":
+    case "dismissError":
       return nonEmpty(v.sessionID);
     default:
       return false;
@@ -4141,8 +4173,12 @@ function parseSpokeMessage(raw) {
   switch (m.t) {
     case "hello":
       return (m.role === undefined || m.role === "spoke") && num(m.v) && nonEmpty(m.processID) && (m.kind === "service" || m.kind === "standalone") && str2(m.directory) && num(m.pid) && (m.mode === "always" || m.mode === "session") && (str2(m.opencodeVersion) || m.opencodeVersion === undefined && m.harness !== undefined && m.harness !== HARNESS_OPENCODE) && str2(m.pluginVersion) && (m.features === undefined || featureList(m.features)) && (m.harness === undefined || token(m.harness, 64)) && (m.harnessVersion === undefined || str2(m.harnessVersion) && m.harnessVersion.length <= 100) && (m.evidence === undefined || token(m.evidence, 32)) && (m.launchID === undefined || str2(m.launchID) && ID.test(m.launchID)) ? m : undefined;
-    case "sessions":
-      return Array.isArray(m.sessions) && m.sessions.every(isSession) ? m : undefined;
+    case "sessions": {
+      if (!Array.isArray(m.sessions))
+        return;
+      const sessions = m.sessions.map(lenientSession);
+      return sessions.every(isSession) ? { ...m, sessions } : undefined;
+    }
     case "terminals":
       return m.herdr === undefined || isHerdrInfo(m.herdr) ? m : undefined;
     case "event":
@@ -4150,13 +4186,34 @@ function parseSpokeMessage(raw) {
     case "req":
       return nonEmpty(m.id) && isSpokeRequest(m.req) ? m : undefined;
     case "res":
-      return isResFrame(m) ? m : undefined;
+      return isResFrame(m) ? lenientRes(m) : undefined;
     case "bye":
       return isByeFrame(m) ? m : undefined;
     default:
       return;
   }
 }
+function lenientRes(m) {
+  if (m.code === undefined || nonEmpty(m.code) && m.code.length <= RES_CODE_MAX)
+    return m;
+  const { code: _dropped, ...rest } = m;
+  return rest;
+}
+function lenientSession(v) {
+  if (!isObj(v))
+    return v;
+  let out = v;
+  if (out.revertCommitted !== undefined && !isRevertCommitted(out.revertCommitted)) {
+    const { revertCommitted: _dropped, ...rest } = out;
+    out = rest;
+  }
+  const revert = out.revert;
+  if (isObj(revert) && revert.stagedAt !== undefined && !num(revert.stagedAt)) {
+    const { stagedAt: _dropped, ...rest } = revert;
+    out = { ...out, revert: rest };
+  }
+  return out;
+}
 function parseServerMessage(raw) {
   const m = parseFrame(raw);
   if (!m)
@@ -4167,7 +4224,7 @@ function parseServerMessage(raw) {
     case "req":
       return nonEmpty(m.id) && isServerRequest(m.req) ? m : undefined;
     case "res":
-      return isResFrame(m) ? m : undefined;
+      return isResFrame(m) ? lenientRes(m) : undefined;
     case "bye":
       return isByeFrame(m) ? m : undefined;
     default:
@@ -5847,6 +5904,10 @@ function launchText(l) {
 `);
 }
 
+// packages/cli/src/tool-args.ts
+class ToolArgError extends Error {
+}
+
 // packages/cli/src/artifacts-mcp.ts
 var MCP_INLINE_TEXT_BYTES = 256 * 1024;
 var KINDS = ["markdown", "code", "image", "table", "chart", "dashboard", "html", "app", "file"];
@@ -5870,7 +5931,7 @@ var FILE_ARGS = {
 var need = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
-    throw new Error(`"${key}" is required (a non-empty string)`);
+    throw new ToolArgError(`"${key}" is required (a non-empty string)`);
   return value;
 };
 var optional2 = (args, key) => {
@@ -5878,20 +5939,20 @@ var optional2 = (args, key) => {
   if (value === undefined || value === null)
     return;
   if (typeof value !== "string")
-    throw new Error(`"${key}" must be a string`);
+    throw new ToolArgError(`"${key}" must be a string`);
   return value.trim() ? value : undefined;
 };
 function files(args, kind) {
   const text = args.text;
   if (text !== undefined && typeof text !== "string")
-    throw new Error('"text" must be a string');
+    throw new ToolArgError('"text" must be a string');
   const blobs = args.blobs;
   if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null)))
-    throw new Error('"blobs" must be a list of blob references');
+    throw new ToolArgError('"blobs" must be a list of blob references');
   if (text === undefined && (blobs === undefined || blobs.length === 0))
-    throw new Error("give text or blobs (stage bigger content first and pass its reference)");
+    throw new ToolArgError("give text or blobs (stage bigger content first and pass its reference)");
   if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES)
-    throw new Error(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`);
+    throw new ToolArgError(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`);
   const path = optional2(args, "path");
   const entry = optional2(args, "entry");
   const mediaType = optional2(args, "mediaType") ?? (kind && DEFAULT_MEDIA[kind]) ?? "text/plain";
@@ -5958,7 +6019,7 @@ var artifactTools = [
       const title = need(args, "title");
       const kind = need(args, "kind");
       if (!KINDS.includes(kind))
-        throw new Error(`"kind" must be one of ${KINDS.join(", ")}`);
+        throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`);
       const body = files(args, kind);
       const description = optional2(args, "description");
       const visibility = optional2(args, "visibility");
@@ -5997,7 +6058,7 @@ var KINDS2 = ["ask", "propose-edit", "run-action"];
 var need2 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
-    throw new Error(`"${key}" is required (a non-empty string)`);
+    throw new ToolArgError(`"${key}" is required (a non-empty string)`);
   return value;
 };
 var optional3 = (args, key) => {
@@ -6005,24 +6066,24 @@ var optional3 = (args, key) => {
   if (value === undefined || value === null)
     return;
   if (typeof value !== "string")
-    throw new Error(`"${key}" must be a string`);
+    throw new ToolArgError(`"${key}" must be a string`);
   return value.trim() ? value : undefined;
 };
 var integer = (args, key) => {
   const value = args[key];
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
-    throw new Error(`"${key}" is required (a whole number)`);
+    throw new ToolArgError(`"${key}" is required (a whole number)`);
   return value;
 };
 function handlerOf(args) {
   const session = optional3(args, "session");
   const machine = optional3(args, "machine");
   if (session && machine)
-    throw new Error('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both');
+    throw new ToolArgError('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both');
   if (session)
     return { session };
   if (!machine)
-    throw new Error('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")');
+    throw new ToolArgError('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")');
   const repo = need2(args, "repo");
   const harness = optional3(args, "harness");
   const model = optional3(args, "model");
@@ -6086,7 +6147,7 @@ var artifactJobTools = [
     run: async (hub, args, signal) => {
       const kind = optional3(args, "kind");
       if (kind && !KINDS2.includes(kind))
-        throw new Error(`"kind" must be one of ${KINDS2.join(", ")}`);
+        throw new ToolArgError(`"kind" must be one of ${KINDS2.join(", ")}`);
       const action = optional3(args, "action");
       const apply = optional3(args, "apply");
       const key = optional3(args, "key");
@@ -6155,12 +6216,12 @@ var artifactJobTools = [
       const answer = optional3(args, "answer");
       const text = args.text;
       if (text !== undefined && typeof text !== "string")
-        throw new Error('"text" must be a string');
+        throw new ToolArgError('"text" must be a string');
       if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES)
-        throw new Error(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`);
+        throw new ToolArgError(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`);
       const keep = args.keep;
       if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string")))
-        throw new Error('"keep" must be a list of paths');
+        throw new ToolArgError('"keep" must be a list of paths');
       const path = optional3(args, "path");
       const entry = optional3(args, "entry");
       const result = error ? { error } : text !== undefined || keep !== undefined ? {
@@ -6207,7 +6268,7 @@ var UPDATES = TEAM_INTAKE_STATUS_INPUTS;
 var need3 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
-    throw new Error(`"${key}" is required (a non-empty string)`);
+    throw new ToolArgError(`"${key}" is required (a non-empty string)`);
   return value;
 };
 var optional4 = (args, key) => {
@@ -6215,7 +6276,7 @@ var optional4 = (args, key) => {
   if (value === undefined || value === null)
     return;
   if (typeof value !== "string")
-    throw new Error(`"${key}" must be a string`);
+    throw new ToolArgError(`"${key}" must be a string`);
   return value.trim() ? value : undefined;
 };
 var strings2 = (args, key) => {
@@ -6223,13 +6284,13 @@ var strings2 = (args, key) => {
   if (value === undefined || value === null)
     return;
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
-    throw new Error(`"${key}" must be a list of strings`);
+    throw new ToolArgError(`"${key}" must be a list of strings`);
   return value;
 };
 var oneOf4 = (args, key, allowed) => {
   const value = optional4(args, key);
   if (value !== undefined && !allowed.includes(value))
-    throw new Error(`"${key}" must be one of ${allowed.join(", ")}`);
+    throw new ToolArgError(`"${key}" must be one of ${allowed.join(", ")}`);
   return value;
 };
 function dueOf(args) {
@@ -6238,7 +6299,7 @@ function dueOf(args) {
     return;
   const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
   if (!Number.isSafeInteger(ms) || ms <= 0)
-    throw new Error(`"due" must be an ISO date/time or epoch milliseconds`);
+    throw new ToolArgError(`"due" must be an ISO date/time or epoch milliseconds`);
   return ms;
 }
 var line4 = (i) => `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}`;
@@ -6325,10 +6386,10 @@ ${intakeText(intake)}`;
     run: async (hub, args, signal) => {
       const status = oneOf4(args, "status", UPDATES);
       if (!status)
-        throw new Error(`"status" is required: one of ${UPDATES.join(", ")}`);
+        throw new ToolArgError(`"status" is required: one of ${UPDATES.join(", ")}`);
       const expectedRevision = args.expectedRevision;
       if (expectedRevision !== undefined && expectedRevision !== null && (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0))
-        throw new Error(`"expectedRevision" must be the revision you read (or left out)`);
+        throw new ToolArgError(`"expectedRevision" must be the revision you read (or left out)`);
       const reason = optional4(args, "reason");
       const { intake, assignment } = await reportIntakeStatus(hub.teams, need3(args, "team"), need3(args, "intake"), { status, ...typeof expectedRevision === "number" ? { expectedRevision } : {}, ...reason ? { reason } : {} }, { signal });
       return `${intake.id} is ${intake.status}${intake.progress ? ` (${intake.progress})` : ""}, revision ${intake.revision}${assignment ? `; assignment ${assignment.id} ${assignment.status}` : ""}`;
@@ -6421,9 +6482,7 @@ var LAUNCH = {
   required: ["workspace"]
 };
 var SCOPES = "App tokens need scope teams:read (reads) or teams:manage (changes); seats, status and staffing also need sessions:read. Session tokens read only teams they are seated in and never change definitions. Team roles confer no authority.";
-
-class ArgError extends Error {
-}
+var ArgError = ToolArgError;
 var need4 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
@@ -6790,10 +6849,7 @@ var META_FIELDS = {
   projects: { ...STRINGS2, description: "Project names the profile is meant for (≤ 16)." }
 };
 var SCOPES2 = "App tokens need scope profiles:read (reads) or profiles:manage (changes; profile_version_create with content fields and the skill/command set/remove tools read the latest version first, so they also need profiles:read); pins need profiles:assign and sessions:read (an app also needs a prompt grant on the session). Session tokens never change profiles. A profile confers no authority.";
-
-class ProfileArgError extends Error {
-}
-var ArgError2 = ProfileArgError;
+var ArgError2 = ToolArgError;
 var need5 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
@@ -7048,7 +7104,7 @@ var STRINGS3 = { type: "array", items: { type: "string" } };
 var need6 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
-    throw new Error(`"${key}" is required (a non-empty string)`);
+    throw new ToolArgError(`"${key}" is required (a non-empty string)`);
   return value;
 };
 var flag = (args, key, fallback) => {
@@ -7056,7 +7112,7 @@ var flag = (args, key, fallback) => {
   if (value === undefined || value === null)
     return fallback;
   if (typeof value !== "boolean")
-    throw new Error(`"${key}" must be true or false`);
+    throw new ToolArgError(`"${key}" must be true or false`);
   return value;
 };
 var UPDATE_FIELDS = ["autoActive", "activeWithinHours", "usePins", "sessions", "projects", "labels", "muted", "mutedProjects"];
@@ -7088,10 +7144,10 @@ var watchlistTools = [
     run: async (hub, args, signal) => {
       const expected = args.expectedRevision;
       if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0)
-        throw new Error(`"expectedRevision" is required (the revision you read)`);
+        throw new ToolArgError(`"expectedRevision" is required (the revision you read)`);
       const unknown = Object.keys(args).filter((k) => k !== "expectedRevision" && !UPDATE_FIELDS.includes(k));
       if (unknown.length)
-        throw new Error(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`);
+        throw new ToolArgError(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`);
       const patch = {};
       for (const field of UPDATE_FIELDS)
         if (args[field] !== undefined && args[field] !== null)
@@ -7137,9 +7193,7 @@ ${watchlistConfigText(r.config)}`;
 // packages/cli/src/mcp.ts
 var MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var RPC = { parse: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internal: -32603 };
-
-class ArgError3 extends Error {
-}
+var ArgError3 = ToolArgError;
 var need7 = (args, key) => {
   const value = args[key];
   if (typeof value !== "string" || !value.trim())
@@ -8324,7 +8378,7 @@ function createMcpServer(options) {
     } catch (cause) {
       if (controller.signal.aborted)
         return;
-      const text = cause instanceof ArgError3 || cause instanceof ProfileArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+      const text = cause instanceof ToolArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`;
       return ok2(id, toolResult(clean(text, token), true));
     } finally {
       if (inFlight.get(key(id)) === controller)
@@ -8761,7 +8815,7 @@ import { arch as osArch, platform as osPlatform } from "node:os";
 // packages/node/package.json
 var package_default2 = {
   name: "@huynle/hub-node",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -9853,7 +9907,7 @@ import path13 from "node:path";
 // packages/runtime-openshell/package.json
 var package_default3 = {
   name: "@huynle/hub-runtime-openshell",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -11395,6 +11449,15 @@ function wsURL2(server) {
 var defaultSocket2 = (url, headers) => new WebSocket(url, { headers });
 var message2 = (cause) => cause instanceof Error ? cause.message : String(cause);
 
+class CodedError extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CodedError";
+  }
+}
+
 class SpokeConnection {
   options;
   state = "off";
@@ -11564,7 +11627,7 @@ class SpokeConnection {
     try {
       reply = { t: "res", id, ok: true, result: await this.options.handle(req) };
     } catch (cause) {
-      reply = { t: "res", id, ok: false, error: message2(cause) };
+      reply = { t: "res", id, ok: false, error: message2(cause), ...cause instanceof CodedError ? { code: cause.code } : {} };
     }
     this.send(reply);
   }
@@ -13528,7 +13591,7 @@ import path22 from "node:path";
 // packages/claude-code/package.json
 var package_default4 = {
   name: "@huynle/hub-claude-code",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -13817,7 +13880,7 @@ import path25 from "node:path";
 // packages/preset/package.json
 var package_default5 = {
   name: "@huynle/hub-preset",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -14342,7 +14405,7 @@ import { openSync as openSync5, closeSync as closeSync5, readFileSync as readFil
 // packages/codex/package.json
 var package_default6 = {
   name: "@huynle/hub-codex",
-  version: "0.8.1",
+  version: "0.8.3",
   private: true,
   description: "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/src/artifact-jobs-mcp.ts

@@ -7,6 +7,7 @@
 // (+ artifacts:read) for an app token. Content never travels in requests or job listings, only in the context.
 import type { ArtifactJob, ArtifactJobContext, ArtifactJobKind, ArtifactJobRequest } from "../../sdk/src/artifact-jobs.ts"
 import type { Artifacts } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of the inline proposal text one tool call may carry. */
 export const MCP_JOB_TEXT_BYTES = 256 * 1024
@@ -33,27 +34,27 @@ const KINDS: readonly ArtifactJobKind[] = ["ask", "propose-edit", "run-action"]
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
-  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
   return value
 }
 const optional = (args: Args, key: string): string | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (typeof value !== "string") throw new Error(`"${key}" must be a string`)
+  if (typeof value !== "string") throw new ToolArgError(`"${key}" must be a string`)
   return value.trim() ? value : undefined
 }
 const integer = (args: Args, key: string): number => {
   const value = args[key]
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`"${key}" is required (a whole number)`)
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ToolArgError(`"${key}" is required (a whole number)`)
   return value
 }
 
 function handlerOf(args: Args): ArtifactJobRequest["handler"] {
   const session = optional(args, "session")
   const machine = optional(args, "machine")
-  if (session && machine) throw new Error('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
+  if (session && machine) throw new ToolArgError('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
   if (session) return { session }
-  if (!machine) throw new Error('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
+  if (!machine) throw new ToolArgError('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
   const repo = need(args, "repo")
   const harness = optional(args, "harness")
   const model = optional(args, "model")
@@ -114,7 +115,7 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
     readOnly: false,
     run: async (hub, args, signal) => {
       const kind = optional(args, "kind") as ArtifactJobKind | undefined
-      if (kind && !KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (kind && !KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const action = optional(args, "action")
       const apply = optional(args, "apply") as "manual" | "auto" | undefined
       const key = optional(args, "key")
@@ -181,10 +182,10 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
       const error = optional(args, "error")
       const answer = optional(args, "answer")
       const text = args.text
-      if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
-      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new Error(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
+      if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
+      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new ToolArgError(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
       const keep = args.keep
-      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new Error('"keep" must be a list of paths')
+      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new ToolArgError('"keep" must be a list of paths')
       const path = optional(args, "path")
       const entry = optional(args, "entry")
       const result = error

package/packages/cli/src/artifacts-mcp.ts

@@ -5,6 +5,7 @@
 // tool ever reads local files). Needs scope artifacts:read / artifacts:write for an app token; sessions create and
 // read workspace-shared artifacts only (revising stays with the user in v1).
 import type { Artifact, ArtifactKind, ArtifactRevision, Artifacts, BlobRef } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of inline text one tool call may carry (bigger content: stage it, then pass `blobs`). */
 export const MCP_INLINE_TEXT_BYTES = 256 * 1024
@@ -45,24 +46,24 @@ const FILE_ARGS = {
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
-  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
   return value
 }
 const optional = (args: Args, key: string): string | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (typeof value !== "string") throw new Error(`"${key}" must be a string`)
+  if (typeof value !== "string") throw new ToolArgError(`"${key}" must be a string`)
   return value.trim() ? value : undefined
 }
 
 /** The files of a publish/revise: inline text and/or blob references (one of them required). */
 function files(args: Args, kind: ArtifactKind | undefined): { blobs?: BlobRef[]; upload?: { mediaType: string; data: string; path?: string }[]; entry?: string } {
   const text = args.text
-  if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
+  if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
   const blobs = args.blobs
-  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new Error('"blobs" must be a list of blob references')
-  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new Error('give text or blobs (stage bigger content first and pass its reference)')
-  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new Error(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
+  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new ToolArgError('"blobs" must be a list of blob references')
+  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new ToolArgError('give text or blobs (stage bigger content first and pass its reference)')
+  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new ToolArgError(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
   const path = optional(args, "path")
   const entry = optional(args, "entry")
   const mediaType = optional(args, "mediaType") ?? (kind && DEFAULT_MEDIA[kind]) ?? "text/plain"
@@ -126,7 +127,7 @@ export const artifactTools: readonly ArtifactTool[] = [
     run: async (hub, args, signal) => {
       const title = need(args, "title")
       const kind = need(args, "kind") as ArtifactKind
-      if (!KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (!KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const body = files(args, kind)
       const description = optional(args, "description")
       const visibility = optional(args, "visibility") as "private" | "workspace" | undefined

package/packages/cli/src/mcp.ts

@@ -26,7 +26,8 @@ import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
 import { teamTools } from "./teams-mcp"
-import { ProfileArgError, profileLifecycleTools } from "./profiles-mcp"
+import { profileLifecycleTools } from "./profiles-mcp"
+import { ToolArgError } from "./tool-args"
 import { watchlistTools } from "./watchlist"
 
 /** The protocol revisions the server speaks, newest first: a client's supported one is echoed, else the newest. */
@@ -48,7 +49,7 @@ type Id = string | number | null
 type Args = Record<string, unknown>
 
 /** A bad tool argument (an isError result, not a protocol error). */
-class ArgError extends Error {}
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
@@ -1143,7 +1144,7 @@ export function createMcpServer(options: McpServerOptions): McpServer {
       return controller.signal.aborted ? undefined : ok(id, toolResult(clean(text, token), false))
     } catch (cause) {
       if (controller.signal.aborted) return undefined // cancelled: no answer (MCP cancellation)
-      const text = cause instanceof ArgError || cause instanceof ProfileArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
+      const text = cause instanceof ToolArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
       return ok(id, toolResult(clean(text, token), true))
     } finally {
       if (inFlight.get(key(id)) === controller) inFlight.delete(key(id))

package/packages/cli/src/profiles-mcp.ts

@@ -14,6 +14,7 @@
 // version can be restored with fromVersion); archive/restore (no new versions or pins) and pins (applied to a running
 // session) keep the default destructiveHint. Changes send expectedRevision, so repeating one is idempotent.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { ToolArgError } from "./tool-args"
 import type { Profiles } from "../../sdk/src/client.ts"
 import type { ProfileCommand, ProfileContent, ProfileSkill, ProfileVersionSummary, ProfileView } from "../../sdk/src/types.ts"
 
@@ -53,9 +54,8 @@ const META_FIELDS = {
 } as const
 const SCOPES = "App tokens need scope profiles:read (reads) or profiles:manage (changes; profile_version_create with content fields and the skill/command set/remove tools read the latest version first, so they also need profiles:read); pins need profiles:assign and sessions:read (an app also needs a prompt grant on the session). Session tokens never change profiles. A profile confers no authority."
 
-/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result). */
-export class ProfileArgError extends Error {}
-const ArgError = ProfileArgError
+/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result; tool-args.ts). */
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]