@oked/sdk 0.6.3 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/classify.js CHANGED
@@ -1376,16 +1376,76 @@ function classifyDirectoryGrant(tool, toolInput) {
1376
1376
  return "review";
1377
1377
  return "warning";
1378
1378
  }
1379
+ /**
1380
+ * Desktop app (`ccd_*`) tools that only change what the app shows or how it
1381
+ * tracks this session: panes, split view, the sidebar, the PR bar, archiving.
1382
+ * sync_with_base_branch merges the base branch into the session's worktree on
1383
+ * the host, the same as a Bash `git merge` or `git pull` (both safe); a push
1384
+ * after it is gated on its own. The app's tools with a real effect stay out
1385
+ * of this table: set_auto_merge (GitHub merges the PR), set_setting,
1386
+ * permission or model changes, worktree clean-up and discards.
1387
+ */
1388
+ const CCD_SAFE_TOOLS = new Map([
1389
+ ["ccd_pr", new Set(["bind_pr", "unbind_pr"])],
1390
+ ["ccd_view", new Set(["show_pane", "close_pane", "set_transcript_view"])],
1391
+ ["ccd_session", new Set(["spawn_task"])],
1392
+ ["ccd_window", new Set(["open_session_in", "close_split", "set_sidebar_collapsed"])],
1393
+ ["ccd_sidebar", new Set([
1394
+ "create_group", "create_section", "rename_group", "rename_section",
1395
+ "move_sessions", "set_pinned", "set_unread", "set_view",
1396
+ ])],
1397
+ ["ccd_host", new Set(["open_in_editor", "reveal_path", "request_keep_awake", "sync_with_base_branch"])],
1398
+ ["ccd_session_mgmt", new Set(["set_session_title", "archive_session", "unarchive_session"])],
1399
+ ]);
1400
+ // claude.ai connectors reach Claude Code as mcp__<uuid>__<tool>, so the server
1401
+ // name does not say which connector it is.
1402
+ const CONNECTOR_SERVER_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
1403
+ // Tool names that are a read verb alone (the prefix rules below need "read_").
1404
+ const SAFE_BARE_TOOLS = new Set(["read", "get", "list", "search", "find", "view", "guide", "help"]);
1405
+ function isRecord(v) {
1406
+ return typeof v === "object" && v !== null && !Array.isArray(v);
1407
+ }
1408
+ /**
1409
+ * Claude Docs connector writes: `batch` (create a doc or apply edits to one)
1410
+ * and `update` (edit a tab, rename, change a stored value). They change the
1411
+ * user's own docs on claude.ai, which are private until the user shares them.
1412
+ * Log them (`warning`), no prompt. The input shape identifies the connector,
1413
+ * because its server name is a UUID and the tool names are generic. Sharing
1414
+ * and deletes are not in this rule.
1415
+ */
1416
+ function isClaudeDocsWrite(server, tool, input) {
1417
+ if (!CONNECTOR_SERVER_RE.test(server))
1418
+ return false;
1419
+ if (tool === "batch") {
1420
+ return isRecord(input.container) && typeof input.container.kind === "string" &&
1421
+ (input.batch === undefined || Array.isArray(input.batch));
1422
+ }
1423
+ if (tool === "update") {
1424
+ return isRecord(input.ref) && typeof input.ref.object === "string" && typeof input.ref.id === "string" &&
1425
+ input.payload !== undefined;
1426
+ }
1427
+ return false;
1428
+ }
1379
1429
  function classifyMcpTool(toolName, toolInput = {}) {
1380
1430
  const parts = toolName.split("__");
1381
1431
  const tool = parts[parts.length - 1] || "";
1382
1432
  if (parts.includes("ccd_directory") && (tool === "change_directory" || tool === "request_directory")) {
1383
1433
  return classifyDirectoryGrant(tool, toolInput);
1384
1434
  }
1435
+ if (parts.slice(1, -1).some((p) => CCD_SAFE_TOOLS.get(p)?.has(tool)))
1436
+ return "safe";
1437
+ // The PR bar's CI monitor switches. auto_fix lets the session push fixes,
1438
+ // but each push is gated on its own. Log it, no prompt.
1439
+ if (parts.includes("ccd_pr") && tool === "set_monitor")
1440
+ return "warning";
1441
+ if (parts.length === 3 && isClaudeDocsWrite(parts[1] || "", tool, toolInput))
1442
+ return "warning";
1385
1443
  const browserServer = parts.slice(1, -1).find((p) => BROWSER_MCP_SERVERS.has(p));
1386
1444
  if (browserServer)
1387
1445
  return classifyBrowserTool(tool, toolInput, browserServer);
1388
1446
  // Read-only retrieval verbs.
1447
+ if (SAFE_BARE_TOOLS.has(tool))
1448
+ return "safe";
1389
1449
  if (tool.startsWith("list_") || tool.startsWith("get_") || tool.startsWith("search_") ||
1390
1450
  tool.startsWith("read_") || tool.startsWith("fetch_") || tool.startsWith("query_") ||
1391
1451
  tool.startsWith("find_") || tool.startsWith("view_") || tool.startsWith("show_") ||
package/dist/describe.js CHANGED
@@ -879,7 +879,13 @@ function summarizeBrowser(tool, input, server) {
879
879
  }
880
880
  function summarizeMcp(toolName, input) {
881
881
  const parts = toolName.split("__");
882
- const server = parts[1] || "unknown";
882
+ // claude.ai connectors have a UUID as the server name. The UUID means nothing to the approver.
883
+ // Desktop app tools have internal server names (ccd_host, ccd_pr).
884
+ const server = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(parts[1] || "")
885
+ ? "claude.ai connector"
886
+ : /^ccd_/.test(parts[1] || "")
887
+ ? "Claude desktop app"
888
+ : parts[1] || "unknown";
883
889
  const tool = parts[2] || "";
884
890
  if (parts.includes("ccd_directory") && (tool === "change_directory" || tool === "request_directory")) {
885
891
  const dir = typeof input.path === "string" && input.path.trim() ? shortenPath(input.path.trim()) : undefined;
@@ -959,7 +965,7 @@ function summarizeMcp(toolName, input) {
959
965
  if (tool.startsWith("list_") || tool.startsWith("get_") || tool.startsWith("search_")) {
960
966
  return { title: `${toWords(tool)} via ${server}`, kind: "unknown_tool" };
961
967
  }
962
- return { title: `${toWords(tool)} via ${server}`, kind: "unknown_tool" };
968
+ return { title: `${toSentence(tool)} via ${server}`, kind: "unknown_tool" };
963
969
  }
964
970
  function identifyTarget(input) {
965
971
  const id = input.id ?? input.name ?? input.path ?? input.target ?? input.repo ?? input.repository ?? null;
@@ -1207,6 +1213,13 @@ function formatByteCount(bytes) {
1207
1213
  function toWords(snake) {
1208
1214
  return snake.replace(/_/g, " ").split(" ").map((w) => (w.length <= 3 ? w.toUpperCase() : w)).join(" ");
1209
1215
  }
1216
+ // "set_auto_merge" -> "Set auto merge", "bind_pr" -> "Bind PR": the first word
1217
+ // is a verb, so it is not read as an acronym.
1218
+ function toSentence(snake) {
1219
+ const [first = "", ...rest] = snake.split("_");
1220
+ const head = first.charAt(0).toUpperCase() + first.slice(1).toLowerCase();
1221
+ return rest.length ? `${head} ${toWords(rest.join("_"))}` : head;
1222
+ }
1210
1223
  function shortenPath(filePath) {
1211
1224
  return filePath
1212
1225
  .replace(/^\/home\/[^/]+\//, "~/")
package/dist/errors.d.ts CHANGED
@@ -4,11 +4,21 @@
4
4
  *
5
5
  * - OKedAuthError -> bad/missing API key. Always deny. Never an
6
6
  * outage, so degraded-mode does NOT apply.
7
- * - OKedBackendUnreachableError -> connect failure or 5xx. This is the
8
- * outage case degradedDecision() handles. A
9
- * request the backend accepted and then held
10
- * past a timer is NOT an outage: approve()
11
- * returns { decision: "timeout" } for it.
7
+ * - OKedBackendUnreachableError -> connect failure, 5xx, a hosting-platform
8
+ * reply instead of the backend (Railway
9
+ * "Application not found"), or any reply that
10
+ * is not JSON. This is the outage case
11
+ * degradedDecision() handles. A request the
12
+ * backend accepted and then held past a timer
13
+ * is NOT an outage: approve() returns
14
+ * { decision: "timeout" } for it.
15
+ *
16
+ * - OKedTooManyPendingError -> HTTP 429: too many approvals already wait for
17
+ * a decision. Always deny, with a message that
18
+ * says what to do. Never an outage.
19
+ *
20
+ * - OKedHttpError -> any other HTTP error from the backend. Always
21
+ * deny. Carries the status and a short detail.
12
22
  *
13
23
  * - OKedReceiptError -> the decision came with a receipt that does not
14
24
  * verify (or with none, when requireReceipt is
@@ -24,7 +34,19 @@ export declare class OKedAuthError extends Error {
24
34
  }
25
35
  export declare class OKedBackendUnreachableError extends Error {
26
36
  readonly cause?: unknown;
27
- constructor(message: string, cause?: unknown);
37
+ /** The HTTP status, when a reply came back at all. */
38
+ readonly status?: number;
39
+ constructor(message: string, cause?: unknown, status?: number);
40
+ }
41
+ export declare class OKedTooManyPendingError extends Error {
42
+ readonly status = 429;
43
+ constructor(detail?: string);
44
+ }
45
+ export declare class OKedHttpError extends Error {
46
+ readonly status: number;
47
+ /** A short, one-line part of the reply body. */
48
+ readonly detail: string;
49
+ constructor(status: number, detail: string);
28
50
  }
29
51
  export declare class OKedReceiptError extends Error {
30
52
  /** e.g. ["bad_signature"], ["subject_mismatch"], ["missing"] */
package/dist/errors.js CHANGED
@@ -4,11 +4,21 @@
4
4
  *
5
5
  * - OKedAuthError -> bad/missing API key. Always deny. Never an
6
6
  * outage, so degraded-mode does NOT apply.
7
- * - OKedBackendUnreachableError -> connect failure or 5xx. This is the
8
- * outage case degradedDecision() handles. A
9
- * request the backend accepted and then held
10
- * past a timer is NOT an outage: approve()
11
- * returns { decision: "timeout" } for it.
7
+ * - OKedBackendUnreachableError -> connect failure, 5xx, a hosting-platform
8
+ * reply instead of the backend (Railway
9
+ * "Application not found"), or any reply that
10
+ * is not JSON. This is the outage case
11
+ * degradedDecision() handles. A request the
12
+ * backend accepted and then held past a timer
13
+ * is NOT an outage: approve() returns
14
+ * { decision: "timeout" } for it.
15
+ *
16
+ * - OKedTooManyPendingError -> HTTP 429: too many approvals already wait for
17
+ * a decision. Always deny, with a message that
18
+ * says what to do. Never an outage.
19
+ *
20
+ * - OKedHttpError -> any other HTTP error from the backend. Always
21
+ * deny. Carries the status and a short detail.
12
22
  *
13
23
  * - OKedReceiptError -> the decision came with a receipt that does not
14
24
  * verify (or with none, when requireReceipt is
@@ -28,10 +38,33 @@ export class OKedAuthError extends Error {
28
38
  }
29
39
  export class OKedBackendUnreachableError extends Error {
30
40
  cause;
31
- constructor(message, cause) {
41
+ /** The HTTP status, when a reply came back at all. */
42
+ status;
43
+ constructor(message, cause, status) {
32
44
  super(message);
33
45
  this.name = "OKedBackendUnreachableError";
34
46
  this.cause = cause;
47
+ this.status = status;
48
+ }
49
+ }
50
+ export class OKedTooManyPendingError extends Error {
51
+ status = 429;
52
+ constructor(detail = "") {
53
+ super("OKed: too many approvals are waiting for your decision. " +
54
+ "Approve or deny them in Telegram or on the dashboard, then try again." +
55
+ (detail ? ` (HTTP 429: ${detail})` : " (HTTP 429)"));
56
+ this.name = "OKedTooManyPendingError";
57
+ }
58
+ }
59
+ export class OKedHttpError extends Error {
60
+ status;
61
+ /** A short, one-line part of the reply body. */
62
+ detail;
63
+ constructor(status, detail) {
64
+ super(`OKed backend error HTTP ${status}${detail ? `: ${detail}` : ""}`);
65
+ this.name = "OKedHttpError";
66
+ this.status = status;
67
+ this.detail = detail;
35
68
  }
36
69
  }
37
70
  export class OKedReceiptError extends Error {
package/dist/index.d.ts CHANGED
@@ -41,7 +41,7 @@ export declare class OKedClient {
41
41
  */
42
42
  heartbeat(): Promise<void>;
43
43
  }
44
- export { OKedAuthError, OKedBackendUnreachableError, OKedReceiptError } from "./errors.js";
44
+ export { OKedAuthError, OKedBackendUnreachableError, OKedHttpError, OKedReceiptError, OKedTooManyPendingError, } from "./errors.js";
45
45
  export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./receipt.js";
46
46
  export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
47
47
  export { verifyReceipt, verifyChain, shortReceiptId, type SignedReceipt, type ReceiptBody, type ReceiptKey, } from "@oked/receipt-core";
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { readFileSync, writeFileSync, mkdirSync } from "fs";
2
2
  import { dirname } from "path";
3
3
  import { loadOKedConfig, OKED_RULES_CACHE_PATH, OKED_HEARTBEAT_PATH } from "./config.js";
4
- import { OKedAuthError, OKedBackendUnreachableError } from "./errors.js";
4
+ import { OKedAuthError, OKedBackendUnreachableError, OKedHttpError, OKedTooManyPendingError } from "./errors.js";
5
5
  import { randomUUID } from "crypto";
6
6
  import { checkReceipt, OKED_RECEIPT_KEYS_URL } from "./receipt.js";
7
7
  import { hostname } from "os";
@@ -197,28 +197,53 @@ export class OKedClient {
197
197
  }
198
198
  if (!res.ok) {
199
199
  const body = await res.text().catch(() => "");
200
- if (res.status === 401 || res.status === 403) {
201
- throw new OKedAuthError(`OKed backend error ${res.status}: ${body}`, res.status);
202
- }
200
+ const detail = shortDetail(body);
203
201
  // A gateway that gave up waiting on a held long-poll: same as above.
204
202
  if (res.status === 504)
205
203
  return HELD_TIMEOUT;
204
+ // Auth first, whatever the body: a bad key must never become an "outage",
205
+ // or degraded mode could allow an action with an invalid key.
206
+ if (res.status === 401 || res.status === 403) {
207
+ throw new OKedAuthError(`OKed backend error ${res.status}: ${body}`, res.status);
208
+ }
209
+ if (res.status === 429)
210
+ throw new OKedTooManyPendingError(errorField(body) || detail);
211
+ // The hosting platform answered instead of the backend (the backend is
212
+ // gone or not deployed), or something answered that is not the backend
213
+ // at all. Both are an outage, so degraded mode applies.
214
+ if (res.headers.get("x-railway-fallback") || /application not found/i.test(body)) {
215
+ throw new OKedBackendUnreachableError(`OKed backend unreachable: HTTP ${res.status}, the hosting platform answered "application not found" (${this.config.backendUrl})`, undefined, res.status);
216
+ }
217
+ if (!isJson(body)) {
218
+ throw new OKedBackendUnreachableError(`OKed backend unreachable: HTTP ${res.status} with a reply that is not JSON${detail ? `: ${detail}` : ""}`, undefined, res.status);
219
+ }
206
220
  if (res.status >= 500) {
207
- throw new OKedBackendUnreachableError(`OKed backend error ${res.status}: ${body}`);
221
+ throw new OKedBackendUnreachableError(`OKed backend error HTTP ${res.status}: ${detail}`, undefined, res.status);
208
222
  }
209
- throw new Error(`OKed backend error ${res.status}: ${body}`);
223
+ throw new OKedHttpError(res.status, errorField(body) || detail);
210
224
  }
211
225
  let result;
226
+ let text;
212
227
  try {
213
228
  // The backend sends headers at once and streams whitespace heartbeats
214
229
  // while it waits, so the wait for a human happens here, in the body.
215
- result = (await res.json());
230
+ text = await res.text();
216
231
  }
217
232
  catch (err) {
218
233
  if (isHeldRequestTimeout(err))
219
234
  return HELD_TIMEOUT;
220
235
  throw err;
221
236
  }
237
+ try {
238
+ result = JSON.parse(text);
239
+ if (!result || typeof result !== "object")
240
+ throw new Error("not an object");
241
+ }
242
+ catch {
243
+ // HTTP 200 with a body that is not our JSON: not the backend. An outage.
244
+ throw new OKedBackendUnreachableError(`OKed backend unreachable: HTTP ${res.status} with a reply that is not JSON` +
245
+ ` (content-type ${res.headers.get("content-type") || "none"})`, undefined, res.status);
246
+ }
222
247
  // Nobody acts on a decision we cannot prove: an invalid receipt throws
223
248
  // OKedReceiptError (every integration denies), and so does an approval
224
249
  // with no receipt while requireReceipt is on (the default).
@@ -320,6 +345,31 @@ const HELD_TIMEOUT = { approved: false, approval_id: null, decision: "timeout" }
320
345
  * abort (TimeoutError), or undici's 300s headers/body timeouts, which fire
321
346
  * regardless of the abort signal on a silent long-poll.
322
347
  */
348
+ function isJson(text) {
349
+ try {
350
+ JSON.parse(text);
351
+ return true;
352
+ }
353
+ catch {
354
+ return false;
355
+ }
356
+ }
357
+ /** One line, at most 200 characters: for error messages, never a whole page. */
358
+ function shortDetail(body) {
359
+ const line = body.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
360
+ return line.length > 200 ? line.slice(0, 197) + "..." : line;
361
+ }
362
+ /** The backend's own error text ({"error": "..."} or {"message": "..."}), if any. */
363
+ function errorField(body) {
364
+ try {
365
+ const j = JSON.parse(body);
366
+ const v = typeof j.error === "string" ? j.error : typeof j.message === "string" ? j.message : "";
367
+ return shortDetail(v);
368
+ }
369
+ catch {
370
+ return "";
371
+ }
372
+ }
323
373
  function isHeldRequestTimeout(err) {
324
374
  if (!err || typeof err !== "object")
325
375
  return false;
@@ -342,7 +392,7 @@ function isRetriableConnectError(err) {
342
392
  code === "ETIMEDOUT" ||
343
393
  code === "UND_ERR_CONNECT_TIMEOUT");
344
394
  }
345
- export { OKedAuthError, OKedBackendUnreachableError, OKedReceiptError } from "./errors.js";
395
+ export { OKedAuthError, OKedBackendUnreachableError, OKedHttpError, OKedReceiptError, OKedTooManyPendingError, } from "./errors.js";
346
396
  export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./receipt.js";
347
397
  export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
348
398
  export { verifyReceipt, verifyChain, shortReceiptId, } from "@oked/receipt-core";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oked/sdk",
3
- "version": "0.6.3",
3
+ "version": "0.6.5",
4
4
  "description": "OKed SDK - human approval layer for AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -45,7 +45,7 @@
45
45
  "access": "public"
46
46
  },
47
47
  "dependencies": {
48
- "@oked/receipt-core": "0.6.3"
48
+ "@oked/receipt-core": "0.6.5"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@types/node": "^22.13.10",