@twinsearth/w2m-dsh-plugin 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.57.0] — 2026-10-15
+
+**An image path becomes text evidence: the vision subprocess, and the credential path that does not touch argv.**
+
+### What this is, and what it deliberately is not
+
+`src/chatops/vision.mjs` runs the vendored `vision.py` as a subprocess. **It is not the WeChat integration** —
+the bridge still answers an image with a help message. The two halves are kept apart because each has a different
+failure mode and can be verified alone, **and this half is verifiable today**: give it a real image and it either
+returns text or a named reason.
+
+**Verified against the real endpoint, on this machine:** a generated 32×32 red PNG, `glm-4v-plus`, **1.77 s**,
+reply `"红色。"` — and `prompt_tokens` 64 → 2374, so the image genuinely reached the model rather than being
+ignored.
+
+### The credential never enters `argv`
+
+`vision.py` resolves its key as `--api-key` > `VISION_API_KEY` > the provider's own variable — read out of its
+own source, not assumed. **Passing it on the command line would put a live key into `ps` output and into any
+argument logging**, so this module only ever sets it **in the child's environment**, and the caller supplies it
+from a file.
+
+**The settings file is a parser, not a shell.** No expansion, no quoting rules, no `export` prefix: a value of
+`$HOME` stays the four characters `$HOME`. **A settings file that is half a shell is a shell**, and the point of
+this one is that it is read rather than executed.
+
+### An error message I wrote that collapsed three causes into one
+
+My first probe of the credential printed
+`==> refused; the key or the model name is not accepted` for **any** non-2xx response. The actual response was:
+
+```
+HTTP 400  code 1210  "图片输入格式/解析错误"
+```
+
+**That is an image-decoding failure — which is proof the credential was accepted**, because bigmodel answers
+**401** for a bad key. **My hand-built base64 PNG was malformed, and I reported it as a credential problem.** One
+conclusion for three different causes is the failure this repository keeps naming, and I committed it while
+writing a file whose own header complains about that pattern.
+
+The re-probe generates the PNG from `zlib.deflateSync` plus a hand-written CRC — **correct by construction** —
+and splits the two questions: a text-only request isolates the key, and the image isolates the vision path. Both
+returned 200.
+
+### One ordering the code decided and the test got wrong
+
+The module checks the image argument, then the script, then whether the image exists. My new assertion claimed a
+non-existent image outranks a missing script — **it does not, and the code was right.** The assertion was
+narrowed to the ordering that is actually guaranteed: **an empty argument is rejected before the installation is
+consulted.**
+
+**17 new tests, 0 failures**, and none of them needs a network or a key — every refusal path is asserted, and the
+one thing not asserted is a real model answer, because a suite that needs a credential is a suite that skips
+wherever the credential is absent.
+
+## [0.56.0] — 2026-10-15
+
+**The declared endpoint is now tested against the real binary, so a drifted port turns the pre-flight red.**
+
+### The gap the sixteen transport tests left open
+
+`mcp-http.test.mjs` drives `createRequestHandler` **in process**, with fake request and response objects. That
+proves the framing, and it proves **nothing about the CLI path**: a wrong default port, a crash during startup,
+an import cycle, or a `--http` flag that is never reached would all pass while `mcp.json` pointed at a dead URL.
+
+**A wrong end of a declared address is not a unit-test-shaped bug.** It has to be dialled.
+
+### What the new suite does differently
+
+`test/mcp-http-live.test.mjs` **spawns `bin/w2m-mcp.mjs --http`** and speaks to **the URL read out of
+`mcp.json`** — not a URL the test picks, because a healthy server on port 0 would prove nothing about `8766`.
+
+It asserts the far end is reachable and speaking the protocol, and **deliberately does not assert a successful
+tool result**: the relay needs an operator token the test does not carry, so **a `401` is the expected
+outcome**. That refusal is *stronger* evidence than a mocked `200` — **it proves the request left this process,
+crossed the binding, and was answered by the fleet's real relay**, which a mock could not distinguish from a
+server that never dialled out.
+
+**stdout is asserted empty.** The stdio binding owns stdout; if this path ever wrote a frame there, a client
+launching both would see a corrupted stream and the symptom would be a hang rather than an error.
+
+### Three levels of nesting, which is why this was worth checking
+
+`pre-flight` → runs the declared suite as a child → which runs this suite → which spawns the server. **That
+works**, and the run proved it rather than assuming it.
+
+### The one failure it produced, and it was mine
+
+The first run went red on `claims.test.mjs`: **`package.json` said 0.56.0 and the newest CHANGELOG entry said
+0.55.0.** I bumped the version before writing the entry. **This project's own check caught my ordering mistake**
+— which is the whole point of `claims` existing, and the second time this session that a version bump without an
+entry has been the only red line in an otherwise green run.
+
+**6 new tests, 0 failures.** Full suite 2324 in 87 files. **Pre-flight GREEN with FIFTEEN checks.**
+
 ## [0.55.0] — 2026-10-15
 
 **A second transport binding — and `mcp.json` now declares both.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",
@@ -116,13 +116,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "Cross-platform fleet execution between Windows and macOS: one DeepSeek Harness account, a Rabbit relay, and signed device identity. Ships four Agent Skills describing fleet dispatch, field-level memory acceptance, session references, and resource scheduling.",
   "license": "MIT",
   "keywords": [

package/src/chatops/vision.mjs

@@ -0,0 +1,267 @@
+/**
+ * Invoke the vendored `vision.py` as a subprocess (v0.57.0).
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * It turns an image path into text evidence by running a Python script. **It is not the WeChat integration.** The
+ * bridge still answers an image with a help message, and wiring this into it is a separate change -- kept apart
+ * because each half has a different failure mode and can be verified alone. **This half is verifiable today:**
+ * give it a real image and it either returns text or a named reason.
+ *
+ * ## The credential never enters `argv`
+ *
+ * `vision.py` resolves its key as `--api-key` > `VISION_API_KEY` > the provider's own variable (`ZHIPU_API_KEY`
+ * for `glm`). **Passing it on the command line would put a live key into `ps` output and into any argv logging**,
+ * so this module only ever sets it **in the child's environment**, and the caller supplies it from a file.
+ *
+ * ## Why the settings file is read here rather than exported by a shell
+ *
+ * The bridge is started by hand sometimes and by a launcher other times, **so an `export` in a shell rc is only
+ * sometimes in effect** -- and a credential that works until the start method changes is worse than one that
+ * never worked, because the failure looks like a broken API. A file with mode 0600 is read the same way
+ * whichever process is asking.
+ *
+ * ## Why the exit code and the stdout are both inspected
+ *
+ * `vision.py` writes its diagnosis to **stderr** and exits non-zero, and a caller that checks only stdout sees
+ * an empty string. It also prints the model's reply to **stdout**, so a caller that checks only the exit code
+ * discards the answer. Both are read, and the failure message is the script's own words rather than a
+ * paraphrase.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Where the vendored script lives, matching the layout the skill repository uses. */
+export const DEFAULT_SKILL_DIR = join(homedir(), '.agents', 'skills', 'vision-multimodal');
+/** The settings file the bridge reads. Mode 0600, one `KEY=value` per line, `provider` accepted as a key. */
+export const DEFAULT_ENV_FILE = join(homedir(), '.config', 'w2m', 'vision.env');
+
+/** Longest image this will hand to the script, in bytes. */
+export const MAX_IMAGE_BYTES = 12 * 1024 * 1024;
+
+/**
+ * Read a `KEY=value` settings file.
+ *
+ * Deliberately not a dotenv implementation: no expansion, no quoting rules, no `export` prefix. **A settings
+ * file that is half a shell is a shell**, and the whole point of this one is that it is read by a parser rather
+ * than executed.
+ *
+ * @param {string} path
+ * @returns {{values: Record<string,string>, problem: string|null}}
+ */
+export function readEnvFile(path) {
+  if (!existsSync(path)) return { values: {}, problem: `no settings file at ${path}` };
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    return { values: {}, problem: `could not read ${path}: ${error.message}` };
+  }
+  const values = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const at = line.indexOf('=');
+    if (at < 1) return { values: {}, problem: `${path}: line ${JSON.stringify(raw.slice(0, 40))} is not KEY=value` };
+    const key = line.slice(0, at).trim();
+    let value = line.slice(at + 1).trim();
+    // Strip one layer of matching quotes, because a key pasted from a web page often carries them.
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return { values, problem: null };
+}
+
+/** Mode on POSIX, or null where the platform has no such bits (Windows reports 0o666 for everything). */
+const modeOf = (path) => {
+  try {
+    const mode = statSync(path).mode & 0o777;
+    return process.platform === 'win32' ? null : mode;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Turn the settings values into the environment `vision.py` expects.
+ *
+ * `provider` is translated to `VISION_PROVIDER` because the script reads that name; everything else is passed
+ * through, so the file can carry `ZHIPU_API_KEY`, `VISION_API_KEY`, `VISION_BASE_URL` and `VISION_MODEL`
+ * without this module having to know which provider is in use.
+ *
+ * @param {Record<string,string>} values
+ * @param {Record<string,string>} [base] the parent environment
+ */
+export function visionEnv(values, base = process.env) {
+  const env = { ...base };
+  for (const [key, value] of Object.entries(values)) {
+    env[key === 'provider' ? 'VISION_PROVIDER' : key] = value;
+  }
+  return env;
+}
+
+/** Does the resolved environment actually carry a key for the selected provider? */
+const KEY_FOR = { glm: 'ZHIPU_API_KEY', qwen: 'DASHSCOPE_API_KEY', kimi: 'MOONSHOT_API_KEY', openai: 'OPENAI_API_KEY', siliconflow: 'SILICONFLOW_API_KEY' };
+
+export function keyPresent(env) {
+  if (typeof env.VISION_API_KEY === 'string' && env.VISION_API_KEY !== '') return true;
+  const provider = env.VISION_PROVIDER ?? 'qwen';
+  if (provider === 'ollama') return true; // needs no key by design
+  const name = KEY_FOR[provider] ?? 'VISION_API_KEY';
+  return typeof env[name] === 'string' && env[name] !== '';
+}
+
+/**
+ * Run one vision command.
+ *
+ * @param {{command?: string, image: string, prompt?: string, scriptDir?: string, env: object, python?: string, timeoutMs?: number}} options
+ * @returns {Promise<{ok: boolean, text: string, reason: string|null, code: number|null, ms: number}>}
+ */
+export function analyze({ command = 'chat', image, prompt, scriptDir = DEFAULT_SKILL_DIR, env, python = 'python3', timeoutMs = 120_000 }) {
+  const script = join(scriptDir, 'vision.py');
+  /**
+   * Caller mistakes are reported before configuration mistakes.
+   *
+   * A wrong image path and a missing script are both refusals, and the order decides which one a caller sees.
+   * **The image is the argument; the script is the installation.** Checking the installation first meant every
+   * malformed call on a machine without the skill answered "no vision.py at …" -- true, and useless, because
+   * the caller's own mistake was never mentioned.
+   */
+  if (typeof image !== 'string' || image === '') return Promise.resolve({ ok: false, text: '', reason: 'no image path given', code: null, ms: 0 });
+  if (!existsSync(script)) return Promise.resolve({ ok: false, text: '', reason: `no vision.py at ${script}`, code: null, ms: 0 });
+  if (!existsSync(image)) return Promise.resolve({ ok: false, text: '', reason: `image does not exist: ${image}`, code: null, ms: 0 });
+  try {
+    const size = statSync(image).size;
+    if (size > MAX_IMAGE_BYTES) return Promise.resolve({ ok: false, text: '', reason: `image is ${size} bytes, over the ${MAX_IMAGE_BYTES}-byte limit`, code: null, ms: 0 });
+  } catch (error) {
+    return Promise.resolve({ ok: false, text: '', reason: `could not stat the image: ${error.message}`, code: null, ms: 0 });
+  }
+
+  // `shell: false` and an argv array: the image path is data, never a command fragment.
+  const argv = [script, command, '--image', image];
+  if (typeof prompt === 'string' && prompt !== '') argv.push('--prompt', prompt);
+  const started = Date.now();
+
+  return new Promise((resolve) => {
+    const child = spawn(python, argv, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    let settled = false;
+    const finish = (result) => { if (!settled) { settled = true; resolve(result); } };
+    const timer = setTimeout(() => {
+      child.kill();
+      finish({ ok: false, text: '', reason: `vision.py did not finish within ${timeoutMs} ms`, code: null, ms: Date.now() - started });
+    }, timeoutMs);
+
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.on('data', (c) => { err += c; });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      // A missing interpreter is the most likely error here, and it must read as itself rather than as a
+      // generic failure -- the deploy that installs the script does not install python3.
+      finish({ ok: false, text: '', reason: error.code === 'ENOENT' ? `no ${python} on PATH` : `could not start ${python}: ${error.message}`, code: null, ms: Date.now() - started });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const ms = Date.now() - started;
+      if (code === 0) {
+        const text = out.trim();
+        if (text === '') finish({ ok: false, text: '', reason: 'vision.py exited 0 but printed nothing', code, ms });
+        else finish({ ok: true, text, reason: null, code, ms });
+        return;
+      }
+      // The script's own words, not a paraphrase: it names the missing key env var, the bad path, or the HTTP
+      // status, and replacing that with "vision failed" throws away the only actionable part.
+      const detail = (err.trim() || out.trim() || `exit ${code}`).split(/\r?\n/).slice(-3).join(' | ');
+      finish({ ok: false, text: '', reason: detail, code, ms });
+    });
+  });
+}
+
+/**
+ * Is vision usable right now, and if not, why?
+ *
+ * ## Why the bridge calls this
+ *
+ * The bridge answers an image with a help message. **Without this it can only say "unsupported"**, which is the
+ * same sentence whether the skill is missing, the key is absent, or the interpreter is not installed -- and an
+ * operator reading it has no next step. With it, the message names the one thing that is missing.
+ *
+ * **This is the module's first production caller**, and it is deliberately the smallest useful one: a capability
+ * probe, not the analysis path. The orphan gate in `scripts/preflight.mjs` is what required a caller at all, and
+ * it was right to -- **a mechanism with no caller is indistinguishable from a finished feature**, which this
+ * repository has shipped four times.
+ *
+ * @param {{envFile?: string, scriptDir?: string, python?: string, env?: object}} [options]
+ * @returns {Promise<{ready: boolean, reason: string|null, provider: string|null}>}
+ */
+export async function visionStatus(options = {}) {
+  const envFile = options.envFile ?? DEFAULT_ENV_FILE;
+  const scriptDir = options.scriptDir ?? DEFAULT_SKILL_DIR;
+  if (!existsSync(join(scriptDir, 'vision.py'))) {
+    return { ready: false, reason: `no vision.py at ${join(scriptDir, 'vision.py')}`, provider: null };
+  }
+  const { values, problem } = readEnvFile(envFile);
+  if (problem !== null) return { ready: false, reason: problem, provider: null };
+  const env = visionEnv(values, options.env ?? process.env);
+  const provider = env.VISION_PROVIDER ?? 'qwen';
+  if (!keyPresent(env)) {
+    return { ready: false, reason: `${envFile} has no key for provider "${provider}" (set ${KEY_FOR[provider] ?? 'VISION_API_KEY'})`, provider };
+  }
+  const python = options.python ?? 'python3';
+  // The interpreter is checked last because it is the one failure a deploy cannot fix on its own.
+  const found = await new Promise((resolve) => {
+    const child = spawn(python, ['--version'], { stdio: 'ignore' });
+    child.on('error', () => resolve(false));
+    child.on('close', (code) => resolve(code === 0));
+  });
+  if (!found) return { ready: false, reason: `no ${python} on PATH`, provider };
+  return { ready: true, reason: null, provider };
+}
+
+/**
+ * One sentence for a person who sent an image the bridge cannot hand to a model.
+ *
+ * @param {{envFile?: string, scriptDir?: string, python?: string, env?: object}} [options]
+ * @returns {Promise<string>}
+ */
+export async function visionUnavailableNote(options = {}) {
+  const status = await visionStatus(options);
+  if (status.ready) return `vision is configured (${status.provider}) and can read an image on disk`;
+  return `vision is not available: ${status.reason}`;
+}
+
+/**
+ * The whole path, from a settings file to an answer.
+ *
+ * @param {{image: string, prompt?: string, command?: string, envFile?: string, scriptDir?: string, python?: string, env?: object, timeoutMs?: number}} options
+ */
+export async function describeImage(options) {
+  const envFile = options.envFile ?? DEFAULT_ENV_FILE;
+  const { values, problem } = readEnvFile(envFile);
+  if (problem !== null) return { ok: false, text: '', reason: problem, code: null, ms: 0 };
+
+  const mode = modeOf(envFile);
+  if (mode !== null && (mode & 0o077) !== 0) {
+    // A settings file holding a credential that others can read is worth saying out loud, but it is not a
+    // refusal: the operator may have a reason, and refusing would make the tool unusable on a shared box.
+    return {
+      ok: false,
+      text: '',
+      reason: `${envFile} is mode ${mode.toString(8)}; a file holding a key should be 0600 (chmod 600 ${envFile})`,
+      code: null,
+      ms: 0,
+    };
+  }
+
+  const env = visionEnv(values, options.env ?? process.env);
+  if (!keyPresent(env)) {
+    const provider = env.VISION_PROVIDER ?? 'qwen';
+    return { ok: false, text: '', reason: `no key for provider "${provider}": set ${KEY_FOR[provider] ?? 'VISION_API_KEY'} in ${envFile}`, code: null, ms: 0 };
+  }
+  return analyze({ ...options, env });
+}

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.55.0';
+const PLUGIN_VERSION = '0.57.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;