@argszero/cordis-plugin-read-image-guidance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @argszero/cordis-plugin-read-image-guidance
+
+**Actionable `read_image` refusal for dsh.**
+
+When the harness refuses to read an image because the resolved model route does
+not *declare* image input, it currently tells you to *switch models* — but the
+model is usually fine. The **declaration** is what's missing. This plugin turns
+that opaque refusal into concrete config guidance: declare
+`input: [text, image]` on the model's `models` entry (or extend its catalog
+entry), instead of sending you on a model-swap hunt.
+
+## The gap
+
+`read_image`'s capability gate (`assertImageCapableRoute` in `dsh-tool-fs`)
+reads the **declared** `inputModalities` of the resolved route. For custom
+providers with no catalog entry, the resolution chain
+(`declaredInput ?? base?.input ?? defaultInput`) falls back to `['text']`, so a
+vision-capable model is refused with:
+
+> cannot read "<path>" as an image: model "<model>" does not declare image
+> input; switch to an image-capable model to read images
+
+The correct fix is `input: [text, image]` on the model entry — not a model swap.
+This is the request-① gap of discussion #6049 (the `inputModalities` family,
+6th member: the *tool-read-side* capability gate).
+
+## How it works
+
+It wraps `tools/execute` (the same around-dispatch seam as the in-tree
+`guard/timeout-policy`). When a `read_image` result carries the exact refusal
+signature, it rewrites the model-facing message into actionable guidance while
+**preserving** the `isError` flag and the structured `error` (so retry/replay code
+paths stay routable). Every other tool result passes through untouched.
+
+## Usage
+
+Mount as a dsh bundle plugin (defaults are sane, rewrite on):
+
+```sh
+dsh plugin --profile web add github:argszero/cordis-plugin-read-image-guidance
+```
+
+Tune via a profile layer:
+
+```yaml
+- set:
+    - id: read-image-guidance
+      config:
+        rewrite: false  # observe-only, no rewrite
+```
+
+## Config
+
+| field | type | default | description |
+|-------|------|---------|-------------|
+| `rewrite` | `boolean` | `true` | Set `false` to observe-only (no rewrite). |
+
+## Scope
+
+- Rewrites **only** the exact `read_image` refusal marker
+  (`does not declare image input; switch to an image-capable model to read images`).
+- Never drops the refusal, never touches `isError`, never touches other tools.
+- No native/OCR dependency in v0.1 (an OCR-fallback form is a separate, heavier
+  candidate; this one is the "declaration detection + actionable error" half).
+
+## Compatibility
+
+- dsh `0.1.5-alpha.1` (verified against `packages/fs/tool-fs/src/read-image.ts`
+  and `packages/core/tools/src/index.ts`).
+- `peerDependencies`: `@deepseek-ai/cordis ^4.0.2`, `@deepseek-ai/dsh-tools >=0.1.2`.
+
+## Test
+
+```sh
+npm test
+```
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# The @argszero/cordis-plugin-read-image-guidance bundle patch: no deployment-
+# specific config is needed to mount (rewrite is on by default). Tune via a
+# profile layer if desired:
+#
+#   - set:
+#       - id: read-image-guidance
+#         config:
+#           rewrite: true
+#
+# The plugin only rewrites the exact read_image refusal message that points the
+# user at a model swap; every other tool result passes through untouched.
+
+- insert:
+    - id: read-image-guidance
+      name: '@argszero/cordis-plugin-read-image-guidance'

package/lib/index.js

@@ -0,0 +1,132 @@
+/**
+ * Actionable `read_image` refusal for the dsh harness.
+ *
+ * `packages/fs/tool-fs/src/read-image.ts` gates the model-facing `read_image`
+ * tool on the *declared* input modalities of the resolved model route
+ * (`assertImageCapableRoute`). When a vision-capable model's image input is not
+ * declared for the route in use (common for custom providers that lack a
+ * catalog entry — the resolution chain `declaredInput ?? base?.input ??
+ * defaultInput` then falls back to `['text']`), the tool refuses with:
+ *
+ *   cannot read "<path>" as an image: model "<model>" does not declare image
+ *   input; switch to an image-capable model to read images
+ *
+ * That message sends the user to swap models — but the model is fine; the
+ * *declaration* is what's missing. The correct fix is to declare
+ * `input: [text, image]` on the model's `models` entry (or, for catalog-backed
+ * providers, to extend the catalog). This is the request-① gap of discussion
+ * #6049.
+ *
+ * The in-tree core fix is a one-line message change, but it lives in the tarred
+ * read path of `dsh-tool-fs` and is an upstream-fix candidate the community
+ * cannot merge. This plugin is the community-side replacement: it wraps
+ * `tools/execute` (the same around-dispatch seam the in-tree
+ * `guard/timeout-policy` uses) and, when the exact refusal signature is
+ * detected on a `read_image` result, rewrites the model-facing message into
+ * actionable config guidance. Every other tool result passes through untouched.
+ *
+ * Mechanism notes (verified against packages/core/tools/src/index.ts and
+ * packages/fs/tool-fs/src/read-image.ts on dsh 0.1.5-alpha.1):
+ *  - `tools/execute` is a Cordis waterfall around dispatch; a wrapper's `next()`
+ *    returns a resolved `ToolExecutionResult`. A tool body that throws (which
+ *    `assertImageCapableRoute` does) is converted by the registry into an
+ *    `isError` result before the around-dispatch waterfall sees it, so the
+ *    wrapper observes a resolved error — never a thrown one.
+ *  - The refusal is a plain `Error` with a stable textual signature (the
+ *    "does not declare image input; switch to an image-capable model" suffix).
+ *    The plugin matches that exact substring and rewrites the `content` text
+ *    while preserving the structured `error` (retry/replay code paths stay
+ *    routable).
+ *  - The plugin never drops the refusal; it only makes it actionable. The
+ *    `isError` flag is preserved, so a model that genuinely cannot image-read
+ *    still learns the read failed and can fall back / try another route.
+ *
+ * @module @argszero/cordis-plugin-read-image-guidance
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'read-image-guidance';
+/** The tool registry service this plugin wraps (`tools/execute`). */
+export const inject = ['tools'];
+export const Config = z.object({
+    rewrite: z.boolean().default(true),
+});
+/** The only tool this plugin examines: the model-facing image reader. */
+const READ_IMAGE_TOOL = 'read_image';
+/** The stable refusal suffix (from `assertImageCapableRoute` in dsh-tool-fs). */
+const REFUSAL_MARKER = 'does not declare image input; switch to an image-capable model to read images';
+/** Limit guard: never let a single rewrite chain grow unboundedly. */
+const MAX_MESSAGE_BYTES = 12_000;
+/** Extract the model name from a refusal, if it is present and parseable. */
+function modelOf(message) {
+    // "cannot read "<path>" as an image: model "<model>" does not declare ..."
+    const m = /model "([^"]+)"/.exec(message);
+    return m?.[1] ?? '';
+}
+/** Extract the requested path from a refusal, if present. */
+function pathOf(message) {
+    // "cannot read "<path>" as an image: ..."
+    const m = /cannot read "([^"]+)"/.exec(message);
+    return m?.[1] ?? '';
+}
+/**
+ * Rewrite the refuser's message into concrete config guidance. Returns the
+ * original `message` unchanged when the refusal marker is absent (so non-image
+ * errors and other tool results are never touched).
+ */
+export function rewriteMessage(message) {
+    if (!message.includes(REFUSAL_MARKER))
+        return message;
+    const model = modelOf(message);
+    const path = pathOf(message);
+    const modelPart = model.length > 0 ? `model "${model}"` : `the resolved model`;
+    const pathPart = path.length > 0 ? `"${path}"` : 'the requested image';
+    const guidance = `cannot read ${pathPart} as an image: ${modelPart} does not declare image input. ` +
+        `This is a declaration issue, not a model-capability issue: the route in use has no ` +
+        `\`image\` input declared, so the harness refuses before reading. If this model supports ` +
+        `images, declare \`input: [text, image]\` on its \`models\` entry (under the active provider ` +
+        `in \`settings.yaml\` / your custom provider config) and restart the session. For a catalog-` +
+        `backed provider, extend its catalog entry instead. If you meant to read a non-image file, use ` +
+        `\`read_file\` instead; if the model truly cannot process images, switch to an image-capable model.`;
+    return guidance.length > MAX_MESSAGE_BYTES ? message : guidance;
+}
+/**
+ * The pure around-dispatch logic, exported separately from {@link apply} so it
+ * is testable without a live Cordis context. Returns the dispatch result to
+ * pass on (either the tool's own result or the rewritten one).
+ */
+/** Return the string content of a text block, or undefined for any other block. */
+export function textOf(block) {
+    if (block.type !== 'text')
+        return undefined;
+    const t = block.text;
+    return typeof t === 'string' ? t : undefined;
+}
+export async function runWrapper(config, exec, next) {
+    const result = await next();
+    // Only examine a failing read_image with the exact refusal signature.
+    if (!config.rewrite)
+        return result;
+    if (exec.name !== READ_IMAGE_TOOL || !result.isError)
+        return result;
+    const firstText = result.content.find((block) => textOf(block) !== undefined);
+    if (firstText === undefined)
+        return result;
+    const original = textOf(firstText) ?? '';
+    const rewritten = rewriteMessage(original);
+    if (rewritten === original)
+        return result;
+    return {
+        ...result,
+        content: result.content.map((block) => textOf(block) === original ? { ...block, text: rewritten } : block),
+    };
+}
+/**
+ * Register the wrapper. {@link runWrapper}'s structural {@link WrapperExec} is a
+ * subset of the registry's own `ToolDispatchExecution`, so the registration is a
+ * plain delegate with no casts.
+ */
+export function apply(ctx, config) {
+    ctx.on('tools/execute', (exec, next) => runWrapper(config, exec, next));
+}

package/lib/types/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Actionable `read_image` refusal for the dsh harness.
+ *
+ * `packages/fs/tool-fs/src/read-image.ts` gates the model-facing `read_image`
+ * tool on the *declared* input modalities of the resolved model route
+ * (`assertImageCapableRoute`). When a vision-capable model's image input is not
+ * declared for the route in use (common for custom providers that lack a
+ * catalog entry — the resolution chain `declaredInput ?? base?.input ??
+ * defaultInput` then falls back to `['text']`), the tool refuses with:
+ *
+ *   cannot read "<path>" as an image: model "<model>" does not declare image
+ *   input; switch to an image-capable model to read images
+ *
+ * That message sends the user to swap models — but the model is fine; the
+ * *declaration* is what's missing. The correct fix is to declare
+ * `input: [text, image]` on the model's `models` entry (or, for catalog-backed
+ * providers, to extend the catalog). This is the request-① gap of discussion
+ * #6049.
+ *
+ * The in-tree core fix is a one-line message change, but it lives in the tarred
+ * read path of `dsh-tool-fs` and is an upstream-fix candidate the community
+ * cannot merge. This plugin is the community-side replacement: it wraps
+ * `tools/execute` (the same around-dispatch seam the in-tree
+ * `guard/timeout-policy` uses) and, when the exact refusal signature is
+ * detected on a `read_image` result, rewrites the model-facing message into
+ * actionable config guidance. Every other tool result passes through untouched.
+ *
+ * Mechanism notes (verified against packages/core/tools/src/index.ts and
+ * packages/fs/tool-fs/src/read-image.ts on dsh 0.1.5-alpha.1):
+ *  - `tools/execute` is a Cordis waterfall around dispatch; a wrapper's `next()`
+ *    returns a resolved `ToolExecutionResult`. A tool body that throws (which
+ *    `assertImageCapableRoute` does) is converted by the registry into an
+ *    `isError` result before the around-dispatch waterfall sees it, so the
+ *    wrapper observes a resolved error — never a thrown one.
+ *  - The refusal is a plain `Error` with a stable textual signature (the
+ *    "does not declare image input; switch to an image-capable model" suffix).
+ *    The plugin matches that exact substring and rewrites the `content` text
+ *    while preserving the structured `error` (retry/replay code paths stay
+ *    routable).
+ *  - The plugin never drops the refusal; it only makes it actionable. The
+ *    `isError` flag is preserved, so a model that genuinely cannot image-read
+ *    still learns the read failed and can fall back / try another route.
+ *
+ * @module @argszero/cordis-plugin-read-image-guidance
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "read-image-guidance";
+/** The tool registry service this plugin wraps (`tools/execute`). */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * When `true` (default), rewrite the exact `read_image` refusal into
+     * actionable config guidance. Set `false` to observe-only (no rewrite).
+     */
+    rewrite?: boolean;
+}
+/** Resolved config: every field carries its validated default. */
+export type ResolvedConfig = Required<Config>;
+export declare const Config: z<Config>;
+/** Structural view of the exec object this wrapper needs. */
+export interface WrapperExec {
+    readonly name: string;
+}
+/** Structural view of the delegated dispatch (`next()`). */
+export type WrapperNext = () => Promise<ToolExecutionResult>;
+/**
+ * Rewrite the refuser's message into concrete config guidance. Returns the
+ * original `message` unchanged when the refusal marker is absent (so non-image
+ * errors and other tool results are never touched).
+ */
+export declare function rewriteMessage(message: string): string;
+/**
+ * The pure around-dispatch logic, exported separately from {@link apply} so it
+ * is testable without a live Cordis context. Returns the dispatch result to
+ * pass on (either the tool's own result or the rewritten one).
+ */
+/** Return the string content of a text block, or undefined for any other block. */
+export declare function textOf(block: ContentBlock): string | undefined;
+export declare function runWrapper(config: ResolvedConfig, exec: WrapperExec, next: WrapperNext): Promise<ToolExecutionResult>;
+/**
+ * Register the wrapper. {@link runWrapper}'s structural {@link WrapperExec} is a
+ * subset of the registry's own `ToolDispatchExecution`, so the registration is a
+ * plain delegate with no casts.
+ */
+export declare function apply(ctx: Context, config: ResolvedConfig): void;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@argszero/cordis-plugin-read-image-guidance",
+  "description": "Actionable read_image refusal for dsh: when the harness refuses to read an image because the resolved model route does not declare image input, turn that opaque 'switch to an image-capable model' message into concrete config guidance (declare \"input: [text, image]\" on the model's entry) instead of sending the user to swap models. Compatible with dsh 0.1.5-alpha.1 (read_image assertImageCapableRoute refuses on undeclared image input).",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "cordis",
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "read_image",
+    "image",
+    "inputModalities",
+    "guidance"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.1.5-alpha.1",
+    "@types/node": "^26.5.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test \"test/*.test.js\"",
+    "prepublishOnly": "tsc"
+  }
+}