@masstensor/diagnose 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,13 +4,13 @@
4
4
 
5
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 gateways, controllers and other devices reachable from an on-site computer, apply authorized fixes, and verify the result. A user-controlled probe and an end-to-end encrypted relay provide the connection.
6
6
 
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)
7
+ [Quick start](USER_GUIDE.md#quick-start) · [Diagnostic walkthroughs](docs/guide/examples.md) · [npm](https://www.npmjs.com/package/@masstensor/diagnose) · [Website](https://diagnose.fenginwind.com)
8
8
 
9
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
 
13
- On the computer being diagnosed:
13
+ On the on-site computer connected to the device:
14
14
 
15
15
  ```sh
16
16
  npx @masstensor/diagnose@latest start
@@ -18,9 +18,9 @@ npx @masstensor/diagnose@latest start
18
18
 
19
19
  In v0.8+, press Enter to review tasks and results, choose `a` to approve tasks and results automatically after confirming the connection, or choose `e` to preapprove all three for this one-time invitation. Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
20
20
 
21
- ### Use Diagnose in your existing agent
21
+ ### Manual agent mode (recommended for a first session)
22
22
 
23
- Install once from this GitHub repository. The native Skill uses Diagnose 0.8.0 and starts the local runtime on demand through Node.js and npm.
23
+ Install once from this GitHub repository. The native Skill uses Diagnose 0.8.2 and starts the local runtime on demand through Node.js and npm.
24
24
 
25
25
  | Agent | Install | Use |
26
26
  | --- | --- | --- |
@@ -28,33 +28,32 @@ Install once from this GitHub repository. The native Skill uses Diagnose 0.8.0 a
28
28
  | Codex CLI | `codex plugin marketplace add zkwasm/diagnose`, then `codex plugin add diagnose@diagnose` | `$diagnose:connect` in a new session. |
29
29
  | Gemini CLI | `gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect` | Ask Gemini to use the `connect` skill. |
30
30
 
31
- ### Start from the command line or automate a diagnosis
32
-
33
- On the diagnostician's computer, use the npm launcher when a script or job needs to start and configure an agent:
31
+ Open your agent, give it the private invitation and the device symptom, then guide the next checks in chat. You can also start an interactive session with Diagnose MCP already configured:
34
32
 
35
33
  ```sh
36
34
  npx @masstensor/diagnose@latest agent codex
37
35
  # Or: agent claude / agent gemini
38
36
  ```
39
37
 
40
- The agent launcher requires **0.3.1+**. It loads Diagnose MCP for this launch without adding a permanent MCP entry. Tell the agent:
38
+ The launcher loads Diagnose MCP for this session. Tell the agent what to check:
39
+
40
+ > Use Diagnose with invitation abc-def-ghi. The OWON gateway is connected to the on-site computer by USB serial. Plug readings have stopped. Confirm the interface and look for relevant logs. Explain the evidence before proposing a change. We can verify recovery when fresh readings reach the dashboard.
41
41
 
42
- > Use Diagnose to connect to this pairing code: abc-def-ghi . Help resolve the user's application startup failure. First investigate without changing anything. Explain the cause, proposed fix, and risks. Apply only authorized changes, then check whether the application starts successfully and report anything still unresolved.
42
+ Diagnose 0.8.1 reports pairing progress. Check the [first device check](docs/guide/diagnose.md#run-a-diagnostic-session) for how to distinguish a connected probe, an identified interface, and an actual response from the device.
43
43
 
44
44
  The user grants permission locally, either when the connection arrives or in advance with **Approve everything**. Automatic task approval includes both execution and result transmission. Possessing a pairing code does not establish the diagnostician's real identity.
45
45
 
46
- For repeated use:
46
+ ### Start automatically with a device procedure
47
+
48
+ If you have a Markdown procedure, pass its path when launching the agent:
47
49
 
48
50
  ```sh
49
- npm install -g @masstensor/diagnose@latest
50
- diagnose start
51
- # On the diagnostician's machine:
52
- diagnose agent codex
51
+ npx @masstensor/diagnose@latest agent codex --skill ./device.md
53
52
  ```
54
53
 
55
- Short invitations require **0.7.0+ on both endpoints** and the updated relay. They last 30 minutes, tolerate case/spaces/hyphens, and still require local approval. Existing remembered pairings remain valid. See the [protocol design](PAIRING_PROTOCOL.md).
54
+ Short invitations require **0.7.0+ on both endpoints** and a compatible relay. They last 30 minutes and are consumed by successful pairing. The site user authorizes pairing at the prompt or in advance by choosing **Approve everything**. Existing remembered pairings remain valid. See the [protocol design](PAIRING_PROTOCOL.md).
56
55
 
57
- For a custom automation client, run `diagnose mcp` as a stdio subprocess. See the [native setup](USER_GUIDE.md#use-diagnose-as-a-native-agent-skill) and [automation setup](USER_GUIDE.md#8-manual-operation-and-other-mcp-clients) for the two entry points.
56
+ For a custom automation client, run `diagnose mcp` as a stdio subprocess. See the [native setup](docs/guide/diagnose.md#use-diagnose-as-a-native-agent-skill) and [automation setup](docs/guide/automation.md#direct-cli-and-other-mcp-clients) for the two entry points.
58
57
 
59
58
  ## Pair once, return later
60
59
 
@@ -67,7 +66,7 @@ diagnose agent codex --device alice-pc --skill ./devices/owon.md
67
66
  # Same options for claude or gemini; --skill is optional.
68
67
  ```
69
68
 
70
- 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).
69
+ 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](docs/guide/reconnect.md#keep-a-device-paired-for-future-diagnosis).
71
70
 
72
71
  ## Start with a device skill or Markdown task
73
72
 
@@ -81,13 +80,13 @@ diagnose agent gemini --skill ./devices/owon.md
81
80
 
82
81
  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.
83
82
 
84
- 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).
83
+ 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](docs/guide/procedures.md#start-with-a-device-skill-or-markdown-task) and [examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
85
84
 
86
85
  ## Keep and improve device knowledge
87
86
 
88
87
  Version 0.6 adds device diagnosis cases, evidence-linked conclusions, reviewed skill drafts, a local versioned library and optional encrypted cross-computer synchronization. Tell your agent to create a case and propose a reusable procedure when useful. Review drafts locally; the agent cannot accept them through MCP. Complete skill bundles can be shared through the relay using a separate private recovery credential. Raw case logs are not synced automatically.
89
88
 
90
- See the [case and knowledge guide](USER_GUIDE.md#record-a-device-diagnosis-and-improve-your-procedures) and [security/operations design](KNOWLEDGE_SECURITY.md).
89
+ See the [case and knowledge guide](docs/guide/procedures.md#record-a-device-diagnosis-and-improve-your-procedures) and [security/operations design](KNOWLEDGE_SECURITY.md).
91
90
 
92
91
  ## From problem to verified result
93
92
 
@@ -97,10 +96,12 @@ See the [case and knowledge guide](USER_GUIDE.md#record-a-device-diagnosis-and-i
97
96
  4. **Act with permission:** use approved commands, scripts, or file changes to carry out the fix.
98
97
  5. **Verify and hand off:** repeat the original check, summarize changes, and identify any remaining issues.
99
98
 
100
- 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).
99
+ 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](docs/guide/diagnose.md#from-a-reported-problem-to-a-verified-result).
101
100
 
102
101
  ## Remote tools
103
102
 
103
+ The [native skill](docs/guide/diagnose.md#what-the-native-skill-can-do) supports temporary pairing, progress updates, system inspection, serial diagnostics, bounded file operations, single shell commands, and batches. The full launcher and stdio MCP provide the wider tool set below, including whole scripts, live terminals, file transfers, and remembered connections.
104
+
104
105
  | Capability | Interface |
105
106
  | --- | --- |
106
107
  | Inspect OS, runtime, commands, privileges, and serial ports | `system.inspect` |
@@ -125,7 +126,7 @@ No device-specific integration is required in the probe. An approved script can
125
126
  - 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.
126
127
  - `permissions ask`, `cancel`, and `Ctrl+C` are local controls. Data already transmitted cannot be recalled.
127
128
 
128
- Read the [user guide](USER_GUIDE.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
129
+ Read the [user guide](docs/guide/troubleshooting.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
129
130
 
130
131
  ## Development
131
132
 
@@ -140,7 +141,7 @@ npm pack
140
141
 
141
142
  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.
142
143
 
143
- 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.
144
+ 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 60-second English animation illustrates a USB gateway diagnosis using the native agent skill, local approval, and a fresh dashboard reading to verify recovery. Reproduce it with `npm run video:render`. [Video documentation](https://github.com/zkwasm/diagnose/blob/main/video/README.md)
144
145
 
145
146
  ## Relay deployment
146
147