@masstensor/diagnose 0.3.0 → 0.5.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.
Files changed (62) hide show
  1. package/README.md +77 -111
  2. package/USER_GUIDE.md +567 -0
  3. package/deploy/Caddyfile +15 -1
  4. package/dist/agent-command.d.ts +4 -0
  5. package/dist/agent-command.js +33 -0
  6. package/dist/agent.d.ts +2 -0
  7. package/dist/agent.js +115 -0
  8. package/dist/cli.js +178 -22
  9. package/dist/discover.js +1 -1
  10. package/dist/engine.d.ts +2 -0
  11. package/dist/engine.js +37 -4
  12. package/dist/history.d.ts +13 -0
  13. package/dist/history.js +57 -0
  14. package/dist/journal.d.ts +23 -1
  15. package/dist/journal.js +82 -5
  16. package/dist/maintenance.d.ts +2 -0
  17. package/dist/maintenance.js +46 -0
  18. package/dist/mcp.d.ts +1 -1
  19. package/dist/mcp.js +21 -18
  20. package/dist/operator.d.ts +2 -0
  21. package/dist/operator.js +17 -5
  22. package/dist/pairing.d.ts +40 -0
  23. package/dist/pairing.js +92 -0
  24. package/dist/peer.d.ts +4 -0
  25. package/dist/peer.js +10 -3
  26. package/dist/resources.js +47 -26
  27. package/dist/schema.d.ts +2 -0
  28. package/dist/schema.js +2 -2
  29. package/dist/skill.d.ts +8 -0
  30. package/dist/skill.js +58 -0
  31. package/dist/transfers.js +28 -11
  32. package/dist/util.d.ts +2 -0
  33. package/dist/util.js +16 -3
  34. package/examples/skills/device-troubleshooting/SKILL.md +35 -0
  35. package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
  36. package/examples/skills/owon.md +27 -0
  37. package/npm-shrinkwrap.json +215 -5
  38. package/package.json +23 -5
  39. package/scripts/setup-node.ps1 +54 -0
  40. package/scripts/setup-node.sh +52 -0
  41. package/src/agent-command.ts +25 -0
  42. package/src/agent.ts +79 -0
  43. package/src/cli.ts +53 -20
  44. package/src/discover.ts +1 -1
  45. package/src/engine.ts +19 -4
  46. package/src/history.ts +43 -0
  47. package/src/journal.ts +41 -5
  48. package/src/maintenance.ts +30 -0
  49. package/src/mcp.ts +18 -16
  50. package/src/operator.ts +15 -6
  51. package/src/pairing.ts +64 -0
  52. package/src/peer.ts +6 -4
  53. package/src/resources.ts +35 -13
  54. package/src/schema.ts +4 -4
  55. package/src/skill.ts +44 -0
  56. package/src/transfers.ts +14 -3
  57. package/src/util.ts +14 -3
  58. package/test/agent.test.ts +104 -0
  59. package/test/pairing.test.ts +124 -0
  60. package/test/review.test.ts +128 -0
  61. package/test/setup.test.ts +16 -0
  62. package/test/skill.test.ts +25 -0
package/USER_GUIDE.md ADDED
@@ -0,0 +1,567 @@
1
+ # Diagnose user guide
2
+
3
+ Diagnose helps an AI agent remotely diagnose and resolve problems on a consenting user's computer or connected devices. The goal is to move from a reported symptom to an authorized fix and a checked result. The same probe can access the computer itself, a USB device, or a device reachable on its local network.
4
+
5
+ There are two people in a session:
6
+
7
+ - **User:** the person whose computer or connected device needs diagnosis. They run `diagnose start` and control permissions locally.
8
+ - **Diagnostician:** the person directing the AI agent. They run `diagnose agent codex`, `diagnose agent claude`, or `diagnose agent gemini` and give the agent the user's pairing code.
9
+
10
+ The AI runs on the diagnostician's side. The user does not need to install an AI agent or configure MCP.
11
+
12
+ ## Quick start
13
+
14
+ ### 1. Prepare both computers
15
+
16
+ Run the one-line setup command for your computer. It downloads our open-source installer, reuses existing Node.js without updating it, and installs Node.js/npm/npx only if Node.js is absent. No administrator access is normally needed.
17
+
18
+ **Windows:** open the Start menu, type **Windows PowerShell**, and open it. Paste:
19
+
20
+ ```powershell
21
+ curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String | Invoke-Expression
22
+ ```
23
+
24
+ **Mac:** press **Command + Space**, type **Terminal**, and press Return. **Linux:** open Terminal. Paste:
25
+
26
+ ```sh
27
+ curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
28
+ ```
29
+
30
+ Wait for **Setup complete** and three version numbers. Then close the terminal and open a fresh one before continuing, so a newly installed Node.js is available. On Windows, close all terminal windows and reopen Windows PowerShell from the Start menu. On Windows, use `npx.cmd` and `npm.cmd` wherever this guide says `npx` and `npm`; this avoids PowerShell script-policy errors without changing your security settings. See [setup details and troubleshooting](#first-time-setup-install-nodejs-and-npm) if setup fails.
31
+
32
+ Only the **diagnostician** needs an installed, signed-in Codex CLI, Claude Code, or Gemini CLI. The person receiving help needs no AI account.
33
+
34
+ ### 2. On the computer receiving help
35
+
36
+ ```sh
37
+ npx @masstensor/diagnose@latest start
38
+ ```
39
+
40
+ If npm asks to install the package, type `y`. Keep this terminal open. Send the complete `D1.…` code privately to your diagnostician.
41
+
42
+ ### 3. On the diagnostician's computer
43
+
44
+ ```sh
45
+ npx @masstensor/diagnose@latest agent codex
46
+ # Or replace codex with claude or gemini.
47
+ ```
48
+
49
+ In the agent conversation, provide the code and a concrete problem:
50
+
51
+ > Use Diagnose to connect to this code: D1.… . Investigate why the user's application fails to start. Explain the proposed fix before changing anything, apply only authorized changes, and verify that the application starts afterward.
52
+
53
+ ### 4. Approve, diagnose, and finish
54
+
55
+ 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.
56
+
57
+ The diagnostician directs the agent to investigate, repair within permission, and check the result. 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.
58
+
59
+ ### Return later or load a device procedure
60
+
61
+ **Requires v0.5.0+ on both computers.** Use a release supporting these options before following the additional commands below.
62
+
63
+ ```sh
64
+ npm install -g @masstensor/diagnose@latest
65
+ # Diagnostician: pair once while the user's probe is running.
66
+ diagnose pair --name alice-pc
67
+ # User: explicitly approve remembering this diagnostician.
68
+ # Diagnostician: use this whenever diagnosis is needed again.
69
+ diagnose agent codex --device alice-pc --skill ./devices/owon.md
70
+ ```
71
+
72
+ The skill file is your local Markdown procedure; create it first or omit `--skill`. The same flags work with `claude` and `gemini`. The user must keep `diagnose start` running, or start it again after a restart. Pairing survives; execution approval remains separately controlled. See [remembered pairing](#keep-a-device-paired-for-future-diagnosis) and [skills](#start-with-a-device-skill-or-markdown-task) for full details.
73
+
74
+ ## From a reported problem to a verified result
75
+
76
+ Use the session to work toward a concrete outcome:
77
+
78
+ 1. **Describe the problem.** Explain what fails, what you expected, and how to reproduce it. Agree on the check that will show whether the problem is resolved.
79
+ 2. **Investigate first.** Ask the agent to inspect the environment and collect relevant logs or other evidence. Distinguish confirmed facts from possible causes.
80
+ 3. **Review a repair plan.** Have the agent explain what it intends to change, why, the expected impact, and any recovery option. Where practical, preserve the original configuration before editing it.
81
+ 4. **Apply authorized changes.** The agent can use commands, scripts, file edits, and device tools under the user's existing permission mode. Only proceed within the agreed scope.
82
+ 5. **Verify the result.** Repeat the original failing action or an appropriate health check. Ask for a summary of what changed, the verification evidence, and anything still unresolved. An executed command alone does not establish that the user's problem is fixed.
83
+
84
+ These are instructions for directing the agent, not a separate enforced plan-approval system. The local task/channel permissions described below still apply. Automatic mode continues to allow execution and transmission under the user's grant; general automatic rollback is not provided.
85
+
86
+ You can also request a read-only investigation and stop after the explanation. Computer software, configuration, local services, networks, and connected hardware can all be investigated with the same general-purpose tools; successful fixes depend on the issue, available access, and the user's authorization.
87
+
88
+ ## 1. Requirements
89
+
90
+ Both computers need **Node.js 20.10 or later**, npm, an interactive terminal, and outbound access to the relay. The default relay is `https://diagnose.fenginwind.com`. No inbound port, router change, or SSH server is required.
91
+
92
+ For an AI session, the diagnostician must separately install and sign in to Codex CLI, Claude Code, or Gemini CLI. Diagnose does not install an agent, provide a model subscription, or change the agent's approval mode.
93
+
94
+ Node.js 20.10+ runtime compatibility is available in Diagnose 0.5.0+. Earlier Diagnose packages declare Node.js 22.18+; use a compatible Diagnose version rather than automatically upgrading the user's Node.js. The relay deployment wrapper requires Node.js 22+ separately.
95
+
96
+ Use the latest package on both endpoints. Session agent launchers require 0.3.1 or later; live resource features require 0.3 or later. macOS probes and the Linux relay have been tested. Automated CI runs the full suite on macOS/Linux and targeted history, transfer-conflict, long-session, encryption, and npm-launcher tests on Windows. Windows ConPTY, interactive authentication, and physical USB/serial behavior still need real-environment validation.
97
+
98
+ ## First-time setup: install Node.js and npm
99
+
100
+ If you are the person receiving help, this is the only software setup you need. You do **not** need a Codex, Claude, Gemini, or npm account. Your diagnostician runs the AI on their own computer.
101
+
102
+ **Node.js** runs Diagnose. **npm** downloads it. **npx** starts it without requiring a separate global installation. The official Node.js installer includes npm and npx; do not download them from separate websites.
103
+
104
+ ### Windows: copy and paste setup
105
+
106
+ Open the **Start** menu, type **Windows PowerShell**, and open it normally. Copy the complete block below, paste it into that window, and press Enter:
107
+
108
+ ```powershell
109
+ curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String | Invoke-Expression
110
+ ```
111
+
112
+ The script detects x64 or ARM64 automatically, checks Node.js/npm/npx, and installs into your user profile only if Node.js is absent. An existing version is never upgraded or replaced. Wait for **Setup complete**, close all terminal windows, and open Windows PowerShell again from the Start menu. Then run `npx.cmd @masstensor/diagnose@latest start`. No execution-policy change or administrator terminal is required. Windows support remains experimental; this installer has not yet had Windows hardware validation.
113
+
114
+ ### Mac or Linux: copy and paste setup
115
+
116
+ On a Mac, press **Command + Space**, type **Terminal**, and press Return. On Linux, open Terminal. Copy the entire block, paste it, and press Return:
117
+
118
+ ```sh
119
+ curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
120
+ ```
121
+
122
+ Wait for **Setup complete**, then close Terminal and open it again to load the new PATH. Run `npx @masstensor/diagnose@latest start` in the new window. If Node.js is absent, the script selects Intel/x64 or ARM64 automatically. It needs curl, tar, and a SHA-256 utility, which are included on macOS and common Linux desktop distributions. Linux requires a compatible official Node.js binary; minimal, musl-based or older distributions may need help from the diagnostician.
123
+
124
+ ### What setup changes
125
+
126
+ - Reuses a working Node.js **20.10+**, npm and npx without changes. If any Node.js installation exists, setup does not update it, replace it, change PATH, or repair missing npm automatically. An older or incomplete installation stops setup and explains the requirement.
127
+ - Only when Node.js is absent, downloads Node.js 22 binaries and SHA-256 checksums from **nodejs.org**, verifies the download, and installs under `~/.diagnose/node` on Mac/Linux or `%USERPROFILE%\.diagnose\node` on Windows.
128
+ - For a new installation only, configures the current user's PATH. On Mac it adds a guarded environment line to `.zshrc` and `.bash_profile`; on Linux, to `.bashrc` and `.profile`. It preserves other profile contents and avoids duplicate lines. On Windows it prepends the private runtime directory to your user PATH.
129
+ - Prints Node.js, npm and npx versions and stops on a download, checksum or verification error. It does not install an AI agent or start a diagnosis automatically.
130
+
131
+ You can read the [Mac/Linux script](https://diagnose.fenginwind.com/setup/setup-node.sh), [Windows script](https://diagnose.fenginwind.com/setup/setup-node.ps1), or [their source on GitHub](https://github.com/zkwasm/diagnose/tree/main/scripts) before running setup. The installer needs internet access to this website and nodejs.org. If installation is blocked by an organization policy, ask your diagnostician or IT administrator for help.
132
+
133
+ ### Check the installation
134
+
135
+ The setup script performs these checks automatically. To check again in Terminal or Windows Command Prompt, paste one line at a time (in PowerShell use `npm.cmd` and `npx.cmd`):
136
+
137
+ ```sh
138
+ node --version
139
+ npm --version
140
+ npx --version
141
+ ```
142
+
143
+ Each command should print a version number. The Node.js number begins with `v` and must be **20.10.0 or later**. npm and npx have their own version numbers; they do not need to match Node.js. If your installed Node.js already meets the requirement, you do not need to reinstall it.
144
+
145
+ You are now ready. Paste this single command into the same window and press Enter/Return:
146
+
147
+ ```sh
148
+ npx @masstensor/diagnose@latest start
149
+ ```
150
+
151
+ The first run downloads Diagnose and may take a little time. If npm asks whether to install `@masstensor/diagnose`, type `y` and press Enter. You do not need to run `npm login` or create an npm account. When the pairing code appears, installation is complete: keep the window open and send the code privately to your diagnostician. Continue with [Start on the user's computer](#2-start-on-the-users-computer) for the connection and approval details.
152
+
153
+ Copy only the command, not a leading dollar-sign prompt, the surrounding code-box marks, or example output. On a Mac, stopping the probe is **Control + C**, not Command + C.
154
+
155
+ ### If something goes wrong
156
+
157
+ | What you see | What to do |
158
+ | --- | --- |
159
+ | “node is not recognized” or “command not found” | Close and reopen Command Prompt/Terminal, then try again. If it still fails, run the setup block above again, or ask your diagnostician for help. |
160
+ | An older Node.js version | Setup leaves it unchanged. Share the detected version with your diagnostician; a separate runtime can be considered with your agreement. |
161
+ | npm or npx is missing | Setup leaves the existing Node.js unchanged. Ask your diagnostician to repair npm/npx or discuss a separate runtime. |
162
+ | PowerShell says `npm.ps1` or `npx.ps1` cannot run because scripts are disabled | Open **Command Prompt (cmd)** and run the same commands there. You do not need to change PowerShell's execution policy. |
163
+ | “EACCES”, “EPERM”, or “permission denied” during a global install | Use the `npx … start` command above instead of `npm install -g`. If that also fails, share the error with your diagnostician; do not add `sudo` or change folder permissions at random. |
164
+ | A download, certificate, or network error | Check your internet connection and ask your diagnostician or IT administrator for help. Do not disable certificate checks or your firewall. |
165
+ | A build/driver error, or the device is not listed | Share the error with the diagnostician. Node.js installation does not install every device's USB or serial driver. |
166
+
167
+ Official references: [Node.js downloads](https://nodejs.org/en/download) and [npm's Node.js/npm installation guide](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).
168
+
169
+ ## 2. Start on the user's computer
170
+
171
+ ```sh
172
+ npx @masstensor/diagnose@latest start
173
+ ```
174
+
175
+ Or install once:
176
+
177
+ ```sh
178
+ npm install -g @masstensor/diagnose@latest
179
+ diagnose start
180
+ ```
181
+
182
+ The terminal shows a pairing code beginning with `D1.` and the local audit log path. Keep it open. Share the **complete code privately** with the intended diagnostician. The initial invitation lasts 10 minutes. Treat the code as a secret; do not post it publicly or place it in shell arguments.
183
+
184
+ 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.
185
+
186
+ ## 3. Start the diagnostician's agent
187
+
188
+ Choose one:
189
+
190
+ ```sh
191
+ npx @masstensor/diagnose@latest agent codex
192
+ npx @masstensor/diagnose@latest agent claude
193
+ npx @masstensor/diagnose@latest agent gemini
194
+ ```
195
+
196
+ With a global installation, these become:
197
+
198
+ ```sh
199
+ diagnose agent codex
200
+ diagnose agent claude
201
+ diagnose agent gemini
202
+ ```
203
+
204
+ Do **not** separately run `diagnose mcp` or register a global MCP server. The launcher starts your chosen CLI with Diagnose MCP loaded for this launch, using the exact installed Diagnose version.
205
+
206
+ Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
207
+
208
+ > Use Diagnose to connect to pairing code D1.… . 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. Summarize what changed and anything still unresolved.
209
+
210
+ The code and diagnostic results enter your chosen AI provider's context. The user must still accept the connection on their own computer. Ask the agent to use the `diagnose_*` tools for remote actions: its normal shell and file tools still act on the diagnostician's computer.
211
+
212
+ ### Keep a device paired for future diagnosis
213
+
214
+ Requires **0.5.0+ on both computers**. Use this when the same diagnostician will return later. The user starts the probe as usual and shares the temporary code privately. On the diagnostician's computer, pair once:
215
+
216
+ ```sh
217
+ diagnose pair --name alice-pc
218
+ # Enter the user's code, then your label and AI provider when prompted.
219
+ ```
220
+
221
+ The user's terminal explicitly asks whether to **remember** this diagnostician. Check the label and fingerprint with each other before agreeing. Choose `y` to remember the relationship with per-task approval, or `a` to also grant automatic execution **and transmission for one hour**. The invitation is replaced by a new random private credential exchanged only inside the approved encrypted connection. Neither side prints that credential or sends it in process arguments. Each later connection has a fresh Noise handshake and encryption keys.
222
+
223
+ After pairing, the diagnostician can start, stop, and restart any supported agent using the same device name:
224
+
225
+ ```sh
226
+ diagnose agent codex --device alice-pc --skill ./devices/owon.md
227
+ diagnose agent claude --device alice-pc --skill ./devices/owon.md
228
+ diagnose agent gemini --device alice-pc --skill ./devices/owon.md
229
+ # --skill is optional.
230
+ ```
231
+
232
+ Tell the agent what problem to resolve and to use Diagnose. The MCP tools connect to the saved device when first used; no pairing code is needed. The device name identifies the user's computer, not a particular USB device. The selected task can identify the actual device to investigate. Each agent still uses its own login and local tool permissions.
233
+
234
+ Keep `diagnose start` running on the user's computer. It re-registers with the relay after a dropped connection. If it is stopped or the computer restarts, run `diagnose start` again: the pairing and its saved permission expiry remain. This release does not install a background service or start at login. One probe accepts one remembered diagnostician at a time; a diagnostician can save multiple user computers. Use local `unpair` before pairing a different diagnostician.
235
+
236
+ **Remembering is separate from automatic approval.** The default is still per-task approval. In the user's running probe terminal:
237
+
238
+ | Command | Effect |
239
+ | --- | --- |
240
+ | `pairing` | Show the remembered diagnostician and automatic grant expiry. |
241
+ | `permissions auto`, then `permissions allow-auto` | Grant one hour of automatic execution and transmission, across reconnects and restarts. |
242
+ | `permissions auto forever`, then `permissions allow-auto` | Explicitly grant automatic execution and transmission until revoked locally. |
243
+ | `permissions ask` | Revoke automatic permission, cancel work/resources, keep the pairing. |
244
+ | `pause` | Disconnect and block access while retaining the pairing and its original grant expiry. |
245
+ | `resume` | Allow connections again. An expired grant does not become valid again. |
246
+ | `unpair` | Revoke the private credential, cancel work/resources, and return to a new invitation. |
247
+ | `exit` or `Ctrl+C` | Stop access and close resources. Remembered pairing remains for the next start. |
248
+
249
+ Time disconnected counts toward a timed grant. Restarting an agent, probe, or relay does not renew it. Pausing does not extend it. The remote agent cannot change this policy. A continuously authorized diagnostician still has the user's OS permissions; results may reach their AI provider.
250
+
251
+ On the diagnostician's computer:
252
+
253
+ ```sh
254
+ diagnose devices
255
+ diagnose connect --device alice-pc
256
+ diagnose terminal --device alice-pc
257
+ diagnose mcp --device alice-pc
258
+ diagnose forget --device alice-pc
259
+ ```
260
+
261
+ `devices` lists local pairings, not live online status. `forget` removes only the diagnostician's local copy. To invalidate a credential, the user must run `unpair` in their probe terminal. If initial pairing is interrupted before the diagnostician saves it, use `unpair` and pair again. Losing local pairing files requires pairing again.
262
+
263
+ A new MCP operation will reconnect to a remembered device for up to 30 seconds if needed. **No already-sent command, input, upload commit, or other modification is automatically retried.** An interrupted task can have an uncertain outcome; inspect state before retrying. Old task IDs are not carried into a new connection. Retained resources require their original resource ID, recovery credential, and authorization; see [Disconnect and recover](#6-disconnect-and-recover).
264
+
265
+ ## Start with a device skill or Markdown task
266
+
267
+ Version **0.4.0+** can start the agent with a selected diagnostic procedure. The syntax is identical for all three agents:
268
+
269
+ ```sh
270
+ diagnose agent codex --skill ./devices/owon.md
271
+ diagnose agent claude --skill ./devices/owon.md
272
+ diagnose agent gemini --skill ./devices/owon.md
273
+ ```
274
+
275
+ Use a local UTF-8 `.md` or `.markdown` file, up to 256 KiB. A directory containing `SKILL.md` also works:
276
+
277
+ ```sh
278
+ diagnose agent codex --skill ./skills/my-device
279
+ ```
280
+
281
+ For example:
282
+
283
+ ```text
284
+ skills/my-device/
285
+ SKILL.md
286
+ references/device-profile.md
287
+ scripts/check-device.js
288
+ ```
289
+
290
+ The launcher reads and validates the entry before starting the agent, saves a private `0600` session snapshot with its source path, reference directory, and SHA-256, and supplies an initial task to read that snapshot and begin. The instruction text is not placed in process arguments. The adapter adds only the private task subdirectory to the agent's session working directories so its file tools can read the snapshot. Gemini's temporary settings and login links are outside that task subdirectory. The original skill directory is not automatically added; reading its references may still require the agent's normal local permission. The snapshot is removed when the launcher exits normally or handles termination. An uncatchable kill or power loss can leave temporary files behind.
291
+
292
+ The agent follows the entry, reads references as needed, and works toward diagnosis, authorized repair, and verification. If a pairing code, target identity, or necessary detail is missing, it asks before continuing. Do not store pairing codes, credentials, or other secrets in reusable task files; selected instructions and referenced material that the agent reads can enter the AI provider's context.
293
+
294
+ Relative references resolve against the original entry directory, not the temporary snapshot. Keep that directory available during the session. Only the entry is snapshotted; referenced files are read from the original directory. Scripts are not executed by the launcher merely because they exist. The agent runs them only as required by the task and existing permissions.
295
+
296
+ Referenced scripts initially live on the diagnostician computer. To use one remotely, the agent must explicitly submit its contents or transfer it to the user's computer with authorization. A path on one endpoint is not automatically a path on the other.
297
+
298
+ ### Writing a reusable procedure
299
+
300
+ Describe:
301
+
302
+ - The supported device or problem and the desired verification check.
303
+ - How to identify the target, and what missing information to ask for.
304
+ - Read-only evidence to collect and how to interpret it.
305
+ - Permitted repairs, their impact, prohibited actions, and available recovery steps.
306
+ - How to verify the original problem and report unresolved issues.
307
+
308
+ A minimal task could be:
309
+
310
+ ```markdown
311
+ # Local service troubleshooting
312
+
313
+ Start now using Diagnose MCP. Ask for the pairing code and target service
314
+ if missing. Pair and wait for local consent. Inspect logs and configuration
315
+ without changing them first. Explain the likely cause and repair plan.
316
+ Apply only authorized changes, repeat the original failing check, and
317
+ report what changed, the evidence, and anything unresolved.
318
+ ```
319
+
320
+ The package includes `examples/skills/owon.md` and `examples/skills/device-troubleshooting/SKILL.md` with a referenced profile template. They are templates, not verified universal repair recipes. Customize them for the actual device and authorization scope. [Browse or download the examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
321
+
322
+ ### Permissions and compatibility
323
+
324
+ The task starts automatically; permissions do not change automatically. Remote pairing and local user consent still apply. For continuous execution and transmission, the user can explicitly choose session auto mode. The coding agent's own tool approvals may still appear; Diagnose does not bypass them.
325
+
326
+ This is portable Markdown task loading, not native installation of a Codex, Claude, or Gemini skill. Frontmatter can remain in the file as text. Vendor-specific hooks, tool names, scripts, and dependencies are not automatically translated or installed. Use `diagnose_*` names for remote tools and adapt any agent-specific instructions.
327
+
328
+ With `--skill`, use native startup flags such as `--model` after `--`; do not also supply a separate prompt, headless prompt option, resume command, or another CLI subcommand. Gemini explicitly rejects a second prompt option. Use the normal launcher without `--skill` for those other modes.
329
+
330
+ ### Session configuration and extra arguments
331
+
332
+ ```sh
333
+ diagnose agent codex --relay https://your-relay.example -- --model your-model
334
+ ```
335
+
336
+ Options before `--` belong to Diagnose. Everything after it is passed literally to the agent, without a shell. Do not put pairing codes, passwords, or recovery credentials in these arguments.
337
+
338
+ - **Codex:** receives temporary `-c` MCP overrides.
339
+ - **Claude Code:** receives a temporary `--mcp-config` value.
340
+ - **Gemini CLI:** uses a private temporary user configuration directory. Diagnose copies the user settings, adds its MCP entry, and links existing login/history files. Administrator policies and workspace trust checks remain in effect. On Windows, directories use junctions and login files are copied into the private temporary directory, avoiding administrator-only file symlinks. Sign in with the native Gemini CLI first; changes to copied login files in this session are not saved back. The directory is removed on normal exit; changes to user settings in this Gemini session are not written back to the original `settings.json`.
341
+
342
+ The launcher does not add a permanent MCP entry. Other MCP servers already configured in your agent may still load. If you previously registered Diagnose globally, remove that entry separately if you no longer want it in ordinary sessions. An uncatchable kill or power loss may leave a temporary directory behind.
343
+
344
+ ## 4. Choose permissions on the user's computer
345
+
346
+ At the connection prompt:
347
+
348
+ | Choice | Effect |
349
+ | --- | --- |
350
+ | `y` | Approve the session, then review each operation or batch and its result transmission. |
351
+ | `a` | Authorize automatic execution **and automatic transmission** for this temporary session. Subsequent tasks do not prompt again. |
352
+ | `N` or Enter | Refuse the connection. |
353
+
354
+ In manual mode, a batch has one execution approval and one combined result approval, rather than one prompt per step. Complete scripts are approved as a whole, not line by line.
355
+
356
+ Opening a live process, file transfer, or network tunnel asks for permission to its **continuing raw input/output before the resource is created**. Once granted, input, reads, resizing, signals, and connections within that handle's scope do not prompt again.
357
+
358
+ Automatic mode is powerful: commands run with the user's OS permissions and results go directly to the diagnostician and their AI. The probe is not a sandbox. Arbitrary programs can have side effects that Diagnose cannot fully observe or undo.
359
+
360
+ ### Local session controls
361
+
362
+ Type these into the user's probe terminal:
363
+
364
+ | Command | Effect |
365
+ | --- | --- |
366
+ | `permissions` | Show the current mode. |
367
+ | `permissions ask` | Revoke automatic approval, cancel active work and resources, and require approval again. |
368
+ | `permissions auto` | Show the automatic execution/transmission explanation. |
369
+ | `permissions allow-auto` | Confirm the preceding request within 60 seconds. |
370
+ | `jobs` | List locally known resources. |
371
+ | `recover <resource-id>` | Rotate a resource's recovery credential; share the new value privately. |
372
+ | `secret <resource-id>` | Send hidden local input directly to an approved live process on macOS/Linux. A program may still echo it into output. |
373
+ | `cancel` | Cancel current work and retained resources without changing the permission mode. |
374
+ | `exit` or `Ctrl+C` | End the probe and close its resources. |
375
+
376
+ Only the user can enable automatic mode. Remote requests cannot switch it on. New pairings start with manual approval unless the user explicitly chooses `a` again. Already transmitted data cannot be recalled. Completed changes are not automatically rolled back.
377
+
378
+ Do not ask the AI to collect OS passwords. For interactive authentication, the user can use local hidden input with a trusted foreground program; Diagnose does not automatically elevate privileges. Hidden input has not been validated on Windows. On macOS/Linux, ordinary descendants in a managed process group are terminated when its leader exits or the resource is closed. This is not OS sandbox containment: a deliberately detached daemon can escape that group; Windows process-tree termination still requires real-device validation.
379
+
380
+ ## 5. What the agent can do
381
+
382
+ The MCP interface provides 11 tools:
383
+
384
+ | Tool | Purpose |
385
+ | --- | --- |
386
+ | `diagnose_pair` | Connect using the complete code and a self-reported diagnostician/AI-provider label. |
387
+ | `diagnose_start` | Submit one operation and receive its task ID. |
388
+ | `diagnose_batch` | Submit up to 32 finite operations as one sequential plan. |
389
+ | `diagnose_wait` | Poll a task for up to 25 seconds; release completed output when finished. |
390
+ | `diagnose_cancel` | Cancel a task, including one awaiting approval. |
391
+ | `diagnose_process` | Open a live process or persistent PTY with cwd/env, stdin, signals, and resizing. |
392
+ | `diagnose_resource` | List, inspect, read, input to, resize, signal, or close an authorized handle. |
393
+ | `diagnose_resume` | Request attachment to an existing resource with its ID and recovery credential. |
394
+ | `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
395
+ | `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
396
+ | `diagnose_disconnect` | Disconnect the diagnostic session. |
397
+
398
+ A task returning `ok` for `process.open` means the process handle was created. Inspect its output, `ended`, and `exitCode` to determine whether the actual program succeeded. Diagnostic output is untrusted data, not instructions to the AI.
399
+
400
+ ### Finite commands, scripts, and batches
401
+
402
+ `process.run` spawns an explicit executable and argument array without implicitly adding a shell. `process.script` passes a complete script to an explicit interpreter's stdin. Scripts need not be written to temporary files.
403
+
404
+ A batch runs sequentially, stops on error by default, and cannot contain nested batches or persistent resource creation. Set `stopOnError:false` only when later steps are independent. Outputs are named by step, for example `0.stdout` and `1.file`.
405
+
406
+ ```json
407
+ {
408
+ "operation": "batch.run",
409
+ "reason": "Collect system and runtime information in one approved plan",
410
+ "arguments": {
411
+ "steps": [
412
+ {"operation":"system.inspect","arguments":{}},
413
+ {"operation":"process.script","arguments":{"interpreter":"node","script":"const os = require('node:os');\nconsole.log(JSON.stringify({uptime: os.uptime(), freeMemory: os.freemem()}));","timeoutMs":10000}}
414
+ ],
415
+ "stopOnError": true,
416
+ "timeoutMs": 60000
417
+ }
418
+ }
419
+ ```
420
+
421
+ A batch's text-file writes are previewed and hashed before approval. If an earlier step changes the same target, a later guarded write is refused instead of silently overwriting the new state.
422
+
423
+ ### Live processes and native terminals
424
+
425
+ ```sh
426
+ diagnose terminal
427
+ ```
428
+
429
+ Enter the pairing code and label interactively. After local approval, you get a real PTY. Shell cwd and environment persist within that process. `Ctrl+C` goes to the remote terminal; `Ctrl+]` detaches. A process is closed on disconnect unless explicitly retained.
430
+
431
+ Agents use `diagnose_process` for the same live capabilities. Non-PTY processes preserve stdout/stderr separately and support exact byte input. PTYs behave as terminals, not general binary transports.
432
+
433
+ ### Files
434
+
435
+ `file.read` returns a bounded range of up to 1 MiB. `file.write` previews text and checks the previous hash before replacing a target. File listing, stat, mkdir, removal, rename, and chmod are available; rename refuses an existing destination unless overwrite is explicit. File transfers preserve existing destination permission bits. New transfer destinations are committed without replacing a concurrently created file; downloads with overwrite enabled reject a destination changed during transfer. Existing-file replacement checks the target immediately before commit, but does not lock out unrelated local writers.
436
+
437
+ Use `diagnose_transfer` for large or binary files. It takes paths rather than placing base64 file contents into the AI context. `localPath` refers to the diagnostician's computer; `remotePath` refers to the user's computer.
438
+
439
+ Uploads use a private staging file. Exact size, SHA-256, destination hash, and parent-directory checks must pass before replacement. Downloads use `.diagnose.part` plus a private `.diagnose.json` recovery sidecar. A completed download is verified before replacement. Overwriting an existing destination must be explicit. Raw file bytes are not redacted.
440
+
441
+ ### TCP forwarding
442
+
443
+ First authorize `net.forward`, wait for its resource ID, then use `diagnose_forward` to open the corresponding endpoint.
444
+
445
+ - `local`: a loopback listener on the diagnostician's computer reaches a fixed target accessible from the user's computer.
446
+ - `remote`: a loopback listener on the user's computer forwards to a declared target on the diagnostician's side.
447
+ - `socks`: a SOCKS5 TCP listener on the diagnostician's loopback interface reaches targets from the user's side, restricted by `allowedHosts`.
448
+
449
+ SOCKS defaults to `allowedHosts:["*"]`, which permits any target. Narrow it when possible. Listeners are loopback-only. UDP, TUN, public listeners, SSH agent forwarding, and X11 forwarding are not implemented. Tunnel bytes are not redacted.
450
+
451
+ ### Serial devices
452
+
453
+ `system.inspect` lists serial ports. `serial.capture` reads a selected port; `serial.exchange` first sends explicitly authorized `dataHex`. Both use 8N1 with DTR/RTS set false. Opening a port can still reset some hardware. Verify the selected device and avoid opening unrelated ports.
454
+
455
+ ## 6. Disconnect and recover
456
+
457
+ When a connection drops, finite jobs are cancelled and serial handles close. With a remembered pairing, the probe stays available and the next new MCP operation reconnects without another code. For temporary sessions, the probe displays a new code and requires local connection consent again. Resume retained resources explicitly using their original IDs and recovery credentials. Diagnose never silently replays a creation command.
458
+
459
+ Ordinary live processes default to `retainOnDisconnect:false`; file transfers default to retained. A retained live process survives network loss only while the original probe process remains running. If the probe itself disappears, a new probe can recover encrypted saved output and supported file staging, but cannot take over the old process's PTY. Network connections must be recreated.
460
+
461
+ For download resume, keep the partial file and sidecar together. Upload resume uses the resource ID and recovery credential reported in progress. If a response is lost during a modifying action, inspect resource status before retrying; do not blindly restart the command.
462
+
463
+ ## 7. Limits and timeouts
464
+
465
+ | Limit | Default / maximum |
466
+ | --- | --- |
467
+ | Invitation | 10 minutes |
468
+ | Temporary session idle / total | 10 minutes / 60 minutes by default |
469
+ | Remembered pairing | Until revoked locally; requires the foreground probe |
470
+ | Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
471
+ | Finite command or script | 60 seconds by default; 300 seconds maximum |
472
+ | Batch | Up to 32 steps; 300 seconds; 10 MiB combined output |
473
+ | Concurrent finite jobs | 4 |
474
+ | Active live resource handles | 128 |
475
+ | Live process | 1 hour by default; `timeoutMs:0` removes its timer |
476
+ | Retained output per live process | 64 MiB by default; 1 GiB maximum; reaching the cap terminates the process |
477
+ | Relay session | At most 7 days, also subject to cipher frame limits |
478
+
479
+ ```sh
480
+ diagnose start --session-minutes 240 --idle-minutes 30
481
+ ```
482
+
483
+ 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.
484
+
485
+ ## 8. Manual operation and other MCP clients
486
+
487
+ ```sh
488
+ diagnose connect
489
+ ```
490
+
491
+ Enter task JSON on one line. Requests return a task ID. Use `wait <task-id>`, `cancel <task-id>`, `resources`, `read <resource-id> [cursor]`, `input <resource-id> "text\n"`, `resize <resource-id> 120 40`, `signal <resource-id> SIGINT`, and `close <resource-id>`.
492
+
493
+ `forward <resource-id> [local-port]` opens an approved forward. `upload` and `download` accept JSON with `localPath`, `remotePath`, `reason`, and optional `overwrite`, `resumeId`, and `resumeToken`.
494
+
495
+ For another stdio MCP client, configure it to launch:
496
+
497
+ ```json
498
+ {"mcpServers":{"diagnose":{"command":"diagnose","args":["mcp"]}}}
499
+ ```
500
+
501
+ This is a local child process, not a public HTTP MCP endpoint. Running `diagnose mcp` in a separate terminal does not automatically connect it to an agent.
502
+
503
+ The direct commands accept an optional relay URL, for example `diagnose start https://your-relay.example` and `diagnose mcp https://your-relay.example`. Remote relays require HTTPS/WSS; HTTP/WS is allowed only for loopback testing.
504
+
505
+ ## Security and local data
506
+
507
+ Remembered pairing credentials and policy are stored encrypted under `~/.diagnose/pairings`, with a local key in that protected directory (directory `0700`, files `0600` where supported). This protects stored contents from casual access, not a compromised OS account or a backup containing both ciphertext and key. Possession of a relationship credential authenticates that relationship, not a person’s legal identity. Revocation removes the user-side credential and terminates access. Stable relay routing identifiers can correlate repeated connections; the relay still sees connection metadata.
508
+
509
+
510
+ Diagnose uses Noise `NNpsk0_25519_ChaChaPoly_BLAKE2b`, a random 256-bit pairing secret, ephemeral X25519 keys, independent direction counters, and routing/role/version binding. Tests include a public Cacophony test vector. Each direction is limited to one million frames, below the dependency's 32-bit counter boundary. WSS also validates the relay certificate. No independent security audit has been completed.
511
+
512
+ The relay keeps rooms and ciphertext buffers in memory. It does not persist diagnostic contents, endpoint decryption keys, or offline messages. It can see IP addresses, routing identifiers, connection timing, and traffic volume, and can deny service. A self-reported label is not verified identity.
513
+
514
+ The diagnostician, their endpoint software, and their AI provider can see results. Do not share a code or approve a session with someone you do not intend to trust.
515
+
516
+ ### Audit logs
517
+
518
+ `~/.diagnose/audit-*.jsonl` uses mode `0600`. Events record task IDs, operation types, target paths/executables/interpreters, ranges and serial settings, argument digests, decisions, collection/transmission byte counts, cancellations, and outcomes. Batch steps include their parent task and individual status. Automatic mode records its permission changes and automatic approvals.
519
+
520
+ Built-in file mutations record paths and, where available, before/after hashes and byte counts. JSONL audit logs contain metadata only; the separate encrypted history below stores full tasks and finite collected results. Neither is a filesystem monitor: arbitrary programs can change files, services, and devices outside the built-in operations. Audit writes are flushed; an unwritable audit log stops the affected operation. Metadata logs rotate at 8 MiB; inactive archives are pruned after seven days or when their aggregate budget exceeds 32 MiB.
521
+
522
+ ### Review local history and clean up
523
+
524
+ Available in **0.5.0+** on the computer receiving help:
525
+
526
+ ```sh
527
+ diagnose history
528
+ diagnose show TASK_ID
529
+ diagnose show RESOURCE_ID --cursor 0
530
+ diagnose cleanup
531
+ # Remove all inactive local history and resources now:
532
+ diagnose cleanup --days 0
533
+ ```
534
+
535
+ History records exact requested commands or scripts, approval previews, decisions, finite collected results (including results the user declined to send), attempted transfers, and known built-in changes. A completed send records that the local transport accepted it, not proof that a human read it. Continuous process output is stored in the resource journal; `show` returns a page with a cursor for the next page. Remote process input is recorded locally; hidden input entered with `secret` records only its byte count. Raw tunnel traffic and exact transferred file bodies are not duplicated in task history; their scope, paths, hashes, and traffic counts are recorded. Arbitrary script side effects and automatic rollback are not provided.
536
+
537
+ Full history can contain sensitive data, even if results were never sent. It is encrypted locally in `~/.diagnose/history`, with the key beside it under the same user account. This protects against casual file inspection, not someone controlling that account. History is not automatically uploaded and has no dedicated remote MCP tool. An authorized remote command still has your OS account's file access.
538
+
539
+ History and resource journals each have a **256 MiB / 2,000-record** budget. Inactive records expire after **seven days** and may be evicted sooner to stay within budget. Maintenance runs when storage is used and when `cleanup` is requested. Live retained resources are protected; if they exhaust the budget, collection stops rather than growing without bound. Close unused jobs before cleaning up. Abandoned upload staging files are removed with expired resource records; destination files and remembered pairings are never deleted by cleanup. Upload staging bytes are separate from the journal budget and consume space beside the destination.
540
+
541
+ Both endpoints at 0.5.0+ use increasing task sequence numbers, so a connection can run more than 1,000 tasks while rejecting replayed sequences. The diagnostician retains at most 128 task results and 32 MiB in memory; save needed results or use local history before they expire. Older clients retain the 1,000-task limit and require an explicit reconnect. Neither path automatically repeats a modifying command.
542
+
543
+ ### Saved output and recovery data
544
+
545
+ Raw live output and recovery metadata are stored under `~/.diagnose/resources` using AES-256-GCM records. The local key has mode `0600` in the same account's directory. This protects stored ciphertext from casual inspection, not an attacker who controls that OS account and can read the key. Saved output is not automatically pruned; clean it up when it is no longer needed.
546
+
547
+ Finite text results receive best-effort common-credential redaction and terminal-control filtering. Regexes cannot identify every secret. Live terminals, exact file transfers, and TCP channels retain raw data and are not redacted. Collection and transmission are audited separately.
548
+
549
+ Commands run with the current user's OS permissions. Diagnose neither provides a sandbox nor automatically elevates privileges. It cannot completely observe arbitrary process side effects, undo completed modifications, or isolate against hostile local concurrent changes.
550
+
551
+ ## Troubleshooting
552
+
553
+ - **Agent CLI not found:** install and sign in to that CLI separately, and ensure it is on `PATH`.
554
+ - **No Diagnose tools:** use `diagnose agent <name>` to start a new agent session. An already running unrelated agent will not acquire the new MCP automatically.
555
+ - **Invitation expired or connection refused:** keep the probe open and use its latest complete code; the user must accept locally.
556
+ - **Gemini trust or account error:** complete its normal workspace trust and authentication flow. Diagnose does not bypass these checks.
557
+ - **Resource not attached:** request `diagnose_resume` after the new pairing, with the original ID and recovery credential.
558
+ - **Upload/download hash mismatch:** do not replace the destination. Confirm the source has not changed and inspect transfer status before retrying.
559
+ - **Missing serial device:** verify the cable carries data, check OS drivers and permissions, and list ports again. Opening a port may reset the device.
560
+
561
+ ## Source, hosting, and video
562
+
563
+ [Source and issues](https://github.com/zkwasm/diagnose) · [npm package](https://www.npmjs.com/package/@masstensor/diagnose)
564
+
565
+ The public relay is hosted at `diagnose.fenginwind.com`. You can self-host using the deployment templates in the repository. Keep local credentials, hardware logs, firmware, and resource journals out of server deployments and public packages.
566
+
567
+ The [one-minute English walkthrough](https://diagnose.fenginwind.com/#walkthrough) covers the current agent launcher, local permissions, encrypted transport, investigation, authorized repair, and verification. It includes English narration and captions. The port-mismatch repair is an illustrative example, not a live diagnosis. The earlier Chinese video is retained separately.
package/deploy/Caddyfile CHANGED
@@ -1,3 +1,17 @@
1
1
  diagnose.fenginwind.com {
2
- reverse_proxy 127.0.0.1:8792
2
+ encode zstd gzip
3
+ @relay path /v1/connect /healthz /downloads/*
4
+ handle @relay {
5
+ reverse_proxy 127.0.0.1:8792
6
+ }
7
+ handle {
8
+ root * /var/www/diagnose/current
9
+ header {
10
+ X-Content-Type-Options nosniff
11
+ Referrer-Policy strict-origin-when-cross-origin
12
+ Permissions-Policy "camera=(), microphone=(), geolocation=()"
13
+ Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; media-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'"
14
+ }
15
+ file_server
16
+ }
3
17
  }
@@ -0,0 +1,4 @@
1
+ export declare function agentCommand(name: string, args: string[], env: NodeJS.ProcessEnv, platform?: string): Promise<{
2
+ command: string;
3
+ args: string[];
4
+ }>;
@@ -0,0 +1,33 @@
1
+ import { access, readFile } from 'node:fs/promises';
2
+ import { join, resolve, relative, isAbsolute, dirname } from 'node:path';
3
+ // npm's Windows .cmd wrappers are not executables. Resolve their Node entry
4
+ // point instead of interpolating user prompts or JSON through cmd.exe.
5
+ export async function agentCommand(name, args, env, platform = process.platform) {
6
+ if (platform !== 'win32')
7
+ return { command: name, args };
8
+ const path = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
9
+ for (const directory of path.split(';').filter(Boolean)) {
10
+ for (const extension of ['.exe', '.cmd']) {
11
+ const candidate = join(directory.replace(/^"|"$/g, ''), name + extension);
12
+ try {
13
+ await access(candidate);
14
+ }
15
+ catch {
16
+ continue;
17
+ }
18
+ if (extension === '.exe')
19
+ return { command: candidate, args };
20
+ const wrapper = await readFile(candidate, 'utf8');
21
+ const match = /"%dp0%[\\/]([^"\r\n]+\.(?:cjs|mjs|js))"/i.exec(wrapper);
22
+ if (!match)
23
+ throw new Error(`Unsupported ${name}.cmd launcher. Install the official npm package or native executable; Diagnose will not pass prompts through a shell.`);
24
+ const entry = resolve(dirname(candidate), match[1].replace(/\\/g, '/'));
25
+ const diff = relative(dirname(candidate), entry);
26
+ if (diff.startsWith('..') || isAbsolute(diff))
27
+ throw new Error('Agent npm entry point is outside its installation directory');
28
+ await access(entry);
29
+ return { command: process.execPath, args: [entry, ...args] };
30
+ }
31
+ }
32
+ throw new Error(`${name} was not found on PATH. Install and sign in to its CLI first.`);
33
+ }
@@ -0,0 +1,2 @@
1
+ export declare const agentUsage = "diagnose agent codex|claude|gemini [--device NAME] [--skill FILE.md|DIRECTORY] [--relay URL] [-- agent arguments...]";
2
+ export declare function launchAgent(argv: string[]): Promise<number>;