paseo-dsh 0.2.0 → 0.2.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/README.md CHANGED
@@ -16,6 +16,14 @@ including the stdio bridge bundle it carries — no shell script, no manual
16
16
  profile setup. The only thing left is your model route in
17
17
  `~/.dsh/profiles/paseo/cordis.patch.yml`.
18
18
 
19
+ This package also ships a small CLI for that setup:
20
+
21
+ ```bash
22
+ npx paseo-dsh doctor # check CLIs, profile, bridge, model route and credentials
23
+ npx paseo-dsh probe --base-url https://your-gateway/v1 \
24
+ --api-key-env YOUR_KEY_ENV --model your-model-id # discover reasoning levels etc.
25
+ ```
26
+
19
27
  What you get that the ACP boundary can't carry:
20
28
 
21
29
  - `ask_user_question` → real Paseo question cards
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paseo-dsh` CLI — helper commands for a DeepSeek Harness × Paseo install.
4
+ *
5
+ * paseo-dsh doctor self-check the install (CLIs, profile, bridge, route, key)
6
+ * paseo-dsh probe probe a model route's reasoning/developer-role support
7
+ * paseo-dsh help
8
+ *
9
+ * Ships inside the `paseo-dsh` npm package, so it runs from `npx paseo-dsh ...`
10
+ * with no repository clone.
11
+ *
12
+ * @module paseo-dsh/bin
13
+ */
14
+ import { runDoctor } from "../lib/doctor.mjs";
15
+ import { runProbe } from "../lib/probe-provider.mjs";
16
+
17
+ const HELP = `paseo-dsh — DeepSeek Harness × Paseo helper
18
+
19
+ Usage:
20
+ paseo-dsh doctor Check this install: dsh/paseo, the DSH
21
+ profile, the bridge, the model route, keys.
22
+ paseo-dsh probe [options] Probe a model route before writing its config.
23
+ --base-url <url> OpenAI-compatible endpoint, e.g. https://gw/v1
24
+ --api-key-env <ENV_VAR> Env var holding the key (never printed)
25
+ --model <id> [--model <id>] One or more model ids
26
+ paseo-dsh help
27
+
28
+ Install the plugin itself with: paseo plugin add npm:paseo-dsh
29
+ `;
30
+
31
+ const [command, ...rest] = process.argv.slice(2);
32
+
33
+ switch (command) {
34
+ case undefined:
35
+ case "doctor":
36
+ runDoctor();
37
+ break;
38
+ case "probe":
39
+ await runProbe(rest, "paseo-dsh probe");
40
+ break;
41
+ case "help":
42
+ case "-h":
43
+ case "--help":
44
+ process.stdout.write(HELP);
45
+ break;
46
+ default:
47
+ process.stderr.write(`unknown command "${command}"\n\n${HELP}`);
48
+ process.exitCode = 2;
49
+ }
package/lib/doctor.mjs ADDED
@@ -0,0 +1,176 @@
1
+ /**
2
+ * `paseo-dsh doctor` — one-command self-check for a DeepSeek Harness × Paseo
3
+ * install.
4
+ *
5
+ * It verifies the things that silently break a fresh install: the CLIs are
6
+ * present, the plugin has provisioned the DSH profile (which only happens once
7
+ * the daemon loads the plugin), the bridge is materialized, a model route is
8
+ * actually configured, and every referenced `apiKeyEnv` has a credential. It
9
+ * only reads; it never changes anything.
10
+ *
11
+ * @module paseo-dsh/lib/doctor
12
+ */
13
+ import { execFileSync } from "node:child_process";
14
+ import { existsSync, readFileSync } from "node:fs";
15
+ import { homedir } from "node:os";
16
+ import { dirname, join } from "node:path";
17
+ import { fileURLToPath } from "node:url";
18
+
19
+ const HERE = dirname(fileURLToPath(import.meta.url));
20
+
21
+ const GREEN = "\u001b[32m";
22
+ const YELLOW = "\u001b[33m";
23
+ const RED = "\u001b[31m";
24
+ const DIM = "\u001b[2m";
25
+ const RESET = "\u001b[0m";
26
+
27
+ const results = [];
28
+ function report(level, label, detail) {
29
+ results.push(level);
30
+ const tag = level === "ok" ? `${GREEN}ok ${RESET}` : level === "warn" ? `${YELLOW}warn${RESET}` : `${RED}fail${RESET}`;
31
+ process.stdout.write(` [${tag}] ${label}${detail ? `\n ${DIM}${detail}${RESET}` : ""}\n`);
32
+ }
33
+
34
+ function run(cmd, args) {
35
+ try {
36
+ return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
37
+ } catch {
38
+ return undefined;
39
+ }
40
+ }
41
+
42
+ function findPaseo() {
43
+ // Prefer the app-bundled CLI: a `paseo` on PATH is often a stale npm install.
44
+ const bundled = "/Applications/Paseo.app/Contents/Resources/bin/paseo";
45
+ if (existsSync(bundled)) {
46
+ const v = run(bundled, ["--version"]);
47
+ if (v !== undefined) return { cmd: bundled, version: v };
48
+ }
49
+ const v = run("paseo", ["--version"]);
50
+ if (v !== undefined) return { cmd: "paseo", version: v };
51
+ return undefined;
52
+ }
53
+
54
+ function line(v) {
55
+ return v.split("\n").find((entry) => entry.trim() !== "") ?? v;
56
+ }
57
+
58
+ /** Strip full-line comments so "route configured?" isn't fooled by the template. */
59
+ function activeLines(text) {
60
+ return text
61
+ .split("\n")
62
+ .filter((l) => !l.trimStart().startsWith("#"))
63
+ .join("\n");
64
+ }
65
+
66
+ export function runDoctor() {
67
+ const pluginVersion = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
68
+ const dshHome = process.env.DSH_HOME ?? join(homedir(), ".dsh");
69
+ const profile = process.env.DSH_PASEO_PROFILE ?? "paseo";
70
+ const profileDir = join(dshHome, "profiles", profile);
71
+
72
+ process.stdout.write(`\n${DIM}paseo-dsh doctor (plugin ${pluginVersion})${RESET}\n\n`);
73
+
74
+ // 1. CLIs
75
+ const dshVersion = run("dsh", ["--version"]);
76
+ if (dshVersion === undefined) {
77
+ report("fail", "dsh on PATH", "install the official DeepSeek Harness and put `dsh` on the daemon's PATH");
78
+ } else {
79
+ const dshLine = line(dshVersion);
80
+ const dshMM = dshLine.match(/(\d+)\.(\d+)/);
81
+ const pluginMM = pluginVersion.match(/^(\d+)\.(\d+)/);
82
+ if (dshMM && pluginMM && `${dshMM[1]}.${dshMM[2]}` !== `${pluginMM[1]}.${pluginMM[2]}`) {
83
+ report("warn", `dsh ${dshLine}`, `plugin ${pluginVersion} targets the ${pluginMM[1]}.${pluginMM[2]}.x DSH line`);
84
+ } else {
85
+ report("ok", `dsh ${dshLine}`);
86
+ }
87
+ }
88
+
89
+ const paseo = findPaseo();
90
+ if (paseo === undefined) {
91
+ report("fail", "paseo CLI not found", "expected `paseo` on PATH or /Applications/Paseo.app");
92
+ } else if (Number(paseo.version.match(/\d+\.(\d+)/)?.[1] ?? 0) < 9) {
93
+ report("warn", `paseo ${paseo.version}`, "needs Paseo >= 0.9.2 for the direct provider plugin API");
94
+ } else {
95
+ report("ok", `paseo ${paseo.version}`);
96
+ }
97
+
98
+ // 2. profile provisioned by the plugin
99
+ if (!existsSync(profileDir)) {
100
+ report(
101
+ "fail",
102
+ `DSH profile "${profile}" missing`,
103
+ `expected ${profileDir}. Install the plugin and restart the daemon — the plugin creates it on load.`,
104
+ );
105
+ finish(pluginVersion);
106
+ return;
107
+ }
108
+ report("ok", `DSH profile at ${profileDir}`);
109
+
110
+ const bridgeDir = join(profileDir, "node_modules", "dsh-paseo-bridge");
111
+ const bridgeEntry = join(bridgeDir, "lib", "server.js");
112
+ if (existsSync(bridgeEntry)) {
113
+ report("ok", "bridge bundle provisioned", bridgeDir);
114
+ } else {
115
+ report("fail", "bridge bundle missing", `expected ${bridgeEntry}; restart the daemon to let the plugin re-provision`);
116
+ }
117
+
118
+ // 3. model route
119
+ const patchPath = join(profileDir, "cordis.patch.yml");
120
+ if (!existsSync(patchPath)) {
121
+ report("fail", "no cordis.patch.yml", `the plugin should have written one at ${patchPath}`);
122
+ finish(pluginVersion);
123
+ return;
124
+ }
125
+ const patch = readFileSync(patchPath, "utf8");
126
+ const active = activeLines(patch);
127
+ const configured = active.includes("agent-default-model") && /providers:\s*$/m.test(active);
128
+ if (configured) {
129
+ const tail = active.split("agent-default-model").pop() ?? "";
130
+ const provider = tail.match(/provider:\s*([^\s#]+)/)?.[1];
131
+ const model = tail.match(/model:\s*([^\s#]+)/)?.[1];
132
+ report("ok", "model route configured", provider && model ? `default: ${provider} / ${model}` : undefined);
133
+ } else {
134
+ report(
135
+ "warn",
136
+ "model route not configured yet",
137
+ `edit ${patchPath} (see the README install walkthrough) then restart the daemon`,
138
+ );
139
+ }
140
+
141
+ // 4. credentials for every referenced apiKeyEnv
142
+ const credentialPath = join(dshHome, ".credentials.yaml");
143
+ const credentialText = existsSync(credentialPath) ? readFileSync(credentialPath, "utf8") : "";
144
+ const referenced = [...active.matchAll(/apiKeyEnv:\s*([A-Za-z0-9_]+)/g)].map((m) => m[1]);
145
+ const unique = [...new Set(referenced)];
146
+ if (unique.length === 0) {
147
+ report("warn", "no apiKeyEnv referenced", "the route above should name the credential to use");
148
+ } else {
149
+ for (const name of unique) {
150
+ const has = new RegExp(`(^|\\n)\\s*${name}\\s*:`).test(credentialText);
151
+ if (has) report("ok", `credential ${name} found`);
152
+ else
153
+ report(
154
+ "warn",
155
+ `credential ${name} missing`,
156
+ `add "${name}: <your-key>" under refs: in ${credentialPath}`,
157
+ );
158
+ }
159
+ }
160
+
161
+ finish(pluginVersion);
162
+ }
163
+
164
+ function finish() {
165
+ const fails = results.filter((r) => r === "fail").length;
166
+ const warns = results.filter((r) => r === "warn").length;
167
+ process.stdout.write("\n");
168
+ if (fails > 0) {
169
+ process.stdout.write(`${RED}${fails} blocking issue(s)${RESET}${warns ? `, ${warns} warning(s)` : ""}.\n`);
170
+ process.exitCode = 1;
171
+ } else if (warns > 0) {
172
+ process.stdout.write(`${YELLOW}${warns} warning(s)${RESET} — nothing blocking, but fix the above before relying on it.\n`);
173
+ } else {
174
+ process.stdout.write(`${GREEN}All checks passed.${RESET} New a session in Paseo with provider "DeepSeek Harness (native)".\n`);
175
+ }
176
+ }
@@ -0,0 +1,211 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Discover what a model route can actually do, so its capabilities can be
4
+ * declared in a DSH profile with evidence instead of guesswork.
5
+ *
6
+ * DSH resolves a route's reasoning support from its model metadata. A route the
7
+ * installed catalog knows nothing about — any self-hosted or self-configured
8
+ * provider — reports *no* reasoning at all, and DSH then rejects every effort
9
+ * with `UNSUPPORTED_REASONING_EFFORT`. That reads like a model limitation but is
10
+ * usually just a missing declaration, so this probes the endpoint itself.
11
+ *
12
+ * It answers the two questions that decide the profile config:
13
+ * 1. Does the route do reasoning, and which `reasoning_effort` spellings does
14
+ * it accept? (`off` is special: the parameter must be omitted entirely,
15
+ * because most gateways reject the literal string.)
16
+ * 2. Does it accept the OpenAI reasoning-model `developer` role? If not, the
17
+ * profile must set `compat.supportsDeveloperRole: false`, or every turn
18
+ * fails with a 422 the moment reasoning is declared.
19
+ *
20
+ * The key is read from the named environment variable and never printed.
21
+ *
22
+ * Exposed as a function so the `paseo-dsh` CLI and the repo's standalone
23
+ * `tools/probe-provider.mjs` share one implementation.
24
+ *
25
+ * @module paseo-dsh/lib/probe-provider
26
+ */
27
+ import { pathToFileURL } from "node:url";
28
+
29
+ const CANDIDATE_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
30
+
31
+ /** Parse `--flag value` pairs into a plain object. */
32
+ function parseArgs(argv) {
33
+ const out = {};
34
+ for (let i = 0; i < argv.length; i += 1) {
35
+ const token = argv[i];
36
+ if (!token.startsWith("--")) continue;
37
+ const key = token.slice(2);
38
+ const next = argv[i + 1];
39
+ if (next === undefined || next.startsWith("--")) {
40
+ out[key] = true;
41
+ } else {
42
+ out[key] = next;
43
+ i += 1;
44
+ }
45
+ }
46
+ return out;
47
+ }
48
+
49
+ function usage(program, message) {
50
+ if (message !== undefined) process.stderr.write(`error: ${message}\n\n`);
51
+ process.stderr.write(
52
+ `usage: ${program} --base-url <url> --api-key-env <ENV_VAR> --model <id> [--model <id>...]\n`,
53
+ );
54
+ process.exit(message === undefined ? 0 : 2);
55
+ }
56
+
57
+ /** One chat completion, reporting whether the endpoint accepted the request. */
58
+ async function attempt(endpoint, apiKey, body) {
59
+ let response;
60
+ try {
61
+ response = await fetch(endpoint, {
62
+ method: "POST",
63
+ headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
64
+ body: JSON.stringify(body),
65
+ signal: AbortSignal.timeout(120_000),
66
+ });
67
+ } catch (error) {
68
+ return { ok: false, status: 0, detail: error instanceof Error ? error.message : String(error) };
69
+ }
70
+ const text = await response.text();
71
+ let parsed;
72
+ try {
73
+ parsed = JSON.parse(text);
74
+ } catch {
75
+ parsed = undefined;
76
+ }
77
+ if (!response.ok) {
78
+ const detail = parsed?.error?.message ?? parsed?.message ?? text.slice(0, 240);
79
+ return { ok: false, status: response.status, detail: String(detail) };
80
+ }
81
+ return { ok: true, status: response.status, body: parsed };
82
+ }
83
+
84
+ /** The message object of the first choice, if the response carried one. */
85
+ function messageOf(body) {
86
+ return body?.choices?.[0]?.message;
87
+ }
88
+
89
+ function reasoningChars(message) {
90
+ return String(message?.reasoning_content ?? message?.reasoning ?? "").length;
91
+ }
92
+
93
+ async function probeModel(endpoint, apiKey, model) {
94
+ const findings = { levels: [], developerRole: undefined, reasonsAtBaseline: undefined };
95
+
96
+ const baseline = await attempt(endpoint, apiKey, {
97
+ model,
98
+ messages: [{ role: "user", content: "What is 17*23? Reply with just the number." }],
99
+ max_tokens: 256,
100
+ });
101
+ if (!baseline.ok) return { ...findings, fatal: baseline };
102
+
103
+ const baselineMessage = messageOf(baseline.body);
104
+ findings.reasonsAtBaseline =
105
+ baselineMessage === undefined ? false : "reasoning_content" in baselineMessage || reasoningChars(baselineMessage) > 0;
106
+
107
+ const developer = await attempt(endpoint, apiKey, {
108
+ model,
109
+ messages: [
110
+ { role: "developer", content: "You are terse." },
111
+ { role: "user", content: "What is 17*23? Reply with just the number." },
112
+ ],
113
+ max_tokens: 256,
114
+ });
115
+ findings.developerRole = developer.ok;
116
+
117
+ for (const level of CANDIDATE_LEVELS) {
118
+ const result = await attempt(endpoint, apiKey, {
119
+ model,
120
+ messages: [{ role: "user", content: "What is 17*23? Reply with just the number." }],
121
+ max_tokens: 256,
122
+ reasoning_effort: level,
123
+ });
124
+ findings.levels.push({ level, ok: result.ok, status: result.status, detail: result.detail });
125
+ }
126
+ return findings;
127
+ }
128
+
129
+ /** Render the profile fragment a user can paste after the probe. */
130
+ function profileSnippet(model, findings) {
131
+ const accepted = findings.levels.filter((entry) => entry.ok).map((entry) => entry.level);
132
+ const lines = [` - id: ${model}`, ` name: ${model}`];
133
+ if (accepted.length === 0) return lines.join("\n");
134
+ lines.push(" reasoningEfforts:");
135
+ // `off` must carry no value: omitting the parameter is what turns thinking
136
+ // off, while the literal string is rejected by most gateways.
137
+ lines.push(" off:");
138
+ for (const level of accepted) lines.push(` ${level}: ${level}`);
139
+ return lines.join("\n");
140
+ }
141
+
142
+ /**
143
+ * Run the probe. `argv` excludes the node/script prefix.
144
+ * @param {string[]} argv
145
+ * @param {string} program - Program name shown in usage/errors.
146
+ */
147
+ export async function runProbe(argv, program = "paseo-dsh probe") {
148
+ const args = parseArgs(argv);
149
+ if (args.help === true) usage(program);
150
+ const baseUrl = typeof args["base-url"] === "string" ? args["base-url"].replace(/\/$/, "") : undefined;
151
+ const keyEnv = typeof args["api-key-env"] === "string" ? args["api-key-env"] : undefined;
152
+ const models = [];
153
+ for (let i = 0; i < argv.length; i += 1) {
154
+ if (argv[i] === "--model" && argv[i + 1] !== undefined) models.push(argv[i + 1]);
155
+ }
156
+ if (baseUrl === undefined) usage(program, "--base-url is required");
157
+ if (keyEnv === undefined) usage(program, "--api-key-env is required");
158
+ if (models.length === 0) usage(program, "at least one --model is required");
159
+
160
+ const apiKey = process.env[keyEnv];
161
+ if (apiKey === undefined || apiKey === "") {
162
+ process.stderr.write(`error: environment variable ${keyEnv} is empty or unset\n`);
163
+ process.exit(2);
164
+ }
165
+
166
+ const endpoint = `${baseUrl}/chat/completions`;
167
+ process.stdout.write(`endpoint: ${endpoint}\n\n`);
168
+
169
+ for (const model of models) {
170
+ process.stdout.write(`model: ${model}\n`);
171
+ const findings = await probeModel(endpoint, apiKey, model);
172
+ if (findings.fatal !== undefined) {
173
+ process.stdout.write(
174
+ ` baseline call .......... FAILED (${findings.fatal.status || "network"}) ${findings.fatal.detail}\n`,
175
+ );
176
+ process.stdout.write(" cannot probe further; check the base URL, key, and model id\n\n");
177
+ continue;
178
+ }
179
+ process.stdout.write(
180
+ ` baseline call .......... ok (reasoning content at baseline: ${
181
+ findings.reasonsAtBaseline ? "yes" : "no"
182
+ })\n`,
183
+ );
184
+ process.stdout.write(
185
+ ` role=developer ......... ${
186
+ findings.developerRole ? "accepted" : "REJECTED -> needs compat.supportsDeveloperRole: false"
187
+ }\n`,
188
+ );
189
+ for (const entry of findings.levels) {
190
+ process.stdout.write(
191
+ ` reasoning_effort=${entry.level.padEnd(8)} ${entry.ok ? "accepted" : `rejected (${entry.status})`}\n`,
192
+ );
193
+ }
194
+ const accepted = findings.levels.filter((entry) => entry.ok);
195
+ process.stdout.write("\n profile fragment:\n\n");
196
+ process.stdout.write(`${profileSnippet(model, findings)}\n`);
197
+ if (accepted.length === 0) {
198
+ process.stdout.write(
199
+ "\n no reasoning_effort spelling was accepted; declare `reasoningEfforts: false`\n"
200
+ + " for this model so DSH reports it as a non-reasoning route\n",
201
+ );
202
+ }
203
+ process.stdout.write("\n");
204
+ }
205
+ }
206
+
207
+ const invokedDirectly =
208
+ process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
209
+ if (invokedDirectly) {
210
+ await runProbe(process.argv.slice(2), "node lib/probe-provider.mjs");
211
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paseo-dsh",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "DeepSeek Harness (dsh) as a native Paseo provider: question cards, plan mode, thinking levels, steering, images and a real slash menu.",
5
5
  "keywords": [
6
6
  "paseo",
@@ -19,10 +19,15 @@
19
19
  },
20
20
  "homepage": "https://github.com/liuxing7954/paseo-dsh#readme",
21
21
  "bugs": "https://github.com/liuxing7954/paseo-dsh/issues",
22
+ "bin": {
23
+ "paseo-dsh": "bin/paseo-dsh.mjs"
24
+ },
22
25
  "files": [
23
26
  "paseo-plugin.json",
24
27
  "index.server.ts",
25
28
  "server/",
29
+ "lib/",
30
+ "bin/",
26
31
  "icon.svg",
27
32
  "README.md",
28
33
  "LICENSE"