switchroom 0.13.35 → 0.13.36

package/dist/cli/switchroom.js

@@ -47711,8 +47711,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.35";
-var COMMIT_SHA = "c41aabe5";
+var VERSION = "0.13.36";
+var COMMIT_SHA = "73e8bb05";
 
 // src/cli/agent.ts
 init_source();
@@ -61580,6 +61580,23 @@ function registerVaultBackupCommand(vault, program3) {
   });
 }
 
+// src/cli/vault-denied-envelope.ts
+var ENVELOPE_SENTINEL = "ERROR-ENVELOPE:";
+function writeVaultDeniedEnvelope(vaultKey, brokerCode, human) {
+  const envelope = {
+    v: 1,
+    code: "VAULT-BROKER-DENIED",
+    human: `${brokerCode}: ${human}`,
+    fix: {
+      kind: "request_vault_grant",
+      vault_key: vaultKey
+    },
+    request_id: `vault-cli-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+  };
+  process.stderr.write(`${ENVELOPE_SENTINEL} ${JSON.stringify(envelope)}
+`);
+}
+
 // src/cli/vault.ts
 function isSandboxContext() {
   return process.env.SWITCHROOM_RUNTIME === "docker";
@@ -61805,6 +61822,7 @@ function registerVaultCommand(program3) {
         }
         process.stderr.write(`VAULT-BROKER-DENIED [${result.code}]: ${result.msg}
 `);
+        writeVaultDeniedEnvelope(key, result.code, result.msg);
         process.exit(VAULT_EXIT_DENIED);
       }
       if (inSandbox) {
@@ -62020,6 +62038,7 @@ Push passphrase to broker for future requests? [Y/n]: `);
             process.stderr.write(`VAULT-BROKER-DENIED [${result.code}]: ${result.msg}
 ` + `${recoveryHint("denied", key)}
 `);
+            writeVaultDeniedEnvelope(key, result.code, result.msg);
             process.exit(2);
           }
         } else {
@@ -76198,7 +76217,34 @@ function denyPendingScheduleEntry(opts) {
 
 // src/cli/agent-config-write.ts
 import { existsSync as existsSync73, readFileSync as readFileSync59 } from "node:fs";
+import { randomUUID as randomUUID5 } from "node:crypto";
 var MAX_ENTRIES_PER_AGENT = 20;
+var MIN_CRON_INTERVAL_MIN = 5;
+function extractCronSmallestGapMin(expr) {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length < 5)
+    return 0;
+  const min = fields[0];
+  if (min === "*")
+    return 1;
+  const step = min.match(/^\*\/(\d+)$/);
+  if (step)
+    return Number(step[1]);
+  if (min.includes(",")) {
+    const parts = min.split(",").map((s) => Number(s)).filter((n) => Number.isFinite(n));
+    if (parts.length >= 2) {
+      const sorted = [...parts].sort((a, b) => a - b);
+      let smallest = Infinity;
+      for (let i = 1;i < sorted.length; i++) {
+        const gap = sorted[i] - sorted[i - 1];
+        if (gap > 0 && gap < smallest)
+          smallest = gap;
+      }
+      return Number.isFinite(smallest) ? smallest : 0;
+    }
+  }
+  return 0;
+}
 function checkOperatorContext(verb, env2 = process.env) {
   if (env2.SWITCHROOM_OPERATOR === "1")
     return { ok: true };
@@ -76211,8 +76257,45 @@ function checkOperatorContext(verb, env2 = process.env) {
   }
   return { ok: true };
 }
+function buildEnvelopeForCode(code, message, extra) {
+  const request_id = `agent-config-${randomUUID5()}`;
+  if (code === "E_CRON_TOO_FREQUENT") {
+    return {
+      v: 1,
+      code,
+      human: message,
+      fix: {
+        kind: "quota_exceeded",
+        quota: "cron_min_interval_minutes",
+        current: typeof extra.requested_interval_min === "number" ? extra.requested_interval_min : 0,
+        limit: MIN_CRON_INTERVAL_MIN
+      },
+      request_id
+    };
+  }
+  if (code === "E_QUOTA_EXCEEDED") {
+    const current = typeof extra.current === "number" ? extra.current : MAX_ENTRIES_PER_AGENT;
+    return {
+      v: 1,
+      code,
+      human: message,
+      fix: {
+        kind: "quota_exceeded",
+        quota: "schedule_entries_per_agent",
+        current,
+        limit: MAX_ENTRIES_PER_AGENT
+      },
+      request_id
+    };
+  }
+  return;
+}
 function emitError(code, message, extra = {}) {
-  process.stderr.write(JSON.stringify({ code, message, ...extra }) + `
+  const error_envelope = buildEnvelopeForCode(code, message, extra);
+  const line = { code, message, ...extra };
+  if (error_envelope)
+    line.error_envelope = error_envelope;
+  process.stderr.write(JSON.stringify(line) + `
 `);
 }
 function exitCodeFor(code) {
@@ -76276,7 +76359,8 @@ function scheduleAdd(opts) {
       ok: false,
       code: "E_CRON_TOO_FREQUENT",
       message: "cron interval is tighter than the minimum (5 minutes)",
-      exit: 9
+      exit: 9,
+      meta: { requested_interval_min: extractCronSmallestGapMin(opts.cronExpr) }
     };
   }
   const rej = filterOverlaySecrets(dry.doc, "overlay");
@@ -76294,7 +76378,8 @@ function scheduleAdd(opts) {
       ok: false,
       code: "E_QUOTA_EXCEEDED",
       message: `agent already has ${existing.length} overlay entries (max ${MAX_ENTRIES_PER_AGENT})`,
-      exit: 9
+      exit: 9,
+      meta: { current: existing.length }
     };
   }
   const hash2 = cronUnitHash(opts.cronExpr, opts.prompt);
@@ -76493,7 +76578,7 @@ function registerAgentConfigWriteCommands(program3) {
     else if (process.env.SWITCHROOM_AGENT_NAME)
       resolvedAgent = process.env.SWITCHROOM_AGENT_NAME;
     if (!r.ok) {
-      emitError(r.code, r.message);
+      emitError(r.code, r.message, r.meta ?? {});
       appendAudit(resolvedAgent, "schedule.add", { cron: opts.cron, prompt: opts.prompt, name: opts.name, code: r.code, would_recreate: false }, r.exit);
       process.exit(r.exit);
     }
@@ -76606,7 +76691,7 @@ function registerAgentConfigWriteCommands(program3) {
     else if (process.env.SWITCHROOM_AGENT_NAME)
       resolvedAgent = process.env.SWITCHROOM_AGENT_NAME;
     if (!r.ok) {
-      emitError(r.code, r.message);
+      emitError(r.code, r.message, r.meta ?? {});
       appendAudit(resolvedAgent, "schedule.remove", { ...opts, code: r.code }, r.exit);
       process.exit(r.exit);
     }

package/dist/host-control/main.js

@@ -14920,16 +14920,6 @@ function deniedResponse(request_id, error, duration_ms = 0) {
     error
   };
 }
-function errorResponse(request_id, error, duration_ms = 0) {
-  return {
-    v: 1,
-    request_id,
-    result: "error",
-    exit_code: null,
-    duration_ms,
-    error
-  };
-}
 
 // src/analytics/error-friction.ts
 import { createHash as createHash2 } from "node:crypto";
@@ -19515,6 +19505,11 @@ class ErrorBuilder {
     return this;
   }
   docs(url) {
+    try {
+      new URL(url);
+    } catch {
+      throw new TypeError(`err().docs(): invalid URL: ${JSON.stringify(url)} — ErrorEnvelopeSchema requires a fully-qualified URL`);
+    }
     this._docs = url;
     return this;
   }
@@ -20391,6 +20386,14 @@ var CONFIG_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
 function defaultApprovalId() {
   return randomBytes(4).toString("hex");
 }
+function formatConfigApprovalDenyError(approval, approvalId) {
+  if (approval.denySource === "dispatch_failure") {
+    const detail = approval.reason ?? "card dispatch failed";
+    return `E_APPROVAL_DISPATCH_FAILED: ${detail} (approval_id=${approvalId})`;
+  }
+  const suffix = approval.reason ? `: ${approval.reason}` : "";
+  return `E_DENIED: operator denied config_propose_edit${suffix} (approval_id=${approvalId})`;
+}
 function unlinkSyncBestEffort(path2) {
   try {
     unlinkSync(path2);
@@ -20627,8 +20630,10 @@ class HostdServer {
           resp = await this.handleConfigProposeEdit(req, caller, started);
           break;
       }
-    } catch (err2) {
-      resp = errorResponse(req.request_id, `hostd dispatch failed: ${err2.message}`, Date.now() - started);
+    } catch (e) {
+      const msg = e.message;
+      resp = err("E_DISPATCH_FAILED", "hostd dispatch failed").why(msg).op(req.op).caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).build(req.request_id, Date.now() - started);
+      resp = { ...resp, error: `hostd dispatch failed: ${msg}` };
     }
     await this.writeAudit({ caller, req, resp });
     socket.write(encodeResponse(resp));
@@ -20924,7 +20929,7 @@ class HostdServer {
   async handleConfigProposeEdit(req, caller, started) {
     const enabled = this.opts.config.hostd?.config_edit_enabled === true;
     if (!enabled) {
-      return err("E_CONFIG_EDIT_DISABLED", "config_propose_edit is disabled").why("operator opt-in per RFC §3.3").fixFlipFlag("hostd.config_edit_enabled", true).docs("https://switchroom.dev/docs/config-edit#opt-in").op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).build(req.request_id, Date.now() - started);
+      return err("E_CONFIG_EDIT_DISABLED", "config_propose_edit is disabled").why("operator opt-in per RFC §3.3").fixFlipFlag("hostd.config_edit_enabled", true).docs("https://switchroom.dev/docs/config-edit#opt-in").op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).asDenied().build(req.request_id, Date.now() - started);
     }
     const configPath = this.opts.configPath ?? req.args.target_path;
     const verdict = validateConfigEdit({
@@ -20933,10 +20938,12 @@ class HostdServer {
       unifiedDiff: req.args.unified_diff
     });
     if (!verdict.ok) {
-      return errorResponse(req.request_id, `${verdict.code}: ${verdict.detail}`, Date.now() - started);
+      return err(verdict.code, verdict.detail).fixBadInput("unified_diff").op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).build(req.request_id, Date.now() - started);
     }
     if (!this.opts.approvalGateway) {
-      return errorResponse(req.request_id, "E_NO_APPROVAL_GATEWAY: validation passed but hostd was " + "started without an approval-gateway wiring; the operator " + "build is missing the telegram-plugin link", Date.now() - started);
+      return err("E_NO_APPROVAL_GATEWAY", "validation passed but hostd was started without an approval-gateway wiring; the operator build is missing the telegram-plugin link").fixOperatorAction("infra", [
+        "ensure hostd was launched with --approval-gateway / telegram-plugin link"
+      ]).op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).build(req.request_id, Date.now() - started);
     }
     const callerName = caller.kind === "agent" ? caller.name : "operator";
     const approvalId = (this.opts.generateApprovalId ?? defaultApprovalId)();
@@ -20948,35 +20955,45 @@ class HostdServer {
       timeoutMs: CONFIG_APPROVAL_TIMEOUT_MS
     });
     if (approval.verdict === "deny") {
-      return errorResponse(req.request_id, `E_DENIED: operator denied config_propose_edit (approval_id=${approvalId})`, Date.now() - started);
+      const legacy = formatConfigApprovalDenyError(approval, approvalId);
+      const isDispatchFailure = approval.denySource === "dispatch_failure";
+      const code = isDispatchFailure ? "E_APPROVAL_DISPATCH_FAILED" : "E_DENIED";
+      const human = isDispatchFailure ? "approval card dispatch failed before the operator could see it" : "operator denied config_propose_edit";
+      const b = err(code, human).why(legacy).fixOperatorAction(isDispatchFailure ? "infra" : "policy_denied", isDispatchFailure ? ["check telegram-plugin gateway connectivity"] : undefined).op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined);
+      if (!isDispatchFailure)
+        b.asDenied();
+      const built = b.build(req.request_id, Date.now() - started);
+      return { ...built, error: legacy };
     }
     if (approval.verdict === "timeout") {
-      return errorResponse(req.request_id, `E_APPROVAL_TIMEOUT: operator approval card expired without a tap (approval_id=${approvalId})`, Date.now() - started);
+      const legacy = `E_APPROVAL_TIMEOUT: operator approval card expired without a tap (approval_id=${approvalId})`;
+      const built = err("E_APPROVAL_TIMEOUT", "operator approval card expired without a tap").why(`approval_id=${approvalId}`).fixOperatorAction("policy_denied").op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).asDenied().build(req.request_id, Date.now() - started);
+      return { ...built, error: legacy };
     }
     const release = await this.acquireConfigApplyLock();
     try {
       let snapshot;
       try {
         snapshot = readFileSync5(configPath, "utf-8");
-      } catch (err2) {
+      } catch (e) {
         await approval.finalize({
           outcome: "reconcile_failed_rolled_back",
-          detail: `pre-write snapshot read failed: ${err2.message}`
+          detail: `pre-write snapshot read failed: ${e.message}`
         });
-        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: snapshot read failed: ${err2.message}`, Date.now() - started);
+        return this.reconcileFailedRolledBack(`snapshot read failed: ${e.message}`, req, caller, started);
       }
       const postApply = verdict.postApplyContent;
       const tmp = configPath + ".tmp";
       try {
         writeFileSync3(tmp, postApply);
         renameSync(tmp, configPath);
-      } catch (err2) {
+      } catch (e) {
         unlinkSyncBestEffort(tmp);
         await approval.finalize({
           outcome: "reconcile_failed_rolled_back",
-          detail: `atomic write failed: ${err2.message}`
+          detail: `atomic write failed: ${e.message}`
         });
-        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: write failed: ${err2.message}`, Date.now() - started);
+        return this.reconcileFailedRolledBack(`write failed: ${e.message}`, req, caller, started);
       }
       const runner = this.opts.runReconcile ?? (async () => this.runSwitchroom(["apply"]));
       const recRes = await runner({ requestId: approvalId });
@@ -20996,13 +21013,13 @@ class HostdServer {
       try {
         writeFileSync3(tmp, snapshot);
         renameSync(tmp, configPath);
-      } catch (err2) {
-        rollbackDetail = `snapshot restore failed: ${err2.message}`;
+      } catch (e) {
+        rollbackDetail = `snapshot restore failed: ${e.message}`;
         await approval.finalize({
           outcome: "reconcile_failed_rolled_back",
           detail: rollbackDetail
         });
-        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: ${rollbackDetail}`, Date.now() - started);
+        return this.reconcileFailedRolledBack(rollbackDetail, req, caller, started);
       }
       const recRes2 = await runner({ requestId: approvalId });
       const recoveryNote = recRes2.exit_code === 0 ? "rolled back successfully" : `rolled back but recovery reconcile also failed (exit ${recRes2.exit_code})`;
@@ -21010,11 +21027,18 @@ class HostdServer {
         outcome: "reconcile_failed_rolled_back",
         detail: recoveryNote
       });
-      return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: reconcile exit ${recRes.exit_code}; ${recoveryNote}`, Date.now() - started);
+      return this.reconcileFailedRolledBack(`reconcile exit ${recRes.exit_code}; ${recoveryNote}`, req, caller, started);
     } finally {
       release();
     }
   }
+  reconcileFailedRolledBack(detail, req, caller, started) {
+    const legacy = `E_RECONCILE_FAILED_ROLLED_BACK: ${detail}`;
+    const built = err("E_RECONCILE_FAILED_ROLLED_BACK", "config write or reconcile failed; live file rolled back to snapshot").why(detail).fixOperatorAction("infra", [
+      "inspect hostd logs + switchroom apply output to identify the underlying failure"
+    ]).op("config_propose_edit").caller(caller.kind === "agent" ? "agent" : "operator").agentName(caller.kind === "agent" ? caller.name : undefined).build(req.request_id, Date.now() - started);
+    return { ...built, error: legacy };
+  }
   configApplyLock = Promise.resolve();
   async acquireConfigApplyLock() {
     let release;
@@ -21180,7 +21204,9 @@ class HostdServer {
   handleGetStatus(req, _caller, started) {
     const entry = this.statusByRequestId.get(req.args.target_request_id);
     if (!entry) {
-      return errorResponse(req.request_id, `get_status: internal: entry missing despite gate accept`, Date.now() - started);
+      const legacy = `get_status: internal: entry missing despite gate accept`;
+      const built = err("E_INTERNAL", "entry missing despite gate accept").op("get_status").build(req.request_id, Date.now() - started);
+      return { ...built, error: legacy };
     }
     return this.statusEntryToResponse(req.request_id, entry);
   }
@@ -21339,6 +21365,8 @@ class SocketApprovalGateway {
     if (sockPath === null) {
       return {
         verdict: "deny",
+        reason: "no reachable telegram gateway socket for this agent",
+        denySource: "dispatch_failure",
         finalize: async () => {}
       };
     }
@@ -21379,7 +21407,12 @@ class SocketApprovalGateway {
             return;
           resolved = true;
           log(`request_config_approval write failed (requestId=${req.requestId}): ${err2.message}`);
-          resolve6({ verdict: "deny", finalize: async () => {} });
+          resolve6({
+            verdict: "deny",
+            reason: `request_config_approval write failed: ${err2.message}`,
+            denySource: "dispatch_failure",
+            finalize: async () => {}
+          });
         }
       });
       client2.on("data", (chunk2) => {
@@ -21400,8 +21433,13 @@ class SocketApprovalGateway {
           const obj = parsed;
           if (obj.type === "config_approval_resolved" && obj.requestId === req.requestId && (obj.verdict === "approve" || obj.verdict === "deny" || obj.verdict === "timeout") && !resolved) {
             resolved = true;
+            const verdict = obj.verdict;
+            const reasonField = typeof obj.reason === "string" ? obj.reason : undefined;
+            const denySource = verdict === "deny" ? obj.denySource === "dispatch_failure" ? "dispatch_failure" : "operator" : undefined;
             resolve6({
-              verdict: obj.verdict,
+              verdict,
+              ...reasonField !== undefined ? { reason: reasonField } : {},
+              ...denySource !== undefined ? { denySource } : {},
               finalize
             });
           }
@@ -21412,13 +21450,23 @@ class SocketApprovalGateway {
           return;
         resolved = true;
         log(`gateway socket error (requestId=${req.requestId}): ${err2.message}`);
-        resolve6({ verdict: "deny", finalize: async () => {} });
+        resolve6({
+          verdict: "deny",
+          reason: `gateway socket error: ${err2.message}`,
+          denySource: "dispatch_failure",
+          finalize: async () => {}
+        });
       });
       client2.on("close", () => {
         if (resolved)
           return;
         resolved = true;
-        resolve6({ verdict: "deny", finalize: async () => {} });
+        resolve6({
+          verdict: "deny",
+          reason: "gateway socket closed before verdict",
+          denySource: "dispatch_failure",
+          finalize: async () => {}
+        });
       });
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.35",
+  "version": "0.13.36",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {