@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.
- package/README.md +46 -7
- package/USER_GUIDE.md +305 -12
- package/dist/agent-command.d.ts +4 -0
- package/dist/agent-command.js +33 -0
- package/dist/agent.d.ts +1 -1
- package/dist/agent.js +38 -8
- package/dist/cli.js +173 -22
- package/dist/discover.js +1 -1
- package/dist/engine.d.ts +2 -0
- package/dist/engine.js +37 -4
- package/dist/history.d.ts +13 -0
- package/dist/history.js +57 -0
- package/dist/journal.d.ts +23 -1
- package/dist/journal.js +82 -5
- package/dist/maintenance.d.ts +2 -0
- package/dist/maintenance.js +46 -0
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +21 -18
- package/dist/operator.d.ts +2 -0
- package/dist/operator.js +17 -5
- package/dist/pairing.d.ts +40 -0
- package/dist/pairing.js +92 -0
- package/dist/peer.d.ts +4 -0
- package/dist/peer.js +10 -3
- package/dist/resources.js +47 -26
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +2 -2
- package/dist/skill.d.ts +8 -0
- package/dist/skill.js +58 -0
- package/dist/transfers.js +28 -11
- package/dist/util.d.ts +2 -0
- package/dist/util.js +16 -3
- package/examples/skills/device-troubleshooting/SKILL.md +35 -0
- package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
- package/examples/skills/owon.md +27 -0
- package/npm-shrinkwrap.json +199 -3
- package/package.json +11 -5
- package/scripts/setup-node.ps1 +54 -0
- package/scripts/setup-node.sh +52 -0
- package/src/agent-command.ts +25 -0
- package/src/agent.ts +30 -7
- package/src/cli.ts +51 -20
- package/src/discover.ts +1 -1
- package/src/engine.ts +19 -4
- package/src/history.ts +43 -0
- package/src/journal.ts +41 -5
- package/src/maintenance.ts +30 -0
- package/src/mcp.ts +18 -16
- package/src/operator.ts +15 -6
- package/src/pairing.ts +64 -0
- package/src/peer.ts +6 -4
- package/src/resources.ts +35 -13
- package/src/schema.ts +4 -4
- package/src/skill.ts +44 -0
- package/src/transfers.ts +14 -3
- package/src/util.ts +14 -3
- package/test/agent.test.ts +53 -6
- package/test/pairing.test.ts +124 -0
- package/test/review.test.ts +128 -0
- package/test/setup.test.ts +16 -0
- package/test/skill.test.ts +25 -0
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# Diagnose
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Diagnose and fix problems remotely with your AI agent.**
|
|
4
4
|
|
|
5
|
-
Diagnose is an open-source
|
|
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
|
|
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.… .
|
|
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
|
-
##
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.… .
|
|
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.
|
|
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
|
-
|
|
|
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.
|
|
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
|
|
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,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>;
|