@masstensor/diagnose 0.7.0 → 0.8.0

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.
@@ -20,7 +20,7 @@ The probe enforces at most five attempted handshakes per invitation, even if the
20
20
  2. The diagnostician endpoint initiates OPAQUE login; the relay forwards binary start, response and finish messages. Both roles bind `diagnose/v2/operator/ROOM` and `diagnose/v2/probe/ROOM` identifiers.
21
21
  3. Both derive a 32-byte Noise PSK with HKDF-SHA-256 from the OPAQUE session key, salt `diagnose/opaque/v2`, info `noise-psk/ROOM`.
22
22
  4. The existing `Noise_NNpsk0_25519_ChaChaPoly_BLAKE2b` exchange runs with that PSK. Its prologue includes the room, roles and protocol. Labels are sent inside Noise, after PAKE.
23
- 5. The probe requests local confirmation, then locks the invitation and sends the existing encrypted acceptance message. Optional remembered credentials are sent only inside this accepted channel. Session idle/lifetime clocks start at activation, not while the invitation is waiting.
23
+ 5. Once the probe has local consent, it locks the invitation and sends the existing encrypted acceptance message. **Approve everything** can supply that consent in advance for one temporary invitation. Remembered credentials still require confirmation and are sent only inside the accepted encrypted channel. A temporary session starts a six-hour idle clock at activation. Diagnostic messages and explicit result polls renew it. Automatic heartbeats do not. The updated relay renews its room on encrypted traffic as it cannot distinguish diagnostics from heartbeats. The probe enforces the actual idle timeout. An explicit total time limit, when configured, still applies.
24
24
 
25
25
  Implementation: pinned `@serenity-kit/opaque` 1.1.0, using its default memory-constrained Argon2id configuration, plus the existing pinned Noise implementation. OPAQUE protocol implementation and parameters are not reimplemented here. Sources: [library and implementation details](https://github.com/serenity-kit/opaque), [OPAQUE specification](https://www.rfc-editor.org/rfc/rfc9807.html). The upstream library has undergone a public security review; this integration has not received an independent audit. Secret Buffers are cleared where possible and obsolete OPAQUE state references are discarded; JavaScript/WASM does not guarantee erasure of every memory copy.
26
26
 
package/README.md CHANGED
@@ -16,9 +16,21 @@ On the computer being diagnosed:
16
16
  npx @masstensor/diagnose@latest start
17
17
  ```
18
18
 
19
- Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
19
+ In v0.8+, press Enter to review tasks and results, choose `a` to approve tasks and results automatically after confirming the connection, or choose `e` to preapprove all three for this one-time invitation. Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
20
20
 
21
- On the diagnostician's computer, start an already installed and authenticated agent:
21
+ ### Use Diagnose in your existing agent
22
+
23
+ Install once from this GitHub repository. The native Skill uses Diagnose 0.8.0 and starts the local runtime on demand through Node.js and npm.
24
+
25
+ | Agent | Install | Use |
26
+ | --- | --- | --- |
27
+ | Claude Code | `/plugin install diagnose --marketplace zkwasm/diagnose` | `/diagnose:connect` |
28
+ | Codex CLI | `codex plugin marketplace add zkwasm/diagnose`, then `codex plugin add diagnose@diagnose` | `$diagnose:connect` in a new session. |
29
+ | Gemini CLI | `gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect` | Ask Gemini to use the `connect` skill. |
30
+
31
+ ### Start from the command line or automate a diagnosis
32
+
33
+ On the diagnostician's computer, use the npm launcher when a script or job needs to start and configure an agent:
22
34
 
23
35
  ```sh
24
36
  npx @masstensor/diagnose@latest agent codex
@@ -29,7 +41,7 @@ The agent launcher requires **0.3.1+**. It loads Diagnose MCP for this launch wi
29
41
 
30
42
  > Use Diagnose to connect to this pairing code: abc-def-ghi . Help resolve the user's application startup failure. First investigate without changing anything. Explain the cause, proposed fix, and risks. Apply only authorized changes, then check whether the application starts successfully and report anything still unresolved.
31
43
 
32
- The user must approve the connection locally. They choose per-task approval or automatic execution **and transmission** for this temporary session. Possessing a pairing code does not establish the diagnostician's real identity.
44
+ The user grants permission locally, either when the connection arrives or in advance with **Approve everything**. Automatic task approval includes both execution and result transmission. Possessing a pairing code does not establish the diagnostician's real identity.
33
45
 
34
46
  For repeated use:
35
47
 
@@ -42,6 +54,8 @@ diagnose agent codex
42
54
 
43
55
  Short invitations require **0.7.0+ on both endpoints** and the updated relay. They last 30 minutes, tolerate case/spaces/hyphens, and still require local approval. Existing remembered pairings remain valid. See the [protocol design](PAIRING_PROTOCOL.md).
44
56
 
57
+ For a custom automation client, run `diagnose mcp` as a stdio subprocess. See the [native setup](USER_GUIDE.md#use-diagnose-as-a-native-agent-skill) and [automation setup](USER_GUIDE.md#8-manual-operation-and-other-mcp-clients) for the two entry points.
58
+
45
59
  ## Pair once, return later
46
60
 
47
61
  Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
package/USER_GUIDE.md CHANGED
@@ -65,10 +65,12 @@ Then run this on the on-site computer:
65
65
  npx @masstensor/diagnose@latest start
66
66
  ```
67
67
 
68
- If npm asks to install the package, type `y`. Keep this terminal open. Send the nine-letter invitation, such as `abc-def-ghi`, privately to your diagnostician.
68
+ If npm asks to install the package, type `y`. In v0.8+, choose the [approval mode](#2-start-on-the-users-computer) before sharing the invitation. Press Enter for review, `a` for automatic tasks and results, or `e` to also preapprove the connection. Keep this terminal open and share the nine-letter invitation privately.
69
69
 
70
70
  ### 3. On the diagnostician's computer
71
71
 
72
+ For an existing Claude Code, Codex CLI, or Gemini CLI session, install the [native Diagnose skill from GitHub](#use-diagnose-as-a-native-agent-skill) once, then invoke it with the invitation. For a script or an agent session that should start with Diagnose already configured, use the npm launcher:
73
+
72
74
  ```sh
73
75
  npx @masstensor/diagnose@latest agent codex
74
76
  # Or replace codex with claude or gemini.
@@ -80,7 +82,7 @@ In the agent conversation, provide the code, device model, connection method, an
80
82
 
81
83
  ### 4. Approve, diagnose, and finish
82
84
 
83
- The person receiving help checks the diagnostician's label and connection fingerprint, then chooses `y` to review tasks and result transfers. Choosing `a` instead grants automatic execution **and transmission** under the displayed terms. Commands run with that user's OS permissions; results can reach the diagnostician and their AI provider.
85
+ Unless the on-site user chose **Approve everything**, they check the diagnostician's label and connection fingerprint and approve the connection. If they selected auto approval at startup, `y` confirms it for this session and `r` connects with per-task review. Otherwise, `y` uses per-task review and `a` grants auto approval. Auto approval covers both execution **and result transmission**. Commands run with that user's OS permissions, and results can reach the diagnostician and their AI provider.
84
86
 
85
87
  The diagnostician directs the agent to investigate the device, repair within permission, and verify a device result: for example, new sensor readings or a successful communication check. The user can type `permissions ask` to revoke automatic approval or `exit` to stop access. Afterward, `diagnose history` lists local task records and `diagnose show TASK_ID` shows what was requested, collected, and sent.
86
88
 
@@ -209,7 +211,17 @@ npm install -g @masstensor/diagnose@latest
209
211
  diagnose start
210
212
  ```
211
213
 
212
- With v0.7+, the terminal shows a **nine-letter invitation**, such as `abc-def-ghi`, and the audit log path. Keep it open. Share the code privately by message or read it aloud. It lasts **30 minutes** and is consumed by successful pairing. Case, spaces and hyphens do not matter when entering it. The user must still approve locally. Treat the code as a secret; do not post it publicly or put it in shell arguments. After expiry or five attempted handshakes, the running probe generates a new code.
214
+ With v0.8+, a probe starting a new pairing asks which approval mode to use before displaying its invitation.
215
+
216
+ | Startup choice | What it allows |
217
+ | --- | --- |
218
+ | Enter | Confirm the connection and review each task and result transfer. |
219
+ | `a` · Auto tasks only | Confirm the connection once. Tasks and result transfers then proceed automatically. |
220
+ | `e` · Approve everything | Let the holder of this one-time invitation connect automatically, run tasks, and receive results for the temporary session. |
221
+
222
+ Share an **Approve everything** invitation only with the intended diagnostician. Type `permissions ask` to cancel that choice before pairing or revoke auto approval after pairing. The next invitation does not inherit it. Requests to remember a diagnostician still require confirmation.
223
+
224
+ With v0.7+, the terminal shows a **nine-letter invitation**, such as `abc-def-ghi`, and the audit log path. Keep it open. Share the code privately by message or read it aloud. It lasts **30 minutes** and is consumed by successful pairing. Case, spaces and hyphens do not matter when entering it. Treat the code as a secret; do not post it publicly or put it in shell arguments. After expiry or five attempted handshakes, the running probe generates a new code.
213
225
 
214
226
  The probe will show the connecting party's self-reported label and the session fingerprint. Check these with the intended diagnostician before accepting. A code proves possession of the secret, not a person's identity.
215
227
 
@@ -612,7 +624,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
612
624
  | Limit | Default / maximum |
613
625
  | --- | --- |
614
626
  | New short invitation | 30 minutes; one-time; up to five attempted handshakes |
615
- | Temporary session idle / total | 10 minutes / 60 minutes by default |
627
+ | Temporary session idle / total | Six hours idle / no fixed total by default in v0.8+ |
616
628
  | Remembered pairing | Until revoked locally; requires the foreground probe |
617
629
  | Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
618
630
  | Finite command or script | 60 seconds by default; 300 seconds maximum |
@@ -621,7 +633,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
621
633
  | Active live resource handles | 128 |
622
634
  | Live process | 1 hour by default; `timeoutMs:0` removes its timer |
623
635
  | Retained output per live process | 64 MiB by default; 1 GiB maximum; reaching the cap terminates the process |
624
- | Relay session | At most 7 days, also subject to cipher frame limits |
636
+ | Relay session | The updated relay renews an active room without a fixed total. Older relays may cap a room at seven days. |
625
637
 
626
638
  ```sh
627
639
  diagnose start --session-minutes 240 --idle-minutes 30
@@ -629,8 +641,65 @@ diagnose start --session-minutes 240 --idle-minutes 30
629
641
 
630
642
  Session and idle options apply to temporary connections. Remembered connections disable these endpoint timers, while automatic approval has its own saved expiry. Set a temporary session or idle timeout to `0` to disable that endpoint timer; relay and cipher limits still apply. Both endpoints should use a compatible current version. POSIX processes that deliberately detach from their process group cannot always be terminated by group cancellation.
631
643
 
644
+ ## Use Diagnose as a native agent skill
645
+
646
+ Install the skill once through your agent's GitHub installation flow. All three agents use the same `skills/connect/` directory in the repository. The helper runs Diagnose 0.8.0 locally on demand with `npx` and needs Node.js 20.10 or later. There is no separate global Diagnose CLI installation for this workflow.
647
+
648
+ ### Claude Code
649
+
650
+ In Claude Code 2.1.275 or later, enter:
651
+
652
+ ```text
653
+ /plugin install diagnose --marketplace zkwasm/diagnose
654
+ ```
655
+
656
+ Choose the installation scope. Open a new session, or use `/reload-plugins` in the current one. Invoke `/diagnose:connect` with the private invitation and, if known, the device and symptom. [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command)
657
+
658
+ ### Codex CLI
659
+
660
+ In your terminal, run:
661
+
662
+ ```sh
663
+ codex plugin marketplace add zkwasm/diagnose
664
+ codex plugin add diagnose@diagnose
665
+ ```
666
+
667
+ Alternatively, add the marketplace and install Diagnose from `/plugins`. Open a new session and invoke `$diagnose:connect` with your private invitation. [Codex CLI plugin documentation](https://learn.chatgpt.com/docs/cli/reference#codex-plugin)
668
+
669
+ ### Gemini CLI
670
+
671
+ In your terminal, run:
672
+
673
+ ```sh
674
+ gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect
675
+ ```
676
+
677
+ Approve the installation prompt. In a new session, ask Gemini to use the `connect` skill and provide the invitation. Use `/skills reload` if a Gemini session is already open. [Gemini CLI Skills documentation](https://geminicli.com/docs/cli/skills/#managing-skills)
678
+
679
+ ### Run a diagnostic session
680
+
681
+ The on-site user starts the normal probe and shares its one-time invitation. The skill uses it to request pairing through the relay. The on-site user confirms the connection if their startup choice requires it. The agent starts with a relevant read-only check, such as listing visible serial ports. It keeps the connection for follow-up checks, authorized changes, and verification. Normal local execution and transfer permissions still apply.
682
+
683
+ The first result informs the next step. For example, the agent may compare device logs with two related settings, correct one setting, and rerun the original check. If the symptom persists, it uses that result to choose the next test. The skill keeps the connection open after progress reports and verification so you can ask follow-up questions. Ask the agent to close the session when you are done. The on-site user can also stop access.
684
+
685
+ A temporary session normally expires after six hours without diagnostic activity. Task requests, result polling, and live resource interactions renew the timer. Automatic heartbeats keep the network connection alive without renewing the diagnostic idle timer. A probe configured with an explicit total limit can expire the session earlier. A network or process loss can still interrupt a live connection. If interruptions are expected, a remembered pairing can reconnect without a fresh code. A direct stdio MCP session ends when its client stops the MCP process. The native skill keeps its MCP process running across separate shell calls and conversation turns.
686
+
687
+ This path uses temporary pairing and finite diagnostic operations. It supports system inspection, bounded file operations, finite commands, and serial diagnostics. The full agent launcher remains available for remembered connections, live terminals, and case management.
688
+
689
+ For prerelease testing, build the source checkout, install from its local marketplace or skill directory, and set `DIAGNOSE_SKILL_CLI` in the agent's environment to the absolute path of `dist/cli.js`. The GitHub install commands require the repository manifests to be published. The helper's default runtime requires the pinned npm version to be published.
690
+
632
691
  ## 8. Manual operation and other MCP clients
633
692
 
693
+ For scripts and CI, install the npm client and start it directly. The native Skill is optional for these workflows.
694
+
695
+ ```sh
696
+ npm install -g @masstensor/diagnose
697
+ diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
698
+ # Or use diagnose mcp --device workshop-laptop as the MCP server subprocess.
699
+ ```
700
+
701
+ Use `agent codex` or `agent gemini` for the other launchers. You can also run the npm launcher directly with `npx @masstensor/diagnose@latest agent claude`. The `--skill` launcher flag takes your device procedure. It does not require the native Diagnose Skill to be installed.
702
+
634
703
  ```sh
635
704
  diagnose connect
636
705
  ```
package/dist/cli.js CHANGED
@@ -21,6 +21,7 @@ import { History } from './history.js';
21
21
  import { cleanupLocal } from './maintenance.js';
22
22
  import { skillsCommand, skillsUsage } from './skill-library.js';
23
23
  import { knowledgeCommand, knowledgeUsage } from './knowledge-cli.js';
24
+ import { DEFAULT_IDLE_MS } from './session-limits.js';
24
25
  async function attachTerminal(operator, id) {
25
26
  let done = false, cursor = 0;
26
27
  const wasRaw = stdin.isRaw;
@@ -56,6 +57,14 @@ async function attachTerminal(operator, id) {
56
57
  }
57
58
  }
58
59
  async function main() {
60
+ if (process.argv[2] === 'install-skill') {
61
+ await (await import('./install-skill.js')).installSkill(process.argv.slice(3));
62
+ return;
63
+ }
64
+ if (process.argv[2] === 'skill-session') {
65
+ await (await import('./skill-session.js')).skillSessionCommand(process.argv.slice(3));
66
+ return;
67
+ }
59
68
  if (['cases', 'drafts', 'vault'].includes(process.argv[2])) {
60
69
  await knowledgeCommand(process.argv[2], process.argv.slice(3));
61
70
  return;
@@ -68,7 +77,7 @@ async function main() {
68
77
  process.exitCode = await launchAgent(process.argv.slice(3));
69
78
  return;
70
79
  }
71
- const { positionals, values } = parseArgs({ args: process.argv.slice(2), allowPositionals: true, options: { 'session-minutes': { type: 'string', default: '60' }, 'idle-minutes': { type: 'string', default: '10' }, device: { type: 'string' }, case: { type: 'string' }, name: { type: 'string' }, days: { type: 'string', default: '7' }, cursor: { type: 'string', default: '0' } } });
80
+ const { positionals, values } = parseArgs({ args: process.argv.slice(2), allowPositionals: true, options: { 'session-minutes': { type: 'string', default: '0' }, 'idle-minutes': { type: 'string', default: String(DEFAULT_IDLE_MS / 60_000) }, device: { type: 'string' }, case: { type: 'string' }, name: { type: 'string' }, days: { type: 'string', default: '7' }, cursor: { type: 'string', default: '0' } } });
72
81
  const [command = 'help', relay = 'https://diagnose.fenginwind.com'] = positionals;
73
82
  if (command === 'history') {
74
83
  console.log(safeText(JSON.stringify(new History().list(), null, 2)));
@@ -89,7 +98,7 @@ async function main() {
89
98
  throw new Error('Usage: diagnose start|connect|terminal|mcp [relay-url]');
90
99
  const sessionMinutes = Number(values['session-minutes']), idleMinutes = Number(values['idle-minutes']);
91
100
  if (![sessionMinutes, idleMinutes].every(value => Number.isInteger(value) && value >= 0 && value <= 10080))
92
- throw new Error('Timeouts must be 0..10080 minutes; 0 disables endpoint timeout (relay maximum 7 days)');
101
+ throw new Error('Timeouts must be 0..10080 minutes; 0 disables that endpoint timeout');
93
102
  if (command === 'devices') {
94
103
  console.log(JSON.stringify(new PairingStore(join(homedir(), '.diagnose', 'pairings')).list('operator').map(({ name, id, relay }) => ({ name, id, relay })), null, 2));
95
104
  return;
@@ -105,7 +114,7 @@ async function main() {
105
114
  return;
106
115
  }
107
116
  if (!['start', 'connect', 'terminal', 'pair'].includes(command)) {
108
- console.log(`diagnose start|connect|terminal|mcp [relay-url] [--device NAME]\ndiagnose pair [relay-url] --name NAME\ndiagnose history\ndiagnose show ID [--cursor OFFSET]\ndiagnose cleanup [--days 7]\ndiagnose devices\ndiagnose forget --device NAME\n${agentUsage}\n${skillsUsage}\n${knowledgeUsage}\nNode.js >=20.10. Pairing codes are entered interactively, never as arguments.`);
117
+ console.log(`diagnose start|connect|terminal|mcp [relay-url] [--device NAME]\ndiagnose pair [relay-url] --name NAME\ndiagnose history\ndiagnose show ID [--cursor OFFSET]\ndiagnose cleanup [--days 7]\ndiagnose devices\ndiagnose forget --device NAME\n${agentUsage}\n${(await import('./install-skill.js')).installSkillUsage}\n${skillsUsage}\n${knowledgeUsage}\nNode.js >=20.10. Pairing codes are entered interactively, never as arguments.`);
109
118
  return;
110
119
  }
111
120
  if (!stdin.isTTY || !stdout.isTTY)
@@ -142,6 +151,16 @@ async function main() {
142
151
  if (command === 'start') {
143
152
  const store = new PairingStore();
144
153
  console.log('Task details and collected results are saved in encrypted local history for up to 7 days (256 MiB budget). View with diagnose history / diagnose show ID; remove inactive records with diagnose cleanup --days 0. Scripts may contain sensitive data.');
154
+ let nextSessionApproval = 'review';
155
+ if (!store.list('host').length) {
156
+ console.log('Auto approval lets the diagnostician run tasks with your OS permissions and receive results without further prompts.');
157
+ console.log('Approve everything also lets anyone with the next one-time invitation connect without confirmation. Share that invitation privately.');
158
+ const choice = (await rl.question('Task approval for the next session? [Enter=review / a=auto tasks only / e=approve everything] ', { signal: shutdown.signal })).trim().toLowerCase();
159
+ nextSessionApproval = choice === 'e' ? 'everything' : choice === 'a' ? 'tasks' : 'review';
160
+ console.log(nextSessionApproval === 'everything' ? 'Approve everything selected for this temporary invitation: connection, task execution, and result transmission.'
161
+ : nextSessionApproval === 'tasks' ? 'Auto approval selected for the next temporary session, subject to your pairing confirmation.'
162
+ : 'You will review task execution and result transfers.');
163
+ }
145
164
  const firstAudit = new Audit();
146
165
  resources = new SessionResources(join(homedir(), '.diagnose', 'resources'), firstAudit);
147
166
  let sessions = 0;
@@ -194,15 +213,30 @@ async function main() {
194
213
  if (remember)
195
214
  console.log('REMEMBER THIS DIAGNOSTICIAN: this computer will accept future connections using a new private credential until you type "unpair". Task approval remains enabled. AUTO lasts one hour, across reconnects.');
196
215
  console.log(`\nRequested by: ${safeText(label)} (self-asserted identity)\nFingerprint: ${fingerprint}\nResults will be available to the diagnostician and their AI provider.`);
197
- console.log('Choose y: approve each task/batch and its transfer.\nChoose a: grant automatic execution AND transmission (one hour if remembered; otherwise this temporary session).\nAUTO: commands have your OS permissions; results go to the diagnostician and their AI without further prompts. Raw terminal, file and tunnel channels are NOT redacted. A channel grant includes continuing input/output within its scope.\nRevoke locally with "permissions ask", cancel with "cancel", or end with Ctrl+C. Already transmitted data cannot be recalled.');
198
- const answer = (await rl.question(remember ? 'Remember and allow this diagnostician? [y / a=auto for 1 hour / N] ' : 'Allow this temporary diagnostic session? [y / a=auto / N] ', { signal })).trim().toLowerCase();
199
- const allowed = answer === 'y' || answer === 'a';
216
+ if (!remember && nextSessionApproval === 'everything') {
217
+ signal.throwIfAborted();
218
+ nextSessionApproval = 'review';
219
+ audit.record('session.pairing-decision', { allowed: true, fingerprint, approval: 'everything' });
220
+ engine.setPermissionMode('auto');
221
+ console.log('Connection approved by your startup selection (Approve everything).');
222
+ return true;
223
+ }
224
+ const preselectedAuto = nextSessionApproval === 'tasks' && !remember;
225
+ console.log(preselectedAuto ? 'You selected auto approval at startup. Choose y to confirm it or r to connect with per-task review.' : 'Choose y: approve each task/batch and its transfer.\nChoose a: grant automatic execution AND transmission (one hour if remembered; otherwise this temporary session).');
226
+ console.log('AUTO: commands have your OS permissions; results go to the diagnostician and their AI without further prompts. Raw terminal, file and tunnel channels are NOT redacted. A channel grant includes continuing input/output within its scope.\nRevoke locally with "permissions ask", cancel with "cancel", or end with Ctrl+C. Already transmitted data cannot be recalled.');
227
+ const prompt = preselectedAuto ? 'Allow this temporary session with auto approval? [y / r=review / N] '
228
+ : remember ? 'Remember and allow this diagnostician? [y / a=auto for 1 hour / N] ' : 'Allow this temporary diagnostic session? [y / a=auto / N] ';
229
+ const answer = (await rl.question(prompt, { signal })).trim().toLowerCase();
230
+ const auto = preselectedAuto ? answer === 'y' : answer === 'a';
231
+ const allowed = answer === 'y' || (preselectedAuto ? answer === 'r' : auto);
232
+ if (allowed)
233
+ nextSessionApproval = 'review';
200
234
  if (allowed && remember) {
201
235
  provision = createCode();
202
236
  remembered = store.add({ role: 'host', name: 'diagnostician', label, relay, code: provision });
203
237
  audit.record('pairing.remembered', { id: remembered.id });
204
238
  }
205
- if (answer === 'a') {
239
+ if (auto) {
206
240
  engine.setPermissionMode('auto');
207
241
  if (remembered) {
208
242
  remembered.autoUntil = Date.now() + 3600000;
@@ -284,6 +318,7 @@ async function main() {
284
318
  return true;
285
319
  }
286
320
  if (value === 'permissions ask') {
321
+ nextSessionApproval = 'review';
287
322
  autoRequestedAt = 0;
288
323
  clearTimeout(grantTimer);
289
324
  if (remembered) {
@@ -358,6 +393,8 @@ async function main() {
358
393
  await peer.open();
359
394
  console.log(remembered ? `Remembered diagnostician: ${safeText(remembered.label)}. Waiting for connections. Local commands: pairing, pause, resume, unpair, permissions ask, permissions auto [forever], cancel, jobs, exit. Audit: ${audit.path}` : `Relay: ${relay}\nAudit: ${audit.path}\nPairing code (30 minutes, one-time, share privately):\n${code}\nCtrl+C ends the session and cancels active tasks.`);
360
395
  console.log(`Session ended: ${safeText(await peer.ended)}`);
396
+ if (nextSessionApproval === 'everything')
397
+ nextSessionApproval = 'review';
361
398
  }
362
399
  catch (error) {
363
400
  const collision = error.message.includes('Invitation locator occupied');
package/dist/discover.js CHANGED
@@ -19,5 +19,5 @@ export async function inspectSystem() {
19
19
  }
20
20
  }
21
21
  const elevated = process.platform === 'win32' ? /S-1-16-(12288|16384)/.test(spawnSync('whoami', ['/groups'], { encoding: 'utf8', timeout: 3000, windowsHide: true }).stdout ?? '') : process.geteuid?.() === 0;
22
- return { platform: process.platform, arch: process.arch, release: os.release(), node: process.version, hostname: os.hostname(), cwd: process.cwd(), home: os.homedir(), username: os.userInfo().username, elevated, shell: process.platform === 'win32' ? process.env.ComSpec ?? 'cmd.exe' : process.env.SHELL ?? '/bin/sh', commands, serialPorts: await SerialPort.list(), networkInterfaces: os.networkInterfaces(), protocol: 1, version: '0.7.0', capabilities: ['batch', 'script', 'process-stdin', 'pty', 'terminal-resize', 'signals', 'concurrent-jobs', 'encrypted-output-journal', 'resource-resume', 'binary-transfer', 'filesystem', 'local-forward', 'remote-forward', 'socks5'] };
22
+ return { platform: process.platform, arch: process.arch, release: os.release(), node: process.version, hostname: os.hostname(), cwd: process.cwd(), home: os.homedir(), username: os.userInfo().username, elevated, shell: process.platform === 'win32' ? process.env.ComSpec ?? 'cmd.exe' : process.env.SHELL ?? '/bin/sh', commands, serialPorts: await SerialPort.list(), networkInterfaces: os.networkInterfaces(), protocol: 1, version: '0.8.0', capabilities: ['batch', 'script', 'process-stdin', 'pty', 'terminal-resize', 'signals', 'concurrent-jobs', 'encrypted-output-journal', 'resource-resume', 'binary-transfer', 'filesystem', 'local-forward', 'remote-forward', 'socks5'] };
23
23
  }
package/dist/engine.js CHANGED
@@ -4,6 +4,7 @@ import { digest, redact, safeText } from './util.js';
4
4
  import { SessionResources, resourceOperation } from './resources.js';
5
5
  import { randomUUID } from 'node:crypto';
6
6
  import { dirname, join, basename } from 'node:path';
7
+ import { DEFAULT_IDLE_MS } from './session-limits.js';
7
8
  function aborted(promise, signal) {
8
9
  return new Promise((resolve, reject) => {
9
10
  const cancel = () => reject(new Error('Task cancelled'));
@@ -60,18 +61,24 @@ export class ProbeEngine {
60
61
  this.notice = notice;
61
62
  this.resources = options.resources ?? new SessionResources(join(dirname(audit.path), basename(audit.path) + '.resources'), audit);
62
63
  this.resources.setAudit(audit);
64
+ const idleMs = options.idleMs ?? DEFAULT_IDLE_MS;
65
+ const refreshIdle = () => {
66
+ if (!idleMs || this.ended)
67
+ return;
68
+ clearTimeout(this.idle);
69
+ this.idle = setTimeout(() => peer.close('Idle timeout'), idleMs);
70
+ };
63
71
  // Waiting for an invitation/approval is not diagnostic session time.
64
- // Otherwise the default ten-minute idle timer would cut a 30-minute code short.
65
72
  void peer.active.then(() => {
66
73
  if (this.ended)
67
74
  return;
68
- if (options.idleMs !== 0)
69
- this.idle = setTimeout(() => peer.close('Idle timeout'), options.idleMs ?? 600000);
70
- if (options.lifetimeMs !== 0)
71
- this.lifetime = setTimeout(() => peer.close('Session lifetime exceeded'), options.lifetimeMs ?? 3600000);
75
+ refreshIdle();
76
+ if (options.lifetimeMs)
77
+ this.lifetime = setTimeout(() => peer.close('Session lifetime exceeded'), options.lifetimeMs);
72
78
  }).catch(() => { });
79
+ peer.on('activity', refreshIdle);
73
80
  peer.on('message', (message) => {
74
- this.idle?.refresh();
81
+ refreshIdle();
75
82
  if (message.type === 'resource.request') {
76
83
  void this.resources.control(this.owner, message.request).then(value => this.peer.send({ type: 'resource.result', requestId: message.requestId, value }), error => this.peer.send({ type: 'resource.result', requestId: message.requestId, error: redact(error.message).slice(0, 2000) })).catch(() => { });
77
84
  return;
@@ -127,9 +134,9 @@ export class ProbeEngine {
127
134
  this.jobs.set(task.id, controller);
128
135
  void this.run(task, controller);
129
136
  });
130
- peer.on('closed', () => { this.ended = true; clearTimeout(this.idle); clearTimeout(this.lifetime); for (const controller of this.jobs.values())
137
+ peer.on('closed', (reason) => { this.ended = true; clearTimeout(this.idle); clearTimeout(this.lifetime); for (const controller of this.jobs.values())
131
138
  controller.abort(); void this.resources.disconnect(this.owner).catch(() => { }); try {
132
- audit.record('session.closed', {});
139
+ audit.record('session.closed', { reason: reason && redact(reason) });
133
140
  }
134
141
  catch { /* Session is already closed. */ } });
135
142
  }
@@ -0,0 +1,2 @@
1
+ export declare const installSkillUsage = "diagnose install-skill claude|codex|gemini";
2
+ export declare function installSkill(args: string[]): Promise<void>;
@@ -0,0 +1,57 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
3
+ import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ export const installSkillUsage = 'diagnose install-skill claude|codex|gemini';
7
+ const locations = new Map([
8
+ ['claude', { directory: '.claude', invocation: '/diagnose' }],
9
+ ['codex', { directory: '.agents', invocation: '$diagnose' }],
10
+ ['gemini', { directory: '.gemini', invocation: 'Use the Diagnose skill' }],
11
+ ]);
12
+ export async function installSkill(args) {
13
+ const agent = args.length === 1 ? locations.get(args[0]) : undefined;
14
+ if (!agent)
15
+ throw new Error('Usage: ' + installSkillUsage);
16
+ const root = fileURLToPath(new URL('../', import.meta.url));
17
+ const source = join(root, 'skills', 'connect');
18
+ const library = join(homedir(), agent.directory, 'skills');
19
+ const target = join(library, 'diagnose');
20
+ const [skill, helper] = await Promise.all([
21
+ readFile(join(source, 'SKILL.md'), 'utf8'),
22
+ readFile(join(source, 'scripts/run.mjs')),
23
+ ]);
24
+ const files = new Map([
25
+ ['SKILL.md', Buffer.from(skill.replace(/^name: connect$/m, 'name: diagnose'))],
26
+ ['scripts/run.mjs', helper],
27
+ ]);
28
+ const runtime = 'scripts/local-runtime.json';
29
+ if (existsSync(join(root, '.git'))) {
30
+ files.set(runtime, Buffer.from(JSON.stringify({ cli: join(root, 'dist', 'cli.js') }) + '\n'));
31
+ }
32
+ await mkdir(library, { recursive: true, mode: 0o700 });
33
+ try {
34
+ await mkdir(target, { mode: 0o700 });
35
+ }
36
+ catch (error) {
37
+ if (error.code !== 'EEXIST')
38
+ throw error;
39
+ const sameFiles = (await Promise.all([...files].map(async ([file, bytes]) => (await readFile(join(target, file)).catch(() => undefined))?.equals(bytes) === true))).every(Boolean) && (files.has(runtime) || !existsSync(join(target, runtime)));
40
+ if (!sameFiles)
41
+ throw new Error('A different Skill already exists at ' + target + '. Move it before installing.');
42
+ console.log('Diagnose Skill is already installed at ' + target);
43
+ console.log('In a new agent session, use ' + agent.invocation + '.');
44
+ return;
45
+ }
46
+ try {
47
+ await mkdir(join(target, 'scripts'), { mode: 0o700 });
48
+ for (const [file, bytes] of files)
49
+ await writeFile(join(target, file), bytes, { mode: 0o600, flag: 'wx' });
50
+ }
51
+ catch (error) {
52
+ await rm(target, { recursive: true, force: true });
53
+ throw error;
54
+ }
55
+ console.log('Installed Diagnose Skill at ' + target);
56
+ console.log('In a new agent session, use ' + agent.invocation + '.');
57
+ }
package/dist/mcp.js CHANGED
@@ -11,7 +11,7 @@ import { PairingStore, RememberedConnection } from './pairing.js';
11
11
  import { safeText } from './util.js';
12
12
  import { registerKnowledge } from './knowledge-mcp.js';
13
13
  export async function serveMcp(relay, device, caseId) {
14
- const server = new McpServer({ name: 'diagnose', version: '0.7.0' });
14
+ const server = new McpServer({ name: 'diagnose', version: '0.8.0' });
15
15
  let operator;
16
16
  let remembered = device ? new RememberedConnection(new PairingStore().get(device, 'operator')) : undefined;
17
17
  const transfers = new Map(), forwards = new Map();
@@ -109,7 +109,17 @@ export async function serveMcp(relay, device, caseId) {
109
109
  }
110
110
  return answer({ id: value.id, direction: value.direction, host: value.host, port: value.port });
111
111
  });
112
- server.registerTool('diagnose_disconnect', { description: 'End this diagnostic connection. Remembered pairing remains until revoked on the user computer.', inputSchema: {} }, async () => { remembered?.close(); remembered = undefined; operator?.peer.close(); operator = undefined; return answer({ disconnected: true }); });
112
+ server.registerTool('diagnose_disconnect', { description: 'Explicitly end this diagnostic connection. Remembered pairing remains until revoked on the user computer.', inputSchema: {} }, async () => {
113
+ remembered?.close();
114
+ remembered = undefined;
115
+ const peer = operator?.peer;
116
+ operator = undefined;
117
+ if (peer) {
118
+ await peer.send({ type: 'session.closed', reason: 'Diagnostician ended session' }).catch(() => { });
119
+ peer.close();
120
+ }
121
+ return answer({ disconnected: true });
122
+ });
113
123
  let stopped = false;
114
124
  const stop = () => { if (stopped)
115
125
  return; stopped = true; for (const transfer of transfers.values())
package/dist/operator.js CHANGED
@@ -86,6 +86,8 @@ export class Operator {
86
86
  const job = this.jobs.get(id);
87
87
  if (!job)
88
88
  throw new Error('Unknown or expired task result; completed results are bounded to 128 tasks / 32 MiB. Do not replay modifications; inspect remote state or local history.');
89
+ // Polling a real task is diagnostic activity even though the result is cached locally.
90
+ void this.peer.send({ type: 'ping', activity: true }).catch(() => { });
89
91
  let timer;
90
92
  try {
91
93
  return await Promise.race([job.promise, new Promise(resolve => { timer = setTimeout(() => resolve({ id, pending: true }), timeoutMs); })]);
package/dist/peer.js CHANGED
@@ -4,6 +4,7 @@ import { Handshake, parseCode, parseInvitation, INVITATION_MS } from './crypto.j
4
4
  import { CHUNK_SIZE, MAX_FRAME, parseMessage } from './schema.js';
5
5
  import { safeText } from './util.js';
6
6
  import { InvitationHost, InvitationJoin } from './short-pairing.js';
7
+ import { LEGACY_RELAY_MAX_MS } from './session-limits.js';
7
8
  function deferred() { let resolve; let reject; const promise = new Promise((a, b) => { resolve = a; reject = b; }); promise.catch(() => { }); return { promise, resolve, reject }; }
8
9
  export function relayUrl(value) {
9
10
  const url = new URL(value);
@@ -66,7 +67,11 @@ export class Peer extends EventEmitter {
66
67
  this.invitationTimer = setTimeout(() => this.close('Invitation expired; generate a new code'), Math.min(options.invitationMs ?? INVITATION_MS, INVITATION_MS));
67
68
  this.ws.on('open', () => this.ws.send(JSON.stringify({ version: short ? 2 : 1, role: options.role, room })));
68
69
  this.ws.on('error', () => this.close('Relay connection failed'));
69
- this.ws.on('close', (_code, reason) => this.close(reason.toString() === 'Invitation locator occupied' ? 'Invitation locator occupied; generating a new code' : 'Relay disconnected'));
70
+ this.ws.on('close', (_code, reason) => {
71
+ const message = reason.toString();
72
+ this.close(message === 'Invitation locator occupied' ? 'Invitation locator occupied; generating a new code'
73
+ : message === 'Session expired' ? 'Relay session expired' : 'Relay disconnected');
74
+ });
70
75
  this.ws.on('message', (bytes, binary) => {
71
76
  try {
72
77
  if (binary)
@@ -184,7 +189,9 @@ export class Peer extends EventEmitter {
184
189
  this.close('User declined pairing');
185
190
  return;
186
191
  }
187
- this.ws.send(JSON.stringify({ type: 'lock', ...(this.options.sessionMs === undefined ? {} : { ttlMs: this.options.sessionMs || 7 * 86400000 }) }));
192
+ this.ws.send(JSON.stringify(this.options.sessionMs
193
+ ? { type: 'lock', ttlMs: this.options.sessionMs }
194
+ : { type: 'lock', sliding: true, ttlMs: LEGACY_RELAY_MAX_MS }));
188
195
  this.approved = true;
189
196
  await this.send({ type: 'session.accepted', label: safeText(this.options.label ?? 'User probe'), fingerprint: this.fingerprint, ...(hello.remember === true && this.options.provision?.() ? { credential: this.options.provision() } : {}) });
190
197
  this.activate();
@@ -231,6 +238,8 @@ export class Peer extends EventEmitter {
231
238
  if (!this.approved)
232
239
  throw new Error('Not authorized');
233
240
  if (message.type === 'ping') {
241
+ if (message.activity && this.options.role === 'host')
242
+ this.emit('activity');
234
243
  void this.send({ type: 'pong' }).catch(() => this.close('Heartbeat failed'));
235
244
  return;
236
245
  }
@@ -272,6 +281,8 @@ export class Peer extends EventEmitter {
272
281
  // Bound sustained traffic below the relay's shared per-room frame budget.
273
282
  await new Promise(resolve => setTimeout(resolve, 10));
274
283
  }
284
+ if (message.type.startsWith('task.') || message.type.startsWith('resource.'))
285
+ this.emit('activity');
275
286
  }).finally(() => { this.queuedBytes -= payload.length; });
276
287
  this.queue = operation.catch(() => this.close('Encrypted transport failed'));
277
288
  return operation;
package/dist/relay.js CHANGED
@@ -4,11 +4,17 @@ import { WebSocket, WebSocketServer } from 'ws';
4
4
  import { MAX_FRAME } from './schema.js';
5
5
  import { INVITATION_MS } from './crypto.js';
6
6
  import { VaultServer } from './vault-server.js';
7
+ import { DEFAULT_IDLE_MS, LEGACY_RELAY_MAX_MS } from './session-limits.js';
7
8
  const control = (ws, type, extra = {}) => { if (ws.readyState === WebSocket.OPEN)
8
9
  ws.send(JSON.stringify({ type, ...extra })); };
9
10
  export function createRelay(options = {}) {
10
11
  const vault = options.vaultPath ? new VaultServer(options.vaultPath) : undefined;
11
12
  const rooms = new Map();
13
+ const expireRoom = (id, room) => {
14
+ rooms.delete(id);
15
+ room.host.close(1000, 'Session expired');
16
+ room.peer?.close(1000, 'Session expired');
17
+ };
12
18
  const clients = new Map();
13
19
  const connectionsByIp = new Map();
14
20
  const connectionRates = new Map();
@@ -110,8 +116,12 @@ export function createRelay(options = {}) {
110
116
  return;
111
117
  }
112
118
  const room = rooms.get(state.room);
113
- if (!room || room.expires < Date.now())
119
+ if (!room)
114
120
  throw new Error();
121
+ if (room.expires <= Date.now()) {
122
+ expireRoom(state.room, room);
123
+ return;
124
+ }
115
125
  if (binary) {
116
126
  if (Date.now() - room.window > 1000) {
117
127
  room.window = Date.now();
@@ -127,6 +137,10 @@ export function createRelay(options = {}) {
127
137
  buffered += client.bufferedAmount;
128
138
  if (buffered > 64 * 1024 * 1024)
129
139
  throw new Error();
140
+ // The relay can see ciphertext traffic, not diagnostic activity. The
141
+ // probe enforces the real idle timeout without counting heartbeats.
142
+ if (room.renewMs)
143
+ room.expires = Date.now() + room.renewMs;
130
144
  options.observeCiphertext?.(bytes);
131
145
  target.send(bytes, { binary: true });
132
146
  return;
@@ -136,10 +150,12 @@ export function createRelay(options = {}) {
136
150
  const msg = JSON.parse(bytes.toString());
137
151
  if (msg.type === 'lock' && !room.locked) {
138
152
  const requested = msg.ttlMs;
139
- if (requested !== undefined && (!Number.isInteger(requested) || requested < 60000 || requested > 7 * 86400000))
153
+ if (requested !== undefined && (!Number.isInteger(requested) || requested < 60000 || requested > LEGACY_RELAY_MAX_MS))
140
154
  throw new Error();
141
155
  room.locked = true;
142
- room.expires = Date.now() + (requested ?? options.sessionMs ?? 3600000);
156
+ if (msg.sliding === true)
157
+ room.renewMs = options.sessionMs ?? DEFAULT_IDLE_MS;
158
+ room.expires = Date.now() + (room.renewMs ?? requested ?? options.sessionMs ?? DEFAULT_IDLE_MS);
143
159
  }
144
160
  else if (msg.type === 'reject' && !room.locked) {
145
161
  const peer = room.peer;
@@ -178,11 +194,8 @@ export function createRelay(options = {}) {
178
194
  });
179
195
  const sweep = setInterval(() => {
180
196
  for (const [id, room] of rooms)
181
- if (room.expires < Date.now()) {
182
- rooms.delete(id);
183
- room.host.close(1000, 'Session expired');
184
- room.peer?.close(1000, 'Session expired');
185
- }
197
+ if (room.expires <= Date.now())
198
+ expireRoom(id, room);
186
199
  for (const [ws, state] of clients) {
187
200
  if (!state.alive)
188
201
  ws.terminate();
package/dist/schema.d.ts CHANGED
@@ -773,6 +773,9 @@ export type WireMessage = {
773
773
  value?: unknown;
774
774
  error?: string;
775
775
  } | {
776
- type: 'ping' | 'pong';
776
+ type: 'ping';
777
+ activity?: true;
778
+ } | {
779
+ type: 'pong';
777
780
  };
778
781
  export declare function parseMessage(value: unknown): WireMessage;
package/dist/schema.js CHANGED
@@ -35,8 +35,8 @@ export function parseMessage(value) {
35
35
  case 'task.cancel': return { type: basic.type, id: z.string().uuid().parse(basic.id) };
36
36
  case 'resource.request': return { type: basic.type, requestId: z.string().uuid().parse(basic.requestId), request: resourceRequestSchema.parse(basic.request) };
37
37
  case 'resource.result': return z.object({ type: z.literal('resource.result'), requestId: z.string().uuid(), value: z.unknown().optional(), error: z.string().max(2000).optional() }).strict().parse(value);
38
- case 'ping':
39
- case 'pong': return { type: basic.type };
38
+ case 'ping': return basic.activity === true ? { type: 'ping', activity: true } : { type: 'ping' };
39
+ case 'pong': return { type: 'pong' };
40
40
  case 'session.accepted': return z.object({ type: z.literal('session.accepted'), label: z.string().max(120), fingerprint: z.string().max(100), credential: z.string().regex(/^D1\.[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{43}$/).optional() }).strict().parse(value);
41
41
  case 'session.closed': return z.object({ type: z.literal('session.closed'), reason: z.string().max(200) }).strict().parse(value);
42
42
  case 'task.started': return z.object({ type: z.literal('task.started'), id: z.string().uuid(), digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict().parse(value);
@@ -0,0 +1,3 @@
1
+ /** Default inactivity window after a temporary diagnostic connection is approved. */
2
+ export declare const DEFAULT_IDLE_MS: number;
3
+ export declare const LEGACY_RELAY_MAX_MS: number;