@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.
Files changed (46) hide show
  1. package/PAIRING_PROTOCOL.md +1 -1
  2. package/README.md +22 -8
  3. package/USER_GUIDE.md +33 -649
  4. package/dist/cli.js +44 -7
  5. package/dist/discover.js +1 -1
  6. package/dist/engine.js +15 -8
  7. package/dist/install-skill.d.ts +2 -0
  8. package/dist/install-skill.js +57 -0
  9. package/dist/mcp.js +27 -4
  10. package/dist/operator.js +2 -0
  11. package/dist/peer.d.ts +1 -0
  12. package/dist/peer.js +24 -3
  13. package/dist/relay.js +21 -8
  14. package/dist/schema.d.ts +4 -1
  15. package/dist/schema.js +2 -2
  16. package/dist/session-limits.d.ts +3 -0
  17. package/dist/session-limits.js +3 -0
  18. package/dist/skill-session.d.ts +1 -0
  19. package/dist/skill-session.js +272 -0
  20. package/docs/guide/automation.md +184 -0
  21. package/docs/guide/diagnose.md +93 -0
  22. package/docs/guide/on-site.md +139 -0
  23. package/docs/guide/procedures.md +183 -0
  24. package/docs/guide/reconnect.md +58 -0
  25. package/docs/guide/troubleshooting.md +77 -0
  26. package/npm-shrinkwrap.json +2 -2
  27. package/package.json +3 -1
  28. package/skills/connect/SKILL.md +66 -0
  29. package/skills/connect/scripts/run.mjs +37 -0
  30. package/src/cli.ts +42 -8
  31. package/src/discover.ts +1 -1
  32. package/src/engine.ts +12 -5
  33. package/src/install-skill.ts +57 -0
  34. package/src/mcp.ts +25 -5
  35. package/src/operator.ts +2 -0
  36. package/src/peer.ts +24 -4
  37. package/src/relay.ts +20 -4
  38. package/src/schema.ts +4 -2
  39. package/src/session-limits.ts +3 -0
  40. package/src/skill-session.ts +245 -0
  41. package/test/cli.test.ts +55 -7
  42. package/test/install-skill.test.ts +37 -0
  43. package/test/pairing.test.ts +6 -1
  44. package/test/review.test.ts +16 -0
  45. package/test/short-pairing.test.ts +42 -0
  46. package/test/skill-session.test.ts +93 -0
@@ -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. The probe requests local confirmation, then locks the invitation and sends the existing encrypted acceptance message. Optional remembered credentials are sent only inside this accepted channel. Session idle/lifetime clocks start at activation, not while the invitation is waiting.
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
- On the diagnostician's computer, start an already installed and authenticated agent:
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 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.
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](USER_GUIDE.md#keep-a-device-paired-for-future-diagnosis).
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](USER_GUIDE.md#start-with-a-device-skill-or-markdown-task) and [examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
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](USER_GUIDE.md#record-a-device-diagnosis-and-improve-your-procedures) and [security/operations design](KNOWLEDGE_SECURITY.md).
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](USER_GUIDE.md#from-a-reported-problem-to-a-verified-result).
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](USER_GUIDE.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
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