@masstensor/diagnose 0.3.2 → 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 +56 -9
- package/USER_GUIDE.md +460 -20
- package/deploy/Caddyfile +1 -1
- package/deploy/ecosystem.config.cjs +1 -1
- package/dist/agent-command.d.ts +4 -0
- package/dist/agent-command.js +33 -0
- package/dist/agent.d.ts +1 -1
- package/dist/agent.js +48 -8
- package/dist/cases.d.ts +118 -0
- package/dist/cases.js +115 -0
- package/dist/cli.js +187 -25
- package/dist/crypto.d.ts +7 -0
- package/dist/crypto.js +16 -1
- package/dist/discover.js +1 -1
- package/dist/engine.d.ts +3 -0
- package/dist/engine.js +49 -9
- package/dist/history.d.ts +13 -0
- package/dist/history.js +57 -0
- package/dist/journal.d.ts +23 -1
- package/dist/journal.js +82 -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/maintenance.d.ts +2 -0
- package/dist/maintenance.js +46 -0
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +42 -20
- package/dist/operator.d.ts +4 -0
- package/dist/operator.js +33 -8
- package/dist/pairing.d.ts +40 -0
- package/dist/pairing.js +92 -0
- package/dist/peer.d.ts +13 -0
- package/dist/peer.js +87 -11
- package/dist/relay-main.js +1 -1
- package/dist/relay.d.ts +1 -0
- package/dist/relay.js +27 -4
- package/dist/resources.js +47 -26
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +2 -2
- 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 +9 -0
- package/dist/skill.js +59 -0
- package/dist/transfers.js +28 -11
- package/dist/util.d.ts +2 -0
- package/dist/util.js +17 -3
- 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/examples/skills/device-troubleshooting/SKILL.md +35 -0
- package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
- package/examples/skills/owon.md +27 -0
- package/npm-shrinkwrap.json +209 -3
- package/package.json +15 -5
- package/scripts/setup-node.ps1 +54 -0
- package/scripts/setup-node.sh +52 -0
- package/src/agent-command.ts +25 -0
- package/src/agent.ts +37 -7
- package/src/cases.ts +74 -0
- package/src/cli.ts +57 -22
- package/src/crypto.ts +14 -1
- package/src/discover.ts +1 -1
- package/src/engine.ts +28 -7
- package/src/history.ts +43 -0
- package/src/journal.ts +41 -5
- package/src/knowledge-cli.ts +67 -0
- package/src/knowledge-drafts.ts +55 -0
- package/src/knowledge-mcp.ts +35 -0
- package/src/maintenance.ts +30 -0
- package/src/mcp.ts +26 -18
- package/src/operator.ts +25 -9
- package/src/pairing.ts +64 -0
- package/src/peer.ts +42 -14
- package/src/relay-main.ts +1 -1
- package/src/relay.ts +18 -6
- package/src/resources.ts +35 -13
- package/src/schema.ts +4 -4
- package/src/short-pairing.ts +57 -0
- package/src/skill-library.ts +162 -0
- package/src/skill.ts +45 -0
- package/src/transfers.ts +14 -3
- package/src/util.ts +15 -3
- 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 +79 -7
- 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 +124 -0
- package/test/review.test.ts +129 -0
- package/test/setup.test.ts +16 -0
- package/test/short-pairing.test.ts +100 -0
- package/test/skill-library.test.ts +62 -0
- package/test/skill.test.ts +25 -0
|
@@ -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
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# Diagnose
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Diagnose and fix problems remotely with your AI agent.**
|
|
4
4
|
|
|
5
|
-
Diagnose is an open-source
|
|
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
|
|
|
9
|
-
Requires **Node.js
|
|
9
|
+
Requires **Node.js 20.10+**. MIT licensed. TypeScript source is included in the npm package. macOS probes and the Linux relay have been tested. CI covers macOS/Linux and targeted Windows regressions; Windows interactive terminals and physical USB/serial behavior still need real-environment validation.
|
|
10
10
|
|
|
11
11
|
## Quick start
|
|
12
12
|
|
|
@@ -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,7 +40,52 @@ diagnose start
|
|
|
40
40
|
diagnose agent codex
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
|
|
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
|
+
|
|
45
|
+
## Pair once, return later
|
|
46
|
+
|
|
47
|
+
Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
diagnose pair --name alice-pc
|
|
51
|
+
# Enter the temporary code and your label/provider; user confirms remembering.
|
|
52
|
+
diagnose agent codex --device alice-pc --skill ./devices/owon.md
|
|
53
|
+
# Same options for claude or gemini; --skill is optional.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Restart the agent whenever needed without a new code. Pairing persists across probe restarts, but access requires the foreground probe. Task approval remains the default. The user may grant automatic execution and transmission for one hour, or explicitly until revoked. Local `pause`, `permissions ask`, and `unpair` control access. Interrupted modifications are never automatically replayed. See the [pairing guide](USER_GUIDE.md#keep-a-device-paired-for-future-diagnosis).
|
|
57
|
+
|
|
58
|
+
## Start with a device skill or Markdown task
|
|
59
|
+
|
|
60
|
+
Requires **0.4.0+**. Use the same option with every supported agent:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
diagnose agent codex --skill ./devices/owon.md
|
|
64
|
+
diagnose agent claude --skill ./devices/owon.md
|
|
65
|
+
diagnose agent gemini --skill ./devices/owon.md
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
A directory is also accepted: `--skill ./skills/my-device` reads its `SKILL.md`. Relative references remain based on that file's original directory. Diagnose snapshots the entry and supplies a startup task that tells the agent to read it and begin, instead of waiting for you to repeat the task. It asks for a pairing code or other missing target details when needed.
|
|
69
|
+
|
|
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).
|
|
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
|
+
|
|
78
|
+
## From problem to verified result
|
|
79
|
+
|
|
80
|
+
1. **Define the problem:** agree on the symptom and what a successful outcome looks like.
|
|
81
|
+
2. **Investigate:** inspect the environment, gather evidence, and identify the likely cause.
|
|
82
|
+
3. **Plan the fix:** explain the proposed changes, their impact, and recovery options where available.
|
|
83
|
+
4. **Act with permission:** use approved commands, scripts, or file changes to carry out the fix.
|
|
84
|
+
5. **Verify and hand off:** repeat the original check, summarize changes, and identify any remaining issues.
|
|
85
|
+
|
|
86
|
+
This is an agent-guided workflow using the existing tools and permission model. Diagnose does not automatically prove a repair succeeded or roll back arbitrary changes. See the [troubleshooting workflow](USER_GUIDE.md#from-a-reported-problem-to-a-verified-result).
|
|
87
|
+
|
|
88
|
+
## Remote tools
|
|
44
89
|
|
|
45
90
|
| Capability | Interface |
|
|
46
91
|
| --- | --- |
|
|
@@ -63,13 +108,15 @@ No device-specific integration is required in the probe. An approved script can
|
|
|
63
108
|
- Approved processes have the current OS user's permissions. **Diagnose is not a sandbox.** It does not automatically elevate privileges or install a background service.
|
|
64
109
|
- Finite text results receive best-effort credential redaction. Live terminals, exact file transfers, and TCP traffic are raw and **not redacted**.
|
|
65
110
|
- Results are visible to the diagnostician and the AI provider they use. End-to-end encryption does not hide data from those recipients.
|
|
66
|
-
- Local audit logs record decisions, targets, hashes, byte counts, and outcomes. They do not reconstruct every side effect of an arbitrary program. Changes are not automatically rolled back.
|
|
111
|
+
- Local audit logs record decisions, targets, hashes, byte counts, and outcomes. Encrypted history keeps exact task requests, finite collected results, approvals, and send events: use `diagnose history`, `diagnose show ID`, and `diagnose cleanup --days 0`. History and resource journals each have a 256 MiB / 2,000-record budget and seven-day inactive retention. They do not reconstruct every side effect of an arbitrary program. Changes are not automatically rolled back.
|
|
67
112
|
- `permissions ask`, `cancel`, and `Ctrl+C` are local controls. Data already transmitted cannot be recalled.
|
|
68
113
|
|
|
69
114
|
Read the [user guide](USER_GUIDE.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
|
|
70
115
|
|
|
71
116
|
## Development
|
|
72
117
|
|
|
118
|
+
Development scripts use Node.js 22.18+ to run TypeScript directly. Installed CLI runtime support starts at Node.js 20.10; users do not need to upgrade an existing compatible runtime.
|
|
119
|
+
|
|
73
120
|
```sh
|
|
74
121
|
npm ci
|
|
75
122
|
npm run check
|
|
@@ -79,10 +126,10 @@ npm pack
|
|
|
79
126
|
|
|
80
127
|
Tests exercise the actual encrypted protocol, approval boundaries, native terminals, transfers, forwarding, recovery, and the stdio MCP interface. The Noise tests include a public Cacophony interoperability vector. Hardware acceptance scripts and device logs are not distributed.
|
|
81
128
|
|
|
82
|
-
The `site/` directory contains the static landing page, a small TypeScript interaction module, and a build script that renders the guide. Run `npm run build:site` and `npm run check:site`; serve `.site-dist/` to preview. No analytics, third-party scripts, or cookies are required. The
|
|
129
|
+
The `site/` directory contains the static landing page, a small TypeScript interaction module, and a build script that renders the guide. Run `npm run build:site` and `npm run check:site`; serve `.site-dist/` to preview. No analytics, third-party scripts, or cookies are required. The website features a 60-second English animation covering the current agent launcher, permissions, encrypted relay, investigation, authorized repair, and result verification. Its repair story is illustrative, not a live diagnosis. Reproduce it with `npm run video:render`; see [video documentation](https://github.com/zkwasm/diagnose/blob/main/video/README.md). The earlier Chinese video is retained unchanged.
|
|
83
130
|
|
|
84
131
|
## Relay deployment
|
|
85
132
|
|
|
86
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.
|
|
87
134
|
|
|
88
|
-
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.
|