@masstensor/diagnose 0.3.2 → 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 (61) hide show
  1. package/README.md +46 -7
  2. package/USER_GUIDE.md +305 -12
  3. package/dist/agent-command.d.ts +4 -0
  4. package/dist/agent-command.js +33 -0
  5. package/dist/agent.d.ts +1 -1
  6. package/dist/agent.js +38 -8
  7. package/dist/cli.js +173 -22
  8. package/dist/discover.js +1 -1
  9. package/dist/engine.d.ts +2 -0
  10. package/dist/engine.js +37 -4
  11. package/dist/history.d.ts +13 -0
  12. package/dist/history.js +57 -0
  13. package/dist/journal.d.ts +23 -1
  14. package/dist/journal.js +82 -5
  15. package/dist/maintenance.d.ts +2 -0
  16. package/dist/maintenance.js +46 -0
  17. package/dist/mcp.d.ts +1 -1
  18. package/dist/mcp.js +21 -18
  19. package/dist/operator.d.ts +2 -0
  20. package/dist/operator.js +17 -5
  21. package/dist/pairing.d.ts +40 -0
  22. package/dist/pairing.js +92 -0
  23. package/dist/peer.d.ts +4 -0
  24. package/dist/peer.js +10 -3
  25. package/dist/resources.js +47 -26
  26. package/dist/schema.d.ts +2 -0
  27. package/dist/schema.js +2 -2
  28. package/dist/skill.d.ts +8 -0
  29. package/dist/skill.js +58 -0
  30. package/dist/transfers.js +28 -11
  31. package/dist/util.d.ts +2 -0
  32. package/dist/util.js +16 -3
  33. package/examples/skills/device-troubleshooting/SKILL.md +35 -0
  34. package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
  35. package/examples/skills/owon.md +27 -0
  36. package/npm-shrinkwrap.json +199 -3
  37. package/package.json +11 -5
  38. package/scripts/setup-node.ps1 +54 -0
  39. package/scripts/setup-node.sh +52 -0
  40. package/src/agent-command.ts +25 -0
  41. package/src/agent.ts +30 -7
  42. package/src/cli.ts +51 -20
  43. package/src/discover.ts +1 -1
  44. package/src/engine.ts +19 -4
  45. package/src/history.ts +43 -0
  46. package/src/journal.ts +41 -5
  47. package/src/maintenance.ts +30 -0
  48. package/src/mcp.ts +18 -16
  49. package/src/operator.ts +15 -6
  50. package/src/pairing.ts +64 -0
  51. package/src/peer.ts +6 -4
  52. package/src/resources.ts +35 -13
  53. package/src/schema.ts +4 -4
  54. package/src/skill.ts +44 -0
  55. package/src/transfers.ts +14 -3
  56. package/src/util.ts +14 -3
  57. package/test/agent.test.ts +53 -6
  58. package/test/pairing.test.ts +124 -0
  59. package/test/review.test.ts +128 -0
  60. package/test/setup.test.ts +16 -0
  61. package/test/skill.test.ts +25 -0
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Diagnose
2
2
 
3
- **Give your AI agent a temporary, user-approved connection to another computer.**
3
+ **Diagnose and fix problems remotely with your AI agent.**
4
4
 
5
- Diagnose is an open-source remote diagnostics probe for computers, USB devices, and devices on a user's local network. It connects Codex, Claude Code, Gemini CLI, or another MCP client to a user-controlled CLI through an end-to-end encrypted relay.
5
+ Diagnose is an open-source tool for agent-led remote troubleshooting and problem resolution. It gives Codex, Claude Code, Gemini CLI, or another MCP client the remote tools to investigate a user's computer or connected device, apply authorized fixes, and verify the result. A user-controlled probe and an end-to-end encrypted relay provide the connection.
6
6
 
7
7
  [User guide](USER_GUIDE.md) · [Source](https://github.com/zkwasm/diagnose) · [npm](https://www.npmjs.com/package/@masstensor/diagnose) · [Website](https://diagnose.fenginwind.com)
8
8
 
9
- Requires **Node.js 22.18+**. MIT licensed. TypeScript source is included in the npm package. macOS probes and the Linux relay have been tested; Linux and Windows probes remain experimental.
9
+ Requires **Node.js 20.10+**. MIT licensed. TypeScript source is included in the npm package. macOS probes and the Linux relay have been tested. CI covers macOS/Linux and targeted Windows regressions; Windows interactive terminals and physical USB/serial behavior still need real-environment validation.
10
10
 
11
11
  ## Quick start
12
12
 
@@ -27,7 +27,7 @@ npx @masstensor/diagnose@latest agent codex
27
27
 
28
28
  The agent launcher requires **0.3.1+**. It loads Diagnose MCP for this launch without adding a permanent MCP entry. Tell the agent:
29
29
 
30
- > Use Diagnose to connect to this pairing code: D1.… . Inspect the user's connected device and collect its logs. Only read data; do not modify configuration.
30
+ > Use Diagnose to connect to this 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 and report anything still unresolved.
31
31
 
32
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.
33
33
 
@@ -40,7 +40,44 @@ diagnose start
40
40
  diagnose agent codex
41
41
  ```
42
42
 
43
- ## What it can do
43
+ ## Pair once, return later
44
+
45
+ Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
46
+
47
+ ```sh
48
+ diagnose pair --name alice-pc
49
+ # Enter the temporary code and your label/provider; user confirms remembering.
50
+ diagnose agent codex --device alice-pc --skill ./devices/owon.md
51
+ # Same options for claude or gemini; --skill is optional.
52
+ ```
53
+
54
+ Restart the agent whenever needed without a new code. Pairing persists across probe restarts, but access requires the foreground probe. Task approval remains the default. The user may grant automatic execution and transmission for one hour, or explicitly until revoked. Local `pause`, `permissions ask`, and `unpair` control access. Interrupted modifications are never automatically replayed. See the [pairing guide](USER_GUIDE.md#keep-a-device-paired-for-future-diagnosis).
55
+
56
+ ## Start with a device skill or Markdown task
57
+
58
+ Requires **0.4.0+**. Use the same option with every supported agent:
59
+
60
+ ```sh
61
+ diagnose agent codex --skill ./devices/owon.md
62
+ diagnose agent claude --skill ./devices/owon.md
63
+ diagnose agent gemini --skill ./devices/owon.md
64
+ ```
65
+
66
+ A directory is also accepted: `--skill ./skills/my-device` reads its `SKILL.md`. Relative references remain based on that file's original directory. Diagnose snapshots the entry and supplies a startup task that tells the agent to read it and begin, instead of waiting for you to repeat the task. It asks for a pairing code or other missing target details when needed.
67
+
68
+ This is a session task, not a global native-skill installation or an additional permission grant. User approvals and the agent's own tool permissions still apply. Instructions can be sent to your AI provider. See the [guide](USER_GUIDE.md#start-with-a-device-skill-or-markdown-task) and [examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
69
+
70
+ ## From problem to verified result
71
+
72
+ 1. **Define the problem:** agree on the symptom and what a successful outcome looks like.
73
+ 2. **Investigate:** inspect the environment, gather evidence, and identify the likely cause.
74
+ 3. **Plan the fix:** explain the proposed changes, their impact, and recovery options where available.
75
+ 4. **Act with permission:** use approved commands, scripts, or file changes to carry out the fix.
76
+ 5. **Verify and hand off:** repeat the original check, summarize changes, and identify any remaining issues.
77
+
78
+ This is an agent-guided workflow using the existing tools and permission model. Diagnose does not automatically prove a repair succeeded or roll back arbitrary changes. See the [troubleshooting workflow](USER_GUIDE.md#from-a-reported-problem-to-a-verified-result).
79
+
80
+ ## Remote tools
44
81
 
45
82
  | Capability | Interface |
46
83
  | --- | --- |
@@ -63,13 +100,15 @@ No device-specific integration is required in the probe. An approved script can
63
100
  - Approved processes have the current OS user's permissions. **Diagnose is not a sandbox.** It does not automatically elevate privileges or install a background service.
64
101
  - Finite text results receive best-effort credential redaction. Live terminals, exact file transfers, and TCP traffic are raw and **not redacted**.
65
102
  - Results are visible to the diagnostician and the AI provider they use. End-to-end encryption does not hide data from those recipients.
66
- - Local audit logs record decisions, targets, hashes, byte counts, and outcomes. They do not reconstruct every side effect of an arbitrary program. Changes are not automatically rolled back.
103
+ - Local audit logs record decisions, targets, hashes, byte counts, and outcomes. Encrypted history keeps exact task requests, finite collected results, approvals, and send events: use `diagnose history`, `diagnose show ID`, and `diagnose cleanup --days 0`. History and resource journals each have a 256 MiB / 2,000-record budget and seven-day inactive retention. They do not reconstruct every side effect of an arbitrary program. Changes are not automatically rolled back.
67
104
  - `permissions ask`, `cancel`, and `Ctrl+C` are local controls. Data already transmitted cannot be recalled.
68
105
 
69
106
  Read the [user guide](USER_GUIDE.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
70
107
 
71
108
  ## Development
72
109
 
110
+ Development scripts use Node.js 22.18+ to run TypeScript directly. Installed CLI runtime support starts at Node.js 20.10; users do not need to upgrade an existing compatible runtime.
111
+
73
112
  ```sh
74
113
  npm ci
75
114
  npm run check
@@ -79,7 +118,7 @@ npm pack
79
118
 
80
119
  Tests exercise the actual encrypted protocol, approval boundaries, native terminals, transfers, forwarding, recovery, and the stdio MCP interface. The Noise tests include a public Cacophony interoperability vector. Hardware acceptance scripts and device logs are not distributed.
81
120
 
82
- The `site/` directory contains the static landing page, a small TypeScript interaction module, and a build script that renders the guide. Run `npm run build:site` and `npm run check:site`; serve `.site-dist/` to preview. No analytics, third-party scripts, or cookies are required. The existing Chinese explainer video is retained separately; it illustrates version 0.2 and predates the session agent launcher.
121
+ The `site/` directory contains the static landing page, a small TypeScript interaction module, and a build script that renders the guide. Run `npm run build:site` and `npm run check:site`; serve `.site-dist/` to preview. No analytics, third-party scripts, or cookies are required. The website features a 60-second English animation covering the current agent launcher, permissions, encrypted relay, investigation, authorized repair, and result verification. Its repair story is illustrative, not a live diagnosis. Reproduce it with `npm run video:render`; see [video documentation](https://github.com/zkwasm/diagnose/blob/main/video/README.md). The earlier Chinese video is retained unchanged.
83
122
 
84
123
  ## Relay deployment
85
124
 
package/USER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Diagnose user guide
2
2
 
3
- Diagnose gives an AI agent a temporary connection to a consenting user's computer. The same probe can inspect the computer itself, a USB device, or a device reachable on its local network.
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
4
 
5
5
  There are two people in a session:
6
6
 
@@ -9,13 +9,162 @@ There are two people in a session:
9
9
 
10
10
  The AI runs on the diagnostician's side. The user does not need to install an AI agent or configure MCP.
11
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
+
12
88
  ## 1. Requirements
13
89
 
14
- Both computers need **Node.js 22.18 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.
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.
15
91
 
16
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.
17
93
 
18
- 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. Linux and Windows probes, including Windows ConPTY and Gemini symlink permissions, remain experimental.
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/).
19
168
 
20
169
  ## 2. Start on the user's computer
21
170
 
@@ -56,10 +205,128 @@ Do **not** separately run `diagnose mcp` or register a global MCP server. The la
56
205
 
57
206
  Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
58
207
 
59
- > Use Diagnose to connect to pairing code D1.… . Inspect the user's USB-connected gateway, collect its logs, and explain why it is offline. Only read data. Do not reset, flash, or modify configuration.
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.
60
209
 
61
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.
62
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
+
63
330
  ### Session configuration and extra arguments
64
331
 
65
332
  ```sh
@@ -70,7 +337,7 @@ Options before `--` belong to Diagnose. Everything after it is passed literally
70
337
 
71
338
  - **Codex:** receives temporary `-c` MCP overrides.
72
339
  - **Claude Code:** receives a temporary `--mcp-config` value.
73
- - **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. The directory is removed on normal exit; changes to user settings in this Gemini session are not written back to the original `settings.json`.
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`.
74
341
 
75
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.
76
343
 
@@ -108,7 +375,7 @@ Type these into the user's probe terminal:
108
375
 
109
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.
110
377
 
111
- 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.
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.
112
379
 
113
380
  ## 5. What the agent can do
114
381
 
@@ -165,7 +432,7 @@ Agents use `diagnose_process` for the same live capabilities. Non-PTY processes
165
432
 
166
433
  ### Files
167
434
 
168
- `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.
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.
169
436
 
170
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.
171
438
 
@@ -187,7 +454,7 @@ SOCKS defaults to `allowedHosts:["*"]`, which permits any target. Narrow it when
187
454
 
188
455
  ## 6. Disconnect and recover
189
456
 
190
- When a connection drops, finite jobs are cancelled and serial handles close. The user's probe stays running and displays a **new pairing code**. Pair again, obtain new local consent, then resume a retained resource using its original ID and recovery credential. Diagnose never silently replays a creation command.
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.
191
458
 
192
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.
193
460
 
@@ -198,7 +465,9 @@ For download resume, keep the partial file and sidecar together. Upload resume u
198
465
  | Limit | Default / maximum |
199
466
  | --- | --- |
200
467
  | Invitation | 10 minutes |
201
- | Idle session / total session | 10 minutes / 60 minutes by default |
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 |
202
471
  | Finite command or script | 60 seconds by default; 300 seconds maximum |
203
472
  | Batch | Up to 32 steps; 300 seconds; 10 MiB combined output |
204
473
  | Concurrent finite jobs | 4 |
@@ -211,7 +480,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
211
480
  diagnose start --session-minutes 240 --idle-minutes 30
212
481
  ```
213
482
 
214
- Set a 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.
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.
215
484
 
216
485
  ## 8. Manual operation and other MCP clients
217
486
 
@@ -235,6 +504,9 @@ The direct commands accept an optional relay URL, for example `diagnose start ht
235
504
 
236
505
  ## Security and local data
237
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
+
238
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.
239
511
 
240
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.
@@ -245,7 +517,28 @@ The diagnostician, their endpoint software, and their AI provider can see result
245
517
 
246
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.
247
519
 
248
- Built-in file mutations record paths and, where available, before/after hashes and byte counts. Default audit logs do not store full command arguments, script source, or raw collected contents. They are not a complete command replay or filesystem monitor. Audit writes are flushed; an unwritable audit log stops the affected operation.
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.
249
542
 
250
543
  ### Saved output and recovery data
251
544
 
@@ -271,4 +564,4 @@ Commands run with the current user's OS permissions. Diagnose neither provides a
271
564
 
272
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.
273
566
 
274
- The existing one-minute explainer video remains in Chinese. It demonstrates version 0.2's batch and permission flow and predates live resources and the one-command agent launcher. Its screen content is an illustration, not a live session.
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.
@@ -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
+ }
package/dist/agent.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const agentUsage = "diagnose agent codex|claude|gemini [--relay URL] [-- agent arguments...]";
1
+ export declare const agentUsage = "diagnose agent codex|claude|gemini [--device NAME] [--skill FILE.md|DIRECTORY] [--relay URL] [-- agent arguments...]";
2
2
  export declare function launchAgent(argv: string[]): Promise<number>;