@masstensor/diagnose 0.5.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/DEVELOPMENT_PLAN.md +69 -0
  2. package/KNOWLEDGE_SECURITY.md +47 -0
  3. package/PAIRING_PROTOCOL.md +37 -0
  4. package/README.md +28 -6
  5. package/USER_GUIDE.md +250 -34
  6. package/deploy/Caddyfile +1 -1
  7. package/deploy/ecosystem.config.cjs +1 -1
  8. package/dist/agent.d.ts +1 -1
  9. package/dist/agent.js +15 -5
  10. package/dist/cases.d.ts +118 -0
  11. package/dist/cases.js +115 -0
  12. package/dist/cli.js +61 -13
  13. package/dist/crypto.d.ts +7 -0
  14. package/dist/crypto.js +16 -1
  15. package/dist/discover.js +1 -1
  16. package/dist/engine.d.ts +1 -0
  17. package/dist/engine.js +21 -7
  18. package/dist/install-skill.d.ts +2 -0
  19. package/dist/install-skill.js +57 -0
  20. package/dist/knowledge-cli.d.ts +2 -0
  21. package/dist/knowledge-cli.js +164 -0
  22. package/dist/knowledge-drafts.d.ts +47 -0
  23. package/dist/knowledge-drafts.js +76 -0
  24. package/dist/knowledge-mcp.d.ts +5 -0
  25. package/dist/knowledge-mcp.js +65 -0
  26. package/dist/mcp.d.ts +1 -1
  27. package/dist/mcp.js +38 -9
  28. package/dist/operator.d.ts +2 -0
  29. package/dist/operator.js +18 -3
  30. package/dist/peer.d.ts +9 -0
  31. package/dist/peer.js +90 -10
  32. package/dist/relay-main.js +1 -1
  33. package/dist/relay.d.ts +1 -0
  34. package/dist/relay.js +46 -10
  35. package/dist/schema.d.ts +4 -1
  36. package/dist/schema.js +2 -2
  37. package/dist/session-limits.d.ts +3 -0
  38. package/dist/session-limits.js +3 -0
  39. package/dist/short-pairing.d.ts +25 -0
  40. package/dist/short-pairing.js +73 -0
  41. package/dist/skill-library.d.ts +27 -0
  42. package/dist/skill-library.js +226 -0
  43. package/dist/skill-session.d.ts +1 -0
  44. package/dist/skill-session.js +257 -0
  45. package/dist/skill.d.ts +1 -0
  46. package/dist/skill.js +1 -0
  47. package/dist/util.js +1 -0
  48. package/dist/vault-crypto.d.ts +11 -0
  49. package/dist/vault-crypto.js +30 -0
  50. package/dist/vault-server.d.ts +10 -0
  51. package/dist/vault-server.js +156 -0
  52. package/dist/vault.d.ts +19 -0
  53. package/dist/vault.js +72 -0
  54. package/npm-shrinkwrap.json +12 -2
  55. package/package.json +7 -2
  56. package/skills/connect/SKILL.md +60 -0
  57. package/skills/connect/scripts/run.mjs +37 -0
  58. package/src/agent.ts +12 -5
  59. package/src/cases.ts +74 -0
  60. package/src/cli.ts +51 -13
  61. package/src/crypto.ts +14 -1
  62. package/src/discover.ts +1 -1
  63. package/src/engine.ts +17 -4
  64. package/src/install-skill.ts +57 -0
  65. package/src/knowledge-cli.ts +67 -0
  66. package/src/knowledge-drafts.ts +55 -0
  67. package/src/knowledge-mcp.ts +35 -0
  68. package/src/mcp.ts +21 -7
  69. package/src/operator.ts +12 -3
  70. package/src/peer.ts +51 -14
  71. package/src/relay-main.ts +1 -1
  72. package/src/relay.ts +35 -7
  73. package/src/schema.ts +4 -2
  74. package/src/session-limits.ts +3 -0
  75. package/src/short-pairing.ts +57 -0
  76. package/src/skill-library.ts +162 -0
  77. package/src/skill-session.ts +233 -0
  78. package/src/skill.ts +2 -1
  79. package/src/util.ts +1 -0
  80. package/src/vault-crypto.ts +25 -0
  81. package/src/vault-server.ts +72 -0
  82. package/src/vault.ts +51 -0
  83. package/test/agent.test.ts +26 -1
  84. package/test/cli.test.ts +58 -10
  85. package/test/install-skill.test.ts +37 -0
  86. package/test/knowledge-mcp.test.ts +37 -0
  87. package/test/knowledge.test.ts +112 -0
  88. package/test/mcp.test.ts +1 -1
  89. package/test/pairing.test.ts +8 -3
  90. package/test/review.test.ts +17 -0
  91. package/test/short-pairing.test.ts +142 -0
  92. package/test/skill-library.test.ts +62 -0
  93. package/test/skill-session.test.ts +79 -0
  94. package/test/skill.test.ts +1 -1
package/USER_GUIDE.md CHANGED
@@ -1,13 +1,34 @@
1
1
  # Diagnose user guide
2
2
 
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.
3
+ Diagnose connects a remote AI agent to **devices an on-site computer can access**: a home IoT gateway, a factory controller, an industrial PC, or other equipment with a usable USB, serial, or local-network interface. The computer is the bridge; the device is the main target. Computer and software problems can also be investigated when needed.
4
4
 
5
- There are two people in a session:
5
+ ## Why: stop making the user carry every clue
6
6
 
7
- - **User:** the person whose computer or connected device needs diagnosis. They run `diagnose start` and control permissions locally.
8
- - **Diagnostician:** the person directing the AI agent. They run `diagnose agent codex`, `diagnose agent claude`, or `diagnose agent gemini` and give the agent the user's pairing code.
7
+ A device fails at a home or factory, while the person who can help is elsewhere. Remote support often means asking someone on site to run commands, copy logs, send screenshots, and repeat the process. That person may not know the tools. The expert and their AI cannot directly inspect the next clue or verify a change.
9
8
 
10
- The AI runs on the diagnostician's side. The user does not need to install an AI agent or configure MCP.
9
+ Diagnose lets the expert's AI use an authorized connection through a nearby computer. The on-site user still controls access, but no longer has to relay every command and result by hand.
10
+
11
+ ## What: a general-purpose bridge to the device
12
+
13
+ The **probe** is the Diagnose program running on the on-site computer. It gives the remote agent tools to inspect that computer's environment, read exposed serial logs, run installed device utilities, and reach accessible network services. It does not require an AI agent to be installed on the target device.
14
+
15
+ The same probe can serve different devices. A **skill or Markdown procedure** supplies device-specific knowledge: the model, connection method, protocol, useful checks, and acceptable repair steps. Access still depends on available interfaces, drivers, credentials, and tools; Diagnose does not automatically support every device or protocol.
16
+
17
+ For example, an owner connects a gateway's exposed serial interface to a laptop. A remote diagnostician asks the AI to find why readings have stopped. The agent can inspect available logs, check communication, perform an authorized operation if the interface supports it, and check for new readings. If physical work or another interface is needed, it reports that instead.
18
+
19
+ ## How: connect the site, then direct the agent
20
+
21
+ > Remote AI agent ↔ encrypted relay ↔ on-site computer running Diagnose ↔ target device
22
+
23
+ The relay carries encrypted traffic between the computers. The on-site computer accesses the device through USB, serial, or its local network. Diagnose's end-to-end encryption protects the connection between the two computers; the device's local protocol has its own security properties.
24
+
25
+ | Role | What they do |
26
+ | --- | --- |
27
+ | **On-site user** | Connect the device, run the probe, share the pairing code privately, and control local permissions. They need no AI account or agent installation. |
28
+ | **Remote diagnostician** | Launch Codex, Claude Code, or Gemini CLI with Diagnose, provide a concrete goal and any device procedure, and review the investigation and proposed repair. |
29
+ | **AI agent** | Use the authorized tools to collect evidence, carry out permitted changes, and check the device's actual behavior. |
30
+
31
+ The following quick start takes both people through this process.
11
32
 
12
33
  ## Quick start
13
34
 
@@ -31,30 +52,39 @@ Wait for **Setup complete** and three version numbers. Then close the terminal a
31
52
 
32
53
  Only the **diagnostician** needs an installed, signed-in Codex CLI, Claude Code, or Gemini CLI. The person receiving help needs no AI account.
33
54
 
34
- ### 2. On the computer receiving help
55
+ ### 2. Connect the device and start the on-site probe
56
+
57
+ Ask the diagnostician which connection to use:
58
+
59
+ - **USB or serial:** connect the device to the on-site computer using the appropriate data cable or adapter. Install any required driver. A USB port may provide power only; the device must expose a usable interface.
60
+ - **Local network:** use a computer that can reach the device's network address and service. Provide any required device credentials through the agreed private or local method.
61
+
62
+ Then run this on the on-site computer:
35
63
 
36
64
  ```sh
37
65
  npx @masstensor/diagnose@latest start
38
66
  ```
39
67
 
40
- If npm asks to install the package, type `y`. Keep this terminal open. Send the complete `D1.…` code privately to your diagnostician.
68
+ If npm asks to install the package, type `y`. In v0.8+, choose the [approval mode](#2-start-on-the-users-computer) before sharing the invitation. Press Enter for review, `a` for automatic tasks and results, or `e` to also preapprove the connection. Keep this terminal open and share the nine-letter invitation privately.
41
69
 
42
70
  ### 3. On the diagnostician's computer
43
71
 
72
+ For an existing Claude Code, Codex CLI, or Gemini CLI session, install the [native Diagnose skill from GitHub](#use-diagnose-as-a-native-agent-skill) once, then invoke it with the invitation. For a script or an agent session that should start with Diagnose already configured, use the npm launcher:
73
+
44
74
  ```sh
45
75
  npx @masstensor/diagnose@latest agent codex
46
76
  # Or replace codex with claude or gemini.
47
77
  ```
48
78
 
49
- In the agent conversation, provide the code and a concrete problem:
79
+ In the agent conversation, provide the code, device model, connection method, and a concrete goal:
50
80
 
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.
81
+ > Use Diagnose to connect to this code: abc-def-ghi . The on-site laptop is connected to an OWON SEG-X3-C gateway through its exposed USB serial interface. The gateway is online, but no plug readings are arriving. Inspect the available logs and identify the cause. Explain any proposed repair, apply only authorized changes, and check whether readings resume. If the interface does not support a required action, tell us what is needed on site.
52
82
 
53
83
  ### 4. Approve, diagnose, and finish
54
84
 
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.
85
+ Unless the on-site user chose **Approve everything**, they check the diagnostician's label and connection fingerprint and approve the connection. If they selected auto approval at startup, `y` confirms it for this session and `r` connects with per-task review. Otherwise, `y` uses per-task review and `a` grants auto approval. Auto approval covers both execution **and result transmission**. Commands run with that user's OS permissions, and results can reach the diagnostician and their AI provider.
56
86
 
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.
87
+ The diagnostician directs the agent to investigate the device, repair within permission, and verify a device result: for example, new sensor readings or a successful communication check. 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
88
 
59
89
  ### Return later or load a device procedure
60
90
 
@@ -63,30 +93,32 @@ The diagnostician directs the agent to investigate, repair within permission, an
63
93
  ```sh
64
94
  npm install -g @masstensor/diagnose@latest
65
95
  # Diagnostician: pair once while the user's probe is running.
66
- diagnose pair --name alice-pc
96
+ diagnose pair --name workshop-laptop
67
97
  # User: explicitly approve remembering this diagnostician.
68
98
  # Diagnostician: use this whenever diagnosis is needed again.
69
- diagnose agent codex --device alice-pc --skill ./devices/owon.md
99
+ diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
70
100
  ```
71
101
 
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.
102
+ The saved name identifies the on-site computer, not the gateway or controller attached to it. Confirm which device is currently connected before starting work. 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
103
 
74
104
  ## From a reported problem to a verified result
75
105
 
76
- Use the session to work toward a concrete outcome:
106
+ For a device session, work toward an observable device outcome:
77
107
 
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.
108
+ 1. **Describe the problem.** Identify the device model, its connection to the on-site computer, what fails, and what you expected. Agree on the check that will show whether the problem is resolved.
109
+ 2. **Investigate first.** Ask the agent to identify the available interface and tools, then inspect device logs, network responses, or other relevant evidence. Distinguish confirmed facts from possible causes.
80
110
  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
111
  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.
112
+ 5. **Verify the result.** Check the device itself: repeat the failing exchange, observe new readings, or run its supported 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
113
 
84
114
  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
115
 
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.
116
+ You can also request a read-only investigation and stop after the explanation. The on-site computer’s drivers, software, configuration, and network can also be investigated when they are part of the problem; successful fixes depend on the issue, available access, and the user's authorization.
87
117
 
88
118
  ## 1. Requirements
89
119
 
120
+ The on-site computer must have a working connection to the target device, plus any drivers, credentials, or vendor utilities needed for the intended checks. Diagnose cannot bypass a missing interface or perform physical repairs.
121
+
90
122
  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.
91
123
 
92
124
  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.
@@ -179,7 +211,17 @@ npm install -g @masstensor/diagnose@latest
179
211
  diagnose start
180
212
  ```
181
213
 
182
- The terminal shows a pairing code beginning with `D1.` and the local audit log path. Keep it open. Share the **complete code privately** with the intended diagnostician. The initial invitation lasts 10 minutes. Treat the code as a secret; do not post it publicly or place it in shell arguments.
214
+ With v0.8+, a probe starting a new pairing asks which approval mode to use before displaying its invitation.
215
+
216
+ | Startup choice | What it allows |
217
+ | --- | --- |
218
+ | Enter | Confirm the connection and review each task and result transfer. |
219
+ | `a` · Auto tasks only | Confirm the connection once. Tasks and result transfers then proceed automatically. |
220
+ | `e` · Approve everything | Let the holder of this one-time invitation connect automatically, run tasks, and receive results for the temporary session. |
221
+
222
+ Share an **Approve everything** invitation only with the intended diagnostician. Type `permissions ask` to cancel that choice before pairing or revoke auto approval after pairing. The next invitation does not inherit it. Requests to remember a diagnostician still require confirmation.
223
+
224
+ With v0.7+, the terminal shows a **nine-letter invitation**, such as `abc-def-ghi`, and the audit log path. Keep it open. Share the code privately by message or read it aloud. It lasts **30 minutes** and is consumed by successful pairing. Case, spaces and hyphens do not matter when entering it. Treat the code as a secret; do not post it publicly or put it in shell arguments. After expiry or five attempted handshakes, the running probe generates a new code.
183
225
 
184
226
  The probe will show the connecting party's self-reported label and the session fingerprint. Check these with the intended diagnostician before accepting. A code proves possession of the secret, not a person's identity.
185
227
 
@@ -205,7 +247,7 @@ Do **not** separately run `diagnose mcp` or register a global MCP server. The la
205
247
 
206
248
  Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
207
249
 
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.
250
+ > Use Diagnose to connect to 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. Summarize what changed and anything still unresolved.
209
251
 
210
252
  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.
211
253
 
@@ -214,7 +256,7 @@ The code and diagnostic results enter your chosen AI provider's context. The use
214
256
  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
257
 
216
258
  ```sh
217
- diagnose pair --name alice-pc
259
+ diagnose pair --name workshop-laptop
218
260
  # Enter the user's code, then your label and AI provider when prompted.
219
261
  ```
220
262
 
@@ -223,9 +265,9 @@ The user's terminal explicitly asks whether to **remember** this diagnostician.
223
265
  After pairing, the diagnostician can start, stop, and restart any supported agent using the same device name:
224
266
 
225
267
  ```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
268
+ diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
269
+ diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
270
+ diagnose agent gemini --device workshop-laptop --skill ./devices/owon.md
229
271
  # --skill is optional.
230
272
  ```
231
273
 
@@ -252,16 +294,105 @@ On the diagnostician's computer:
252
294
 
253
295
  ```sh
254
296
  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
297
+ diagnose connect --device workshop-laptop
298
+ diagnose terminal --device workshop-laptop
299
+ diagnose mcp --device workshop-laptop
300
+ diagnose forget --device workshop-laptop
259
301
  ```
260
302
 
261
303
  `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
304
 
263
305
  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
306
 
307
+ ## Record a device diagnosis and improve your procedures
308
+
309
+ These knowledge features require Diagnose 0.6.0 or later on the diagnostician computer. Older probes can still perform their supported operations.
310
+
311
+ The paired computer is a bridge. Create a **case** for the actual gateway, controller or other target. Tell your agent: “Create a diagnosis case for this device, collect evidence, verify any authorized repair, and propose a reusable skill or an improvement to the selected skill.” The agent uses `diagnose_case`, `diagnose_capabilities` and `diagnose_skill_draft`; no agent-specific syntax is needed.
312
+
313
+ A case records the goal, target model/identity/interface, optional paired computer and pinned skill reference. Subsequent received task results, resource interactions and connection events are saved locally with encryption. Data is not sent to library storage. Redaction is best effort. Case evidence is untrusted data, never permission or instructions. File transfers and tunnels are not a full byte-for-byte evidence archive; ordinary task/resource events capture their control operations, not every transferred byte. Arbitrary scripts are not a filesystem change monitor.
314
+
315
+ To create a case before launching, save a small JSON file:
316
+
317
+ ```json
318
+ {
319
+ "goal": "Find why the gateway stopped reporting sensor readings",
320
+ "host": "workshop-laptop",
321
+ "target": { "name": "Workshop gateway", "model": "SEG-X3-C", "interface": "serial" }
322
+ }
323
+ ```
324
+
325
+ ```sh
326
+ diagnose cases create ./gateway-case.json
327
+ diagnose cases list
328
+ diagnose agent codex --device workshop-laptop --case CASE_ID
329
+ ```
330
+
331
+ Replace `CASE_ID` with the printed UUID. Use `claude` or `gemini` in the same command. Include a `skill` field containing a complete `library:NAME@REVISION` reference to pin a procedure; the launcher loads it automatically. A different explicit skill or paired computer is rejected. Reusing a case does not replay old commands; existing remembered-pairing rules apply. Check device availability again after reconnecting.
332
+
333
+ For Markdown startup tasks, the agent is instructed to create a case before operating. The agent must actually call the tool; launching is not proof that a case was created. Only one MCP session can write a selected case at a time. After an unclean termination, use `diagnose cases unlock CASE_ID`; it refuses to unlock while the recorded writer process is alive. Cases are optional for ordinary MCP operations. In a selected case, only results actually received by the diagnostician are recorded.
334
+
335
+ ```sh
336
+ diagnose cases show CASE_ID
337
+ diagnose cases export CASE_ID > reviewed-report.json
338
+ diagnose cases remove CASE_ID
339
+ ```
340
+
341
+ Export omits raw results, command arguments and target addresses. Review free-text summaries for sensitive details before sharing. Cases retain at most 200 evidence records each (32 KiB per record; larger values are marked as previews), with at most 100 local cases. Limits are reported, not silently interpreted as a complete investigation. Remove old cases explicitly; `diagnose cleanup` does not delete cases or skills.
342
+
343
+ An agent can report **resolved**, **unresolved**, **needs physical work**, or **insufficient evidence**. Resolved requires baseline and later successful verification evidence IDs from the same case. This proves the cited evidence exists; it does not automatically prove the agent interpreted it correctly. A successful command is not necessarily a healthy device. Connection status distinguishes confirmed relay/probe connectivity from evidence-linked agent assessments of the device interface and response; untested layers remain unknown.
344
+
345
+ ### Review a new skill or improvement
346
+
347
+ The agent proposes a structured draft with applicability, prerequisites, identity checks, read-only checks, repair authorization conditions, recovery, verification and failed approaches. Improvements must refer to the exact library version selected in the case. Reference files and scripts from that base are retained unchanged. Raw logs are not automatically copied. For changes to supporting scripts/resources, edit a separate source directory, review it and import a new version.
348
+
349
+ ```sh
350
+ diagnose drafts list
351
+ diagnose drafts review DRAFT_ID
352
+ diagnose drafts accept DRAFT_ID
353
+ # Or keep the existing procedure:
354
+ diagnose drafts reject DRAFT_ID
355
+ ```
356
+
357
+ Acceptance displays the full before/after entry and evidence references and asks you to confirm in an interactive terminal. The agent has no acceptance MCP tool. Confirm the evidence supports the procedure and remove customer-specific values. Potential-secret warnings assist review; they are not a guarantee. A case result or device log cannot itself authorize an instruction. Accepted drafts become new pinned library versions; older versions remain available.
358
+
359
+ If another version appeared since drafting, acceptance stops and preserves the draft. Ask the agent to reconcile against the version you select, using the original evidence. `diagnose drafts show DRAFT_ID` shows structured input for editing; `diagnose drafts create INPUT.json` creates another proposal. `diagnose drafts remove DRAFT_ID` removes a local draft record after confirmation. At most 100 draft records are retained; removal never removes an imported version.
360
+
361
+ ### Share your private skill library across computers
362
+
363
+ Library sharing is optional and independent of device pairing. Initialize it on the diagnostician computer and save the recovery file somewhere private that you can back up:
364
+
365
+ ```sh
366
+ diagnose vault init ./diagnose-library-recovery.txt
367
+ diagnose vault push library:NAME@FULL_REVISION
368
+ ```
369
+
370
+ Push asks you to confirm publication of the complete bundle. Every file in the imported directory is included. The client encrypts the name, instructions, references, scripts and provenance before uploading. The relay sees opaque IDs, sizes and traffic metadata. Cases, drafts and raw diagnosis logs are not synced automatically. Instructions read by an AI agent can still be sent to its provider.
371
+
372
+ On a second diagnostician computer, securely transfer the recovery file yourself (never through an AI prompt) and run:
373
+
374
+ ```sh
375
+ diagnose vault restore ./diagnose-library-recovery.txt
376
+ diagnose vault pull
377
+ diagnose skills list
378
+ diagnose agent claude --skill library:NAME@FULL_REVISION
379
+ ```
380
+
381
+ Pull verifies and caches complete versions but does not execute or select them. Divergent versions coexist. Cached skills work offline; connecting to a remote probe still needs connectivity. A duplicate concurrent push may report 409; rerun push to verify that version, without rerunning diagnosis. Library sync does not transfer paired-computer credentials.
382
+
383
+ ```sh
384
+ diagnose vault status
385
+ diagnose vault backup ./another-private-recovery-copy.txt
386
+ diagnose vault revoke
387
+ diagnose vault forget
388
+ ```
389
+
390
+ **Protect the recovery file like a password.** It grants full library access. Losing every copy means server-only data cannot be decrypted. The local copy lives at `~/.diagnose/vault/recovery`; private permissions are applied where supported. Do not commit it to Git. Backup refuses to overwrite an existing file. If initialization succeeds but backup fails, use `vault backup` with a new path.
391
+
392
+ Revoke permanently deletes that relay library and blocks its credential on that relay; local copies remain. Forget removes only the local recovery credential. To rotate access, cache wanted versions, revoke the old library, forget locally, initialize a new key, and explicitly push selected versions. Restore the new recovery file only on trusted computers. Previously downloaded data cannot be recalled. Use `--relay https://your-relay.example` consistently for a self-hosted library. Its operator must enable `VAULT_PATH`; the default public relay supports this API in v0.6.
393
+
394
+ Limits are 128 versions / 128 MiB per relay library and 12 MiB per encrypted object. The relay is not your only backup. See [knowledge security and operations](https://github.com/zkwasm/diagnose/blob/main/KNOWLEDGE_SECURITY.md) for formats, limits, retention, threat model and deployment details.
395
+
265
396
  ## Start with a device skill or Markdown task
266
397
 
267
398
  Version **0.4.0+** can start the agent with a selected diagnostic procedure. The syntax is identical for all three agents:
@@ -319,6 +450,26 @@ report what changed, the evidence, and anything unresolved.
319
450
 
320
451
  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
452
 
453
+ ### Local versioned library (v0.6+)
454
+
455
+ The local library requires Diagnose 0.6.0 or later.
456
+
457
+ Import a reviewed skill directory once, then use the exact reference printed by the command:
458
+
459
+ ```sh
460
+ diagnose skills import owon ./examples/skills/device-troubleshooting
461
+ diagnose skills list
462
+ diagnose agent codex --device workshop-laptop --skill library:owon@FULL_SHA256_FROM_IMPORT
463
+ ```
464
+
465
+ Replace `FULL_SHA256_FROM_IMPORT` with the complete digest printed by import, or copy the complete `library:...` reference. The same `--skill` argument works with Claude and Gemini. It pins the complete bundle, including references and scripts. Changing any file creates a different version; older versions remain available and there is no implicit “latest” version. Importing identical contents again reuses the same version. Stored contents are verified before launch. Permission bits are not part of the portable content digest.
466
+
467
+ You can also import a single Markdown file; it becomes `SKILL.md` without copying neighboring files. Use a dedicated directory when the procedure needs references or scripts. Directory imports include all files: review the directory for credentials, customer logs and unrelated files first. Symbolic links, special files, non-portable names, case-colliding paths, more than 128 files, more than 256 directory entries, nesting beyond 16 levels, and bundles over 8 MiB are rejected. The entry retains the 256 KiB Markdown limit. Importing does not execute scripts.
468
+
469
+ The library lives in `~/.diagnose/skills` with private permissions where supported. It is local plaintext, not an encrypted backup; protect it like your other local source files. Do not edit stored versions directly. Edit the original source and import again. Reading or executing the skill still uses your agent's normal permissions and may send its contents to the AI provider.
470
+
471
+ Import/list commands are local. See the diagnosis case and private library sections for reviewed drafts and optional encrypted synchronization.
472
+
322
473
  ### Permissions and compatibility
323
474
 
324
475
  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.
@@ -327,6 +478,10 @@ This is portable Markdown task loading, not native installation of a Codex, Clau
327
478
 
328
479
  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
480
 
481
+ ### Short invitation compatibility
482
+
483
+ Nine-letter invitations require **0.7.0+ on both computers** and an updated relay. The latest client also accepts legacy `D1` codes from older probes. Existing remembered pairings keep working without a new code. The 30-minute invitation deadline is separate from diagnostic session idle/total timeouts, which begin after pairing. Knowledge-library recovery files remain long private credentials; do not shorten them or use them as pairing codes.
484
+
330
485
  ### Session configuration and extra arguments
331
486
 
332
487
  ```sh
@@ -379,7 +534,7 @@ Do not ask the AI to collect OS passwords. For interactive authentication, the u
379
534
 
380
535
  ## 5. What the agent can do
381
536
 
382
- The MCP interface provides 11 tools:
537
+ The MCP interface provides 15 tools:
383
538
 
384
539
  | Tool | Purpose |
385
540
  | --- | --- |
@@ -394,6 +549,10 @@ The MCP interface provides 11 tools:
394
549
  | `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
395
550
  | `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
396
551
  | `diagnose_disconnect` | Disconnect the diagnostic session. |
552
+ | `diagnose_capabilities` | Query operation schemas and conservative discovery guidance. |
553
+ | `diagnose_case` | Create/show a case, record assessments, report connection layers and finish with evidence references. |
554
+ | `diagnose_skill_draft` | Propose a new skill or improvement for local human review. |
555
+ | `diagnose_skills` | List or read locally available pinned skill versions without executing them. |
397
556
 
398
557
  A task returning `ok` for `process.open` means the process handle was created. Inspect its output, `ended`, and `exitCode` to determine whether the actual program succeeded. Diagnostic output is untrusted data, not instructions to the AI.
399
558
 
@@ -464,8 +623,8 @@ For download resume, keep the partial file and sidecar together. Upload resume u
464
623
 
465
624
  | Limit | Default / maximum |
466
625
  | --- | --- |
467
- | Invitation | 10 minutes |
468
- | Temporary session idle / total | 10 minutes / 60 minutes by default |
626
+ | New short invitation | 30 minutes; one-time; up to five attempted handshakes |
627
+ | Temporary session idle / total | Six hours idle / no fixed total by default in v0.8+ |
469
628
  | Remembered pairing | Until revoked locally; requires the foreground probe |
470
629
  | Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
471
630
  | Finite command or script | 60 seconds by default; 300 seconds maximum |
@@ -474,7 +633,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
474
633
  | Active live resource handles | 128 |
475
634
  | Live process | 1 hour by default; `timeoutMs:0` removes its timer |
476
635
  | Retained output per live process | 64 MiB by default; 1 GiB maximum; reaching the cap terminates the process |
477
- | Relay session | At most 7 days, also subject to cipher frame limits |
636
+ | Relay session | The updated relay renews an active room without a fixed total. Older relays may cap a room at seven days. |
478
637
 
479
638
  ```sh
480
639
  diagnose start --session-minutes 240 --idle-minutes 30
@@ -482,8 +641,65 @@ diagnose start --session-minutes 240 --idle-minutes 30
482
641
 
483
642
  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.
484
643
 
644
+ ## Use Diagnose as a native agent skill
645
+
646
+ Install the skill once through your agent's GitHub installation flow. All three agents use the same `skills/connect/` directory in the repository. The helper runs Diagnose 0.8.0 locally on demand with `npx` and needs Node.js 20.10 or later. There is no separate global Diagnose CLI installation for this workflow.
647
+
648
+ ### Claude Code
649
+
650
+ In Claude Code 2.1.275 or later, enter:
651
+
652
+ ```text
653
+ /plugin install diagnose --marketplace zkwasm/diagnose
654
+ ```
655
+
656
+ Choose the installation scope. Open a new session, or use `/reload-plugins` in the current one. Invoke `/diagnose:connect` with the private invitation and, if known, the device and symptom. [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command)
657
+
658
+ ### Codex CLI
659
+
660
+ In your terminal, run:
661
+
662
+ ```sh
663
+ codex plugin marketplace add zkwasm/diagnose
664
+ codex plugin add diagnose@diagnose
665
+ ```
666
+
667
+ Alternatively, add the marketplace and install Diagnose from `/plugins`. Open a new session and invoke `$diagnose:connect` with your private invitation. [Codex CLI plugin documentation](https://learn.chatgpt.com/docs/cli/reference#codex-plugin)
668
+
669
+ ### Gemini CLI
670
+
671
+ In your terminal, run:
672
+
673
+ ```sh
674
+ gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect
675
+ ```
676
+
677
+ Approve the installation prompt. In a new session, ask Gemini to use the `connect` skill and provide the invitation. Use `/skills reload` if a Gemini session is already open. [Gemini CLI Skills documentation](https://geminicli.com/docs/cli/skills/#managing-skills)
678
+
679
+ ### Run a diagnostic session
680
+
681
+ The on-site user starts the normal probe and shares its one-time invitation. The skill uses it to request pairing through the relay. The on-site user confirms the connection if their startup choice requires it. The agent starts with a relevant read-only check, such as listing visible serial ports. It keeps the connection for follow-up checks, authorized changes, and verification. Normal local execution and transfer permissions still apply.
682
+
683
+ The first result informs the next step. For example, the agent may compare device logs with two related settings, correct one setting, and rerun the original check. If the symptom persists, it uses that result to choose the next test. The skill keeps the connection open after progress reports and verification so you can ask follow-up questions. Ask the agent to close the session when you are done. The on-site user can also stop access.
684
+
685
+ A temporary session normally expires after six hours without diagnostic activity. Task requests, result polling, and live resource interactions renew the timer. Automatic heartbeats keep the network connection alive without renewing the diagnostic idle timer. A probe configured with an explicit total limit can expire the session earlier. A network or process loss can still interrupt a live connection. If interruptions are expected, a remembered pairing can reconnect without a fresh code. A direct stdio MCP session ends when its client stops the MCP process. The native skill keeps its MCP process running across separate shell calls and conversation turns.
686
+
687
+ This path uses temporary pairing and finite diagnostic operations. It supports system inspection, bounded file operations, finite commands, and serial diagnostics. The full agent launcher remains available for remembered connections, live terminals, and case management.
688
+
689
+ For prerelease testing, build the source checkout, install from its local marketplace or skill directory, and set `DIAGNOSE_SKILL_CLI` in the agent's environment to the absolute path of `dist/cli.js`. The GitHub install commands require the repository manifests to be published. The helper's default runtime requires the pinned npm version to be published.
690
+
485
691
  ## 8. Manual operation and other MCP clients
486
692
 
693
+ For scripts and CI, install the npm client and start it directly. The native Skill is optional for these workflows.
694
+
695
+ ```sh
696
+ npm install -g @masstensor/diagnose
697
+ diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
698
+ # Or use diagnose mcp --device workshop-laptop as the MCP server subprocess.
699
+ ```
700
+
701
+ Use `agent codex` or `agent gemini` for the other launchers. You can also run the npm launcher directly with `npx @masstensor/diagnose@latest agent claude`. The `--skill` launcher flag takes your device procedure. It does not require the native Diagnose Skill to be installed.
702
+
487
703
  ```sh
488
704
  diagnose connect
489
705
  ```
@@ -507,7 +723,7 @@ The direct commands accept an optional relay URL, for example `diagnose start ht
507
723
  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
724
 
509
725
 
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.
726
+ Short invitations use OPAQUE between the two endpoints to derive a strong Noise PSK. Only a two-letter locator reaches the relay; the other seven random letters remain the PAKE secret. The probe itself enforces expiry and attempt limits. Remembered relationships and legacy D1 invitations use independent random 256-bit secrets. The transport uses Noise `NNpsk0_25519_ChaChaPoly_BLAKE2b`, ephemeral X25519 keys, independent direction counters, and routing/role/version binding. See the [short invitation protocol](https://github.com/zkwasm/diagnose/blob/main/PAIRING_PROTOCOL.md) for the exact design and limits. 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.
511
727
 
512
728
  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.
513
729
 
package/deploy/Caddyfile CHANGED
@@ -1,6 +1,6 @@
1
1
  diagnose.fenginwind.com {
2
2
  encode zstd gzip
3
- @relay path /v1/connect /healthz /downloads/*
3
+ @relay path /v1/connect /v1/library /v1/library/* /healthz /downloads/*
4
4
  handle @relay {
5
5
  reverse_proxy 127.0.0.1:8792
6
6
  }
@@ -1 +1 @@
1
- module.exports = { apps: [{ name: 'diagnose-relay', cwd: '/home/ubuntu/diagnose-relay', script: 'deploy/start-relay.sh', interpreter: '/bin/sh', instances: 1, exec_mode: 'fork', max_memory_restart: '200M', kill_timeout: 5000, env: { NODE_ENV: 'production', HOST: '127.0.0.1', PORT: '8792', DOWNLOAD_PATH: '/home/ubuntu/diagnose-relay/diagnose-0.1.0.tgz' } }] };
1
+ module.exports = { apps: [{ name: 'diagnose-relay', cwd: '/home/ubuntu/diagnose-relay', script: 'deploy/start-relay.sh', interpreter: '/bin/sh', instances: 1, exec_mode: 'fork', max_memory_restart: '200M', kill_timeout: 5000, env: { NODE_ENV: 'production', HOST: '127.0.0.1', PORT: '8792', VAULT_PATH: '/home/ubuntu/diagnose-data/library', DOWNLOAD_PATH: '/home/ubuntu/diagnose-relay/diagnose-0.1.0.tgz' } }] };
package/dist/agent.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const agentUsage = "diagnose agent codex|claude|gemini [--device NAME] [--skill FILE.md|DIRECTORY] [--relay URL] [-- agent arguments...]";
1
+ export declare const agentUsage = "diagnose agent codex|claude|gemini [--device NAME] [--case ID] [--skill FILE.md|DIRECTORY|library:NAME@REVISION] [--relay URL] [-- agent arguments...]";
2
2
  export declare function launchAgent(argv: string[]): Promise<number>;
package/dist/agent.js CHANGED
@@ -6,13 +6,15 @@ import { join, resolve } from 'node:path';
6
6
  import { fileURLToPath } from 'node:url';
7
7
  import { parseArgs } from 'node:util';
8
8
  import { PairingStore } from './pairing.js';
9
- import { loadSkill, skillPrompt } from './skill.js';
9
+ import { skillPrompt } from './skill.js';
10
+ import { resolveSkill } from './skill-library.js';
11
+ import { Cases } from './cases.js';
10
12
  import { agentCommand } from './agent-command.js';
11
- export const agentUsage = 'diagnose agent codex|claude|gemini [--device NAME] [--skill FILE.md|DIRECTORY] [--relay URL] [-- agent arguments...]';
13
+ export const agentUsage = 'diagnose agent codex|claude|gemini [--device NAME] [--case ID] [--skill FILE.md|DIRECTORY|library:NAME@REVISION] [--relay URL] [-- agent arguments...]';
12
14
  export async function launchAgent(argv) {
13
15
  const separator = argv.indexOf('--');
14
16
  const extra = separator < 0 ? [] : argv.slice(separator + 1);
15
- const { positionals, values } = parseArgs({ args: separator < 0 ? argv : argv.slice(0, separator), allowPositionals: true, options: { relay: { type: 'string' }, skill: { type: 'string' }, device: { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
17
+ const { positionals, values } = parseArgs({ args: separator < 0 ? argv : argv.slice(0, separator), allowPositionals: true, options: { relay: { type: 'string' }, skill: { type: 'string' }, device: { type: 'string' }, case: { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
16
18
  if (values.help || !positionals.length) {
17
19
  console.log(agentUsage);
18
20
  return 0;
@@ -22,7 +24,15 @@ export async function launchAgent(argv) {
22
24
  throw new Error(agentUsage);
23
25
  if (values.device)
24
26
  new PairingStore().get(values.device, 'operator');
25
- const skill = values.skill === undefined ? undefined : await loadSkill(values.skill);
27
+ const selectedCase = values.case ? new Cases().get(values.case) : undefined;
28
+ if (selectedCase?.host && values.device && selectedCase.host !== values.device)
29
+ throw new Error('Selected case belongs to a different paired computer');
30
+ if (selectedCase?.skill && values.skill && selectedCase.skill !== values.skill)
31
+ throw new Error('Case skill revision differs from selected skill');
32
+ const skillInput = values.skill ?? selectedCase?.skill;
33
+ let skill = skillInput ? await resolveSkill(skillInput) : undefined;
34
+ if (selectedCase && !skill)
35
+ skill = { sourceFile: '', baseDirectory: process.cwd(), sha256: '', instructions: 'Use diagnose_case show to read the selected case. Confirm the external target identity, inspect interfaces conservatively, diagnose the stated goal, apply only authorized repairs, and record evidence-backed verification. Propose a reusable skill draft if useful.' };
26
36
  if (skill && agent === 'gemini' && extra.some(arg => ['-p', '--prompt', '-i', '--prompt-interactive'].includes(arg) || arg.startsWith('--prompt=') || arg.startsWith('--prompt-interactive=')))
27
37
  throw new Error('--skill supplies the initial task; do not also pass a Gemini prompt option');
28
38
  if (values.relay) {
@@ -33,7 +43,7 @@ export async function launchAgent(argv) {
33
43
  throw new Error('Relay URL must not contain credentials');
34
44
  }
35
45
  // Reuse this exact installed version. No global install or extra npx download.
36
- const server = { command: process.execPath, args: [fileURLToPath(new URL('./cli.js', import.meta.url)), 'mcp', ...(values.relay ? [values.relay] : []), ...(values.device ? ['--device', values.device] : [])] };
46
+ const server = { command: process.execPath, args: [fileURLToPath(new URL('./cli.js', import.meta.url)), 'mcp', ...(values.relay ? [values.relay] : []), ...(values.device ? ['--device', values.device] : []), ...(values.case ? ['--case', values.case] : [])] };
37
47
  const env = { ...process.env };
38
48
  let directory;
39
49
  try {