dsh-agy-link 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,54 +1,28 @@
 # Changelog
 
+## 0.2.0 (2026-08-19)
+
+- Multimodal (path-based): DSH image attachments are staged to a local media
+  directory (config `mediaDir`, TTL sweep `mediaTtlMs`, caps `mediaMaxBytes` /
+  `mediaMaxImages`) and referenced by absolute path in the agy prompt with
+  `--add-dir` - agy views them with its own tools. Env: `DSH_AGY_MEDIA_DIR`,
+  `DSH_AGY_MEDIA_TTL_MS`.
+- `agy_ask` gains `readPaths` (inline text files into the one-shot prompt;
+  binaries skipped with a note) and `schema` (JSON Schema enforced via
+  `--json-schema`).
+- MCP reverse bridge (experimental, `mcpBridge: true` / `DSH_AGY_MCP_BRIDGE=1`):
+  agy can call DSH-side tools through a loopback, token-guarded endpoint plus a
+  zero-dep stdio MCP server merged into the workspace `.mcp.json`.
+  `mcpToolAllowlist` restricts the exposed set; `run_code` / `agy_ask` are
+  never bridged.
+- Abort semantics locked by a regression test: everything the model produced
+  before the caller hits stop is preserved (open block closed, then failure
+  finish).
+- 12 new tests (51 total).
+
 ## 0.1.5 (2026-08-19)
 
 - README restructured into a single bilingual page: Chinese first, then
   English (README.zh.md removed; package files list updated).
 - Releases now publish to npm automatically (NPM_TOKEN secret configured).
 
-## 0.1.4 (2026-08-19)
-
-- READMEs: added the author promo block (Chinese first, then English).
-- Housekeeping: internal spec documents are no longer part of the repo.
-
-## 0.1.3 (2026-08-19)
-
-- Fixed the client slot registration: the sidebar footer slot entry must
-  register under the slot name `sidebar.footer.action` (not `ui-sidebar`),
-  matching the ui-sidebar slot table - the wrong name failed plugin loading
-  with: slot ui-sidebar is not declared.
-
-## 0.1.2 (2026-08-18)
-
-- Fixed prompt assembly for returning sessions: the last-assistant scan now
-  stops at the newest assistant message, and the history digest covers exactly
-  the foreign turns since the watermark (previously it could re-send stale
-  history or swallow intermediate turns into the trailing prompt).
-- Hardened the stream loop: spawn failures release the concurrency slot and
-  surface as `PROCESS_EXIT` instead of hanging; the collector is fail-safe.
-- `/agy doctor` now exports the real last-run stdout ring (parser wiring).
-- `agy_ask` one-shot runs pass `--print-timeout` consistent with the watchdog.
-
-## 0.1.1 (2026-08-18)
-
-- Fixed cordis activation in app-less profiles (optional services are now
-  resolved via `ctx.get`, not `?`-suffixed inject entries).
-- Added `providerRetryPolicy`: AUTH failures fail fast (no quota-burning
-  retries); transient process failures retry once.
-
-## 0.1.0 (2026-08-18)
-
-Initial release.
-
-- `antigravity` LLM provider route over `agy -p --output-format stream-json`.
-- Streaming text / thinking / tool-activity mapping with token usage.
-- Session ↔ conversation binding with history digest on first contact.
-- Model discovery (`agy models`) with Gemini effort folding and fallback
-  catalog.
-- Google login: `/agy auth` + `/agy auth-code` + GUI panel (QR + paste).
-- `/agy` command family: status / auth / auth-code / models / mode /
-  effort / clear / doctor / help.
-- `agy_ask` delegation tool (optional).
-- Permission modes: plan / accept-edits / skip with red-flag UI on skip.
-- `/agy doctor` diagnostics export with auth redaction.
-- Auxiliary calls (compaction / session-title) via one-shot plan-mode turns.

package/README.md

@@ -34,6 +34,9 @@
 | 🔐 **GUI 内 Google 登录** | `/agy auth` 打印授权 URL；侧栏面板提供二维码 + 授权码粘贴框 |
 | 🤝 **`agy_ask` 工具** | 任何 DSH 模型都可以把一次性任务委托给 Antigravity 模型（AskAntigravity 模式） |
 | ⌨️ **`/agy` 命令族** | `status` / `auth` / `auth-code` / `models` / `mode` / `effort` / `clear` / `doctor` / `help` |
+| 🖼 **图片多模态（v0.2）** | 图片落盘到本地媒体目录（TTL 清理），prompt 以绝对路径引用 + `--add-dir` 授权，agy 用自己的工具看图 |
+| 📎 **文件内联 + 结构化输出（v0.2）** | `agy_ask` 新增 `readPaths`（文本文件内联）与 `schema`（`--json-schema` 强约束答案） |
+| 🌉 **MCP 反向桥（v0.2 实验）** | `mcpBridge: true` 开启后 agy 可直接调 DSH 侧工具（回环 + token 守卫端点 + 零依赖 stdio MCP 服务器，`.mcp.json` 合并写入/禁用还原） |
 | 😴 **休眠安全** | 没装 agy？没登录？插件照常加载并告诉你怎么修 |
 
 ## 🚀 快速开始
@@ -118,6 +121,9 @@ Bring **Google Antigravity models into DeepSeek Harness (DSH)** — chat, thinki
 | 🤝 **`agy_ask` tool** | Let any DSH model delegate a one-shot task to an Antigravity model (the AskAntigravity pattern) |
 | ⌨️ **`/agy` commands** | `status`, `auth`, `auth-code`, `models`, `mode`, `effort`, `clear`, `doctor`, `help` |
 | 😴 **Dormant-safe** | No agy binary? Not signed in? The plugin loads anyway and tells you what to fix |
+| 🖼 **Image multimodal (v0.2)** | image attachments staged to a TTL-swept local dir, referenced by absolute path with `--add-dir`; agy views them with its own tools |
+| 📎 **File inlining + structured output (v0.2)** | `agy_ask` gains `readPaths` (inline text files) and `schema` (enforced via `--json-schema`) |
+| 🌉 **MCP reverse bridge (v0.2, experimental)** | with `mcpBridge: true`, agy calls DSH-side tools directly (loopback token-guarded endpoint + zero-dep stdio MCP server merged into `.mcp.json`, restored on disable) |
 
 ## 🚀 Quick start
 

package/dist/bridge.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// dsh-agy-link MCP bridge script: a minimal stdio MCP server with zero
+// dependencies. agy launches it per the workspace .mcp.json; it forwards
+// tools/list and tools/call to the plugin loopback endpoint whose URL and
+// token arrive via env. Protocol: newline-delimited JSON-RPC 2.0.
+import { request as httpRequest } from 'node:http'
+import process from 'node:process'
+import { createInterface } from 'node:readline'
+
+const URL_BASE = process.env.DSH_MCP_URL || ''
+const TOKEN = process.env.DSH_MCP_TOKEN || ''
+const PROTOCOL = '2024-11-05'
+
+function post(path, body) {
+  return new Promise((resolve, reject) => {
+    if (URL_BASE === '' || TOKEN === '') {
+      reject(new Error('bridge not configured (missing DSH_MCP_URL/DSH_MCP_TOKEN)'))
+      return;
+    }
+    const data = JSON.stringify(body)
+    const u = new URL(URL_BASE)
+    const req = httpRequest({
+      hostname: u.hostname,
+      port: u.port || 80,
+      method: 'POST',
+      path,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        Authorization: 'Bearer ' + TOKEN,
+      },
+      timeout: 600000,
+    });
+    req.on('response', (res) => {
+      const chunks = []
+      res.on('data', (c) => chunks.push(c))
+      res.on('end', () => {
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(Buffer.concat(chunks).toString('utf8')) })
+        } catch (e) {
+          reject(e)
+        }
+      })
+    });
+    req.on('timeout', () => req.destroy(new Error('bridge request timed out')))
+    req.on('error', reject)
+    req.end(data)
+  })
+}
+
+let toolCache = null;
+
+async function listTools() {
+  if (toolCache) return toolCache;
+  const res = await post('/tools', {})
+  if (res.status !== 200) throw new Error('bridge /tools failed: ' + JSON.stringify(res.body))
+  toolCache = (res.body.tools || []).map((t) => ({
+    name: t.name,
+    description: t.description || t.dshName,
+    inputSchema: t.inputSchema || { type: 'object' },
+    _dshName: t.dshName,
+  }))
+  return toolCache;
+}
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n')
+}
+
+async function handle(id, method, params) {
+  if (method === 'initialize') {
+    send({ jsonrpc: '2.0', id, result: { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'dsh-agy-link-bridge', version: '0.2.0' } } })
+    return;
+  }
+  if (method.startsWith('notifications/')) return;
+  if (method === 'tools/list') {
+    const tools = await listTools()
+    send({ jsonrpc: '2.0', id, result: { tools: tools.map(({ _dshName, ...t }) => t) } })
+    return;
+  }
+  if (method === 'tools/call') {
+    const name = params && params.name
+    const args = (params && params.arguments) || {}
+    const tools = await listTools()
+    const hit = tools.find((t) => t.name === name)
+    if (!hit) {
+      send({ jsonrpc: '2.0', id, error: { code: -32602, message: 'unknown tool: ' + name } })
+      return;
+    }
+    try {
+      const res = await post('/call', { dshName: hit._dshName, arguments: args })
+      if (res.status !== 200 || res.body.ok !== true) {
+        send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: 'ERROR: ' + JSON.stringify(res.body) }], isError: true } })
+        return;
+      }
+      send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: res.body.text || '' }] } })
+    } catch (e) {
+      send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: 'ERROR: ' + String(e) }], isError: true } })
+    }
+    return;
+  }
+  if (method === 'ping') {
+    send({ jsonrpc: '2.0', id, result: {} })
+    return;
+  }
+  send({ jsonrpc: '2.0', id, error: { code: -32601, message: 'method not found: ' + method } })
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false })
+rl.on('line', (line) => {
+  const text = line.trim()
+  if (text === '') return
+  let msg;
+  try {
+    msg = JSON.parse(text)
+  } catch {
+    return;
+  }
+  if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return
+  if (msg.id === undefined) {
+  void handle(null, msg.method, msg.params).catch(() => {})
+    return;
+  }
+  void handle(msg.id, msg.method, msg.params).catch((e) => {
+    send({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e) } })
+  })
+})
+process.stdin.on('end', () => process.exit(0))

package/dist/index.js

@@ -1,9 +1,12 @@
-import { delimiter, dirname, join } from "node:path";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { LlmAdapter, LlmError } from "@deepseek-ai/dsh-llm";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { execFileSync, spawn } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
 //#region src/common/types.ts
 const PROVIDER_ID = "antigravity";
 const PLUGIN_ID = "agy-link";
@@ -46,7 +49,13 @@ function defaultConfig() {
 		compactionMaxChars: 8e5,
 		workspaceRoot: "",
 		fallbackModels: DEFAULT_FALLBACK_MODELS,
-		askTool: false
+		askTool: false,
+		mediaDir: "",
+		mediaTtlMs: 864e5,
+		mediaMaxBytes: 10485760,
+		mediaMaxImages: 8,
+		mcpBridge: false,
+		mcpToolAllowlist: ""
 	};
 }
 const Err = {
@@ -138,7 +147,13 @@ function resolveConfig(entry, env = process.env, overrides = readOverrides()) {
 		compactionMaxChars: asNum(get("compactionMaxChars")) ?? base.compactionMaxChars,
 		workspaceRoot: asString(get("workspaceRoot")) ?? base.workspaceRoot,
 		fallbackModels: Array.isArray(get("fallbackModels")) ? get("fallbackModels").filter((x) => !!x && typeof x === "object" && typeof x.id === "string") : base.fallbackModels,
-		askTool: asBool(get("askTool")) ?? base.askTool
+		askTool: asBool(get("askTool")) ?? base.askTool,
+		mediaDir: asString(get("mediaDir")) ?? base.mediaDir,
+		mediaTtlMs: asNum(get("mediaTtlMs")) ?? base.mediaTtlMs,
+		mediaMaxBytes: asNum(get("mediaMaxBytes")) ?? base.mediaMaxBytes,
+		mediaMaxImages: asNum(get("mediaMaxImages")) ?? base.mediaMaxImages,
+		mcpBridge: asBool(get("mcpBridge")) ?? base.mcpBridge,
+		mcpToolAllowlist: asString(get("mcpToolAllowlist")) ?? base.mcpToolAllowlist
 	};
 	if (env.DSH_AGY_ENABLED !== void 0) cfg.enabled = asBool(env.DSH_AGY_ENABLED) ?? cfg.enabled;
 	if (env.DSH_AGY_BIN) cfg.agyBin = env.DSH_AGY_BIN;
@@ -157,6 +172,16 @@ function resolveConfig(entry, env = process.env, overrides = readOverrides()) {
 		if (t && t > 0) cfg.timeoutMs = t;
 	}
 	if (env.DSH_AGY_EXTRA_ARGS) cfg.extraArgs = env.DSH_AGY_EXTRA_ARGS.split(/\s+/).filter(Boolean);
+	if (env.DSH_AGY_MEDIA_DIR) cfg.mediaDir = env.DSH_AGY_MEDIA_DIR;
+	if (env.DSH_AGY_MEDIA_TTL_MS) {
+		const t = asNum(env.DSH_AGY_MEDIA_TTL_MS);
+		if (t && t > 0) cfg.mediaTtlMs = t;
+	}
+	if (env.DSH_AGY_MCP_BRIDGE !== void 0) {
+		const b = asBool(env.DSH_AGY_MCP_BRIDGE);
+		if (b !== void 0) cfg.mcpBridge = b;
+	}
+	if (env.DSH_AGY_MCP_TOOL_ALLOWLIST) cfg.mcpToolAllowlist = env.DSH_AGY_MCP_TOOL_ALLOWLIST;
 	return cfg;
 }
 //#endregion
@@ -892,6 +917,104 @@ var StreamJsonParser = class {
 		return ev;
 	}
 };
+//#endregion
+//#region src/host/media.ts
+const EXT = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif"
+};
+/** Deterministic staged path: same session+turn+index reuses the file. */
+function stagedPath(dir, key, index, mediaType) {
+	const ext = EXT[mediaType] ?? "png";
+	return join(dir, key + "-" + String(index) + "." + ext);
+}
+/**
+* Stage up to `maxImages` images into `dir`, returning prompt lines that
+* reference them by absolute path. Deterministic names mean a retried or
+* replayed turn overwrites the same file instead of accumulating copies.
+*/
+async function stageImages(opts) {
+	const staged = [];
+	const lines = [];
+	let skipped = 0;
+	const budget = Math.max(0, opts.maxImages);
+	if (budget > 0 && opts.images.length > 0) {
+		await mkdir(opts.dir, { recursive: true });
+		let i = 0;
+		for (const ref of opts.images) {
+			if (staged.length >= budget) {
+				skipped += opts.images.length - staged.length - skipped;
+				break;
+			}
+			const label = ref.name ?? ref.attachmentId;
+			if (ref.bytes > opts.maxBytes) {
+				skipped++;
+				lines.push("[image skipped: \"" + label + "\" exceeds mediaMaxBytes]");
+				i++;
+				continue;
+			}
+			let data = null;
+			try {
+				data = await opts.readImage(ref);
+			} catch {
+				data = null;
+			}
+			if (!data) {
+				skipped++;
+				lines.push("[image unavailable: \"" + label + "\" could not be read from attachment storage]");
+				i++;
+				continue;
+			}
+			const path = stagedPath(opts.dir, opts.key, i, ref.mediaType);
+			await writeFile(path, data);
+			staged.push({
+				path,
+				name: label,
+				width: ref.width,
+				height: ref.height,
+				bytes: ref.bytes
+			});
+			lines.push("[image attached: \"" + label + "\" — view it with your file/vision tools at " + path + " (" + ref.width + "x" + ref.height + ", " + ref.bytes + " bytes)]");
+			i++;
+		}
+	}
+	return {
+		promptSuffix: lines.join("\n"),
+		staged,
+		skipped
+	};
+}
+/**
+* Delete staged files older than `ttlMs`. Returns the removed count.
+* Never throws: a failed sweep logs nothing and retries on the next pass.
+*/
+async function sweepDir(dir, ttlMs, now = Date.now()) {
+	if (ttlMs <= 0) return 0;
+	let removed = 0;
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch {
+		return 0;
+	}
+	for (const name of entries) {
+		const full = join(dir, name);
+		try {
+			const st = await stat(full);
+			if (st.isFile() && now - st.mtimeMs > ttlMs) {
+				await unlink(full);
+				removed++;
+			}
+		} catch {}
+	}
+	return removed;
+}
+/** Default media directory: <dsh home>/agy-link/media. */
+function defaultMediaDir(stateDir) {
+	return join(stateDir, "media");
+}
 function resolveAgyBin(cfg) {
 	const candidates = [];
 	if (cfg.agyBin !== "") candidates.push(cfg.agyBin);
@@ -1163,6 +1286,7 @@ var AgyAdapter = class extends LlmAdapter {
 		if (opts.model !== "") args.push("--model", opts.model);
 		if (opts.effort && opts.effort !== "") args.push("--effort", opts.effort);
 		if (opts.conversationId) args.push("--conversation", opts.conversationId);
+		for (const d of opts.addDirs ?? []) args.push("--add-dir", d);
 		args.push(...opts.extraArgs);
 		args.push("-p", opts.prompt);
 		return args;
@@ -1219,8 +1343,29 @@ var AgyAdapter = class extends LlmAdapter {
 				if (span.some((m) => m.role === "assistant")) prompt = buildDigest(span, 0, cfg.digestMaxChars) + prompt;
 			}
 		}
-		if (prompt.trim() === "") throw new LlmError("request carries no user text to forward to agy", Err.AGY_ERROR);
 		if (cfg.forwardSystemPrompt && options.system) prompt = "System instructions:\n" + options.system + "\n\n" + prompt;
+		let stagedDirs = [];
+		if (!isAux) {
+			const imageRefs = [];
+			for (const m of trailingUser) for (const b of m.content ?? []) {
+				const blk = b;
+				if (blk && blk.type === "image" && blk.attachment) imageRefs.push(blk.attachment);
+			}
+			if (imageRefs.length > 0 && this.deps.readImage) {
+				const dir = cfg.mediaDir !== "" ? cfg.mediaDir : defaultMediaDir(stateDir());
+				const res = await stageImages({
+					dir,
+					key: (sessionKey !== "" ? sessionKey.replace(/[^a-zA-Z0-9_-]+/g, "_") : "anon") + "-" + messages.length,
+					images: imageRefs,
+					readImage: this.deps.readImage,
+					maxImages: cfg.mediaMaxImages,
+					maxBytes: cfg.mediaMaxBytes
+				});
+				if (res.promptSuffix !== "") prompt = prompt === "" ? res.promptSuffix : prompt + "\n\n" + res.promptSuffix;
+				if (res.staged.length > 0) stagedDirs = [dir];
+			}
+			if (prompt.trim() === "") throw new LlmError("request carries no user text or images to forward to agy", Err.AGY_ERROR);
+		} else if (prompt.trim() === "") throw new LlmError("request carries no user text to forward to agy", Err.AGY_ERROR);
 		const before = snapshotConversations();
 		const mapper = new EventMapper({ toolOutput: this.deps.toolOutput });
 		const parser = new StreamJsonParser();
@@ -1234,7 +1379,8 @@ var AgyAdapter = class extends LlmAdapter {
 			conversationId: !isAux && binding !== void 0 ? binding.conversationId : void 0,
 			permissionMode: isAux ? "plan" : cfg.permissionMode,
 			timeoutMs: cfg.timeoutMs,
-			extraArgs: cfg.extraArgs
+			extraArgs: cfg.extraArgs,
+			addDirs: stagedDirs
 		});
 		const release = await this.deps.acquire();
 		let released = false;
@@ -1327,6 +1473,59 @@ var AgyAdapter = class extends LlmAdapter {
 };
 //#endregion
 //#region src/host/oneshot.ts
+/** Per-file inline cap; larger files are truncated. */
+const INLINE_MAX_BYTES = 262144;
+/** Text-detection: anything that is very likely not binary. */
+function looksTextual(head) {
+	if (head === "") return true;
+	let suspicious = 0;
+	const n = Math.min(head.length, 2e3);
+	for (let i = 0; i < n; i++) {
+		const c = head.charCodeAt(i);
+		if (c === 0 || c < 9 && c !== 0 || c > 13 && c < 32) suspicious++;
+	}
+	return suspicious / n < .05;
+}
+/**
+* Inline text files into the prompt (v0.2): each readable textual file
+* becomes a fenced section. Paths resolve against the oneshot cwd;
+* absolute paths pass through.
+*/
+async function inlineFiles(prompt, paths, cwd) {
+	if (paths.length === 0) return prompt;
+	const sections = [];
+	for (const raw of paths) {
+		const p = isAbsolute(raw) ? raw : resolve(cwd, raw);
+		let note = "";
+		let body = "";
+		try {
+			const buf = await readFile(p);
+			if (!looksTextual(buf.subarray(0, Math.min(buf.length, 4096)).toString("utf8"))) note = "(skipped: binary file - reference it by path and let agy read it with its own tools)";
+			else if (buf.byteLength > INLINE_MAX_BYTES) {
+				note = "(truncated to the first 262144 bytes)";
+				body = buf.subarray(0, INLINE_MAX_BYTES).toString("utf8");
+			} else body = buf.toString("utf8");
+		} catch {
+			note = "(skipped: unreadable - " + raw + ")";
+		}
+		sections.push("--- file: " + p + " " + note + " ---\n" + body);
+	}
+	return prompt + "\n\n" + sections.join("\n\n");
+}
+/** Write a JSON schema to a temp file; returns the --json-schema argv tail. */
+async function schemaArgs(schema) {
+	const text = JSON.stringify(schema);
+	const dir = await mkdtemp(join(tmpdir(), "agy-schema-"));
+	const file = join(dir, "schema.json");
+	await writeFile(file, text, "utf8");
+	return {
+		args: ["--json-schema", file],
+		cleanup: () => rm(dir, {
+			recursive: true,
+			force: true
+		})
+	};
+}
 async function runAgyOnce(deps, req) {
 	const cfg = deps.cfg();
 	const bin = deps.bin();
@@ -1349,7 +1548,15 @@ async function runAgyOnce(deps, req) {
 	else args.push("--mode", mode);
 	if (req.model) args.push("--model", req.model);
 	if (req.effort) args.push("--effort", req.effort);
-	args.push("-p", req.prompt);
+	let prompt = req.prompt;
+	if (req.readPaths && req.readPaths.length > 0) prompt = await inlineFiles(prompt, req.readPaths, cfg.workspaceRoot !== "" ? cfg.workspaceRoot : process.cwd());
+	let cleanup = null;
+	if (req.schema !== void 0 && req.schema !== null) {
+		const sa = await schemaArgs(req.schema);
+		args.push(...sa.args);
+		cleanup = sa.cleanup;
+	}
+	args.push("-p", prompt);
 	const parser = new StreamJsonParser();
 	const textParts = [];
 	let resultText = "";
@@ -1371,6 +1578,7 @@ async function runAgyOnce(deps, req) {
 			}
 		}
 	}).outcome;
+	if (cleanup) cleanup().catch(() => {});
 	for (const ev of parser.flush()) if (ev.kind === "result") {
 		if (ev.conversationId !== "") conversationId = ev.conversationId;
 		resultText = ev.response;
@@ -1484,6 +1692,14 @@ function defineAgyAskTool(deps) {
 			timeoutMinutes: {
 				type: "number",
 				description: "Optional timeout budget in minutes (default 10)."
+			},
+			readPaths: {
+				type: "string",
+				description: "Optional space/comma-separated text files to inline into the prompt (workspace-relative or absolute; binaries are skipped with a note)."
+			},
+			schema: {
+				type: "string",
+				description: "Optional JSON Schema (as a JSON string) enforcing the final answer via agy --json-schema."
 			}
 		},
 		output: {
@@ -1498,13 +1714,22 @@ function defineAgyAskTool(deps) {
 			exec.signal;
 			const cfg = deps.cfg();
 			const model = resolveAskModel(args.model ?? "", deps.catalog(), cfg.defaultModel);
+			let parsedSchema;
+			if (typeof args.schema === "string" && args.schema.trim() !== "") try {
+				parsedSchema = JSON.parse(args.schema);
+			} catch (e) {
+				throw new Error("agy_ask: schema is not valid JSON: " + String(e));
+			}
+			const readPaths = typeof args.readPaths === "string" && args.readPaths.trim() !== "" ? args.readPaths.split(/[ ,]+/).filter(Boolean) : [];
 			const res = await runAgyOnce(deps, {
 				prompt: args.prompt,
 				model: model === "" ? void 0 : model,
 				effort: args.effort,
 				mode: args.mode,
 				timeoutMs: args.timeoutMinutes ? args.timeoutMinutes * 6e4 : void 0,
-				signal: exec.signal
+				signal: exec.signal,
+				readPaths,
+				schema: parsedSchema
 			});
 			if (!res.ok) throw new Error("agy_ask failed: " + (res.error ?? "unknown error"));
 			const footer = res.conversationId ? "\n\n(agy conversation: " + res.conversationId + " — continue it with: agy --conversation " + res.conversationId + ")" : "";
@@ -1958,6 +2183,193 @@ function require$$basename(p) {
 	return i >= 0 ? p.slice(i + 1) : p;
 }
 //#endregion
+//#region src/host/mcp-bridge.ts
+const MCP_SERVER_KEY = "dsh-tools";
+/** MCP tool names are [a-zA-Z0-9_-]; DSH names may contain dots. */
+function toMcpName(name) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function readBody(req) {
+	return new Promise((resolve) => {
+		const chunks = [];
+		req.on("data", (c) => chunks.push(c));
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", () => resolve(""));
+	});
+}
+function sendJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Content-Length": Buffer.byteLength(text)
+	});
+	res.end(text);
+}
+/** Best-effort extraction of readable text from an execution result. */
+function resultText(result) {
+	if (result === null || result === void 0) return "";
+	const r = result;
+	if (Array.isArray(r.content)) {
+		const parts = [];
+		for (const b of r.content) {
+			const blk = b;
+			if (blk && blk.type === "text" && typeof blk.text === "string") parts.push(blk.text);
+		}
+		if (parts.length > 0) return parts.join("\n");
+	}
+	if (typeof r.text === "string") return r.text;
+	if (typeof r.output === "string") return r.output;
+	try {
+		return JSON.stringify(result, null, 2);
+	} catch {
+		return String(result);
+	}
+}
+/**
+* Start the loopback endpoint. Resolves once listening. The tools service
+* may arrive later (optional service): pass a thunk.
+*/
+function startMcpBridge(opts) {
+	const token = randomBytes(24).toString("hex");
+	let callSeq = 0;
+	const server = createServer((req, res) => {
+		(async () => {
+			const url = (req.url ?? "").split("?")[0];
+			if (String(req.headers["authorization"] ?? "") !== "Bearer " + token) {
+				sendJson(res, 401, { error: "unauthorized" });
+				return;
+			}
+			if ((req.method === "GET" || req.method === "POST") && (url === "/tools" || url === "/mcp/tools")) {
+				const svc = opts.tools();
+				if (!svc) {
+					sendJson(res, 503, { error: "tools service unavailable" });
+					return;
+				}
+				const allow = opts.allowlist().split(",").map((s) => s.trim()).filter(Boolean);
+				const allowSet = new Set(allow);
+				const seen = /* @__PURE__ */ new Set();
+				sendJson(res, 200, { tools: svc.schemas().filter((t) => allow.length === 0 || allowSet.has(t.name)).filter((t) => {
+					if (t.name === "run_code" || t.name === "agy_ask") return false;
+					const mapped = toMcpName(t.name);
+					if (seen.has(mapped)) return false;
+					seen.add(mapped);
+					return true;
+				}).map((t) => ({
+					name: toMcpName(t.name),
+					dshName: t.name,
+					description: t.description,
+					inputSchema: {
+						type: "object",
+						...t.parameters
+					}
+				})) });
+				return;
+			}
+			if (req.method === "POST" && (url === "/call" || url === "/mcp/call")) {
+				const body = await readBody(req);
+				let parsed = {};
+				try {
+					parsed = JSON.parse(body);
+				} catch {
+					sendJson(res, 400, { error: "invalid JSON" });
+					return;
+				}
+				const svc = opts.tools();
+				if (!svc) {
+					sendJson(res, 503, { error: "tools service unavailable" });
+					return;
+				}
+				const dshName = typeof parsed.dshName === "string" ? parsed.dshName : "";
+				if (dshName === "" || dshName === "run_code" || dshName === "agy_ask") {
+					sendJson(res, 400, { error: "bad tool name" });
+					return;
+				}
+				callSeq++;
+				try {
+					sendJson(res, 200, {
+						ok: true,
+						text: resultText(await svc.execute({
+							callId: "agy-mcp-" + callSeq,
+							name: dshName,
+							arguments: parsed.arguments ?? {}
+						}))
+					});
+				} catch (e) {
+					sendJson(res, 200, {
+						ok: false,
+						error: String(e)
+					});
+				}
+				return;
+			}
+			sendJson(res, 404, { error: "not found" });
+		})().catch(() => {
+			try {
+				sendJson(res, 500, { error: "internal" });
+			} catch {}
+		});
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const addr = server.address();
+			const port = typeof addr === "object" && addr !== null ? addr.port : 0;
+			opts.log?.("mcp bridge listening on 127.0.0.1:" + port);
+			resolve({
+				bridgeScript: opts.bridgeScript,
+				token,
+				url: "http://127.0.0.1:" + port,
+				port,
+				close: () => new Promise((done) => server.close(() => done()))
+			});
+		});
+	});
+}
+/**
+* Merge our server entry into the workspace .mcp.json. Returns a restore
+* function that puts the previous content back (or deletes the file we
+* created). Never throws.
+*/
+function writeMcpConfig(workspaceRoot, bridge) {
+	const file = join(workspaceRoot, ".mcp.json");
+	let previous = null;
+	try {
+		if (existsSync(file)) previous = readFileSync(file, "utf8");
+	} catch {
+		previous = null;
+	}
+	let root = {};
+	if (previous !== null) try {
+		const v = JSON.parse(previous);
+		if (v && typeof v === "object") root = v;
+	} catch {
+		root = {};
+	}
+	const servers = root.mcpServers && typeof root.mcpServers === "object" ? root.mcpServers : {};
+	servers[MCP_SERVER_KEY] = {
+		type: "stdio",
+		command: process.execPath,
+		args: [bridge.bridgeScript],
+		env: {
+			DSH_MCP_URL: bridge.url,
+			DSH_MCP_TOKEN: bridge.token
+		}
+	};
+	root.mcpServers = servers;
+	try {
+		writeFileSync(file, JSON.stringify(root, null, 2) + "\n", "utf8");
+	} catch {
+		return () => {};
+	}
+	return () => {
+		try {
+			if (previous === null) {
+				if (existsSync(file)) unlinkSync(file);
+			} else writeFileSync(file, previous, "utf8");
+		} catch {}
+	};
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-agy-link";
 const inject = ["llm", "commands"];
@@ -2036,6 +2448,15 @@ function apply(ctx, entryConfig = {}) {
 		},
 		onParser: (p) => {
 			lastParser = p;
+		},
+		readImage: async (ref) => {
+			const svc = ctx.attachments;
+			if (!svc || typeof svc.readImage !== "function") return null;
+			try {
+				return (await svc.readImage(ref))?.data ?? null;
+			} catch {
+				return null;
+			}
 		}
 	});
 	const setOverride = (key, value) => {
@@ -2275,9 +2696,54 @@ function apply(ctx, entryConfig = {}) {
 			}
 		});
 	}
+	const mediaDir = () => {
+		const cfg = getConfig();
+		return cfg.mediaDir !== "" ? cfg.mediaDir : defaultMediaDir(stateDir());
+	};
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			sweepDir(mediaDir(), getConfig().mediaTtlMs).catch(() => void 0);
+		}, Math.max(6e4, Math.min(getConfig().mediaTtlMs, 36e5)));
+		return () => clearInterval(timer);
+	});
+	const bridgeState = {
+		bridge: null,
+		restore: null
+	};
+	const syncMcpBridge = () => {
+		const cfg = getConfig();
+		const want = cfg.mcpBridge && cfg.enabled;
+		if (want && bridgeState.bridge === null) (async () => {
+			try {
+				const script = new URL("./bridge.mjs", import.meta.url).pathname;
+				const toolsSvc = ctx.get("tools");
+				const bridge = await startMcpBridge({
+					bridgeScript: script,
+					tools: () => ctx.get("tools"),
+					allowlist: () => getConfig().mcpToolAllowlist,
+					log
+				});
+				bridgeState.bridge = bridge;
+				const root = cfg.workspaceRoot !== "" ? cfg.workspaceRoot : process.cwd();
+				bridgeState.restore = writeMcpConfig(root, bridge);
+				log("mcp bridge ready at " + bridge.url + (toolsSvc ? "" : " (tools service not yet available)"));
+			} catch (e) {
+				log("mcp bridge failed to start: " + String(e));
+			}
+		})();
+		else if (!want && bridgeState.bridge !== null) {
+			bridgeState.restore?.();
+			bridgeState.bridge.close();
+			bridgeState.bridge = null;
+			bridgeState.restore = null;
+		}
+	};
+	syncMcpBridge();
 	ctx.effect(() => {
 		auth.dispose();
 		if (askToolDispose.current !== null) askToolDispose.current();
+		bridgeState.restore?.();
+		bridgeState.bridge?.close();
 		return () => void 0;
 	});
 }

package/docs/KNOWN-GAPS.md

@@ -4,13 +4,21 @@ Deliberate v1 boundaries and upstream-behavior notes.
 
 ## Not forwarded to agy
 
-- **Images / attachments** — agy print mode (`-p`) accepts text only.
-  Image blocks in DSH messages are skipped silently.
-- **DSH tools** — agy runs its own closed tool loop; DSH tool schemas are
-  not exported to it. The reverse direction (agy calling DSH tools over MCP)
-  is tracked as future work.
-- **Structured outputs** — `--json-schema` exists on agy but is not wired
-  through DSH tool-call generation in v1.
+- **Images as true multimodal blocks** - agy print mode (`-p`) has no image
+  input flag. Since v0.2 the bridge stages DSH image attachments to a local
+  media directory (`mediaDir`, TTL-swept) and references them by absolute
+  path in the prompt, granting `--add-dir` so agy can view them with its own
+  file/vision tools. Same approach as the pi extension.
+- **DSH tools to agy (reverse MCP bridge)** - available since v0.2 behind the
+  `mcpBridge` config flag (experimental): the plugin runs a loopback-only,
+  token-guarded HTTP endpoint and registers a zero-dependency stdio MCP
+  server (`dsh-tools`) in the workspace `.mcp.json` (merged in, restored on
+  disable). `run_code` and `agy_ask` are never bridged; `mcpToolAllowlist`
+  restricts the set further.
+- **Structured outputs** - `agy_ask` accepts a `schema` parameter (JSON
+  Schema as a JSON string) enforced via `--json-schema` since v0.2. Wiring
+  schema enforcement into DSH-native tool-call generation remains future
+  work: DSH `GenerateOptions` has no schema field to map onto.
 
 ## Mapping choices
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agy-link",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Google Antigravity (agy CLI) models for DeepSeek Harness — stream Gemini/Claude/GPT-OSS subscriptions into DSH with thinking, tool activity, token usage and in-GUI Google OAuth login.",
   "type": "module",
   "license": "MIT",