@clawchatsai/connector 0.2.0 → 0.2.2

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/README.md CHANGED
@@ -34,14 +34,22 @@ The signaling server only facilitates the handshake. After step 4, it is out of
34
34
  Requires OpenClaw 2026.9.7 or newer on the machine that runs your gateway.
35
35
 
36
36
  ```bash
37
- openclaw plugins install @clawchatsai/connector
37
+ openclaw gateway stop && openclaw plugins install npm:@clawchatsai/connector --force --accept-capabilities && openclaw gateway start
38
38
  ```
39
39
 
40
- The gateway loads the plugin right away; no restart is needed. OpenClaw warns that the package is
41
- outside ClawHub review — answer `y` to continue (pass `--force` in scripts).
40
+ This stops the gateway for a moment, installs the plugin, and starts the gateway again with it loaded.
41
+ Stopping first avoids the install failing with a gateway ownership or lock error, which happens for
42
+ example when OpenClaw was updated but the running gateway is still the old version.
42
43
 
43
- Install while your gateway is running. If it is not, OpenClaw installs locally instead and asks you to
44
- re-run the same command with `--accept-capabilities` after reviewing what the plugin declares.
44
+ - `--force` confirms the npm source, which is outside ClawHub review.
45
+ - `--accept-capabilities` approves the capabilities the plugin declares (review them with
46
+ `openclaw plugins inspect connector`).
47
+ - Keep the `npm:` prefix: since OpenClaw 2026.11, a package name without a prefix is looked up only
48
+ on ClawHub, and the install fails with "Package not found on ClawHub".
49
+
50
+ If your gateway runs in a container where stopping it also stops the container, run the install
51
+ without the stop and start: `openclaw plugins install npm:@clawchatsai/connector --force`. A running
52
+ gateway loads the plugin right away.
45
53
 
46
54
  Then connect it to your ClawChats account:
47
55
 
package/dist/index.js CHANGED
@@ -218,7 +218,7 @@ async function ensureNativeModules(ctx) {
218
218
  const ndcRoot = resolvePackageRoot(require, 'node-datachannel');
219
219
  if (!ndcRoot) {
220
220
  throw new Error(`the WebRTC library (node-datachannel) is missing from this install. ` +
221
- `Reinstall the plugin: openclaw plugins install @clawchatsai/connector --force`);
221
+ `Reinstall the plugin: openclaw plugins install npm:@clawchatsai/connector --force`);
222
222
  }
223
223
  const targetPath = path.join(ndcRoot, 'build', 'Release', 'node_datachannel.node');
224
224
  // Already built — nothing to do.
@@ -648,6 +648,14 @@ function setupDataChannelHandler(dc, connectionId, ctx, dtls) {
648
648
  }
649
649
  connectedClients.set(connectionId, dc);
650
650
  ctx.logger.info(`Browser authenticated: ${connectionId} (${label})`);
651
+ // The gateway's chat attachment limits (its hello-ok policy), which this browser checks files against.
652
+ const limits = app?.gatewayClient?.attachmentLimitsFrame();
653
+ if (limits) {
654
+ try {
655
+ dc.send(JSON.stringify({ type: 'gateway-event', payload: limits }));
656
+ }
657
+ catch { /* closed */ }
658
+ }
651
659
  },
652
660
  onMessage: (msg) => processAuthenticatedMessage(dc, connectionId, msg, ctx),
653
661
  onLoginFailure: (reason) => {
package/dist/shim.js CHANGED
@@ -45,20 +45,23 @@ class FakeReq extends Readable {
45
45
  this.push(parsed['data']);
46
46
  }
47
47
  else if (parsed && parsed['_multipart']) {
48
- // Multipart form data: { _multipart: true, fields: { key: string | { filename, contentType, data } } }
48
+ // Multipart form data: { _multipart: true, fields: { key: Entry | Entry[] } } where
49
+ // Entry = string | { filename, contentType, data }. An array is a repeated key (many files).
49
50
  const boundary = '----ClawChatsBoundary' + Date.now();
50
51
  this.headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
51
52
  const fields = parsed['fields'] || {};
52
53
  const parts = [];
53
- for (const [key, value] of Object.entries(fields)) {
54
- if (value && typeof value === 'object' && value['filename']) {
55
- const f = value;
56
- parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"; filename="${f.filename}"\r\nContent-Type: ${f.contentType}\r\n\r\n`));
57
- parts.push(Buffer.from(f.data, 'base64'));
58
- parts.push(Buffer.from('\r\n'));
59
- }
60
- else {
61
- parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"\r\n\r\n${String(value)}\r\n`));
54
+ for (const [key, raw] of Object.entries(fields)) {
55
+ for (const value of Array.isArray(raw) ? raw : [raw]) {
56
+ if (value && typeof value === 'object' && value['filename']) {
57
+ const f = value;
58
+ parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"; filename="${f.filename}"\r\nContent-Type: ${f.contentType}\r\n\r\n`));
59
+ parts.push(Buffer.from(f.data, 'base64'));
60
+ parts.push(Buffer.from('\r\n'));
61
+ }
62
+ else {
63
+ parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${key}"\r\n\r\n${String(value)}\r\n`));
64
+ }
62
65
  }
63
66
  }
64
67
  parts.push(Buffer.from(`--${boundary}--\r\n`));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clawchatsai/connector",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "type": "module",
5
5
  "description": "ClawChats OpenClaw plugin — P2P tunnel + local API bridge",
6
6
  "main": "dist/index.js",
@@ -41,7 +41,7 @@ test('no browser: no approval-client connection; main connection never declares
41
41
  c.connect();
42
42
  await wait(200);
43
43
  assert.equal(gw.conns.length, 1);
44
- assert.deepEqual(gw.conns[0].params.caps, ['tool-events']);
44
+ assert.deepEqual(gw.conns[0].params.caps, ['tool-events', 'chat-queue-status']);
45
45
  assert.equal(gw.approvalConns().length, 0);
46
46
  c.close();
47
47
  await new Promise(r => gw.wss.close(r));
@@ -29,7 +29,9 @@ function createCompletion(llm) {
29
29
  try {
30
30
  return await llm.complete(base);
31
31
  } catch (err) {
32
- if (err?.code === 'LLM_COMPLETION_NOT_AUTHORIZED') throw err;
32
+ // Not a transport problem: isolated mode fails the same way. LLM_RUNTIME_LIFECYCLE (2026.11.5+): the plugin or
33
+ // model runtime is reloading; the host says to retry from a fresh plugin operation, not inside this one.
34
+ if (['LLM_COMPLETION_NOT_AUTHORIZED', 'LLM_RUNTIME_LIFECYCLE', 'LLM_COMPLETION_ABORTED'].includes(err?.code)) throw err;
33
35
  return await llm.complete({ ...base, maxTokens: undefined, execution: { mode: 'isolated-agent-runtime', timeoutMs: TIMEOUT_MS } });
34
36
  }
35
37
  };
@@ -1,7 +1,7 @@
1
1
  import { test } from 'node:test';
2
2
  import assert from 'node:assert/strict';
3
3
  import { Readable } from 'node:stream';
4
- import { createTitleHandler, normalizeTitle, TITLE_PROMPT } from './title.js';
4
+ import { createTitleHandler, createTitler, normalizeTitle, TITLE_PROMPT } from './title.js';
5
5
 
6
6
  function call(handler, body) {
7
7
  const req = Readable.from([Buffer.from(JSON.stringify(body))]);
@@ -44,3 +44,10 @@ test('authorization failures are not retried; bad input is rejected', async () =
44
44
  assert.equal((await call(handler, { message: ' ' })).status, 400);
45
45
  assert.equal((await call(createTitleHandler(undefined), { message: 'x' })).status, 501);
46
46
  });
47
+
48
+ test('a runtime reload (2026.11.5+ LLM_RUNTIME_LIFECYCLE) is not retried in isolated mode', async () => {
49
+ let n = 0;
50
+ const titler = createTitler({ complete: async () => { n++; throw Object.assign(new Error('reloading'), { code: 'LLM_RUNTIME_LIFECYCLE' }); } });
51
+ await assert.rejects(titler('plan the offsite'), /reloading/);
52
+ assert.equal(n, 1);
53
+ });
package/server/gateway.js CHANGED
@@ -5,10 +5,40 @@ import { ApprovalClient } from './approval-client.js';
5
5
 
6
6
  // Per-session run/transcript events; hidden sessions' ones are dropped by the lens.
7
7
  const RUN_EVENTS = new Set(['chat', 'agent', 'session.tool', 'session.operation', 'session.observer']);
8
- const SCOPES = ['operator.read', 'operator.write', 'operator.admin', 'operator.approvals', 'operator.questions'];
8
+ export const SCOPES = ['operator.read', 'operator.write', 'operator.admin', 'operator.approvals', 'operator.questions'];
9
9
  // After the last browser leaves, the approval-client connection stays this long (P2P reconnects, reloads).
10
10
  const APPROVAL_CLIENT_GRACE_MS = 10_000;
11
11
 
12
+ /**
13
+ * The Error for a failed gateway response. The error shape's machine-readable fields stay on it (gatewayCode,
14
+ * retryable, retryAfterMs, details; 2026.11.4+ sets them on startup refusals and persisted-but-unapplied config writes)
15
+ * so callers can tell "try again" from "failed". Not `code`: that name is the peer protocol's (peer/link.js).
16
+ */
17
+ export function gatewayError(error, fallback) {
18
+ const err = new Error(error?.message || fallback);
19
+ if (!error || typeof error !== 'object') return err;
20
+ if (typeof error.code === 'string') err.gatewayCode = error.code;
21
+ if (typeof error.retryable === 'boolean') err.retryable = error.retryable;
22
+ if (typeof error.retryAfterMs === 'number') err.retryAfterMs = error.retryAfterMs;
23
+ if (error.details !== undefined) err.details = error.details;
24
+ return err;
25
+ }
26
+
27
+ /**
28
+ * The chat attachment limits a 2026.11+ gateway advertises in hello-ok (policy.attachments: maxBytes,
29
+ * maxImageBytes) plus one send's byte budget, which has to fit a single frame: the Control UI's
30
+ * resolveChatAttachmentLimits (chat-attachment-admission.ts) and chat-attachment-frame-budget.ts.
31
+ * Null when the gateway doesn't say (older versions): then only the gateway itself checks.
32
+ */
33
+ export function attachmentLimitsOf(hello) {
34
+ const policy = hello?.policy;
35
+ const a = policy?.attachments;
36
+ if (!a || !(a.maxBytes > 0)) return null;
37
+ const maxImageBytes = a.maxImageBytes > 0 ? Math.min(a.maxImageBytes, a.maxBytes) : a.maxBytes;
38
+ const maxBatchBytes = policy.maxPayload > 0 ? Math.max(0, Math.floor(((policy.maxPayload - 256 * 1024) * 3) / 4)) : null;
39
+ return { maxBytes: a.maxBytes, maxImageBytes, ...(maxBatchBytes ? { maxBatchBytes } : {}) };
40
+ }
41
+
12
42
  export class GatewayClient {
13
43
  constructor({ dataDir, debugLogger, gatewayWsUrl, authToken, approvalClientGraceMs = APPROVAL_CLIENT_GRACE_MS }) {
14
44
  this.dataDir = dataDir;
@@ -85,7 +115,7 @@ export class GatewayClient {
85
115
  this._rpc.delete(msg.id);
86
116
  clearTimeout(pending.timer);
87
117
  if (msg.ok) pending.resolve(msg.payload);
88
- else pending.reject(new Error(msg.error?.message || `${pending.method} failed`));
118
+ else pending.reject(gatewayError(msg.error, `${pending.method} failed`));
89
119
  return;
90
120
  }
91
121
 
@@ -99,10 +129,13 @@ export class GatewayClient {
99
129
  if (msg.type === 'event' && this.onEvent) { try { this.onEvent(msg); } catch (e) { console.error('[gateway] event observer:', e.message); } }
100
130
 
101
131
  if (msg.type === 'event' && msg.event === 'connect.challenge') {
102
- this.ws.send(JSON.stringify({ type: 'req', id: 'gw-connect-1', method: 'connect', params: this._connectParams(msg.payload?.nonce || '', ['tool-events']) }));
132
+ // chat-queue-status (2026.11.6+; older gateways ignore unknown caps): a queued send is shown from pendingInputs,
133
+ // as in the Control UI. Without it the gateway sends the "queued" notice as a chat delta carrying text, which
134
+ // browsers would render as reply text and team chat would keep as a stopped turn's partial reply.
135
+ this.ws.send(JSON.stringify({ type: 'req', id: 'gw-connect-1', method: 'connect', params: this._connectParams(msg.payload?.nonce || '', ['tool-events', 'chat-queue-status']) }));
103
136
  return;
104
137
  }
105
- if (msg.type === 'res' && msg.payload?.type === 'hello-ok') { console.log('Gateway handshake complete'); this.connected = true; this.broadcastGatewayStatus(true); this.sync?.onConnected(); this.onConnected?.(); this.request('sessions.subscribe', {}).catch(e => console.warn(`[lens] sessions.subscribe failed: ${e.message}`)); this.lens?.seedWithRetry(); }
138
+ if (msg.type === 'res' && msg.payload?.type === 'hello-ok') { console.log('Gateway handshake complete'); this.connected = true; this.attachmentLimits = attachmentLimitsOf(msg.payload); this.broadcastGatewayStatus(true); if (this.attachmentLimits) this.broadcastToBrowsers(this.attachmentLimitsFrame()); this.sync?.onConnected(); this.onConnected?.(); this.request('sessions.subscribe', {}).catch(e => console.warn(`[lens] sessions.subscribe failed: ${e.message}`)); this.lens?.seedWithRetry(); }
106
139
  // Session events arrive through the connector's own subscription; the lens filters them
107
140
  // for the browser (session.message only for chats a browser subscribed to).
108
141
  if (msg.type === 'event' && (msg.event === 'sessions.changed' || msg.event === 'session.message')) {
@@ -145,6 +178,11 @@ export class GatewayClient {
145
178
  this.broadcastToBrowsers(JSON.stringify({ type: 'clawchats', event: 'gateway-status', connected }));
146
179
  }
147
180
 
181
+ /** The gateway's attachment limits for browsers (sent on each hello-ok and to a browser that joins); null if unknown. */
182
+ attachmentLimitsFrame() {
183
+ return this.attachmentLimits ? JSON.stringify({ type: 'clawchats', event: 'attachment-limits', limits: this.attachmentLimits }) : null;
184
+ }
185
+
148
186
  /** A frame from a browser: the lens may rewrite it or answer it itself. */
149
187
  forwardFromBrowser(data) {
150
188
  const out = this.lens ? this.lens.outbound(data) : data;
@@ -196,6 +234,8 @@ export class GatewayClient {
196
234
  this.browsersChanged();
197
235
  if (ws.readyState === WS.OPEN) {
198
236
  ws.send(JSON.stringify({ type: 'clawchats', event: 'gateway-status', connected: this.connected }));
237
+ const limits = this.attachmentLimitsFrame();
238
+ if (limits) ws.send(limits);
199
239
  }
200
240
  }
201
241
 
@@ -1,7 +1,10 @@
1
1
  import { test } from 'node:test';
2
+ import fs from 'node:fs';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
2
5
  import assert from 'node:assert/strict';
3
6
  import { WebSocketServer } from 'ws';
4
- import { GatewayClient } from './gateway.js';
7
+ import { GatewayClient, attachmentLimitsOf } from './gateway.js';
5
8
 
6
9
  const logger = { logFrame() {} };
7
10
 
@@ -25,3 +28,59 @@ test('close() shuts the socket and stops reconnecting (plugin reload drain)', as
25
28
  assert.equal(connections, 1);
26
29
  await new Promise(r => wss.close(r));
27
30
  });
31
+
32
+ test('request() keeps the error fields the gateway sends (gatewayCode, retryable, retryAfterMs, details)', async () => {
33
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gw-err-'));
34
+ const wss = new WebSocketServer({ port: 0 });
35
+ wss.on('connection', ws => {
36
+ ws.send(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce: 'n' } }));
37
+ ws.on('message', raw => {
38
+ const m = JSON.parse(raw.toString());
39
+ if (m.method === 'connect') return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: true, payload: { type: 'hello-ok' } }));
40
+ if (m.method === 'chat.send') return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: false, error: { code: 'UNAVAILABLE', message: 'chat.send unavailable during gateway startup', retryable: true, retryAfterMs: 500, details: { reason: 'startup-sidecars', method: 'chat.send' } } }));
41
+ if (m.method === 'config.patch') return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: false, error: { code: 'UNAVAILABLE', message: 'config.patch persisted but was not applied', details: { persistedConfig: { hash: 'h2' } } } }));
42
+ if (m.method === 'sessions.subscribe') return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: true, payload: {} }));
43
+ ws.send(JSON.stringify({ type: 'res', id: m.id, ok: false, error: { message: 'plain failure' } })); // 9.7 style: code optional
44
+ });
45
+ });
46
+ await new Promise(r => wss.once('listening', r));
47
+ const gw = new GatewayClient({ dataDir: dir, debugLogger: logger, gatewayWsUrl: `ws://127.0.0.1:${wss.address().port}`, authToken: '' });
48
+ gw.connect();
49
+ for (let i = 0; i < 50 && !gw.connected; i++) await new Promise(r => setTimeout(r, 20));
50
+ assert.ok(gw.connected);
51
+
52
+ const startup = await gw.request('chat.send', {}).catch(e => e);
53
+ assert.equal(startup.message, 'chat.send unavailable during gateway startup');
54
+ assert.equal(startup.gatewayCode, 'UNAVAILABLE');
55
+ assert.equal(startup.retryable, true);
56
+ assert.equal(startup.retryAfterMs, 500);
57
+ assert.equal(startup.details.reason, 'startup-sidecars');
58
+ assert.equal(startup.code, undefined); // `code` stays the peer protocol's
59
+
60
+ const persisted = await gw.request('config.patch', {}).catch(e => e);
61
+ assert.equal(persisted.details.persistedConfig.hash, 'h2');
62
+ assert.equal(persisted.retryable, undefined);
63
+
64
+ const plain = await gw.request('x', {}).catch(e => e);
65
+ assert.equal(plain.message, 'plain failure');
66
+ assert.equal(plain.gatewayCode, undefined);
67
+
68
+ gw.close();
69
+ await new Promise(r => wss.close(r));
70
+ fs.rmSync(dir, { recursive: true, force: true });
71
+ });
72
+
73
+ test('attachment limits come from hello-ok policy (2026.11+); older gateways name none', () => {
74
+ const hello = { type: 'hello-ok', policy: { maxPayload: 25 * 1024 * 1024, attachments: { maxBytes: 20 * 1024 * 1024, maxImageBytes: 6 * 1024 * 1024 } } };
75
+ assert.deepEqual(attachmentLimitsOf(hello), { maxBytes: 20971520, maxImageBytes: 6291456, maxBatchBytes: Math.floor(((25 * 1024 * 1024 - 256 * 1024) * 3) / 4) });
76
+ assert.equal(attachmentLimitsOf({ type: 'hello-ok' }), null);
77
+ assert.equal(attachmentLimitsOf({ type: 'hello-ok', policy: { maxPayload: 1 } }), null);
78
+ });
79
+
80
+ test('browsers hear the attachment limits once the gateway named them', () => {
81
+ const gw = new GatewayClient({ dataDir: '/tmp', debugLogger: logger, gatewayWsUrl: 'ws://127.0.0.1:1', authToken: '' });
82
+ assert.equal(gw.attachmentLimitsFrame(), null);
83
+ gw.attachmentLimits = { maxBytes: 10, maxImageBytes: 5 };
84
+ assert.deepEqual(JSON.parse(gw.attachmentLimitsFrame()), { type: 'clawchats', event: 'attachment-limits', limits: { maxBytes: 10, maxImageBytes: 5 } });
85
+ gw.close();
86
+ });
@@ -13,6 +13,7 @@ import { DatabaseSync } from 'node:sqlite';
13
13
  import { WebSocket } from 'ws';
14
14
  import { loadOrCreateDeviceIdentity, buildDeviceAuth } from './bootstrap/identity.js';
15
15
  import { parseSessionKey } from './util/helpers.js';
16
+ import { SCOPES } from './gateway.js';
16
17
 
17
18
  const PLACEHOLDER_TITLES = new Set(['New chat', '']);
18
19
 
@@ -38,7 +39,10 @@ export async function withGateway({ url, token, identityPath }, fn) {
38
39
  let msg; try { msg = JSON.parse(data.toString()); } catch { return; }
39
40
  if (msg.type === 'event' && msg.event === 'connect.challenge') {
40
41
  const identity = loadOrCreateDeviceIdentity(identityPath);
41
- const scopes = ['operator.read'];
42
+ // The connector's own scopes (it's the same paired device). operator.read alone lists every session on a default
43
+ // gateway, but from 2026.11.5 a gateway with `gateway.roles` set shows a non-admin client none: the export would
44
+ // then take every chat for missing and write duplicates.
45
+ const scopes = SCOPES;
42
46
  const device = buildDeviceAuth(identity, { clientId: 'gateway-client', clientMode: 'backend', role: 'operator', scopes, token, nonce: msg.payload?.nonce || '' });
43
47
  ws.send(JSON.stringify({ type: 'req', id: 'connect', method: 'connect', params: { minProtocol: 3, maxProtocol: 4, client: { id: 'gateway-client', version: '0.1.0', platform: 'node', mode: 'backend' }, role: 'operator', scopes, device, auth: { token } } }));
44
48
  return;
@@ -0,0 +1,63 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import fs from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { DatabaseSync } from 'node:sqlite';
7
+ import { WebSocketServer } from 'ws';
8
+ import { exportHistory } from './history-export.js';
9
+
10
+ const KEY = 'sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789';
11
+
12
+ async function fixture() {
13
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hist-export-'));
14
+ const dataDir = path.join(dir, 'data'), stateDir = path.join(dir, 'state');
15
+ fs.mkdirSync(dataDir); fs.mkdirSync(stateDir);
16
+ fs.writeFileSync(path.join(dataDir, 'workspaces.json'), JSON.stringify({ workspaces: { p: { name: 'proj', label: 'Proj', order: 1 } } }));
17
+ const db = new DatabaseSync(path.join(dataDir, 'proj.db'));
18
+ db.exec('CREATE TABLE threads (id TEXT PRIMARY KEY, title TEXT, session_key TEXT); CREATE TABLE messages (thread_id TEXT, role TEXT, content TEXT, timestamp INTEGER)');
19
+ db.prepare('INSERT INTO threads VALUES (?, ?, ?)').run('t1', 'Env check', 'agent:main:proj:chat:t1');
20
+ db.prepare('INSERT INTO threads VALUES (?, ?, ?)').run('t2', 'Already there', 'agent:main:proj:chat:t2');
21
+ const msg = db.prepare('INSERT INTO messages VALUES (?, ?, ?, ?)');
22
+ msg.run('t1', 'user', 'what is in the .env?', 1000);
23
+ msg.run('t1', 'assistant', `It has ANTHROPIC_API_KEY=${KEY} and PORT=3000. The password policy is documented.`, 2000);
24
+ msg.run('t2', 'user', 'hi', 1000);
25
+ db.close();
26
+ let connect = null;
27
+ const wss = new WebSocketServer({ port: 0 });
28
+ wss.on('connection', ws => {
29
+ ws.send(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce: 'n' } }));
30
+ ws.on('message', raw => {
31
+ const m = JSON.parse(raw.toString());
32
+ if (m.method === 'connect') { connect = m.params; return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: true, payload: { type: 'hello-ok' } })); }
33
+ if (m.method === 'sessions.list') return ws.send(JSON.stringify({ type: 'res', id: m.id, ok: true, payload: { sessions: [{ key: 'agent:main:proj:chat:t2' }], hasMore: false, nextOffset: null } }));
34
+ ws.send(JSON.stringify({ type: 'res', id: m.id, ok: false, error: { message: 'unexpected' } }));
35
+ });
36
+ });
37
+ await new Promise(r => wss.once('listening', r));
38
+ const run = (opts = {}) => exportHistory({ dataDir, stateDir, gatewayUrl: `ws://127.0.0.1:${wss.address().port}`, token: 't', print: () => {}, ...opts });
39
+ const cleanup = async () => { await new Promise(r => wss.close(r)); fs.rmSync(dir, { recursive: true, force: true }); };
40
+ return { run, cleanup, stateDir, connectParams: () => connect };
41
+ }
42
+
43
+ test('export-history copies the text as it was (the user\'s own history, same machine); check mode writes nothing', async () => {
44
+ const f = await fixture();
45
+ try {
46
+ const checked = await f.run({ check: true });
47
+ assert.deepEqual([checked.exported, checked.written], [1, []]);
48
+ assert.equal(fs.existsSync(path.join(f.stateDir, 'agents')), false);
49
+ const res = await f.run();
50
+ assert.equal(res.exported, 1);
51
+ const dir = path.join(f.stateDir, 'agents', 'main', 'sessions');
52
+ assert.ok(fs.readFileSync(path.join(dir, fs.readdirSync(dir).find(n => n.endsWith('.jsonl'))), 'utf8').includes(KEY));
53
+ } finally { await f.cleanup(); }
54
+ });
55
+
56
+ test('export-history connects with the connector\'s own scopes, so a gateway with roles still lists every session', async () => {
57
+ const f = await fixture();
58
+ try {
59
+ await f.run({ check: true });
60
+ const p = f.connectParams();
61
+ assert.ok(p.scopes.includes('operator.read') && p.scopes.includes('operator.admin'));
62
+ } finally { await f.cleanup(); }
63
+ });
package/server/index.js CHANGED
@@ -8,6 +8,7 @@ import { Database } from './bootstrap/native.js';
8
8
  import { GATEWAY_WS_URL, AUTH_TOKEN, discoverWorkspaceDir } from './config.js';
9
9
  import { DebugLogger } from './debug.js';
10
10
  import { GatewayClient } from './gateway.js';
11
+ import { withGatewayRetry } from './util/gateway-retry.js';
11
12
  import { handleServeFile, handleWorkspaceList, handleWorkspaceFileRead, handleWorkspaceFileWrite, handleWorkspaceFileDelete, handleWorkspaceUpload, handleWorkspaceCreate, handleWorkspaceMove, handleWorkspaceCopy } from './controllers/filesystem.js';
12
13
  import { handleTranscribe } from './controllers/transcribe.js';
13
14
  import { createGatewayMediaHandler } from './controllers/gateway-media.js';
@@ -79,7 +80,9 @@ export function createApp(config = {}) {
79
80
  const extras = createExtrasStore(() => globalDbCache.get());
80
81
  try { const n = extras.seedFromWorkspaces(getWorkspaces()); if (n) console.log(`[extras] seeded ${n} project style(s) from workspaces.json`); }
81
82
  catch (e) { console.error('[extras] style seed failed:', e.message); }
82
- const gwRequest = (m, p, t) => gatewayClient.request(m, p, t);
83
+ // The connector's own requests wait out a gateway that is still starting (2026.11.4+ refuses writes with a retryable
84
+ // UNAVAILABLE; util/gateway-retry.js). Frames a browser relays don't pass here: the frontend retries those.
85
+ const gwRequest = withGatewayRetry((m, p, t) => gatewayClient.request(m, p, t));
83
86
  // Gateway sharing (server/peer/): other people's agents in team chats, and ours in theirs. The
84
87
  // plugin host (src/index.ts) supplies the signal server link and the peer transport (config.peer).
85
88
  const peerKey = loadOrCreatePeerKey(DATA_DIR);
@@ -55,17 +55,50 @@ export function hasGuestRestrictions(tools) {
55
55
  export async function ensureGuestRestrictions(request, agentId) {
56
56
  const cfg = await request('config.get', {});
57
57
  if (hasGuestRestrictions(cfg?.parsed?.agents?.entries?.[agentId]?.tools)) return false;
58
- await request('config.patch', {
59
- raw: JSON.stringify({ agents: { entries: { [agentId]: { tools: GUEST_TOOLS } } } }),
60
- ...(cfg?.hash ? { baseHash: cfg.hash } : {}),
61
- // The gateway only lets a patch shrink an array named exactly (a parent path doesn't count),
62
- // e.g. dropping view_image/pdf from an older guest's alsoAllow.
63
- replacePaths: ['', '.alsoAllow', '.deny'].map(p => `agents.entries.${agentId}.tools${p}`),
64
- note: `ClawChats sharing: guest restrictions for ${agentId}`,
65
- }, 60_000);
58
+ try {
59
+ await request('config.patch', {
60
+ raw: JSON.stringify({ agents: { entries: { [agentId]: { tools: GUEST_TOOLS } } } }),
61
+ ...(cfg?.hash ? { baseHash: cfg.hash } : {}),
62
+ // The gateway only lets a patch shrink an array named exactly (a parent path doesn't count),
63
+ // e.g. dropping view_image/pdf from an older guest's alsoAllow.
64
+ replacePaths: ['', '.alsoAllow', '.deny'].map(p => `agents.entries.${agentId}.tools${p}`),
65
+ note: `ClawChats sharing: guest restrictions for ${agentId}`,
66
+ }, 60_000);
67
+ } catch (e) {
68
+ if (!persistedButNotApplied(e, agentId)) throw e;
69
+ // 2026.11.4+: the patch was saved but the running gateway didn't apply it yet (a plugin deferred the reload, or a
70
+ // restart is pending). Sharing it now is fine once it applies: until then the turn check (restrictionsPending)
71
+ // keeps the guest from being served on the old tool policy.
72
+ unappliedGuests.add(agentId);
73
+ }
74
+ return true;
75
+ }
76
+
77
+ /** Guests whose restrictions were saved but not yet applied by the running gateway (see ensureGuestRestrictions). */
78
+ export const unappliedGuests = new Set();
79
+
80
+ /**
81
+ * Whether a guest's saved restrictions still aren't the running gateway's. Only for a guest ensureGuestRestrictions
82
+ * had to leave unapplied: config.get's configRevisionHash (saved) differs from appliedConfigHash (running) until the
83
+ * reload lands (the check the gateway's own CLI uses). Missing hashes (older gateways) count as applied.
84
+ */
85
+ export function restrictionsPending(cfg, agentId) {
86
+ if (!unappliedGuests.has(agentId)) return false;
87
+ const saved = cfg?.configRevisionHash, applied = cfg?.appliedConfigHash;
88
+ if (typeof saved !== 'string' || typeof applied !== 'string' || saved === applied) { unappliedGuests.delete(agentId); return false; }
66
89
  return true;
67
90
  }
68
91
 
92
+ /**
93
+ * Whether a failed config.patch had saved its change anyway (2026.11.4+: UNAVAILABLE with details.persistedConfig).
94
+ * When the error carries the saved config (not on every path), it must show this guest's restrictions.
95
+ */
96
+ export function persistedButNotApplied(e, agentId) {
97
+ const saved = e?.gatewayCode === 'UNAVAILABLE' && e.details?.persistedConfig;
98
+ if (!saved || typeof saved !== 'object') return false;
99
+ return saved.config === undefined || hasGuestRestrictions(saved.config?.agents?.entries?.[agentId]?.tools);
100
+ }
101
+
69
102
  /** A new agent is only usable once the gateway's config reload picked it up. */
70
103
  async function waitForAgent(request, agentId, { tries = 120, ms = 250 } = {}) {
71
104
  for (let i = 0; i < tries; i++) {
@@ -1,6 +1,6 @@
1
1
  import { test } from 'node:test';
2
2
  import assert from 'node:assert/strict';
3
- import { createGuestAgent, GUEST_TOOLS, GUEST_TOOLS_DENY, hasGuestRestrictions } from './guest-agent.js';
3
+ import { createGuestAgent, ensureGuestRestrictions, restrictionsPending, unappliedGuests, GUEST_TOOLS, GUEST_TOOLS_DENY, hasGuestRestrictions } from './guest-agent.js';
4
4
 
5
5
  function fakeGateway() {
6
6
  const agents = [{ id: 'jarvis', identity: { name: 'Jarvis', emoji: '🤖' }, model: { primary: 'anthropic/claude-x' }, workspace: '/home/k/.openclaw/workspace' }];
@@ -102,3 +102,52 @@ test('a guest the gateway shows under the original\'s name is still found (and h
102
102
  assert.equal(findGuestAgent([agents[0], agents[2]], 'capy', new Set(['capy-guest-2']))?.id, 'capy-guest-2');
103
103
  assert.ok(isGuestAgent(agents[1], new Set(['capy-guest'])) && !isGuestAgent(agents[0], new Set(['capy-guest'])));
104
104
  });
105
+
106
+ /** What a 2026.11.4+ gateway answers when config.patch saved the change but the running gateway didn't apply it. */
107
+ const persistedError = (config, extra = {}) => Object.assign(new Error('config.patch persisted but was not applied to the active Gateway (plugin-reload-deferred)'), {
108
+ gatewayCode: 'UNAVAILABLE', details: { persistedConfig: { hash: 'h2', ...(config ? { config } : {}) } }, ...extra,
109
+ });
110
+
111
+ test('config.get -> config.patch round trip: baseHash from config.get, exact-path replacePaths (as the 11.6 handler requires)', async () => {
112
+ const calls = [];
113
+ await ensureGuestRestrictions(async (m, p) => {
114
+ calls.push([m, p]);
115
+ return m === 'config.get' ? { hash: 'abc', parsed: { agents: { entries: { g: { tools: { profile: 'full' } } } } } } : { ok: true };
116
+ }, 'g');
117
+ assert.equal(calls[1][1].baseHash, 'abc');
118
+ assert.deepEqual(calls[1][1].replacePaths, ['agents.entries.g.tools', 'agents.entries.g.tools.alsoAllow', 'agents.entries.g.tools.deny']);
119
+ assert.deepEqual(JSON.parse(calls[1][1].raw), { agents: { entries: { g: { tools: GUEST_TOOLS } } } });
120
+ // Without a hash (a gateway that doesn't send one) the patch still goes out, hash-free.
121
+ const noHash = [];
122
+ await ensureGuestRestrictions(async (m, p) => { noHash.push([m, p]); return m === 'config.get' ? { parsed: {} } : { ok: true }; }, 'g');
123
+ assert.equal('baseHash' in noHash[1][1], false);
124
+ });
125
+
126
+ test('a config.patch that persisted but was not applied counts as written; the guest is not served until it applies', async () => {
127
+ unappliedGuests.clear();
128
+ const patched = async config => ensureGuestRestrictions(async m => {
129
+ if (m === 'config.get') return { hash: 'h1', parsed: {} };
130
+ throw persistedError(config);
131
+ }, 'g1');
132
+ // The saved config the error carries shows the restrictions (or isn't included): accepted.
133
+ assert.equal(await patched({ agents: { entries: { g1: { tools: GUEST_TOOLS } } } }), true);
134
+ assert.equal(await patched(undefined), true);
135
+ // Until the running config catches up, the turn check says "pending"; afterwards it clears.
136
+ assert.equal(restrictionsPending({ configRevisionHash: 'saved', appliedConfigHash: 'older' }, 'g1'), true);
137
+ assert.equal(restrictionsPending({ configRevisionHash: 'saved', appliedConfigHash: 'saved' }, 'g1'), false);
138
+ assert.equal(restrictionsPending({ configRevisionHash: 'saved', appliedConfigHash: 'older' }, 'g1'), false); // forgotten once applied
139
+ // A guest that never failed to apply isn't gated, and neither is a gateway without the hashes (9.7).
140
+ assert.equal(restrictionsPending({ configRevisionHash: 'a', appliedConfigHash: 'b' }, 'other'), false);
141
+ await patched(undefined);
142
+ assert.equal(restrictionsPending({ hash: 'x' }, 'g1'), false);
143
+ });
144
+
145
+ test('a failed config.patch is still a failure unless it saved this guest\'s restrictions', async () => {
146
+ const run = error => ensureGuestRestrictions(async m => { if (m === 'config.get') return { hash: 'h', parsed: {} }; throw error; }, 'g2');
147
+ await assert.rejects(run(new Error('config base hash required')), /base hash/);
148
+ await assert.rejects(run(Object.assign(new Error('x'), { gatewayCode: 'INVALID_REQUEST', details: { persistedConfig: {} } })), /x/);
149
+ await assert.rejects(run(Object.assign(new Error('busy'), { gatewayCode: 'UNAVAILABLE' })), /busy/); // nothing was saved
150
+ // The saved config shows the agent without the restrictions: not what we wrote.
151
+ await assert.rejects(run(persistedError({ agents: { entries: { g2: { tools: { profile: 'full' } } } } })), /persisted/);
152
+ await assert.rejects(run(persistedError({ agents: { entries: {} } })), /persisted/);
153
+ });
@@ -16,9 +16,12 @@
16
16
  import crypto from 'node:crypto';
17
17
  import { PeerLink } from './link.js';
18
18
  import { canonicalJson, verifySignature, fingerprint } from './keys.js';
19
- import { hasGuestRestrictions, ensureGuestRestrictions, findGuestAgent, isGuestAgent } from './guest-agent.js';
19
+ import { redactSecrets } from '../util/redact.js';
20
+ import { hasGuestRestrictions, ensureGuestRestrictions, findGuestAgent, isGuestAgent, restrictionsPending } from './guest-agent.js';
20
21
 
21
22
  const TURN_TIMEOUT_MS = 10 * 60_000;
23
+ /** The gateway's "the run gave no visible reply" failure (2026.10.1+: a passed turn, see team.js PASS_TOKEN). */
24
+ export const EMPTY_REPLY_ERROR = /empty response|did not produce a visible reply/i;
22
25
  const DEFAULT_DAILY_CAP = 50;
23
26
  const MAX_CONCURRENT_TURNS = 2; // per share: the daily cap alone would allow 50 parallel 10-minute runs
24
27
  const ACCESS_MODES = { restricted: 'read-only', trusted: 'guarded' };
@@ -594,12 +597,18 @@ export class SharingManager {
594
597
  this._db().prepare('INSERT INTO peer_usage (share_id, day, turns) VALUES (?, ?, 1) ON CONFLICT(share_id, day) DO UPDATE SET turns = turns + 1').run(shareId, today());
595
598
  this._changed(); // the owner's Sharing view shows today's count
596
599
  try {
597
- const r = await this._runGuestTurn(shareId, grant, agent, roomId, p, emit, this._turns.get(turnKey));
600
+ // Everything the guest's agent says leaves this gateway (to the other person, or into a room they see). The
601
+ // gateway stopped masking secrets in tool output in 2026.10.10, so a credential an agent read can come out in
602
+ // its reply: redact it here (util/redact.js), in the streamed text, the final one and a failed turn's partial.
603
+ const safeEmit = emit && ((event, data) => emit(event, event === 'delta' ? redactSecrets(data) : data));
604
+ const r = await this._runGuestTurn(shareId, grant, agent, roomId, p, safeEmit, this._turns.get(turnKey));
605
+ if (typeof r?.text === 'string') r.text = redactSecrets(r.text);
598
606
  // What this gateway's agent said for that gateway's room: its copy of the room may show it as ours (team.js).
599
607
  if (!p.inOwnerRoom && r?.text) try { this.onGuestReply?.(grant.requesterGatewayId, roomId, shareId, agent.id, r.text); } catch { /* best effort */ }
600
608
  return r;
601
609
  }
602
610
  catch (e) {
611
+ if (typeof e?.partial === 'string') e.partial = redactSecrets(e.partial);
603
612
  // A reply that failed without saying anything doesn't use up the day's replies. A timeout still
604
613
  // counts: it ran for the full turn timeout.
605
614
  if (!e.partial && !/timed out/i.test(e.message)) {
@@ -615,7 +624,7 @@ export class SharingManager {
615
624
  const cfg = await this.request('config.get', {}, 30_000);
616
625
  // A guest version whose restrictions were edited away (e.g. in the Control UI) isn't served.
617
626
  const isGuest = this._db().prepare('SELECT 1 FROM peer_guest_agents WHERE agent_id = ?').get(agent.id);
618
- if (isGuest && !hasGuestRestrictions(cfg?.parsed?.agents?.entries?.[agent.id]?.tools)) {
627
+ if (isGuest && (!hasGuestRestrictions(cfg?.parsed?.agents?.entries?.[agent.id]?.tools) || restrictionsPending(cfg, agent.id))) {
619
628
  this.log.warn?.(`[sharing] ${agent.id} lost its guest restrictions: refusing turn for ${shareId}`);
620
629
  throw Object.assign(new Error(`${agent.name} isn't available right now`), { code: 'unavailable' });
621
630
  }
@@ -647,6 +656,9 @@ export class SharingManager {
647
656
  const r = await done;
648
657
  if (r.state === 'final') return { state: 'final', text: r.message ? messageText(r.message) : await this._lastReply(sessionKey) };
649
658
  if (r.state === 'aborted') return { state: 'aborted', text: r.text || '' };
659
+ // A host on an older connector still asks for NO_REPLY: on 2026.10.1+ that ends the run with an empty-reply
660
+ // error and no final. Report it as an empty reply; the host treats that as a pass.
661
+ if (!r.text && EMPTY_REPLY_ERROR.test(r.errorMessage || '')) return { state: 'final', text: '' };
650
662
  throw Object.assign(new Error(r.errorMessage || 'The agent run failed'), { code: 'run_failed', partial: r.text || '' });
651
663
  } finally {
652
664
  const run = this._runs.get(runId);
@@ -6,7 +6,7 @@ import path from 'node:path';
6
6
  import { Database } from '../bootstrap/native.js';
7
7
  import { SharingManager, defangLocalPaths } from './sharing.js';
8
8
  import { loadOrCreatePeerKey, fingerprint } from './keys.js';
9
- import { GUEST_TOOLS } from './guest-agent.js';
9
+ import { GUEST_TOOLS, unappliedGuests } from './guest-agent.js';
10
10
 
11
11
  const quiet = { warn() {}, info() {} };
12
12
  const keyIn = () => loadOrCreatePeerKey(fs.mkdtempSync(path.join(os.tmpdir(), 'pk-')));
@@ -22,7 +22,7 @@ function pair() {
22
22
  }
23
23
 
24
24
  /** Owner (Kamil, gateway gwK) shares with requester (Houman, gateway gwH). */
25
- function setup({ reply = p => `jarvis says: ${p.message.split('\n\n').pop()}`, config = {} } = {}) {
25
+ function setup({ reply = p => `jarvis says: ${p.message.split('\n\n').pop()}`, config = {}, cfgExtra = {} } = {}) {
26
26
  const kOwner = keyIn(), kReq = keyIn();
27
27
  const ownerCalls = [], ownerSignals = [], reqSignals = [];
28
28
  let owner;
@@ -37,7 +37,7 @@ function setup({ reply = p => `jarvis says: ${p.message.split('\n\n').pop()}`, c
37
37
  });
38
38
  return { runId: params.idempotencyKey, status: 'started' };
39
39
  }
40
- if (method === 'config.get') return { hash: 'h', parsed: config };
40
+ if (method === 'config.get') return { hash: 'h', parsed: config, ...cfgExtra };
41
41
  if (method === 'chat.abort') { setImmediate(() => owner.onGatewayEvent({ event: 'chat', payload: { runId: params.runId, state: 'aborted' } })); return { ok: true }; }
42
42
  return { ok: true };
43
43
  };
@@ -340,6 +340,42 @@ test('a guest agent whose restrictions were removed is not served', async () =>
340
340
  assert.equal(s.ownerCalls.filter(c => c.method === 'chat.send').length, 1);
341
341
  });
342
342
 
343
+ test('a guest whose saved restrictions the running gateway has not applied yet is not served until it has', async () => {
344
+ const config = { agents: { entries: { 'jarvis-guest': { tools: GUEST_TOOLS } } } };
345
+ const cfgExtra = { configRevisionHash: 'saved', appliedConfigHash: 'older' };
346
+ const s = setup({ config, cfgExtra });
347
+ s.owner.markGuestAgent('jarvis-guest');
348
+ s.owner.approve('sh1', { agents: [{ id: 'jarvis-guest', name: 'Jarvis' }] });
349
+ s.activate();
350
+ unappliedGuests.add('jarvis-guest'); // ensureGuestRestrictions saw "persisted but not applied" (2026.11.4+)
351
+ await assert.rejects(s.req.turn('peer:sh1:jarvis-guest', { turnId: 't1', roomId: 'r', message: 'hi' }), e => e.code === 'unavailable');
352
+ assert.equal(s.ownerCalls.filter(c => c.method === 'chat.send').length, 0);
353
+ cfgExtra.appliedConfigHash = 'saved'; // the reload landed
354
+ await s.req.turn('peer:sh1:jarvis-guest', { turnId: 't2', roomId: 'r', message: 'hi' });
355
+ assert.equal(s.ownerCalls.filter(c => c.method === 'chat.send').length, 1);
356
+ });
357
+
358
+ test('credentials in what a guest agent says are redacted: streamed text, the final reply, and the copy kept for the room', async () => {
359
+ const key = 'sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789';
360
+ const s = setup({ reply: () => `Found it: ANTHROPIC_API_KEY=${key} and the host is db.internal` });
361
+ s.owner.approve('sh1', { agents: [{ id: 'jarvis-guest', name: 'Jarvis' }], access: 'restricted', dailyCap: 5 });
362
+ s.activate();
363
+ const seen = [];
364
+ s.owner.onGuestReply = (...args) => seen.push(args.at(-1));
365
+ const deltas = [];
366
+ // Stream a leaked key as well: the first delta carries the text so far.
367
+ const request = s.owner.request;
368
+ s.owner.request = async (method, params) => {
369
+ if (method === 'chat.send') s.owner.onGatewayEvent({ event: 'chat', payload: { runId: params.idempotencyKey, state: 'delta', message: { content: [{ type: 'text', text: 'token ghp_abcdefghijklmnopqrstuvwxyz0123' }] } } });
370
+ return request(method, params);
371
+ };
372
+ const r = await s.req.turn('peer:sh1:jarvis-guest', { turnId: 't1', roomId: 'room1', roomTitle: 'Rivers', message: 'read the env' }, { onDelta: d => deltas.push(d) });
373
+ assert.equal(r.text, 'Found it: ANTHROPIC_API_KEY=[REDACTED] and the host is db.internal');
374
+ assert.ok(!JSON.stringify(deltas).includes('ghp_') && !JSON.stringify(deltas).includes(key));
375
+ assert.ok(deltas.some(d => d.includes('[REDACTED]')));
376
+ assert.deepEqual(seen, [r.text]); // onGuestReply (the requester's copy of the room) got the redacted text too
377
+ });
378
+
343
379
  test('on connect, guests made earlier get the current restrictions; up-to-date and deleted ones are left alone', async () => {
344
380
  const old = { profile: 'minimal', alsoAllow: ['group:fs', 'group:runtime', 'view_image', 'pdf'], deny: ['message'] };
345
381
  const entries = { 'old-guest': { tools: old }, 'ok-guest': { tools: GUEST_TOOLS } };
@@ -40,6 +40,8 @@ export const ROW_FIELDS = new Set([
40
40
  'model', 'modelProvider', 'thinkingLevel', 'contextTokens', 'totalTokens', 'totalTokensFresh',
41
41
  'inputTokens', 'outputTokens', 'permissionMode', 'workspaceDir', 'contextBudgetStatus', 'fastMode', 'effectiveFastMode',
42
42
  'startedAt', 'runtimeMs', 'ccParentKey',
43
+ // Subagents panel: a run waiting on its own runs, and the run's live headline.
44
+ 'hasActiveSubagentRun', 'observerDigest',
43
45
  ]);
44
46
 
45
47
  // `sessions.changed` envelope fields (snapshot fields are spread next to these).
@@ -147,6 +147,24 @@ test('trimRow keeps only allow-listed fields', () => {
147
147
  assert.deepEqual(trimRow({ key: 'k', unread: true, participants: [], thinkingOptions: [] }), { key: 'k', unread: true });
148
148
  });
149
149
 
150
+ test('trimRow keeps the Subagents panel fields (waiting on own runs, live headline)', () => {
151
+ const digest = { runId: 'r1', headline: 'Reading files', revision: 3 };
152
+ assert.deepEqual(trimRow({ key: 'k', hasActiveSubagentRun: true, observerDigest: digest, spawnDepth: 1 }),
153
+ { key: 'k', hasActiveSubagentRun: true, observerDigest: digest });
154
+ });
155
+
156
+ test('a hidden run under a chat reaches the browser with its panel fields and parent', () => {
157
+ const { l } = lens();
158
+ l.observe(CHAT, { key: CHAT, kind: 'direct' });
159
+ const run = 'agent:main:subagent:w1';
160
+ const out = l.sessionsChanged({ sessionKey: run, reason: 'patch', session: { key: run, kind: 'direct', spawnedBy: CHAT,
161
+ status: 'running', hasActiveRun: true, activeRunIds: ['r1'], hasActiveSubagentRun: true, observerDigest: { runId: 'r1', headline: 'Grep' }, startedAt: 5 } });
162
+ assert.equal(out.payload.session.ccParentKey, CHAT);
163
+ assert.equal(out.payload.session.hasActiveSubagentRun, true);
164
+ assert.deepEqual(out.payload.session.observerDigest, { runId: 'r1', headline: 'Grep' });
165
+ assert.equal(out.payload.session.startedAt, 5);
166
+ });
167
+
150
168
  test('chat.history passes through untouched (gateway enforces maxBytes)', () => {
151
169
  const { l } = lens();
152
170
  const f = JSON.stringify({ type: 'req', id: 'h', method: 'chat.history', params: { sessionKey: CHAT, limit: 80, maxBytes: 262144 } });
package/server/team.js CHANGED
@@ -9,14 +9,19 @@
9
9
  //
10
10
  // Routing follows the gateway's broadcast group threads (docs/channels/broadcast-groups.md):
11
11
  // @mentioned agents answer; with no mention every agent gets the message but is told to answer
12
- // NO_REPLY unless it's for them (ClawChats choice); `@all` makes everyone answer. Follow-up rounds
12
+ // PASS_TOKEN unless it's for them (ClawChats choice); `@all` makes everyone answer. Follow-up rounds
13
13
  // (the room's "discuss" toggle) go to agents that replied or were named, with the siblings'
14
14
  // replies, until everyone passes or the round/turn caps are hit. Round state is in memory only.
15
15
 
16
16
  import crypto from 'node:crypto';
17
- import { defangLocalPaths } from './peer/sharing.js';
18
-
19
- export const SILENT = /^\s*NO_REPLY\s*$/i;
17
+ import { defangLocalPaths, EMPTY_REPLY_ERROR } from './peer/sharing.js';
18
+
19
+ // An agent passes with our own token, a visible reply to the gateway. Not NO_REPLY: since 2026.10.1 a user-triggered
20
+ // turn must produce a reply, so NO_REPLY ends a claude-cli run with "CLI backend returned an empty response." (no
21
+ // final) and makes an API-model run re-prompt "NO_REPLY is not allowed", which posts filler. NO_REPLY still counts
22
+ // (older prompts, peers on older connectors).
23
+ export const PASS_TOKEN = 'NOTHING_TO_ADD';
24
+ export const SILENT = /^\s*[`*]*(?:NOTHING_TO_ADD|NO_REPLY)[`*.]*\s*$/i;
20
25
  /** Room entry for an agent asked directly whose run was stopped before it said anything. */
21
26
  const STOPPED_EARLY = '*[stopped before replying]*';
22
27
  // Sessions ("lanes") an agent can answer a room from (team-store team_entries.via / team_lanes):
@@ -688,6 +693,9 @@ export class TeamCoordinator {
688
693
  let result;
689
694
  try {
690
695
  await this.request('chat.send', { sessionKey: workKey, message, deliver: false, idempotencyKey: runId }, 30_000);
696
+ // Stop pressed while the send was on its way (or being retried while the gateway starts): its abort reached the
697
+ // gateway before the run existed and was a no-op (an unknown runId aborts nothing), so the run is stopped now.
698
+ if (stopped()) this.request('chat.abort', { sessionKey: workKey, runId }).catch(e => this.log.warn?.(`[team] abort: ${e.message}`));
691
699
  this._setSeen(roomKey, agentId, OWNER_LANE, fresh);
692
700
  result = await done;
693
701
  } finally {
@@ -709,6 +717,7 @@ export class TeamCoordinator {
709
717
  else this._recoverAfterAbort(roomKey, self, workKey, { marker: mode === 'addressed' });
710
718
  return { agentId, text: null };
711
719
  }
720
+ if (mode !== 'addressed' && !partial && EMPTY_REPLY_ERROR.test(result.errorMessage || '')) return { agentId, text: null }; // it passed
712
721
  throw Object.assign(new Error(result.errorMessage || 'run failed'), { partial });
713
722
  }
714
723
  const text = clean(result.message ? messageText(result.message) : await this._lastReply(workKey));
@@ -888,8 +897,8 @@ export class TeamCoordinator {
888
897
  const untrusted = owner && fresh.some(e => e.remote || e.person || e.forOther);
889
898
  const instruction = {
890
899
  addressed: 'The latest message is addressed to you. Reply to the team chat.',
891
- open: 'The latest message is not addressed to anyone in particular. Reply only if it is clearly meant for you or you have something distinct to add; otherwise reply with exactly NO_REPLY.',
892
- followup: 'Other participants just replied (above). Reply only if you have something new to add or were asked something; otherwise reply with exactly NO_REPLY. Do not just agree or repeat what was said.',
900
+ open: `The latest message is not addressed to anyone in particular. Reply only if it is clearly meant for you or you have something distinct to add; otherwise reply with exactly ${PASS_TOKEN} and nothing else.`,
901
+ followup: `Other participants just replied (above). Reply only if you have something new to add or were asked something; otherwise reply with exactly ${PASS_TOKEN} and nothing else. Do not just agree or repeat what was said.`,
893
902
  }[mode];
894
903
  return [
895
904
  `[Team chat] You are ${self.name}. Other agents here: ${others.join(', ') || 'none'}. Your reply is posted to the team chat as ${self.name}; address someone with @name.`,
@@ -8,7 +8,7 @@ import { SessionLens } from './session-lens.js';
8
8
  const AGENTS = [{ id: 'main', identity: {} }, { id: 'dev', identity: { name: 'Dev' } }, { id: 'atlas', identity: { name: 'Atlas' } }];
9
9
 
10
10
  /** Fake gateway. `reply(agentId, prompt)` returns the agent's reply text, null (abort) or a promise. */
11
- function harness(reply, { preparedTitle = 'Team title', titler = null, remote = null, agents = AGENTS } = {}) {
11
+ function harness(reply, { preparedTitle = 'Team title', titler = null, remote = null, agents = AGENTS, beforeSend = null } = {}) {
12
12
  const sessions = new Map(); // key -> [{ role, content, timestamp, __m: { id } }]
13
13
  const calls = [];
14
14
  const labels = new Map(); // session key -> label
@@ -36,13 +36,16 @@ function harness(reply, { preparedTitle = 'Team title', titler = null, remote =
36
36
  }
37
37
  case 'chat.history': return { messages: (sessions.get(params.sessionKey) || []).slice(-(params.limit || 80)) };
38
38
  case 'chat.send': {
39
+ if (beforeSend) await beforeSend(params);
39
40
  sessions.get(params.sessionKey).push({ role: 'user', content: params.message, timestamp: ++clock, __m: { id: `u${++seq}` } });
40
41
  const agentId = /^agent:([^:]+):/.exec(params.sessionKey)[1];
41
42
  const runId = params.idempotencyKey;
42
43
  Promise.resolve(reply(agentId, params.message)).then(text => {
43
- if (text && typeof text === 'object') { // { partial, state }: streamed some text, then aborted/error
44
- team.onGatewayEvent({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'delta', message: { role: 'assistant', content: [{ type: 'text', text: text.partial }] } } });
45
- team.onGatewayEvent({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'delta', deltaText: ' more' } });
44
+ if (text && typeof text === 'object') { // { partial, state }: streamed some text (none without partial), then aborted/error
45
+ if (text.partial) {
46
+ team.onGatewayEvent({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'delta', message: { role: 'assistant', content: [{ type: 'text', text: text.partial }] } } });
47
+ team.onGatewayEvent({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'delta', deltaText: ' more' } });
48
+ }
46
49
  team.onGatewayEvent({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: text.state, errorMessage: text.error } });
47
50
  return;
48
51
  }
@@ -264,6 +267,47 @@ test('stop: a partial reply is posted marked stopped; a reply that finished anyw
264
267
  assert.equal(h.calls.filter(c => c.method === 'chat.send').length, 2); // no follow-up round after Stop
265
268
  });
266
269
 
270
+ test('stop while the send is still going out (gateway starting): the abort that beat the run is repeated once it lands', async () => {
271
+ let release;
272
+ const gate = new Promise(r => { release = r; });
273
+ let finish;
274
+ const h = harness(() => new Promise(resolve => { finish = resolve; }), { beforeSend: () => gate });
275
+ const { roomKey } = await h.team.createRoom({ agentIds: ['dev', 'atlas'] });
276
+ await h.team.send(roomKey, { text: '@dev go', userLabel: 'H' });
277
+ for (let i = 0; i < 20; i++) await new Promise(r => setImmediate(r));
278
+ await h.team.stop(roomKey);
279
+ const aborts = () => h.calls.filter(c => c.method === 'chat.abort');
280
+ assert.equal(aborts().length, 1); // Stop's own: the run doesn't exist yet, so the gateway ignores it
281
+ release();
282
+ for (let i = 0; i < 20; i++) await new Promise(r => setImmediate(r));
283
+ assert.equal(aborts().length, 2);
284
+ assert.deepEqual(aborts()[1].params, aborts()[0].params); // the same run, aborted again
285
+ finish(null);
286
+ await h.settle();
287
+ });
288
+
289
+ test('passing: the prompt asks for our token; token, NO_REPLY and the 10.1+ empty-reply error all stay out of the room', async () => {
290
+ const EMPTY = { state: 'error', error: 'CLI backend returned an empty response.' };
291
+ const prompts = [];
292
+ const h = harness((agent, prompt) => {
293
+ prompts.push(prompt);
294
+ return { dev: 'dev answer', atlas: 'NOTHING_TO_ADD', main: EMPTY, ops: 'NO_REPLY' }[agent];
295
+ }, { agents: [...AGENTS, { id: 'ops', identity: { name: 'Ops' } }] });
296
+ const { roomKey } = await h.team.createRoom({ agentIds: ['dev', 'atlas', 'main', 'ops'] });
297
+ await h.team.send(roomKey, { text: 'anyone?', userLabel: 'H' });
298
+ await h.settle();
299
+ assert.ok(prompts.every(p => /reply with exactly NOTHING_TO_ADD and nothing else/.test(p) && !/NO_REPLY/.test(p)));
300
+ assert.deepEqual(h.room(roomKey), ['[H]\n\nanyone?', '[Dev]\n\ndev answer']);
301
+ });
302
+
303
+ test('an empty-reply error on a turn addressed to the agent is still shown as a failure', async () => {
304
+ const h = harness(agent => agent === 'dev' ? { state: 'error', error: 'CLI backend returned an empty response.' } : 'x');
305
+ const { roomKey } = await h.team.createRoom({ agentIds: ['dev', 'atlas'] });
306
+ await h.team.send(roomKey, { text: '@dev hi', userLabel: 'H' });
307
+ await h.settle();
308
+ assert.match(h.room(roomKey).at(-1), /^\[Dev\]\n\n⚠️ \*Couldn't finish this reply: CLI backend returned an empty response\.\*$/);
309
+ });
310
+
267
311
  test('a failed turn shows in the room with its partial text', async () => {
268
312
  const h = harness(agent => agent === 'dev' ? { partial: 'started', state: 'error', error: 'runtime died' } : 'NO_REPLY');
269
313
  const { roomKey } = await h.team.createRoom({ agentIds: ['dev', 'atlas'] });
@@ -0,0 +1,58 @@
1
+ // Retry for the connector's OWN gateway requests (team chat, sharing, guest agents, the session lens), never for
2
+ // frames a browser relays (the frontend retries those itself).
3
+ //
4
+ // 2026.11.4+ refuses write RPCs (chat.send, sessions.create/patch/send, agent, ...) with a retryable error while the
5
+ // gateway is starting or its agent DB is preparing: { code: 'UNAVAILABLE', retryable: true, retryAfterMs,
6
+ // details: { reason: 'startup-sidecars' } }. chat.send also answers retryable UNAVAILABLE while the same request is
7
+ // being admitted, the transcript rebuilds, or the model catalog races. Older gateways never send these, so the
8
+ // wrapper is a pass-through there. gateway.js request() keeps the error fields (gatewayCode, retryable, ...).
9
+
10
+ const MAX_TOTAL_MS = 60_000; // cap on time spent waiting between attempts
11
+ const MIN_DELAY_MS = 100;
12
+ const MAX_DELAY_MS = 2_000; // same bounds as the gateway's own client
13
+ const DEFAULT_DELAY_MS = 500;
14
+ // Retryable refusals a retry makes worse or cannot fix: the socket drops on a restart anyway; a busy goal needs the user.
15
+ const NEVER_RETRY_REASONS = new Set(['gateway-restarting', 'goal-session-busy']);
16
+
17
+ const wait = ms => new Promise(r => setTimeout(r, ms));
18
+
19
+ /** The refusal that happens before the method does any work (safe to repeat for every method). */
20
+ export function isAdmissionRefusal(e) {
21
+ if (e?.gatewayCode !== 'UNAVAILABLE' || e.retryable !== true) return false;
22
+ return e.details?.reason === 'startup-sidecars' || e.details?.code === 'agent-database-inspection-pending';
23
+ }
24
+
25
+ /** Whether `method` failing with `e` is worth repeating unchanged. */
26
+ export function isRetryableRefusal(method, e) {
27
+ if (e?.gatewayCode !== 'UNAVAILABLE' || e.retryable !== true) return false;
28
+ if (NEVER_RETRY_REASONS.has(e.details?.reason)) return false;
29
+ if (isAdmissionRefusal(e)) return true;
30
+ // chat.send carries an idempotencyKey, so repeating it can't send twice ("retry the same request").
31
+ return method === 'chat.send';
32
+ }
33
+
34
+ function retryDelay(e) {
35
+ const ms = Number.isFinite(e.retryAfterMs) ? Math.floor(e.retryAfterMs) : DEFAULT_DELAY_MS;
36
+ return Math.min(Math.max(ms, MIN_DELAY_MS), MAX_DELAY_MS);
37
+ }
38
+
39
+ /**
40
+ * Call `request(method, params, timeoutMs)`, repeating it after a retryable refusal, after the gateway's retryAfterMs,
41
+ * until `maxMs` of waiting is used up; then the last refusal is thrown. Other errors pass straight through.
42
+ */
43
+ export async function requestWithRetry(request, method, params, timeoutMs, { maxMs = MAX_TOTAL_MS, sleep = wait } = {}) {
44
+ let waited = 0;
45
+ for (;;) {
46
+ try { return await request(method, params, timeoutMs); }
47
+ catch (e) {
48
+ if (!isRetryableRefusal(method, e)) throw e;
49
+ const delay = retryDelay(e);
50
+ if (waited + delay > maxMs) throw e;
51
+ waited += delay;
52
+ await sleep(delay);
53
+ }
54
+ }
55
+ }
56
+
57
+ /** `request` with the retry above; same signature. */
58
+ export const withGatewayRetry = (request, opts) => (method, params, timeoutMs) => requestWithRetry(request, method, params, timeoutMs, opts);
@@ -0,0 +1,78 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { requestWithRetry, withGatewayRetry, isRetryableRefusal } from './gateway-retry.js';
4
+
5
+ const refusal = (extra = {}) => Object.assign(new Error('chat.send unavailable during gateway startup'), {
6
+ gatewayCode: 'UNAVAILABLE', retryable: true, retryAfterMs: 500, details: { reason: 'startup-sidecars', method: 'chat.send' }, ...extra,
7
+ });
8
+
9
+ /** A request that fails with `errors` in turn, then answers. Records the sleeps. */
10
+ function scripted(errors, answer = { ok: true }) {
11
+ const calls = [];
12
+ const sleeps = [];
13
+ const request = async (method, params, t) => { calls.push({ method, params, t }); const e = errors[calls.length - 1]; if (e) throw e; return answer; };
14
+ return { request, calls, sleeps, sleep: async ms => { sleeps.push(ms); } };
15
+ }
16
+
17
+ test('a startup refusal is retried after retryAfterMs, then the answer comes back', async () => {
18
+ const s = scripted([refusal(), refusal({ retryAfterMs: 1200 })]);
19
+ const res = await requestWithRetry(s.request, 'sessions.create', { key: 'k' }, 7000, { sleep: s.sleep });
20
+ assert.deepEqual(res, { ok: true });
21
+ assert.equal(s.calls.length, 3);
22
+ assert.deepEqual(s.calls.map(c => c.params), [{ key: 'k' }, { key: 'k' }, { key: 'k' }]); // same request each time
23
+ assert.equal(s.calls[0].t, 7000);
24
+ assert.deepEqual(s.sleeps, [500, 1200]);
25
+ });
26
+
27
+ test('the wait is bounded: delays are clamped, and the last refusal is thrown once ~60 s are used up', async () => {
28
+ const s = scripted(Array.from({ length: 1000 }, () => refusal({ retryAfterMs: 60_000 })));
29
+ const err = await requestWithRetry(s.request, 'chat.send', {}, 1000, { sleep: s.sleep }).catch(e => e);
30
+ assert.equal(err.gatewayCode, 'UNAVAILABLE');
31
+ assert.ok(s.sleeps.every(ms => ms === 2000)); // retryAfterMs clamped to 2 s
32
+ assert.equal(s.sleeps.reduce((a, b) => a + b, 0), 60_000);
33
+ assert.equal(s.calls.length, 31);
34
+ const s2 = scripted(Array.from({ length: 10 }, () => refusal({ retryAfterMs: undefined })));
35
+ await requestWithRetry(s2.request, 'chat.send', {}, 1000, { sleep: s2.sleep });
36
+ assert.deepEqual(s2.sleeps, Array(10).fill(500)); // no hint: the gateway's default
37
+ const s3 = scripted(Array.from({ length: 10 }, () => refusal({ retryAfterMs: 5 })));
38
+ await requestWithRetry(s3.request, 'chat.send', {}, 1000, { sleep: s3.sleep });
39
+ assert.ok(s3.sleeps.every(ms => ms === 100));
40
+ });
41
+
42
+ test('other errors are not retried: plain failures, non-retryable UNAVAILABLE, persisted config writes, restarts', async () => {
43
+ const cases = [
44
+ ['chat.send', new Error('boom')],
45
+ ['chat.send', Object.assign(new Error('x'), { gatewayCode: 'INVALID_REQUEST', retryable: true })],
46
+ ['chat.send', Object.assign(new Error('x'), { gatewayCode: 'UNAVAILABLE' })], // retryable missing
47
+ ['config.patch', Object.assign(new Error('persisted'), { gatewayCode: 'UNAVAILABLE', details: { persistedConfig: {} } })],
48
+ ['chat.send', refusal({ details: { reason: 'gateway-restarting' } })],
49
+ ['chat.send', refusal({ details: { reason: 'goal-session-busy' } })],
50
+ ['config.patch', Object.assign(new Error('x'), { gatewayCode: 'UNAVAILABLE', retryable: true, details: { reason: 'something-else' } })], // not an admission refusal, not chat.send
51
+ ];
52
+ for (const [method, error] of cases) {
53
+ const s = scripted([error]);
54
+ const err = await requestWithRetry(s.request, method, {}, 1000, { sleep: s.sleep }).catch(e => e);
55
+ assert.equal(err, error);
56
+ assert.equal(s.calls.length, 1, `${method}: ${error.message}`);
57
+ }
58
+ });
59
+
60
+ test('chat.send is also retried for its other retryable refusals (same idempotencyKey, so it can not send twice)', async () => {
61
+ const admitting = Object.assign(new Error('Chat input is being admitted; retry the same request.'), { gatewayCode: 'UNAVAILABLE', retryable: true });
62
+ const rebuilding = Object.assign(new Error('session transcript is rebuilding; retry shortly'), { gatewayCode: 'UNAVAILABLE', retryable: true, retryAfterMs: 250, details: { method: 'chat.send' } });
63
+ const s = scripted([admitting, rebuilding]);
64
+ await requestWithRetry(s.request, 'chat.send', { idempotencyKey: 'r1' }, 1000, { sleep: s.sleep });
65
+ assert.deepEqual(s.sleeps, [500, 250]);
66
+ assert.ok(s.calls.every(c => c.params.idempotencyKey === 'r1'));
67
+ assert.equal(isRetryableRefusal('sessions.patch', admitting), false); // only chat.send carries an idempotency key
68
+ // An agent DB still being inspected refuses before any work, for every method.
69
+ const dbPending = Object.assign(new Error('agent database inspection pending'), { gatewayCode: 'UNAVAILABLE', retryable: true, retryAfterMs: 250, details: { code: 'agent-database-inspection-pending' } });
70
+ assert.equal(isRetryableRefusal('sessions.create', dbPending), true);
71
+ });
72
+
73
+ test('withGatewayRetry keeps the request signature and passes a healthy gateway through untouched', async () => {
74
+ const seen = [];
75
+ const request = withGatewayRetry(async (m, p, t) => { seen.push([m, p, t]); return { m }; });
76
+ assert.deepEqual(await request('agents.list', {}, 5000), { m: 'agents.list' });
77
+ assert.deepEqual(seen, [['agents.list', {}, 5000]]);
78
+ });
@@ -0,0 +1,84 @@
1
+ // Secret redaction for text that leaves this gateway (guest replies to other people, exported history).
2
+ //
3
+ // Since 2026.10.10 (#169063) the gateway no longer masks credentials in tool arguments and results, so an agent that
4
+ // read a .env or printed a token can pass it on in plain text. This is a conservative port of the common patterns from
5
+ // the gateway's own redactor (src/logging/redact-patterns.ts, 2026.11.6): vendor token prefixes, bearer/Authorization
6
+ // values, URL credentials, private key blocks, and secret-named assignments. It favours not touching ordinary prose
7
+ // over catching every possible secret; it is a safety net, not a vault.
8
+
9
+ export const REDACTED = '[REDACTED]';
10
+
11
+ // Private keys first: the body is base64 that other patterns would otherwise cut into pieces. An unterminated block
12
+ // (a truncated tool result) is redacted to the end of the text.
13
+ const PEM = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/g;
14
+
15
+ // Token shapes with a distinctive prefix. Group 1 is the secret (some patterns keep a leading boundary character).
16
+ const VENDOR_TOKENS = [
17
+ /\b(sk-[A-Za-z0-9_-]{8,})\b/g, // OpenAI, Anthropic (sk-ant-...), OpenRouter, ...
18
+ /(gh[pousr]_[A-Za-z0-9]{10,})/g, // GitHub ghp_ gho_ ghu_ ghs_ ghr_
19
+ /(github_pat_[A-Za-z0-9_]{10,})/g,
20
+ /(glpat-[A-Za-z0-9._=-]{20,})/g, // GitLab
21
+ /(xox[baprs]-[A-Za-z0-9-]{10,})/g, // Slack
22
+ /(xapp-[A-Za-z0-9-]{10,})/g,
23
+ /(https:\/\/hooks\.slack\.com\/(?:services|workflows)\/[A-Za-z0-9/]{20,})/g,
24
+ /(https:\/\/discord(?:app)?\.com\/api\/webhooks\/[0-9]{17,20}\/[A-Za-z0-9_-]{40,})/g,
25
+ /(gsk_[A-Za-z0-9_-]{10,})/g, // Groq
26
+ /(AIza[0-9A-Za-z_-]{30,})/g, // Google API keys (39 chars)
27
+ /(ya29\.[0-9A-Za-z_./+=-]{10,})/g, // Google OAuth access tokens
28
+ /(GOCSPX-[A-Za-z0-9_-]{20,})/g,
29
+ /(eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/g, // JWTs
30
+ /(pplx-[A-Za-z0-9_-]{10,})/g,
31
+ /(xai-[A-Za-z0-9]{30,})/g,
32
+ /(hf_[A-Za-z0-9]{10,})/g, // Hugging Face
33
+ /(npm_[A-Za-z0-9]{10,})/g,
34
+ /(pypi-[A-Za-z0-9_-]{10,})/g,
35
+ /([sr]k_(?:live|test)_[A-Za-z0-9]{10,})/g, // Stripe
36
+ /(SG\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/g, // SendGrid
37
+ /((?:^|[^A-Za-z0-9])(?:AKIA|ASIA)[A-Z0-9]{16}(?![A-Za-z0-9]))/g, // AWS access key ids
38
+ /(\d{8,10}:AA[A-Za-z0-9_-]{33})/g, // Telegram bot tokens
39
+ ];
40
+
41
+ // Authorization: Bearer xxx / Basic xxx / Token xxx (headers, curl -H "...", JSON "Authorization": "..."): keep the scheme.
42
+ const AUTH_HEADER = /(authorization["']?\s*[:=]\s*["']?(?:bearer|basic|token|bot)\s+)([A-Za-z0-9._~+/=-]{8,})/gi;
43
+ // A bare "Bearer <long token>" outside a header. 18+ characters: shorter is prose ("bearer of bad news").
44
+ const BEARER = /\b(bearer\s+)([A-Za-z0-9._~+/=-]{18,})(?![A-Za-z0-9._~+/=-])/gi;
45
+ // user:password@ in a URL: keep the scheme, user and host.
46
+ const URL_CREDENTIALS = /\b([a-z][a-z0-9+.-]{1,15}:\/\/[^\s/@:"'<>]+:)([^\s/@"'<>]{1,200})(@)/gi;
47
+ // ENV_STYLE_NAME=value / "NAME": "value" where the name ends in KEY/TOKEN/SECRET/PASSWORD: upper-case names only, so
48
+ // "monkey: 3" or "the token: here" stay.
49
+ const ENV_ASSIGNMENT = /\b((?:[A-Z][A-Z0-9]*_)*(?:API_?KEY|ACCESS_?KEY|SECRET_?KEY|PRIVATE_?KEY|AUTH_?TOKEN|ACCESS_?TOKEN|REFRESH_?TOKEN|TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|CLIENT_?SECRET)\b["']?\s*[=:]\s*)(["']?)(?!\[REDACTED\])([^\s"'\\,;]{6,})\2/g;
50
+ // JSON/YAML keys naming a secret, with a quoted value ("apiKey": "...", \"password\": \"...\" inside an escaped string).
51
+ const JSON_FIELD = /(\\*"(?:api[-_]?key|apikey|x-api-key|access[-_]?token|refresh[-_]?token|id[-_]?token|auth[-_]?token|client[-_]?secret|private[-_]?key|secret|password|passwd|passphrase|token|bearer[-_]?token|authorization|proxy-authorization|cookie|set-cookie)\\*"\s*:\s*\\*")(?!(?:bearer\s+|basic\s+|token\s+|bot\s+)?\[REDACTED\])([^"\\]{3,})/gi;
52
+ // key=value in query strings, CLI flags and config lines (lower-case): the value stops at whitespace, &, quotes.
53
+ const KEY_VALUE = /((?:^|[\s?&,;({[])(?:--?)?(?:access[-_]?token|refresh[-_]?token|id[-_]?token|api[-_]?key|apikey|client[-_]?secret|secret[-_]?key|private[-_]?key|password|passwd|passphrase|secret|token)=)(["'`]?)(?!\[REDACTED\])([^\s&#"'`<>]{4,})/gi;
54
+ // "password: hunter2" in a config or a chat: only a value that looks like a credential (has a digit or symbol), so
55
+ // "password: required" or "token: none" in prose stay.
56
+ const COLON_PASSWORD = /(\b(?:password|passwd|passphrase)\s*:\s*)(["'`]?)(?!\[REDACTED\])([^\s"'`,;]{6,})/gi;
57
+
58
+ const looksLikeCredential = v => /[^A-Za-z]/.test(v);
59
+
60
+ /**
61
+ * `text` with credentials replaced by [REDACTED]. Non-strings pass through. `onRedact` (optional) is called once per
62
+ * replacement, for callers that count.
63
+ * @param {unknown} text
64
+ * @param {() => void} [onRedact]
65
+ */
66
+ export function redactSecrets(text, onRedact) {
67
+ if (typeof text !== 'string' || text.length < 8) return text;
68
+ const hit = () => { onRedact?.(); return REDACTED; };
69
+ let out = text.replace(PEM, hit);
70
+ out = out.replace(AUTH_HEADER, (_m, head) => head + hit());
71
+ out = out.replace(BEARER, (_m, head) => head + hit());
72
+ out = out.replace(URL_CREDENTIALS, (_m, head, _pw, at) => head + hit() + at);
73
+ for (const re of VENDOR_TOKENS) {
74
+ out = out.replace(re, (match, secret) => {
75
+ const bare = secret.replace(/^[^A-Za-z0-9]/, '');
76
+ return match.replace(bare, hit);
77
+ });
78
+ }
79
+ out = out.replace(ENV_ASSIGNMENT, (_m, head, quote, _v) => head + quote + hit() + quote);
80
+ out = out.replace(JSON_FIELD, (_m, head) => head + hit());
81
+ out = out.replace(KEY_VALUE, (_m, head, quote) => head + quote + hit());
82
+ out = out.replace(COLON_PASSWORD, (m, head, quote, value) => (looksLikeCredential(value) ? head + quote + hit() : m));
83
+ return out;
84
+ }
@@ -0,0 +1,97 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { redactSecrets, REDACTED } from './redact.js';
4
+
5
+ const R = REDACTED;
6
+ const same = text => assert.equal(redactSecrets(text), text, `should be untouched: ${text}`);
7
+
8
+ test('vendor token prefixes are redacted', () => {
9
+ // Fake tokens, assembled at runtime so GitHub push protection doesn't take the fixtures for real secrets.
10
+ const secrets = [
11
+ ['sk-ant-', 'api03-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789'],
12
+ ['sk-proj-', 'abcdefghijklmnop1234'],
13
+ ['ghp_', 'abcdefghijklmnopqrstuvwxyz0123456789'],
14
+ ['github_pat_', '11ABCDEFG0abcdefghijkl_mnopqrstuvwxyz'],
15
+ ['xox', 'b-123456789012-abcdefghijklmnop'],
16
+ ['xapp-', '1-A0123456789-abcdefghij'],
17
+ ['AIza', 'SyA1234567890abcdefghijklmnopqrstuv'],
18
+ ['gsk_', 'abcdefghijklmnopqrstuvwx'],
19
+ ['npm_', 'abcdefghijklmnopqrstuvwxyz0123'],
20
+ ['hf_', 'abcdefghijklmnopqrstuv'],
21
+ ['sk_live_', 'abcdefghijklmnop1234'],
22
+ ['AKIA', 'IOSFODNN7EXAMPLE'],
23
+ ['eyJhbGciOiJIUzI1NiJ9.', 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEjXk'],
24
+ ].map(p => p.join(''));
25
+ for (const s of secrets) {
26
+ const out = redactSecrets(`the key is ${s} ok`);
27
+ assert.equal(out, `the key is ${R} ok`, s);
28
+ }
29
+ assert.equal(redactSecrets('use AKIAIOSFODNN7EXAMPLE here'), `use ${R} here`);
30
+ });
31
+
32
+ test('private key blocks are redacted, also when truncated', () => {
33
+ const block = '-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA1234\nabcdEFGH\n-----END RSA PRIVATE KEY-----';
34
+ assert.equal(redactSecrets(`before\n${block}\nafter`), `before\n${R}\nafter`);
35
+ assert.equal(redactSecrets('-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAA\nQyNTUxOQAAACD'), R);
36
+ same('-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\n-----END PUBLIC KEY-----');
37
+ });
38
+
39
+ test('Authorization headers and bearer tokens keep their scheme', () => {
40
+ assert.equal(redactSecrets('curl -H "Authorization: Bearer abcdef1234567890XYZ" https://x.test'), `curl -H "Authorization: Bearer ${R}" https://x.test`);
41
+ assert.equal(redactSecrets('Authorization: Basic dXNlcjpwYXNzd29yZA=='), `Authorization: Basic ${R}`);
42
+ assert.equal(redactSecrets('{"authorization":"Bearer tok_1234567890abcdef"}'), `{"authorization":"Bearer ${R}"}`);
43
+ assert.equal(redactSecrets('sent Bearer abcdefghijklmnopqrstuvwxyz0123456789 upstream'), `sent Bearer ${R} upstream`);
44
+ same('He was a bearer of bad news and a Bearer token is how you authenticate.');
45
+ });
46
+
47
+ test('passwords in URLs are redacted, hosts and ports are not', () => {
48
+ assert.equal(redactSecrets('postgres://admin:s3cr3tPass@db.internal:5432/app'), `postgres://admin:${R}@db.internal:5432/app`);
49
+ assert.equal(redactSecrets('git clone https://bob:ghs_x@github.com/o/r'), `git clone https://bob:${R}@github.com/o/r`);
50
+ same('https://example.com:8080/path?a=b@c');
51
+ same('git@github.com:org/repo.git');
52
+ same('ssh://git@host:22/repo');
53
+ });
54
+
55
+ test('secret-named assignments are redacted', () => {
56
+ assert.equal(redactSecrets('ANTHROPIC_API_KEY=abc123def456ghi'), `ANTHROPIC_API_KEY=${R}`);
57
+ assert.equal(redactSecrets('export DB_PASSWORD="hunter2hunter2"'), `export DB_PASSWORD="${R}"`);
58
+ assert.equal(redactSecrets('{"apiKey": "abcd1234efgh", "name": "x"}'), `{"apiKey": "${R}", "name": "x"}`);
59
+ assert.equal(redactSecrets('{\\"password\\": \\"hunter22\\"}'), `{\\"password\\": \\"${R}\\"}`);
60
+ assert.equal(redactSecrets('https://api.test/v1?token=abcd1234efgh&x=1'), `https://api.test/v1?token=${R}&x=1`);
61
+ assert.equal(redactSecrets('run --api-key=abcd1234efgh now'), `run --api-key=${R} now`);
62
+ assert.equal(redactSecrets('password: hunter2!'), `password: ${R}`);
63
+ });
64
+
65
+ test('ordinary text is left alone', () => {
66
+ same('The password policy requires 12 characters and a token refresh every hour.');
67
+ same('password: required');
68
+ same('token: none');
69
+ same('monkey: bananas, donkey: carrot, key: value');
70
+ same('Set MAX_RETRIES=5 and TIMEOUT_MS=3000 in the config.');
71
+ same('sk-short');
72
+ same('Please review src/auth/token.ts and the secret santa list.');
73
+ same('const hash = "abcdef0123456789abcdef0123456789abcdef01"; // a git sha, not a key');
74
+ same('see https://example.com/docs#password-reset');
75
+ });
76
+
77
+ test('non-strings pass through and replacements are counted once', () => {
78
+ assert.equal(redactSecrets(undefined), undefined);
79
+ assert.equal(redactSecrets(42), 42);
80
+ assert.equal(redactSecrets(''), '');
81
+ let n = 0;
82
+ const out = redactSecrets('TOKEN=abcdef123456 and Authorization: Bearer abcdef1234567890 and ghp_abcdefghijklmnopqrstuvwxyz', () => n++);
83
+ assert.equal(out, `TOKEN=${R} and Authorization: Bearer ${R} and ${R}`);
84
+ assert.equal(n, 3);
85
+ assert.equal(redactSecrets(out), out); // idempotent
86
+ });
87
+
88
+ test('a large text without secrets stays fast', () => {
89
+ const text = 'lorem ipsum dolor sit amet, consectetur adipiscing elit. '.repeat(20_000);
90
+ const t0 = Date.now();
91
+ assert.equal(redactSecrets(text), text);
92
+ assert.ok(Date.now() - t0 < 2000, 'redaction is linear');
93
+ const noise = 'a1b2'.repeat(100_000);
94
+ const t1 = Date.now();
95
+ redactSecrets(noise);
96
+ assert.ok(Date.now() - t1 < 2000, 'long token-like runs are linear');
97
+ });