@masstensor/diagnose 0.7.0 → 0.8.1
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/PAIRING_PROTOCOL.md +1 -1
- package/README.md +22 -8
- package/USER_GUIDE.md +33 -649
- package/dist/cli.js +44 -7
- package/dist/discover.js +1 -1
- package/dist/engine.js +15 -8
- package/dist/install-skill.d.ts +2 -0
- package/dist/install-skill.js +57 -0
- package/dist/mcp.js +27 -4
- package/dist/operator.js +2 -0
- package/dist/peer.d.ts +1 -0
- package/dist/peer.js +24 -3
- package/dist/relay.js +21 -8
- package/dist/schema.d.ts +4 -1
- package/dist/schema.js +2 -2
- package/dist/session-limits.d.ts +3 -0
- package/dist/session-limits.js +3 -0
- package/dist/skill-session.d.ts +1 -0
- package/dist/skill-session.js +272 -0
- package/docs/guide/automation.md +184 -0
- package/docs/guide/diagnose.md +93 -0
- package/docs/guide/on-site.md +139 -0
- package/docs/guide/procedures.md +183 -0
- package/docs/guide/reconnect.md +58 -0
- package/docs/guide/troubleshooting.md +77 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +3 -1
- package/skills/connect/SKILL.md +66 -0
- package/skills/connect/scripts/run.mjs +37 -0
- package/src/cli.ts +42 -8
- package/src/discover.ts +1 -1
- package/src/engine.ts +12 -5
- package/src/install-skill.ts +57 -0
- package/src/mcp.ts +25 -5
- package/src/operator.ts +2 -0
- package/src/peer.ts +24 -4
- package/src/relay.ts +20 -4
- package/src/schema.ts +4 -2
- package/src/session-limits.ts +3 -0
- package/src/skill-session.ts +245 -0
- package/test/cli.test.ts +55 -7
- package/test/install-skill.test.ts +37 -0
- package/test/pairing.test.ts +6 -1
- package/test/review.test.ts +16 -0
- package/test/short-pairing.test.ts +42 -0
- package/test/skill-session.test.ts +93 -0
package/PAIRING_PROTOCOL.md
CHANGED
|
@@ -20,7 +20,7 @@ The probe enforces at most five attempted handshakes per invitation, even if the
|
|
|
20
20
|
2. The diagnostician endpoint initiates OPAQUE login; the relay forwards binary start, response and finish messages. Both roles bind `diagnose/v2/operator/ROOM` and `diagnose/v2/probe/ROOM` identifiers.
|
|
21
21
|
3. Both derive a 32-byte Noise PSK with HKDF-SHA-256 from the OPAQUE session key, salt `diagnose/opaque/v2`, info `noise-psk/ROOM`.
|
|
22
22
|
4. The existing `Noise_NNpsk0_25519_ChaChaPoly_BLAKE2b` exchange runs with that PSK. Its prologue includes the room, roles and protocol. Labels are sent inside Noise, after PAKE.
|
|
23
|
-
5.
|
|
23
|
+
5. Once the probe has local consent, it locks the invitation and sends the existing encrypted acceptance message. **Approve everything** can supply that consent in advance for one temporary invitation. Remembered credentials still require confirmation and are sent only inside the accepted encrypted channel. A temporary session starts a six-hour idle clock at activation. Diagnostic messages and explicit result polls renew it. Automatic heartbeats do not. The updated relay renews its room on encrypted traffic as it cannot distinguish diagnostics from heartbeats. The probe enforces the actual idle timeout. An explicit total time limit, when configured, still applies.
|
|
24
24
|
|
|
25
25
|
Implementation: pinned `@serenity-kit/opaque` 1.1.0, using its default memory-constrained Argon2id configuration, plus the existing pinned Noise implementation. OPAQUE protocol implementation and parameters are not reimplemented here. Sources: [library and implementation details](https://github.com/serenity-kit/opaque), [OPAQUE specification](https://www.rfc-editor.org/rfc/rfc9807.html). The upstream library has undergone a public security review; this integration has not received an independent audit. Secret Buffers are cleared where possible and obsolete OPAQUE state references are discarded; JavaScript/WASM does not guarantee erasure of every memory copy.
|
|
26
26
|
|
package/README.md
CHANGED
|
@@ -16,9 +16,21 @@ On the computer being diagnosed:
|
|
|
16
16
|
npx @masstensor/diagnose@latest start
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
|
|
19
|
+
In v0.8+, press Enter to review tasks and results, choose `a` to approve tasks and results automatically after confirming the connection, or choose `e` to preapprove all three for this one-time invitation. Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
### Use Diagnose in your existing agent
|
|
22
|
+
|
|
23
|
+
Install once from this GitHub repository. The native Skill uses Diagnose 0.8.1 and starts the local runtime on demand through Node.js and npm.
|
|
24
|
+
|
|
25
|
+
| Agent | Install | Use |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| Claude Code | `/plugin install diagnose --marketplace zkwasm/diagnose` | `/diagnose:connect` |
|
|
28
|
+
| Codex CLI | `codex plugin marketplace add zkwasm/diagnose`, then `codex plugin add diagnose@diagnose` | `$diagnose:connect` in a new session. |
|
|
29
|
+
| Gemini CLI | `gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect` | Ask Gemini to use the `connect` skill. |
|
|
30
|
+
|
|
31
|
+
### Start from the command line or automate a diagnosis
|
|
32
|
+
|
|
33
|
+
On the diagnostician's computer, use the npm launcher when a script or job needs to start and configure an agent:
|
|
22
34
|
|
|
23
35
|
```sh
|
|
24
36
|
npx @masstensor/diagnose@latest agent codex
|
|
@@ -29,7 +41,7 @@ The agent launcher requires **0.3.1+**. It loads Diagnose MCP for this launch wi
|
|
|
29
41
|
|
|
30
42
|
> Use Diagnose to connect to this pairing code: abc-def-ghi . Help resolve the user's application startup failure. First investigate without changing anything. Explain the cause, proposed fix, and risks. Apply only authorized changes, then check whether the application starts successfully and report anything still unresolved.
|
|
31
43
|
|
|
32
|
-
The user
|
|
44
|
+
The user grants permission locally, either when the connection arrives or in advance with **Approve everything**. Automatic task approval includes both execution and result transmission. Possessing a pairing code does not establish the diagnostician's real identity.
|
|
33
45
|
|
|
34
46
|
For repeated use:
|
|
35
47
|
|
|
@@ -42,6 +54,8 @@ diagnose agent codex
|
|
|
42
54
|
|
|
43
55
|
Short invitations require **0.7.0+ on both endpoints** and the updated relay. They last 30 minutes, tolerate case/spaces/hyphens, and still require local approval. Existing remembered pairings remain valid. See the [protocol design](PAIRING_PROTOCOL.md).
|
|
44
56
|
|
|
57
|
+
For a custom automation client, run `diagnose mcp` as a stdio subprocess. See the [native setup](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
|
+
|
|
45
59
|
## Pair once, return later
|
|
46
60
|
|
|
47
61
|
Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
|
|
@@ -53,7 +67,7 @@ diagnose agent codex --device alice-pc --skill ./devices/owon.md
|
|
|
53
67
|
# Same options for claude or gemini; --skill is optional.
|
|
54
68
|
```
|
|
55
69
|
|
|
56
|
-
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](
|
|
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](docs/guide/reconnect.md#keep-a-device-paired-for-future-diagnosis).
|
|
57
71
|
|
|
58
72
|
## Start with a device skill or Markdown task
|
|
59
73
|
|
|
@@ -67,13 +81,13 @@ diagnose agent gemini --skill ./devices/owon.md
|
|
|
67
81
|
|
|
68
82
|
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.
|
|
69
83
|
|
|
70
|
-
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](
|
|
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](docs/guide/procedures.md#start-with-a-device-skill-or-markdown-task) and [examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
|
|
71
85
|
|
|
72
86
|
## Keep and improve device knowledge
|
|
73
87
|
|
|
74
88
|
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.
|
|
75
89
|
|
|
76
|
-
See the [case and knowledge guide](
|
|
90
|
+
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).
|
|
77
91
|
|
|
78
92
|
## From problem to verified result
|
|
79
93
|
|
|
@@ -83,7 +97,7 @@ See the [case and knowledge guide](USER_GUIDE.md#record-a-device-diagnosis-and-i
|
|
|
83
97
|
4. **Act with permission:** use approved commands, scripts, or file changes to carry out the fix.
|
|
84
98
|
5. **Verify and hand off:** repeat the original check, summarize changes, and identify any remaining issues.
|
|
85
99
|
|
|
86
|
-
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](
|
|
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](docs/guide/diagnose.md#from-a-reported-problem-to-a-verified-result).
|
|
87
101
|
|
|
88
102
|
## Remote tools
|
|
89
103
|
|
|
@@ -111,7 +125,7 @@ No device-specific integration is required in the probe. An approved script can
|
|
|
111
125
|
- 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.
|
|
112
126
|
- `permissions ask`, `cancel`, and `Ctrl+C` are local controls. Data already transmitted cannot be recalled.
|
|
113
127
|
|
|
114
|
-
Read the [user guide](
|
|
128
|
+
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.
|
|
115
129
|
|
|
116
130
|
## Development
|
|
117
131
|
|