@masstensor/diagnose 0.5.0 → 0.7.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/DEVELOPMENT_PLAN.md +69 -0
- package/KNOWLEDGE_SECURITY.md +47 -0
- package/PAIRING_PROTOCOL.md +37 -0
- package/README.md +12 -4
- package/USER_GUIDE.md +178 -31
- package/deploy/Caddyfile +1 -1
- package/deploy/ecosystem.config.cjs +1 -1
- package/dist/agent.d.ts +1 -1
- package/dist/agent.js +15 -5
- package/dist/cases.d.ts +118 -0
- package/dist/cases.js +115 -0
- package/dist/cli.js +19 -8
- package/dist/crypto.d.ts +7 -0
- package/dist/crypto.js +16 -1
- package/dist/discover.js +1 -1
- package/dist/engine.d.ts +1 -0
- package/dist/engine.js +12 -5
- package/dist/knowledge-cli.d.ts +2 -0
- package/dist/knowledge-cli.js +164 -0
- package/dist/knowledge-drafts.d.ts +47 -0
- package/dist/knowledge-drafts.js +76 -0
- package/dist/knowledge-mcp.d.ts +5 -0
- package/dist/knowledge-mcp.js +65 -0
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +27 -8
- package/dist/operator.d.ts +2 -0
- package/dist/operator.js +16 -3
- package/dist/peer.d.ts +9 -0
- package/dist/peer.js +78 -9
- package/dist/relay-main.js +1 -1
- package/dist/relay.d.ts +1 -0
- package/dist/relay.js +27 -4
- package/dist/short-pairing.d.ts +25 -0
- package/dist/short-pairing.js +73 -0
- package/dist/skill-library.d.ts +27 -0
- package/dist/skill-library.js +226 -0
- package/dist/skill.d.ts +1 -0
- package/dist/skill.js +1 -0
- package/dist/util.js +1 -0
- package/dist/vault-crypto.d.ts +11 -0
- package/dist/vault-crypto.js +30 -0
- package/dist/vault-server.d.ts +10 -0
- package/dist/vault-server.js +156 -0
- package/dist/vault.d.ts +19 -0
- package/dist/vault.js +72 -0
- package/npm-shrinkwrap.json +12 -2
- package/package.json +6 -2
- package/src/agent.ts +12 -5
- package/src/cases.ts +74 -0
- package/src/cli.ts +11 -7
- package/src/crypto.ts +14 -1
- package/src/discover.ts +1 -1
- package/src/engine.ts +9 -3
- package/src/knowledge-cli.ts +67 -0
- package/src/knowledge-drafts.ts +55 -0
- package/src/knowledge-mcp.ts +35 -0
- package/src/mcp.ts +12 -6
- package/src/operator.ts +10 -3
- package/src/peer.ts +38 -12
- package/src/relay-main.ts +1 -1
- package/src/relay.ts +18 -6
- package/src/short-pairing.ts +57 -0
- package/src/skill-library.ts +162 -0
- package/src/skill.ts +2 -1
- package/src/util.ts +1 -0
- package/src/vault-crypto.ts +25 -0
- package/src/vault-server.ts +72 -0
- package/src/vault.ts +51 -0
- package/test/agent.test.ts +26 -1
- package/test/cli.test.ts +3 -3
- package/test/knowledge-mcp.test.ts +37 -0
- package/test/knowledge.test.ts +112 -0
- package/test/mcp.test.ts +1 -1
- package/test/pairing.test.ts +2 -2
- package/test/review.test.ts +1 -0
- package/test/short-pairing.test.ts +100 -0
- package/test/skill-library.test.ts +62 -0
- package/test/skill.test.ts +1 -1
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Device diagnosis and reusable knowledge
|
|
2
|
+
|
|
3
|
+
Status: all four implementation milestones completed for 0.6.0; release/deployment verification is tracked below.
|
|
4
|
+
|
|
5
|
+
## Product outcome
|
|
6
|
+
|
|
7
|
+
An on-site computer gives an authorized AI diagnostician access to an external device. Each investigation should leave evidence of its outcome and, when useful, a reusable procedure. The same procedure should work from another diagnostician computer without transferring customer logs or device pairing credentials.
|
|
8
|
+
|
|
9
|
+
## Assumptions
|
|
10
|
+
|
|
11
|
+
- Existing remote execution, transport and local approval remain the authority for device actions. A skill never grants permission.
|
|
12
|
+
- Local use works without an account or relay storage. Cloud synchronization is optional.
|
|
13
|
+
- Private skills may contain commercially sensitive instructions. Relay storage must be client-encrypted, including names and references.
|
|
14
|
+
- Session evidence is local by default. Publishing knowledge is a separate, explicit action.
|
|
15
|
+
- First release supports a personal library; team roles and public catalogs are later work.
|
|
16
|
+
|
|
17
|
+
## 1. Local versioned skill library — implemented
|
|
18
|
+
|
|
19
|
+
Import a Markdown file or a complete skill directory, including references and scripts. Address each version by a content digest. Preserve old versions; never silently select a different revision. Existing file-based launch remains supported across Codex, Claude and Gemini.
|
|
20
|
+
|
|
21
|
+
Acceptance: nested resources survive import; imports do not execute scripts; changed resources produce a new version; old versions still load; duplicate imports are idempotent; invalid paths, symlinks, excessive bundles and modified stored files fail validation. CLI output provides the exact launch reference.
|
|
22
|
+
|
|
23
|
+
Implemented: `diagnose skills import`, `diagnose skills list`, and `--skill library:NAME@REVISION` for all three agent launchers. Local tests cover version retention, integrity checks, concurrent duplicate imports, size/file-count limits and launcher integration. Type checking and site checks pass. Cross-platform CI includes the library and knowledge workflow tests. See release validation below for observed environments.
|
|
24
|
+
|
|
25
|
+
## 2. Target and evidence records — implemented
|
|
26
|
+
|
|
27
|
+
Separate the paired on-site computer from the device being investigated. A case records the goal, device model/identity, interface, selected skill revision, task IDs, observations, approved changes, verification and unresolved questions. Record only results actually received by the diagnostician. Allow an explicit outcome of unresolved, needs physical work, or insufficient evidence.
|
|
28
|
+
|
|
29
|
+
Add a tool for querying operation schemas/examples before execution. Start discovery with existing low-interference inspection; network scans, serial writes and repairs retain normal approval. Connection status distinguishes relay, probe, device interface and device response.
|
|
30
|
+
|
|
31
|
+
Acceptance: a gateway case points to the gateway rather than its host alias; disconnect/reconnect does not turn an interrupted repair into an automatic retry; a success report links the original failure to a subsequent verification result. Exports omit credentials and raw evidence by default.
|
|
32
|
+
|
|
33
|
+
## 3. Learn from a diagnosis — implemented
|
|
34
|
+
|
|
35
|
+
An agent proposes either a new skill draft or a revision based on the exact skill used. Keep observations and untrusted device output separate from instructions. Drafts include applicability, prerequisites, identity checks, read-only checks, repair conditions, recovery steps, verification, failed approaches and supporting case/task references. Parameterize device addresses and customer-specific values.
|
|
36
|
+
|
|
37
|
+
Show a diff and evidence to the diagnostician before accepting a version. If the base changed, retain both drafts and require reconciliation. An agent proposal must not silently replace an accepted skill. Secret detection assists review but is not a guarantee of sanitization.
|
|
38
|
+
|
|
39
|
+
Acceptance: a real read-only OWON investigation can produce a reviewed reusable draft without pairing codes or raw logs; an improvement preserves its base revision; rejected drafts do not affect launch; conflicting edits remain recoverable. Hardware writes require a separate justified test.
|
|
40
|
+
|
|
41
|
+
## 4. Optional encrypted personal library — implemented
|
|
42
|
+
|
|
43
|
+
Design a library identity independent from probe pairing. A new computer imports a recovery credential, retrieves ciphertext, authenticates and decrypts locally, then uses the same local versioned loader. Include complete bundles and encrypted manifests. Review key derivation, authenticated encryption, authentication, key recovery and revocation before implementation. Explain that losing all recovery credentials loses access to encrypted data.
|
|
44
|
+
|
|
45
|
+
Relay requirements: persistent storage, authenticated writes, size and rate limits, atomic revision publication, conflict detection, deletion and backup policy. No raw case history is synchronized by default. Retain divergent versions rather than last-writer-wins overwrites. Cache verified versions for offline use; downloading never executes a skill.
|
|
46
|
+
|
|
47
|
+
Acceptance: two isolated clients can sync and launch the same version; the relay cannot read names or contents; wrong keys and modified ciphertext fail; interrupted upload never publishes a partial version; concurrent edits are retained; device pairing credentials cannot access a library. Deploy to the existing AWS relay only after these checks pass.
|
|
48
|
+
|
|
49
|
+
## Release and documentation
|
|
50
|
+
|
|
51
|
+
Ship each completed milestone with English CLI help, guide examples and tests. Mark unreleased commands clearly until npm publication. Update the landing page when a complete user workflow is available, not when a roadmap item is merely planned. Preserve Node.js 20.10 compatibility and verify relevant Windows/macOS/Linux behavior. Avoid requiring connected hardware for library tests.
|
|
52
|
+
|
|
53
|
+
## Release validation
|
|
54
|
+
|
|
55
|
+
- Full initial regression: 85 passing tests on macOS/Node 22.
|
|
56
|
+
- Final knowledge/MCP checks: 8 passing tests, including interrupted upload and quota checks.
|
|
57
|
+
- Final launcher checks: 19 passing tests, including all three agents with a selected case and pinned skill.
|
|
58
|
+
- Node.js 20.10: 30 knowledge, library, MCP and launcher checks passed.
|
|
59
|
+
- Physical user-identified OWON SEG-X3-C: two authorized read-only serial captures received 20,293 and 18,992 bytes. Encrypted local case and a pending reviewed draft were produced; no serial command or raw-log publication occurred. This verifies log transport, not device health.
|
|
60
|
+
- English guide, landing page, CLI help and security/operations document updated. Site link, anchor and interaction checks pass.
|
|
61
|
+
- AWS relay and website deployed. Two isolated clients completed an HTTPS encrypted-library roundtrip and revoked the synthetic library. Existing Noise diagnostic sessions were also verified through the public relay.
|
|
62
|
+
- Windows/macOS/Linux CI passed after fixing Windows concurrent-directory publication and a nonportable test filename. Final single-writer case protection passed 28 local tests and is included in the next CI run.
|
|
63
|
+
- npm publication awaits official account verification.
|
|
64
|
+
|
|
65
|
+
The first release deliberately retains explicit pinned revisions, a personal capability-based library, human draft review, and agent-assessed device status. Team roles/public catalogs, automatic rollback, native agent skill installation, proof of inventory freshness, and an independent security audit are outside this plan.
|
|
66
|
+
|
|
67
|
+
## 0.7 invitation usability
|
|
68
|
+
|
|
69
|
+
Implemented nine-letter invitations with a 30-minute deadline, OPAQUE endpoint authentication, local consent, independent endpoint attempt limits, and unchanged high-entropy remembered credentials. Session idle/lifetime clocks now begin after pairing. Legacy D1 invitations remain accepted. See PAIRING_PROTOCOL.md for the design, entropy accounting and rollout requirements. The previously pending 0.6 features are included in this release; npm 0.6 publication was not completed.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Personal knowledge library security and operations
|
|
2
|
+
|
|
3
|
+
## Scope and threat model
|
|
4
|
+
|
|
5
|
+
Remote device sessions retain the existing Noise protocol and user-controlled permissions. The knowledge library is separate: a person holding its recovery credential can retrieve, publish and revoke that person's library. It is not an account, proof of identity, team role system or device pairing credential.
|
|
6
|
+
|
|
7
|
+
The relay is trusted for availability, storage quotas and revocation, but not with skill plaintext. It sees source IPs, request times, ciphertext sizes, the number of objects, an opaque stable namespace, and stable object identifiers. The AI provider can see instructions and evidence supplied to the agent. Local files and recovery credentials are accessible to the same OS user; this is not a sandbox against a malicious local process.
|
|
8
|
+
|
|
9
|
+
## Cryptographic format v1
|
|
10
|
+
|
|
11
|
+
- Recovery credential: `K1.` followed by 32 random bytes encoded as canonical base64url. Never a password or a probe pairing code.
|
|
12
|
+
- HKDF-SHA-256 with salt `diagnose-library-v1` and distinct info strings `authentication`, `encryption`, and `object-names` derives independent 32-byte keys.
|
|
13
|
+
- The authentication key is sent as an HTTPS Bearer capability. The storage namespace is SHA-256 of its base64url text. The server cannot derive the encryption key from this capability.
|
|
14
|
+
- Object names are HMAC-SHA-256 of the complete pinned library reference using the object-name key. Names and paths are not sent in plaintext.
|
|
15
|
+
- A bundle is encrypted with AES-256-GCM, a fresh random 12-byte nonce and a 16-byte tag. AAD is `diagnose-library-v1:NAMESPACE:OBJECT_ID`. Wire layout is one version byte (`1`), nonce, ciphertext, tag.
|
|
16
|
+
- Decrypted JSON contains the reference and the complete file bundle. Clients validate the object HMAC, portable paths, file/size limits and the content digest before importing. Encryption covers provenance as well as instructions and resources. Downloads never execute anything.
|
|
17
|
+
|
|
18
|
+
Objects are immutable. Concurrent different revisions have different identifiers and are retained. There is no remote mutable “latest” pointer, so no overwrite or head compare-and-swap is needed. A concurrent duplicate upload can return 409; rerun the explicit push to verify the stored plaintext matches. No modifying diagnostic command is replayed as a consequence of sync.
|
|
19
|
+
|
|
20
|
+
A malicious relay can omit or replay a previously valid object or deny service. It cannot forge new plaintext under the key. This version does not provide cryptographic proof of inventory completeness or freshness on a newly restored computer. Local cached versions are never removed by pull. Permission bits are not part of portable content identity; restored files are private non-executable files and scripts can be run explicitly through an interpreter after review.
|
|
21
|
+
|
|
22
|
+
## Review boundary
|
|
23
|
+
|
|
24
|
+
The agent can propose drafts and cite locally recorded evidence. There is no MCP tool to accept drafts, reveal recovery keys or upload skills. CLI acceptance displays the exact proposed entry and evidence references and requires an interactive confirmation. CLI push separately confirms publishing the complete bundle. Base references/scripts are preserved, not regenerated silently.
|
|
25
|
+
|
|
26
|
+
This separation is a workflow guard, not an OS security boundary: an agent allowed unrestricted local shell access can read or modify the diagnostician's files. Continue to use the agent's own permissions. Treat captured output as untrusted data. Automated redaction is best effort; review addresses, identifiers, credentials and customer details before accepting or sharing. Do not place raw logs in skill directories.
|
|
27
|
+
|
|
28
|
+
## Local retention
|
|
29
|
+
|
|
30
|
+
- Cases: encrypted metadata with a same-user local key; at most 100 cases, 200 evidence records each. Each record retains at most 32 KiB of sanitized JSON (larger values retain a preview and digest). Limit exhaustion is surfaced; no claim of complete evidence is made. Remove cases explicitly after exporting a reviewed summary.
|
|
31
|
+
- Drafts: at most 100 encrypted draft records. Accepted/rejected records can be removed without removing imported versions.
|
|
32
|
+
- Skills: local private plaintext source bundles. No automatic deletion. Every directory import includes all regular files within the declared limits.
|
|
33
|
+
- Recovery credential: private local file at `~/.diagnose/vault/recovery`. Backups use exclusive file creation and private permissions where supported. Never include a recovery key in a prompt, argv, issue or report.
|
|
34
|
+
|
|
35
|
+
## Relay operations
|
|
36
|
+
|
|
37
|
+
Set `VAULT_PATH` to persistent storage outside release directories. Run one relay process, not multiple workers sharing this filesystem. Route `/v1/library` and `/v1/library/*` through the existing HTTPS proxy. Do not log Authorization headers. Current limits: 12 MiB per encrypted object, 128 objects and 128 MiB per library, 1 GiB total, 1,000 namespaces including revocation tombstones, two concurrent uploads, 600 requests per IP per minute, 30-second total upload deadline. Hosting a public capability store still requires monitoring for abuse; quotas bound this implementation's storage use.
|
|
38
|
+
|
|
39
|
+
A write is staged and atomically renamed only after the full declared body arrives and quotas are rechecked. Unpublished staging files are removed on startup. Per-object writes are flushed before publication. Keep the host disk backed by a reliable filesystem; atomic publication does not promise survival of every filesystem or power failure.
|
|
40
|
+
|
|
41
|
+
No automatic server backups are created by the application. Local verified skills plus an offline recovery backup are the user's recovery path. Operators may back up the ciphertext store and tombstones, using encrypted snapshots with an explicit retention policy. Restoring an older server backup can resurrect deleted ciphertext and lose recent revocations; preserve and reconcile tombstones before restoring service. Do not promise deletion from external backups the application cannot control.
|
|
42
|
+
|
|
43
|
+
`vault revoke` deletes the current server library and persists a tombstone for that capability. It revokes all computers using that credential on that relay. It cannot erase previously downloaded plaintext or ciphertext. For rotation: pull/cache wanted versions first, revoke, forget the local credential, initialize a new credential and backup, then explicitly push chosen versions and restore the new credential on trusted computers. A lost or exposed credential cannot be repaired by changing a device pairing code. Losing all recovery copies loses decryption access to server-only versions.
|
|
44
|
+
|
|
45
|
+
## Validation
|
|
46
|
+
|
|
47
|
+
Tests cover real stdio MCP case recording and draft proposal; base preservation and conflicts; independent clients; wrong keys and AAD; ciphertext tampering; invalid bundle paths; immutable writes; unauthenticated access; revocation; offline cached use; quota/partial-request behavior. Cryptography uses Node's standard primitives; this is not a claim of an independent security audit.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Short invitation protocol (Diagnose 0.7)
|
|
2
|
+
|
|
3
|
+
## User experience
|
|
4
|
+
|
|
5
|
+
New invitations are nine uniformly random English letters, displayed as `abc-def-ghi`. Input ignores case, whitespace and hyphens. They expire after 30 minutes, including time spent awaiting local confirmation. Successful pairing consumes the invitation. Declining, reaching the attempt limit, or ending the probe also invalidates it. A running probe generates a new invitation when the old one ends.
|
|
6
|
+
|
|
7
|
+
Remembered pairing still exchanges an independent 256-bit random `D1` credential inside the approved encrypted session. It is stored privately and is not spoken or manually entered. Existing remembered credentials work unchanged. Knowledge-library `K1` recovery credentials are unrelated and unchanged.
|
|
8
|
+
|
|
9
|
+
## Routing and authentication
|
|
10
|
+
|
|
11
|
+
The first two letters form a public locator: relay room `S2.ab`. The remaining seven letters are the PAKE password, with approximately 32.9 bits of entropy. The total nine-letter string has approximately 42.3 bits, but the public locator is **not** counted as authentication entropy. There are 676 locator slots; the current relay allows at most 100 active rooms. A collision is rejected without replacing the first host, and the CLI generates a fresh invitation before showing it.
|
|
12
|
+
|
|
13
|
+
The complete code, password, or a publicly testable hash of them is never sent to the relay. Publishing a hash of all nine letters as the routing identifier would create an offline password-checking oracle and is deliberately avoided.
|
|
14
|
+
|
|
15
|
+
The probe enforces at most five attempted handshakes per invitation, even if the relay ignores its own limits. The relay also enforces five attempts, 30-minute expiry, concurrent connection limits and 60 new connections per IP per minute. Wrong passwords cannot reach the local approval prompt. These limits bound online guessing; they cannot guarantee availability against a malicious relay. A holder of the complete code can request access, but still needs local user approval. A supplied name is not verified identity.
|
|
16
|
+
|
|
17
|
+
## Cryptographic flow
|
|
18
|
+
|
|
19
|
+
1. The probe creates fresh OPAQUE server setup and a password registration record entirely in its own memory. No registration messages or verifier are published. A new setup is generated for each invitation.
|
|
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
|
+
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
|
+
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.
|
|
24
|
+
|
|
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
|
+
|
|
27
|
+
## Wire compatibility and bounds
|
|
28
|
+
|
|
29
|
+
The WebSocket endpoint remains `/v1/connect`. Registration version 2 accepts only `S2.` plus two lowercase letters. Version 1 accepts the existing 16-character room IDs. The formats cannot negotiate or silently downgrade between mechanisms. New clients accept old `D1` invitations; old clients cannot use new short invitations. Upgrade both endpoints and the relay for the short-code flow.
|
|
30
|
+
|
|
31
|
+
OPAQUE messages are strict JSON binary frames with exactly `pake` and `value` fields. Stage values are `start`, `response`, `finish`; each frame is bounded to 4 KiB and the encoded value to 2,048 characters. Stage ordering is enforced. The join endpoint accepts one relay join notification, preventing repeated password trials against one client handshake. The probe keeps a local invitation deadline and attempt counter independent from relay state. After OPAQUE completes, the existing Noise framing, counters, approval and resource authorization remain in force.
|
|
32
|
+
|
|
33
|
+
The relay can see locators, opaque handshake transcripts, source IPs, timing and traffic sizes. It can interrupt service or send misleading control messages, but those messages do not disable endpoint expiry/attempt limits or authorize commands. Session transport continues to require TLS for non-loopback relays.
|
|
34
|
+
|
|
35
|
+
## Validation
|
|
36
|
+
|
|
37
|
+
Tests cover normalization, malformed inputs, wrong passwords and locator binding, successful key agreement, no approval before authentication, hidden long credential provisioning, one-time use, endpoint and relay expiry, malicious relay reset attempts, locator collisions and session timer ordering. Existing Noise vector, execution approval, persistent pairing and resource-recovery regressions remain required. The nine-letter examples in documentation are placeholders, never production credentials.
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Diagnose and fix problems remotely with your AI agent.**
|
|
4
4
|
|
|
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
|
|
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
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
|
|
|
@@ -16,7 +16,7 @@ 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
|
|
19
|
+
Keep the terminal open and privately share its nine-letter invitation, such as `abc-def-ghi`, with the diagnostician.
|
|
20
20
|
|
|
21
21
|
On the diagnostician's computer, start an already installed and authenticated agent:
|
|
22
22
|
|
|
@@ -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:
|
|
30
|
+
> 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
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,6 +40,8 @@ diagnose start
|
|
|
40
40
|
diagnose agent codex
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
+
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
|
+
|
|
43
45
|
## Pair once, return later
|
|
44
46
|
|
|
45
47
|
Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
|
|
@@ -67,6 +69,12 @@ A directory is also accepted: `--skill ./skills/my-device` reads its `SKILL.md`.
|
|
|
67
69
|
|
|
68
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).
|
|
69
71
|
|
|
72
|
+
## Keep and improve device knowledge
|
|
73
|
+
|
|
74
|
+
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
|
+
|
|
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).
|
|
77
|
+
|
|
70
78
|
## From problem to verified result
|
|
71
79
|
|
|
72
80
|
1. **Define the problem:** agree on the symptom and what a successful outcome looks like.
|
|
@@ -124,4 +132,4 @@ The `site/` directory contains the static landing page, a small TypeScript inter
|
|
|
124
132
|
|
|
125
133
|
`deploy/ecosystem.config.cjs`, `deploy/start-relay.sh`, and `deploy/Caddyfile` provide deployment templates. The relay binds to `127.0.0.1:8792`; Caddy terminates TLS. Its launcher disables core dumps. The service has no database or runtime decryption keys, does not persist diagnostic content, and does not enable Caddy access logging.
|
|
126
134
|
|
|
127
|
-
The production domain serves the landing page and guide while `/v1/connect`, `/healthz`, and `/downloads/*`
|
|
135
|
+
The production domain serves the landing page and guide while `/v1/connect`, `/v1/library`, `/v1/library/*`, `/healthz`, and `/downloads/*` reach the relay. Set `VAULT_PATH` to a persistent directory outside code releases to enable the optional encrypted skill store. It persists ciphertext and revocation markers, never plaintext skill contents or raw case logs. See [library operations](KNOWLEDGE_SECURITY.md). Deploy only the package's allowlisted files and public website assets. Never synchronize a diagnostic workspace, credentials, or hardware logs to the server.
|
package/USER_GUIDE.md
CHANGED
|
@@ -1,13 +1,34 @@
|
|
|
1
1
|
# Diagnose user guide
|
|
2
2
|
|
|
3
|
-
Diagnose
|
|
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
|
-
|
|
5
|
+
## Why: stop making the user carry every clue
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
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,13 +52,20 @@ 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.
|
|
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
|
|
68
|
+
If npm asks to install the package, type `y`. Keep this terminal open. Send the nine-letter invitation, such as `abc-def-ghi`, privately to your diagnostician.
|
|
41
69
|
|
|
42
70
|
### 3. On the diagnostician's computer
|
|
43
71
|
|
|
@@ -46,15 +74,15 @@ npx @masstensor/diagnose@latest agent codex
|
|
|
46
74
|
# Or replace codex with claude or gemini.
|
|
47
75
|
```
|
|
48
76
|
|
|
49
|
-
In the agent conversation, provide the code and a concrete
|
|
77
|
+
In the agent conversation, provide the code, device model, connection method, and a concrete goal:
|
|
50
78
|
|
|
51
|
-
> Use Diagnose to connect to this code:
|
|
79
|
+
> 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
80
|
|
|
53
81
|
### 4. Approve, diagnose, and finish
|
|
54
82
|
|
|
55
83
|
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
84
|
|
|
57
|
-
The diagnostician directs the agent to investigate, repair within permission, and
|
|
85
|
+
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
86
|
|
|
59
87
|
### Return later or load a device procedure
|
|
60
88
|
|
|
@@ -63,30 +91,32 @@ The diagnostician directs the agent to investigate, repair within permission, an
|
|
|
63
91
|
```sh
|
|
64
92
|
npm install -g @masstensor/diagnose@latest
|
|
65
93
|
# Diagnostician: pair once while the user's probe is running.
|
|
66
|
-
diagnose pair --name
|
|
94
|
+
diagnose pair --name workshop-laptop
|
|
67
95
|
# User: explicitly approve remembering this diagnostician.
|
|
68
96
|
# Diagnostician: use this whenever diagnosis is needed again.
|
|
69
|
-
diagnose agent codex --device
|
|
97
|
+
diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
|
|
70
98
|
```
|
|
71
99
|
|
|
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.
|
|
100
|
+
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
101
|
|
|
74
102
|
## From a reported problem to a verified result
|
|
75
103
|
|
|
76
|
-
|
|
104
|
+
For a device session, work toward an observable device outcome:
|
|
77
105
|
|
|
78
|
-
1. **Describe the problem.**
|
|
79
|
-
2. **Investigate first.** Ask the agent to
|
|
106
|
+
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.
|
|
107
|
+
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
108
|
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
109
|
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.**
|
|
110
|
+
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
111
|
|
|
84
112
|
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
113
|
|
|
86
|
-
You can also request a read-only investigation and stop after the explanation.
|
|
114
|
+
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
115
|
|
|
88
116
|
## 1. Requirements
|
|
89
117
|
|
|
118
|
+
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.
|
|
119
|
+
|
|
90
120
|
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
121
|
|
|
92
122
|
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 +209,7 @@ npm install -g @masstensor/diagnose@latest
|
|
|
179
209
|
diagnose start
|
|
180
210
|
```
|
|
181
211
|
|
|
182
|
-
|
|
212
|
+
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. The user must still approve locally. 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
213
|
|
|
184
214
|
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
215
|
|
|
@@ -205,7 +235,7 @@ Do **not** separately run `diagnose mcp` or register a global MCP server. The la
|
|
|
205
235
|
|
|
206
236
|
Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
|
|
207
237
|
|
|
208
|
-
> Use Diagnose to connect to pairing code
|
|
238
|
+
> 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
239
|
|
|
210
240
|
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
241
|
|
|
@@ -214,7 +244,7 @@ The code and diagnostic results enter your chosen AI provider's context. The use
|
|
|
214
244
|
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
245
|
|
|
216
246
|
```sh
|
|
217
|
-
diagnose pair --name
|
|
247
|
+
diagnose pair --name workshop-laptop
|
|
218
248
|
# Enter the user's code, then your label and AI provider when prompted.
|
|
219
249
|
```
|
|
220
250
|
|
|
@@ -223,9 +253,9 @@ The user's terminal explicitly asks whether to **remember** this diagnostician.
|
|
|
223
253
|
After pairing, the diagnostician can start, stop, and restart any supported agent using the same device name:
|
|
224
254
|
|
|
225
255
|
```sh
|
|
226
|
-
diagnose agent codex --device
|
|
227
|
-
diagnose agent claude --device
|
|
228
|
-
diagnose agent gemini --device
|
|
256
|
+
diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
|
|
257
|
+
diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
|
|
258
|
+
diagnose agent gemini --device workshop-laptop --skill ./devices/owon.md
|
|
229
259
|
# --skill is optional.
|
|
230
260
|
```
|
|
231
261
|
|
|
@@ -252,16 +282,105 @@ On the diagnostician's computer:
|
|
|
252
282
|
|
|
253
283
|
```sh
|
|
254
284
|
diagnose devices
|
|
255
|
-
diagnose connect --device
|
|
256
|
-
diagnose terminal --device
|
|
257
|
-
diagnose mcp --device
|
|
258
|
-
diagnose forget --device
|
|
285
|
+
diagnose connect --device workshop-laptop
|
|
286
|
+
diagnose terminal --device workshop-laptop
|
|
287
|
+
diagnose mcp --device workshop-laptop
|
|
288
|
+
diagnose forget --device workshop-laptop
|
|
259
289
|
```
|
|
260
290
|
|
|
261
291
|
`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
292
|
|
|
263
293
|
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
294
|
|
|
295
|
+
## Record a device diagnosis and improve your procedures
|
|
296
|
+
|
|
297
|
+
These knowledge features require Diagnose 0.6.0 or later on the diagnostician computer. Older probes can still perform their supported operations.
|
|
298
|
+
|
|
299
|
+
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.
|
|
300
|
+
|
|
301
|
+
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.
|
|
302
|
+
|
|
303
|
+
To create a case before launching, save a small JSON file:
|
|
304
|
+
|
|
305
|
+
```json
|
|
306
|
+
{
|
|
307
|
+
"goal": "Find why the gateway stopped reporting sensor readings",
|
|
308
|
+
"host": "workshop-laptop",
|
|
309
|
+
"target": { "name": "Workshop gateway", "model": "SEG-X3-C", "interface": "serial" }
|
|
310
|
+
}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
```sh
|
|
314
|
+
diagnose cases create ./gateway-case.json
|
|
315
|
+
diagnose cases list
|
|
316
|
+
diagnose agent codex --device workshop-laptop --case CASE_ID
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
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.
|
|
320
|
+
|
|
321
|
+
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.
|
|
322
|
+
|
|
323
|
+
```sh
|
|
324
|
+
diagnose cases show CASE_ID
|
|
325
|
+
diagnose cases export CASE_ID > reviewed-report.json
|
|
326
|
+
diagnose cases remove CASE_ID
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
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.
|
|
330
|
+
|
|
331
|
+
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.
|
|
332
|
+
|
|
333
|
+
### Review a new skill or improvement
|
|
334
|
+
|
|
335
|
+
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.
|
|
336
|
+
|
|
337
|
+
```sh
|
|
338
|
+
diagnose drafts list
|
|
339
|
+
diagnose drafts review DRAFT_ID
|
|
340
|
+
diagnose drafts accept DRAFT_ID
|
|
341
|
+
# Or keep the existing procedure:
|
|
342
|
+
diagnose drafts reject DRAFT_ID
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
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.
|
|
346
|
+
|
|
347
|
+
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.
|
|
348
|
+
|
|
349
|
+
### Share your private skill library across computers
|
|
350
|
+
|
|
351
|
+
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:
|
|
352
|
+
|
|
353
|
+
```sh
|
|
354
|
+
diagnose vault init ./diagnose-library-recovery.txt
|
|
355
|
+
diagnose vault push library:NAME@FULL_REVISION
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
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.
|
|
359
|
+
|
|
360
|
+
On a second diagnostician computer, securely transfer the recovery file yourself (never through an AI prompt) and run:
|
|
361
|
+
|
|
362
|
+
```sh
|
|
363
|
+
diagnose vault restore ./diagnose-library-recovery.txt
|
|
364
|
+
diagnose vault pull
|
|
365
|
+
diagnose skills list
|
|
366
|
+
diagnose agent claude --skill library:NAME@FULL_REVISION
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
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.
|
|
370
|
+
|
|
371
|
+
```sh
|
|
372
|
+
diagnose vault status
|
|
373
|
+
diagnose vault backup ./another-private-recovery-copy.txt
|
|
374
|
+
diagnose vault revoke
|
|
375
|
+
diagnose vault forget
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
**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.
|
|
379
|
+
|
|
380
|
+
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.
|
|
381
|
+
|
|
382
|
+
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.
|
|
383
|
+
|
|
265
384
|
## Start with a device skill or Markdown task
|
|
266
385
|
|
|
267
386
|
Version **0.4.0+** can start the agent with a selected diagnostic procedure. The syntax is identical for all three agents:
|
|
@@ -319,6 +438,26 @@ report what changed, the evidence, and anything unresolved.
|
|
|
319
438
|
|
|
320
439
|
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
440
|
|
|
441
|
+
### Local versioned library (v0.6+)
|
|
442
|
+
|
|
443
|
+
The local library requires Diagnose 0.6.0 or later.
|
|
444
|
+
|
|
445
|
+
Import a reviewed skill directory once, then use the exact reference printed by the command:
|
|
446
|
+
|
|
447
|
+
```sh
|
|
448
|
+
diagnose skills import owon ./examples/skills/device-troubleshooting
|
|
449
|
+
diagnose skills list
|
|
450
|
+
diagnose agent codex --device workshop-laptop --skill library:owon@FULL_SHA256_FROM_IMPORT
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
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.
|
|
454
|
+
|
|
455
|
+
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.
|
|
456
|
+
|
|
457
|
+
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.
|
|
458
|
+
|
|
459
|
+
Import/list commands are local. See the diagnosis case and private library sections for reviewed drafts and optional encrypted synchronization.
|
|
460
|
+
|
|
322
461
|
### Permissions and compatibility
|
|
323
462
|
|
|
324
463
|
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 +466,10 @@ This is portable Markdown task loading, not native installation of a Codex, Clau
|
|
|
327
466
|
|
|
328
467
|
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
468
|
|
|
469
|
+
### Short invitation compatibility
|
|
470
|
+
|
|
471
|
+
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.
|
|
472
|
+
|
|
330
473
|
### Session configuration and extra arguments
|
|
331
474
|
|
|
332
475
|
```sh
|
|
@@ -379,7 +522,7 @@ Do not ask the AI to collect OS passwords. For interactive authentication, the u
|
|
|
379
522
|
|
|
380
523
|
## 5. What the agent can do
|
|
381
524
|
|
|
382
|
-
The MCP interface provides
|
|
525
|
+
The MCP interface provides 15 tools:
|
|
383
526
|
|
|
384
527
|
| Tool | Purpose |
|
|
385
528
|
| --- | --- |
|
|
@@ -394,6 +537,10 @@ The MCP interface provides 11 tools:
|
|
|
394
537
|
| `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
|
|
395
538
|
| `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
|
|
396
539
|
| `diagnose_disconnect` | Disconnect the diagnostic session. |
|
|
540
|
+
| `diagnose_capabilities` | Query operation schemas and conservative discovery guidance. |
|
|
541
|
+
| `diagnose_case` | Create/show a case, record assessments, report connection layers and finish with evidence references. |
|
|
542
|
+
| `diagnose_skill_draft` | Propose a new skill or improvement for local human review. |
|
|
543
|
+
| `diagnose_skills` | List or read locally available pinned skill versions without executing them. |
|
|
397
544
|
|
|
398
545
|
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
546
|
|
|
@@ -464,7 +611,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
|
|
|
464
611
|
|
|
465
612
|
| Limit | Default / maximum |
|
|
466
613
|
| --- | --- |
|
|
467
|
-
|
|
|
614
|
+
| New short invitation | 30 minutes; one-time; up to five attempted handshakes |
|
|
468
615
|
| Temporary session idle / total | 10 minutes / 60 minutes by default |
|
|
469
616
|
| Remembered pairing | Until revoked locally; requires the foreground probe |
|
|
470
617
|
| Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
|
|
@@ -507,7 +654,7 @@ The direct commands accept an optional relay URL, for example `diagnose start ht
|
|
|
507
654
|
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
655
|
|
|
509
656
|
|
|
510
|
-
|
|
657
|
+
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
658
|
|
|
512
659
|
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
660
|
|
package/deploy/Caddyfile
CHANGED
|
@@ -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>;
|