@masstensor/diagnose 0.7.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PAIRING_PROTOCOL.md +1 -1
- package/README.md +22 -8
- package/USER_GUIDE.md +33 -649
- package/dist/cli.js +44 -7
- package/dist/discover.js +1 -1
- package/dist/engine.js +15 -8
- package/dist/install-skill.d.ts +2 -0
- package/dist/install-skill.js +57 -0
- package/dist/mcp.js +27 -4
- package/dist/operator.js +2 -0
- package/dist/peer.d.ts +1 -0
- package/dist/peer.js +24 -3
- package/dist/relay.js +21 -8
- package/dist/schema.d.ts +4 -1
- package/dist/schema.js +2 -2
- package/dist/session-limits.d.ts +3 -0
- package/dist/session-limits.js +3 -0
- package/dist/skill-session.d.ts +1 -0
- package/dist/skill-session.js +272 -0
- package/docs/guide/automation.md +184 -0
- package/docs/guide/diagnose.md +93 -0
- package/docs/guide/on-site.md +139 -0
- package/docs/guide/procedures.md +183 -0
- package/docs/guide/reconnect.md +58 -0
- package/docs/guide/troubleshooting.md +77 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +3 -1
- package/skills/connect/SKILL.md +66 -0
- package/skills/connect/scripts/run.mjs +37 -0
- package/src/cli.ts +42 -8
- package/src/discover.ts +1 -1
- package/src/engine.ts +12 -5
- package/src/install-skill.ts +57 -0
- package/src/mcp.ts +25 -5
- package/src/operator.ts +2 -0
- package/src/peer.ts +24 -4
- package/src/relay.ts +20 -4
- package/src/schema.ts +4 -2
- package/src/session-limits.ts +3 -0
- package/src/skill-session.ts +245 -0
- package/test/cli.test.ts +55 -7
- package/test/install-skill.test.ts +37 -0
- package/test/pairing.test.ts +6 -1
- package/test/review.test.ts +16 -0
- package/test/short-pairing.test.ts +42 -0
- package/test/skill-session.test.ts +93 -0
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
import { fork } from 'node:child_process';
|
|
2
|
+
import { randomBytes } from 'node:crypto';
|
|
3
|
+
import { createServer } from 'node:http';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
6
|
+
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
7
|
+
import { pairingProgress, relayUrl } from './peer.js';
|
|
8
|
+
import { DEFAULT_IDLE_MS } from './session-limits.js';
|
|
9
|
+
const cli = fileURLToPath(new URL('./cli.js', import.meta.url));
|
|
10
|
+
const loopback = '127.0.0.1';
|
|
11
|
+
const defaultRelay = 'https://diagnose.fenginwind.com';
|
|
12
|
+
const requestMs = 135_000;
|
|
13
|
+
const diagnosticOperations = new Set([
|
|
14
|
+
'system.inspect', 'file.read', 'file.stat', 'file.list', 'file.write',
|
|
15
|
+
'process.run', 'serial.capture', 'serial.exchange',
|
|
16
|
+
]);
|
|
17
|
+
const tools = new Set(['diagnose_start', 'diagnose_batch', 'diagnose_wait', 'diagnose_cancel']);
|
|
18
|
+
function record(value) {
|
|
19
|
+
if (!value || typeof value !== 'object' || Array.isArray(value))
|
|
20
|
+
throw new Error('Expected a JSON object');
|
|
21
|
+
return value;
|
|
22
|
+
}
|
|
23
|
+
async function readJson(stream) {
|
|
24
|
+
const chunks = [];
|
|
25
|
+
let length = 0;
|
|
26
|
+
for await (const part of stream) {
|
|
27
|
+
const bytes = Buffer.from(part);
|
|
28
|
+
length += bytes.length;
|
|
29
|
+
if (length > 2 * 1024 * 1024)
|
|
30
|
+
throw new Error('JSON request is too large');
|
|
31
|
+
chunks.push(bytes);
|
|
32
|
+
}
|
|
33
|
+
let parsed;
|
|
34
|
+
try {
|
|
35
|
+
parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
throw new Error('Invalid JSON on stdin or in session request');
|
|
39
|
+
}
|
|
40
|
+
return record(parsed);
|
|
41
|
+
}
|
|
42
|
+
function respond(response, status, body) {
|
|
43
|
+
response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
|
|
44
|
+
response.end(JSON.stringify(body));
|
|
45
|
+
}
|
|
46
|
+
function validateCall(name, args) {
|
|
47
|
+
if (typeof name !== 'string' || !tools.has(name))
|
|
48
|
+
throw new Error('Unsupported tool for a skill session');
|
|
49
|
+
if (name === 'diagnose_start' && !diagnosticOperations.has(String(args.operation)))
|
|
50
|
+
throw new Error('Unsupported operation for a skill session');
|
|
51
|
+
if (name === 'diagnose_batch' && (!Array.isArray(args.steps) || args.steps.some(step => !diagnosticOperations.has(String(record(step).operation))))) {
|
|
52
|
+
throw new Error('Unsupported batch operation for a skill session');
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
async function serve(relay) {
|
|
56
|
+
if (!process.send || !process.connected)
|
|
57
|
+
throw new Error('Skill session worker must be started by the CLI');
|
|
58
|
+
const secret = randomBytes(32).toString('hex');
|
|
59
|
+
const client = new Client({ name: 'diagnose-skill-session', version: '1' });
|
|
60
|
+
const transport = new StdioClientTransport({ command: process.execPath, args: [cli, 'mcp', relay], stderr: 'ignore' });
|
|
61
|
+
let idle;
|
|
62
|
+
let stopped = false;
|
|
63
|
+
let closing = false;
|
|
64
|
+
let connected = false;
|
|
65
|
+
let busy = false;
|
|
66
|
+
const stop = () => {
|
|
67
|
+
if (stopped)
|
|
68
|
+
return;
|
|
69
|
+
stopped = true;
|
|
70
|
+
clearTimeout(idle);
|
|
71
|
+
server.close();
|
|
72
|
+
server.closeAllConnections();
|
|
73
|
+
void client.close().catch(() => { });
|
|
74
|
+
if (process.connected)
|
|
75
|
+
process.disconnect?.();
|
|
76
|
+
};
|
|
77
|
+
const refreshIdle = (ms = DEFAULT_IDLE_MS) => {
|
|
78
|
+
clearTimeout(idle);
|
|
79
|
+
idle = setTimeout(stop, ms);
|
|
80
|
+
};
|
|
81
|
+
const handle = async (request, response) => {
|
|
82
|
+
if (request.headers.authorization !== 'Bearer ' + secret) {
|
|
83
|
+
respond(response, 403, { error: 'Invalid skill session' });
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
if (request.method !== 'POST' || !['/pair', '/call', '/close'].includes(request.url ?? '')) {
|
|
87
|
+
respond(response, 404, { error: 'Unknown skill session action' });
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
if (closing) {
|
|
91
|
+
respond(response, 409, { error: 'Skill session is closing' });
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
if (request.url === '/close') {
|
|
95
|
+
closing = true;
|
|
96
|
+
if (connected)
|
|
97
|
+
await client.callTool({ name: 'diagnose_disconnect', arguments: {} }, undefined, { timeout: 3000 }).catch(() => { });
|
|
98
|
+
response.once('finish', stop);
|
|
99
|
+
respond(response, 200, { disconnected: true });
|
|
100
|
+
return;
|
|
101
|
+
}
|
|
102
|
+
if (busy) {
|
|
103
|
+
respond(response, 409, { error: 'Another call is in progress for this session' });
|
|
104
|
+
return;
|
|
105
|
+
}
|
|
106
|
+
busy = true;
|
|
107
|
+
let activity = false;
|
|
108
|
+
try {
|
|
109
|
+
const input = await readJson(request);
|
|
110
|
+
let name;
|
|
111
|
+
let args;
|
|
112
|
+
if (request.url === '/pair') {
|
|
113
|
+
if (connected)
|
|
114
|
+
throw new Error('Skill session is already paired');
|
|
115
|
+
args = { code: input.code, label: input.label };
|
|
116
|
+
name = 'diagnose_pair';
|
|
117
|
+
}
|
|
118
|
+
else {
|
|
119
|
+
if (!connected)
|
|
120
|
+
throw new Error('Skill session is not paired');
|
|
121
|
+
args = record(input.arguments);
|
|
122
|
+
validateCall(input.tool, args);
|
|
123
|
+
name = input.tool;
|
|
124
|
+
activity = true;
|
|
125
|
+
refreshIdle();
|
|
126
|
+
}
|
|
127
|
+
const result = await client.callTool({ name, arguments: args }, undefined, {
|
|
128
|
+
timeout: requestMs,
|
|
129
|
+
...(name === 'diagnose_pair' && { onprogress: ({ progress }) => {
|
|
130
|
+
if (progress < pairingProgress.length && process.connected)
|
|
131
|
+
process.send?.({ progress }, () => { });
|
|
132
|
+
} }),
|
|
133
|
+
});
|
|
134
|
+
if (result.isError) {
|
|
135
|
+
const content = result.content;
|
|
136
|
+
const error = Array.isArray(content) ? content.find(item => item.type === 'text')?.text : undefined;
|
|
137
|
+
respond(response, 400, { error: typeof error === 'string' ? error : 'Diagnose rejected the request' });
|
|
138
|
+
}
|
|
139
|
+
else {
|
|
140
|
+
if (name === 'diagnose_pair') {
|
|
141
|
+
connected = true;
|
|
142
|
+
refreshIdle();
|
|
143
|
+
}
|
|
144
|
+
respond(response, 200, result.structuredContent ?? result.content);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
catch (error) {
|
|
148
|
+
respond(response, 400, { error: error.message });
|
|
149
|
+
}
|
|
150
|
+
finally {
|
|
151
|
+
busy = false;
|
|
152
|
+
if (activity && !stopped)
|
|
153
|
+
refreshIdle();
|
|
154
|
+
}
|
|
155
|
+
};
|
|
156
|
+
const server = createServer((request, response) => { void handle(request, response); });
|
|
157
|
+
server.maxConnections = 8;
|
|
158
|
+
server.requestTimeout = requestMs;
|
|
159
|
+
process.once('SIGINT', stop);
|
|
160
|
+
process.once('SIGTERM', stop);
|
|
161
|
+
client.onclose = stop;
|
|
162
|
+
try {
|
|
163
|
+
await client.connect(transport, { timeout: 15_000 });
|
|
164
|
+
await new Promise((resolve, reject) => {
|
|
165
|
+
server.once('error', reject);
|
|
166
|
+
server.listen(0, loopback, resolve);
|
|
167
|
+
});
|
|
168
|
+
const port = server.address().port;
|
|
169
|
+
refreshIdle(requestMs + 25_000);
|
|
170
|
+
process.send({ port, secret });
|
|
171
|
+
}
|
|
172
|
+
catch (error) {
|
|
173
|
+
stop();
|
|
174
|
+
throw error;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
function endpoint(value) {
|
|
178
|
+
if (typeof value !== 'string' || !/^\d{1,5}\.[a-f0-9]{64}$/.test(value))
|
|
179
|
+
throw new Error('Invalid skill session handle');
|
|
180
|
+
const [port, secret] = value.split('.');
|
|
181
|
+
if (Number(port) < 1 || Number(port) > 65535)
|
|
182
|
+
throw new Error('Invalid skill session handle');
|
|
183
|
+
return { port: Number(port), secret: secret };
|
|
184
|
+
}
|
|
185
|
+
async function requestSession(session, action, body = {}) {
|
|
186
|
+
let response;
|
|
187
|
+
try {
|
|
188
|
+
response = await fetch(`http://${loopback}:${session.port}/${action}`, {
|
|
189
|
+
method: 'POST',
|
|
190
|
+
headers: { authorization: 'Bearer ' + session.secret, 'content-type': 'application/json' },
|
|
191
|
+
body: JSON.stringify(body),
|
|
192
|
+
signal: AbortSignal.timeout(requestMs + 5000),
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
catch {
|
|
196
|
+
throw new Error('Skill session unavailable or timed out. Inspect the result before retrying a change.');
|
|
197
|
+
}
|
|
198
|
+
const result = record(await response.json());
|
|
199
|
+
if (!response.ok)
|
|
200
|
+
throw new Error(String(result.error ?? 'Skill session request failed'));
|
|
201
|
+
return result;
|
|
202
|
+
}
|
|
203
|
+
async function open(input) {
|
|
204
|
+
if (typeof input.code !== 'string' || input.code.length > 120 || !input.code.trim())
|
|
205
|
+
throw new Error('Supply the one-time pairing code on stdin');
|
|
206
|
+
if (typeof input.label !== 'string' || !input.label.trim() || input.label.length > 120)
|
|
207
|
+
throw new Error('Supply a diagnostic label on stdin');
|
|
208
|
+
if (input.relay !== undefined && typeof input.relay !== 'string')
|
|
209
|
+
throw new Error('Invalid relay URL');
|
|
210
|
+
const relay = input.relay ?? defaultRelay;
|
|
211
|
+
relayUrl(relay);
|
|
212
|
+
console.error('Connecting to the Diagnose relay.');
|
|
213
|
+
const worker = fork(cli, ['skill-session', '_serve', relay], { detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
|
|
214
|
+
try {
|
|
215
|
+
const session = await new Promise((resolve, reject) => {
|
|
216
|
+
const done = (error, result) => {
|
|
217
|
+
clearTimeout(timer);
|
|
218
|
+
worker.off('error', failed);
|
|
219
|
+
worker.off('exit', exited);
|
|
220
|
+
worker.off('message', ready);
|
|
221
|
+
if (error)
|
|
222
|
+
reject(error);
|
|
223
|
+
else
|
|
224
|
+
resolve(result);
|
|
225
|
+
};
|
|
226
|
+
const failed = (error) => done(error);
|
|
227
|
+
const exited = () => done(new Error('Skill session worker exited during startup'));
|
|
228
|
+
const ready = (message) => {
|
|
229
|
+
try {
|
|
230
|
+
done(undefined, endpoint(`${message.port}.${message.secret}`));
|
|
231
|
+
}
|
|
232
|
+
catch (error) {
|
|
233
|
+
done(error);
|
|
234
|
+
}
|
|
235
|
+
};
|
|
236
|
+
const timer = setTimeout(() => done(new Error('Skill session worker did not start')), 20_000);
|
|
237
|
+
worker.once('error', failed);
|
|
238
|
+
worker.once('exit', exited);
|
|
239
|
+
worker.once('message', ready);
|
|
240
|
+
});
|
|
241
|
+
worker.on('message', (message) => {
|
|
242
|
+
if (typeof message.progress !== 'number')
|
|
243
|
+
return;
|
|
244
|
+
const text = pairingProgress[message.progress - 1];
|
|
245
|
+
if (text)
|
|
246
|
+
console.error(text);
|
|
247
|
+
});
|
|
248
|
+
const result = await requestSession(session, 'pair', { code: input.code, label: input.label });
|
|
249
|
+
console.error(pairingProgress[2]);
|
|
250
|
+
worker.disconnect();
|
|
251
|
+
worker.unref();
|
|
252
|
+
return { ...result, session: session.port + '.' + session.secret, idleSeconds: DEFAULT_IDLE_MS / 1000 };
|
|
253
|
+
}
|
|
254
|
+
catch (error) {
|
|
255
|
+
worker.kill();
|
|
256
|
+
throw error;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
export async function skillSessionCommand(args) {
|
|
260
|
+
if (args[0] === '_serve' && args.length === 2) {
|
|
261
|
+
await serve(args[1]);
|
|
262
|
+
return;
|
|
263
|
+
}
|
|
264
|
+
const [action] = args;
|
|
265
|
+
if (args.length !== 1 || !['open', 'call', 'close'].includes(action ?? '')) {
|
|
266
|
+
throw new Error('Usage: diagnose skill-session open|call|close (JSON on stdin)');
|
|
267
|
+
}
|
|
268
|
+
const input = await readJson(process.stdin);
|
|
269
|
+
const result = action === 'open' ? await open(input)
|
|
270
|
+
: await requestSession(endpoint(input.session), action, action === 'call' ? { tool: input.tool, arguments: input.arguments } : {});
|
|
271
|
+
console.log(JSON.stringify(result));
|
|
272
|
+
}
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Run Diagnose from a script or MCP client
|
|
2
|
+
|
|
3
|
+
Use the npm launcher for a configured agent session, or start Diagnose directly from your own MCP client. Use the [native agent skill](diagnose.md#use-diagnose-as-a-native-agent-skill) when you already have an interactive agent open.
|
|
4
|
+
|
|
5
|
+
[All guide scenarios](../../USER_GUIDE.md)
|
|
6
|
+
|
|
7
|
+
## Launch an agent with Diagnose MCP
|
|
8
|
+
|
|
9
|
+
To start an interactive session and give the agent its task in chat, choose one:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx @masstensor/diagnose@latest agent codex
|
|
13
|
+
npx @masstensor/diagnose@latest agent claude
|
|
14
|
+
npx @masstensor/diagnose@latest agent gemini
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
With a global installation, these become:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
diagnose agent codex
|
|
21
|
+
diagnose agent claude
|
|
22
|
+
diagnose agent gemini
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Do **not** separately run `diagnose mcp` or register a global MCP server. The launcher starts your chosen CLI with Diagnose MCP loaded for this launch, using the exact installed Diagnose version.
|
|
26
|
+
|
|
27
|
+
Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
|
|
28
|
+
|
|
29
|
+
> 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.
|
|
30
|
+
|
|
31
|
+
The code and diagnostic results enter your chosen AI provider's context. The user confirms the connection if their [startup choice](on-site.md#start-the-probe) requires it. Ask the agent to use the `diagnose_*` tools for remote actions: its normal shell and file tools still act on the diagnostician's computer.
|
|
32
|
+
|
|
33
|
+
To give the agent its task at launch, [pass a device procedure with `--skill`](procedures.md#start-with-a-device-skill-or-markdown-task).
|
|
34
|
+
|
|
35
|
+
## Direct CLI and other MCP clients
|
|
36
|
+
|
|
37
|
+
For scripts and CI, install the npm client and start it directly. The native Skill is optional for these workflows.
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npm install -g @masstensor/diagnose
|
|
41
|
+
diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
|
|
42
|
+
# Or use diagnose mcp --device workshop-laptop as the MCP server subprocess.
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Use `agent codex` or `agent gemini` for the other launchers. You can also run the npm launcher directly with `npx @masstensor/diagnose@latest agent claude`. The `--skill` launcher flag takes your device procedure. It does not require the native Diagnose Skill to be installed.
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
diagnose connect
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Enter task JSON on one line. Requests return a task ID. Use `wait <task-id>`, `cancel <task-id>`, `resources`, `read <resource-id> [cursor]`, `input <resource-id> "text\n"`, `resize <resource-id> 120 40`, `signal <resource-id> SIGINT`, and `close <resource-id>`.
|
|
52
|
+
|
|
53
|
+
`forward <resource-id> [local-port]` opens an approved forward. `upload` and `download` accept JSON with `localPath`, `remotePath`, `reason`, and optional `overwrite`, `resumeId`, and `resumeToken`.
|
|
54
|
+
|
|
55
|
+
For another stdio MCP client, configure it to launch:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{"mcpServers":{"diagnose":{"command":"diagnose","args":["mcp"]}}}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This is a local child process, not a public HTTP MCP endpoint. Running `diagnose mcp` in a separate terminal does not automatically connect it to an agent.
|
|
62
|
+
|
|
63
|
+
The direct commands accept an optional relay URL, for example `diagnose start https://your-relay.example` and `diagnose mcp https://your-relay.example`. Remote relays require HTTPS/WSS; HTTP/WS is allowed only for loopback testing.
|
|
64
|
+
|
|
65
|
+
## Tool reference
|
|
66
|
+
|
|
67
|
+
The MCP interface provides 15 tools:
|
|
68
|
+
|
|
69
|
+
| Tool | Purpose |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `diagnose_pair` | Connect using the complete code and a self-reported diagnostician/AI-provider label. |
|
|
72
|
+
| `diagnose_start` | Submit one operation and receive its task ID. |
|
|
73
|
+
| `diagnose_batch` | Submit up to 32 finite operations as one sequential plan. |
|
|
74
|
+
| `diagnose_wait` | Poll a task for up to 25 seconds; release completed output when finished. |
|
|
75
|
+
| `diagnose_cancel` | Cancel a task, including one awaiting approval. |
|
|
76
|
+
| `diagnose_process` | Open a live process or persistent PTY with cwd/env, stdin, signals, and resizing. |
|
|
77
|
+
| `diagnose_resource` | List, inspect, read, input to, resize, signal, or close an authorized handle. |
|
|
78
|
+
| `diagnose_resume` | Request attachment to an existing resource with its ID and recovery credential. |
|
|
79
|
+
| `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
|
|
80
|
+
| `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
|
|
81
|
+
| `diagnose_disconnect` | Disconnect the diagnostic session. |
|
|
82
|
+
| `diagnose_capabilities` | Query operation schemas and conservative discovery guidance. |
|
|
83
|
+
| `diagnose_case` | Create/show a case, record assessments, report connection layers and finish with evidence references. |
|
|
84
|
+
| `diagnose_skill_draft` | Propose a new skill or improvement for local human review. |
|
|
85
|
+
| `diagnose_skills` | List or read locally available pinned skill versions without executing them. |
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
### Finite commands, scripts, and batches
|
|
90
|
+
|
|
91
|
+
`process.run` spawns an explicit executable and argument array without implicitly adding a shell. `process.script` passes a complete script to an explicit interpreter's stdin. Scripts need not be written to temporary files.
|
|
92
|
+
|
|
93
|
+
A batch runs sequentially, stops on error by default, and cannot contain nested batches or persistent resource creation. Set `stopOnError:false` only when later steps are independent. Outputs are named by step, for example `0.stdout` and `1.file`.
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"operation": "batch.run",
|
|
98
|
+
"reason": "Collect system and runtime information in one approved plan",
|
|
99
|
+
"arguments": {
|
|
100
|
+
"steps": [
|
|
101
|
+
{"operation":"system.inspect","arguments":{}},
|
|
102
|
+
{"operation":"process.script","arguments":{"interpreter":"node","script":"const os = require('node:os');\nconsole.log(JSON.stringify({uptime: os.uptime(), freeMemory: os.freemem()}));","timeoutMs":10000}}
|
|
103
|
+
],
|
|
104
|
+
"stopOnError": true,
|
|
105
|
+
"timeoutMs": 60000
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A batch's text-file writes are previewed and hashed before approval. If an earlier step changes the same target, a later guarded write is refused instead of silently overwriting the new state.
|
|
111
|
+
|
|
112
|
+
### Live processes and native terminals
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
diagnose terminal
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Enter the pairing code and label interactively. After local approval, you get a real PTY. Shell cwd and environment persist within that process. `Ctrl+C` goes to the remote terminal; `Ctrl+]` detaches. A process is closed on disconnect unless explicitly retained.
|
|
119
|
+
|
|
120
|
+
Agents use `diagnose_process` for the same live capabilities. Non-PTY processes preserve stdout/stderr separately and support exact byte input. PTYs behave as terminals, not general binary transports.
|
|
121
|
+
|
|
122
|
+
### Files
|
|
123
|
+
|
|
124
|
+
`file.read` returns a bounded range of up to 1 MiB. `file.write` previews text and checks the previous hash before replacing a target. File listing, stat, mkdir, removal, rename, and chmod are available; rename refuses an existing destination unless overwrite is explicit. File transfers preserve existing destination permission bits. New transfer destinations are committed without replacing a concurrently created file; downloads with overwrite enabled reject a destination changed during transfer. Existing-file replacement checks the target immediately before commit, but does not lock out unrelated local writers.
|
|
125
|
+
|
|
126
|
+
Use `diagnose_transfer` for large or binary files. It takes paths rather than placing base64 file contents into the AI context. `localPath` refers to the diagnostician's computer; `remotePath` refers to the user's computer.
|
|
127
|
+
|
|
128
|
+
Uploads use a private staging file. Exact size, SHA-256, destination hash, and parent-directory checks must pass before replacement. Downloads use `.diagnose.part` plus a private `.diagnose.json` recovery sidecar. A completed download is verified before replacement. Overwriting an existing destination must be explicit. Raw file bytes are not redacted.
|
|
129
|
+
|
|
130
|
+
### TCP forwarding
|
|
131
|
+
|
|
132
|
+
First authorize `net.forward`, wait for its resource ID, then use `diagnose_forward` to open the corresponding endpoint.
|
|
133
|
+
|
|
134
|
+
- `local`: a loopback listener on the diagnostician's computer reaches a fixed target accessible from the user's computer.
|
|
135
|
+
- `remote`: a loopback listener on the user's computer forwards to a declared target on the diagnostician's side.
|
|
136
|
+
- `socks`: a SOCKS5 TCP listener on the diagnostician's loopback interface reaches targets from the user's side, restricted by `allowedHosts`.
|
|
137
|
+
|
|
138
|
+
SOCKS defaults to `allowedHosts:["*"]`, which permits any target. Narrow it when possible. Listeners are loopback-only. UDP, TUN, public listeners, SSH agent forwarding, and X11 forwarding are not implemented. Tunnel bytes are not redacted.
|
|
139
|
+
|
|
140
|
+
### Serial devices
|
|
141
|
+
|
|
142
|
+
`system.inspect` lists serial ports. `serial.capture` reads a selected port; `serial.exchange` first sends explicitly authorized `dataHex`. Both use 8N1 with DTR/RTS set false. Opening a port can still reset some hardware. Verify the selected device and avoid opening unrelated ports.
|
|
143
|
+
|
|
144
|
+
## Limits and timeouts
|
|
145
|
+
|
|
146
|
+
| Limit | Default / maximum |
|
|
147
|
+
| --- | --- |
|
|
148
|
+
| New short invitation | 30 minutes; one-time; up to five attempted handshakes |
|
|
149
|
+
| Temporary session idle / total | Six hours idle / no fixed total by default in v0.8+ |
|
|
150
|
+
| Remembered pairing | Until revoked locally; requires the foreground probe |
|
|
151
|
+
| Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
|
|
152
|
+
| Finite command or script | 60 seconds by default; 300 seconds maximum |
|
|
153
|
+
| Batch | Up to 32 steps; 300 seconds; 10 MiB combined output |
|
|
154
|
+
| Concurrent finite jobs | 4 |
|
|
155
|
+
| Active live resource handles | 128 |
|
|
156
|
+
| Live process | 1 hour by default; `timeoutMs:0` removes its timer |
|
|
157
|
+
| Retained output per live process | 64 MiB by default; 1 GiB maximum; reaching the cap terminates the process |
|
|
158
|
+
| Relay session | The updated relay renews an active room without a fixed total. Older relays may cap a room at seven days. |
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
diagnose start --session-minutes 240 --idle-minutes 30
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Session and idle options apply to temporary connections. Remembered connections disable these endpoint timers, while automatic approval has its own saved expiry. Set a temporary session or idle timeout to `0` to disable that endpoint timer; relay and cipher limits still apply. Both endpoints should use a compatible current version. POSIX processes that deliberately detach from their process group cannot always be terminated by group cancellation.
|
|
165
|
+
|
|
166
|
+
Temporary-session activity includes task requests, result polls, and live resource interactions. Automatic heartbeats maintain the transport without extending the diagnostic idle timer.
|
|
167
|
+
|
|
168
|
+
## Short invitation compatibility
|
|
169
|
+
|
|
170
|
+
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.
|
|
171
|
+
|
|
172
|
+
## Session configuration and extra arguments
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
diagnose agent codex --relay https://your-relay.example -- --model your-model
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Options before `--` belong to Diagnose. Everything after it is passed literally to the agent, without a shell. Do not put pairing codes, passwords, or recovery credentials in these arguments.
|
|
179
|
+
|
|
180
|
+
- **Codex:** receives temporary `-c` MCP overrides.
|
|
181
|
+
- **Claude Code:** receives a temporary `--mcp-config` value.
|
|
182
|
+
- **Gemini CLI:** uses a private temporary user configuration directory. Diagnose copies the user settings, adds its MCP entry, and links existing login/history files. Administrator policies and workspace trust checks remain in effect. On Windows, directories use junctions and login files are copied into the private temporary directory, avoiding administrator-only file symlinks. Sign in with the native Gemini CLI first; changes to copied login files in this session are not saved back. The directory is removed on normal exit; changes to user settings in this Gemini session are not written back to the original `settings.json`.
|
|
183
|
+
|
|
184
|
+
The launcher does not add a permanent MCP entry. Other MCP servers already configured in your agent may still load. If you previously registered Diagnose globally, remove that entry separately if you no longer want it in ordinary sessions. An uncatchable kill or power loss may leave a temporary directory behind.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Diagnose a remote device
|
|
2
|
+
|
|
3
|
+
Use this guide if a person on site has shared a nine-letter invitation. Choose the instructions for your existing agent, then describe what you need to verify on the device.
|
|
4
|
+
|
|
5
|
+
[All guide scenarios](../../USER_GUIDE.md)
|
|
6
|
+
|
|
7
|
+
## Choose how to start
|
|
8
|
+
|
|
9
|
+
- **Manual agent mode** is the easiest way to try Diagnose. Use the native skill below, or [launch an agent with Diagnose MCP](automation.md#launch-an-agent-with-diagnose-mcp). Give the agent the invitation and symptom in chat, then guide the investigation as it returns evidence.
|
|
10
|
+
- **Start with a device procedure** when you have steps you want the agent to follow at launch. [Load a Markdown file with `--skill`](procedures.md#start-with-a-device-skill-or-markdown-task). The on-site probe still controls permissions.
|
|
11
|
+
|
|
12
|
+
## Use Diagnose as a native agent skill
|
|
13
|
+
|
|
14
|
+
Install the skill once through your agent's GitHub installation flow. All three agents use the same `skills/connect/` directory in the repository. The helper runs Diagnose 0.8.1 locally on demand with `npx` and needs Node.js 20.10 or later. There is no separate global Diagnose CLI installation for this workflow.
|
|
15
|
+
|
|
16
|
+
### Claude Code
|
|
17
|
+
|
|
18
|
+
In Claude Code 2.1.275 or later, enter:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
/plugin install diagnose --marketplace zkwasm/diagnose
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Choose the installation scope. Open a new session, or use `/reload-plugins` in the current one. Invoke `/diagnose:connect` with the private invitation and, if known, the device and symptom. [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command)
|
|
25
|
+
|
|
26
|
+
### Codex CLI
|
|
27
|
+
|
|
28
|
+
In your terminal, run:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
codex plugin marketplace add zkwasm/diagnose
|
|
32
|
+
codex plugin add diagnose@diagnose
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Alternatively, add the marketplace and install Diagnose from `/plugins`. Open a new session and invoke `$diagnose:connect` with your private invitation. [Codex CLI plugin documentation](https://learn.chatgpt.com/docs/cli/reference#codex-plugin)
|
|
36
|
+
|
|
37
|
+
### Gemini CLI
|
|
38
|
+
|
|
39
|
+
In your terminal, run:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Approve the installation prompt. In a new session, ask Gemini to use the `connect` skill and provide the invitation. Use `/skills reload` if a Gemini session is already open. [Gemini CLI Skills documentation](https://geminicli.com/docs/cli/skills/#managing-skills)
|
|
46
|
+
|
|
47
|
+
## Run a diagnostic session
|
|
48
|
+
|
|
49
|
+
Give the agent the invitation, device model, connection method, and symptom. During pairing, the helper reports when it reaches the relay, authenticates the on-site probe and waits for acceptance, and confirms the pairing. The person on site approves the connection if prompted. When the agent's shell tool streams output, it can share these updates while pairing is still in progress.
|
|
50
|
+
|
|
51
|
+
After pairing, look for three separate results:
|
|
52
|
+
|
|
53
|
+
1. **Probe connected.** The agent can submit permitted checks on the on-site computer.
|
|
54
|
+
2. **Device interface identified.** The agent has evidence for which port or interface belongs to the device. If several ports could match, it asks you to confirm before opening one.
|
|
55
|
+
3. **Device response observed.** The agent reports a recognizable log line, a status reply, or another observation attributable to the device. A silent capture leaves this step unconfirmed.
|
|
56
|
+
|
|
57
|
+
The agent explains what it found in the first check and what it will check next. The skill keeps the connection available for follow-up between messages. Ask the agent to close it when you are done, or have the on-site user stop the probe. See [session timeouts](automation.md#limits-and-timeouts) for details.
|
|
58
|
+
|
|
59
|
+
## What the native skill can do
|
|
60
|
+
|
|
61
|
+
The agent uses these operations on the **on-site computer** through the probe. To reach the device, it uses the serial interface or an available device utility on that computer.
|
|
62
|
+
|
|
63
|
+
| What you can ask the agent to do | Operation |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| Identify the on-site OS and list visible serial ports. | `system.inspect` |
|
|
66
|
+
| Find a known log or configuration file, inspect its metadata, and read the relevant contents. | `file.list`, `file.stat`, `file.read` |
|
|
67
|
+
| Capture output from a confirmed serial port at the device's baud rate. | `serial.capture` |
|
|
68
|
+
| Send a documented request to the device over serial and read its reply. | `serial.exchange` |
|
|
69
|
+
| Run a shell command or installed program on the on-site computer, such as a vendor utility that reports device status. | `process.run` |
|
|
70
|
+
| Apply an authorized configuration edit to a file on the on-site computer. | `file.write` |
|
|
71
|
+
|
|
72
|
+
The agent submits one operation with `diagnose_start` or groups related operations with `diagnose_batch`. It uses `diagnose_wait` to get the result and `diagnose_cancel` to request cancellation of work in progress. Cancellation does not undo changes already made. You can describe the check in plain language. The agent selects the operation and waits for any approval the probe requires.
|
|
73
|
+
|
|
74
|
+
The native skill supports temporary pairing and finite operations. For live terminals, file transfers, remembered pairings, or case management, [launch the agent with Diagnose MCP](automation.md#launch-an-agent-with-diagnose-mcp). A [device procedure](procedures.md#start-with-a-device-skill-or-markdown-task) can tell the agent which checks and verification steps to use for a particular model.
|
|
75
|
+
|
|
76
|
+
### Run a shell command on the on-site computer
|
|
77
|
+
|
|
78
|
+
Ask in chat, for example, “Use Diagnose to check the working directory on the on-site computer and show me the result.” The agent submits `process.run` through the probe and waits for the exit status, standard output, and standard error.
|
|
79
|
+
|
|
80
|
+
For shell syntax such as pipes and conditionals, the agent names the shell explicitly. On macOS or Linux, `process.run` can launch `/bin/sh` with `[-c, pwd]`. On Windows, it can launch `powershell.exe` with `[-NoProfile, -NonInteractive, -Command, Get-Location]`. The agent can also call an installed program directly with an executable and an argument list. Commands follow the probe's execution and result-sharing permissions.
|
|
81
|
+
|
|
82
|
+
## From a reported problem to a verified result
|
|
83
|
+
|
|
84
|
+
Suppose plug readings stopped arriving from an OWON gateway connected by USB serial. Start with a prompt like this:
|
|
85
|
+
|
|
86
|
+
> The OWON gateway stopped reporting plug readings. Start with read-only checks. Confirm which serial port belongs to the gateway, look for recent readings or errors, and tell me what the evidence supports. Ask before changing anything. We’ll consider it fixed when fresh readings appear again.
|
|
87
|
+
|
|
88
|
+
1. **Identify the interface.** The agent can list serial ports with `system.inspect`. If several ports match, confirm the right one and the baud rate with the person on site before opening it.
|
|
89
|
+
2. **Collect a baseline and follow the evidence.** Use `serial.capture` for a short sample. If the sample is silent, check whether the port, baud rate, or cable is correct. If the gateway responds but readings are still absent, inspect the relevant collector logs with `file.read` if available. Reuse the same session to ask for another check.
|
|
90
|
+
3. **Review one proposed change.** If the evidence points to a setting, ask the agent to show the current value, explain the proposed edit, and describe how to restore the original value. The [probe's permissions](on-site.md#choose-and-change-permissions) govern execution and result sharing. You can end the diagnosis after the read-only findings.
|
|
91
|
+
4. **Repeat the original check.** After an authorized repair, use the same capture or status check to look for fresh readings. If they are still missing, use that result to choose the next check. Ask the agent to summarize the evidence, changes, and any remaining uncertainty.
|
|
92
|
+
|
|
93
|
+
Tell the agent when to stop. The on-site user can also end access from the probe terminal. Use the same workflow for a problem on the on-site computer itself. Pick a check that measures whether the original symptom is gone, such as a successful application start or a working device connection.
|