codsh-bundle 0.5.0 → 0.6.1

package/lib/index.js

@@ -1,12 +1,13 @@
-import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { copyFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, parse } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
+import { admitEncodedImages, isImageAdmissionError } from "@deepseek-ai/dsh-attachment";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import stringWidth from "string-width";
 import { readdirSync } from "node:fs";
 import { createInterface } from "node:readline";
@@ -795,6 +796,7 @@ const CONTROLS = {
 	"": { kind: "expand-output" },
 	"": { kind: "toggle-todos" },
 	"": { kind: "kill-input" },
+	"": { kind: "paste-image" },
 	"": { kind: "kill-word" }
 };
 /** Decodes terminal bytes into keys, holding partial sequences between reads. */
@@ -2225,6 +2227,158 @@ var TerminalConsole = class {
 	}
 };
 
+//#endregion
+//#region src/clipboard-image.ts
+/** The most a clipboard image may be; beyond this the read reports none. */
+const MAX_CLIPBOARD_IMAGE_BYTES = 64 * 1024 * 1024;
+/**
+* Run one command, capturing binary stdout.
+* @param command - the executable.
+* @param args - its arguments.
+* @returns stdout as bytes, or undefined on any failure or empty output.
+*/
+function run$1(command, args) {
+	return new Promise((resolve) => {
+		execFile(command, [...args], {
+			encoding: "buffer",
+			maxBuffer: MAX_CLIPBOARD_IMAGE_BYTES,
+			timeout: 1e4
+		}, (error, stdout) => {
+			if (error !== null || stdout.length === 0) resolve(void 0);
+			else resolve(stdout);
+		});
+	});
+}
+/**
+* What image type these bytes are, from their magic numbers.
+*
+* Sniffed rather than taken from the reader's word: the store verifies the
+* declared type against the decoded bytes and refuses a mismatch, so lying
+* here would only defer the failure to a worse moment.
+* @param data - the bytes.
+* @returns the media type, or undefined for anything that is not an image.
+*/
+function sniffImageType(data) {
+	if (data.length < 12) return void 0;
+	if (data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) return "image/png";
+	if (data[0] === 255 && data[1] === 216 && data[2] === 255) return "image/jpeg";
+	if (data[0] === 71 && data[1] === 73 && data[2] === 70 && data[3] === 56) return "image/gif";
+	if (data.subarray(0, 4).toString("latin1") === "RIFF" && data.subarray(8, 12).toString("latin1") === "WEBP") return "image/webp";
+}
+/** The clipboard's image on macOS: AppleScript writes the PNG to a file. */
+async function readDarwin() {
+	const dir = await mkdtemp(join(tmpdir(), "codsh-clip-"));
+	const file = join(dir, "clipboard.png");
+	try {
+		const script = [
+			"-e",
+			"set png_data to (the clipboard as «class PNGf»)",
+			"-e",
+			`set fp to open for access POSIX file "${file}" with write permission`,
+			"-e",
+			"write png_data to fp",
+			"-e",
+			"close access fp"
+		];
+		if (!await new Promise((resolve) => {
+			execFile("osascript", script, { timeout: 1e4 }, (error) => void resolve(error === null));
+		})) return void 0;
+		return await readFile(file).catch(() => void 0);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** The clipboard's image on Linux, Wayland first, X11 as the fallback. */
+async function readLinux(env) {
+	if (env.WAYLAND_DISPLAY !== void 0) {
+		const offered$1 = (await run$1("wl-paste", ["-l"]))?.toString("utf8").match(/image\/(?:png|jpeg|webp|gif)/u)?.[0];
+		if (offered$1 === void 0) return void 0;
+		return run$1("wl-paste", ["-t", offered$1]);
+	}
+	const offered = (await run$1("xclip", [
+		"-selection",
+		"clipboard",
+		"-t",
+		"TARGETS",
+		"-o"
+	]))?.toString("utf8").match(/image\/(?:png|jpeg|webp|gif)/u)?.[0];
+	if (offered === void 0) return void 0;
+	return run$1("xclip", [
+		"-selection",
+		"clipboard",
+		"-t",
+		offered,
+		"-o"
+	]);
+}
+/** The clipboard's image on Windows: PowerShell saves it as a PNG file. */
+async function readWin32() {
+	const dir = await mkdtemp(join(tmpdir(), "codsh-clip-"));
+	const file = join(dir, "clipboard.png");
+	try {
+		const script = `$img = Get-Clipboard -Format Image; if ($img) { $img.Save('${file.replaceAll("\\", "\\\\")}', [System.Drawing.Imaging.ImageFormat]::Png) }`;
+		if (!await new Promise((resolve) => {
+			execFile("powershell", [
+				"-NoProfile",
+				"-Command",
+				script
+			], { timeout: 1e4 }, (error) => void resolve(error === null));
+		})) return void 0;
+		return await readFile(file).catch(() => void 0);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Pixel dimensions from the image header, best effort.
+*
+* sharp decodes properly, but it is a native module and the flash line does
+* not justify failing a paste over it — an unreadable header simply reports
+* no dimensions.
+* @param data - the image bytes.
+* @returns width and height, or undefined.
+*/
+async function probeDimensions(data) {
+	try {
+		const { default: sharp } = await import("sharp");
+		const meta = await sharp(data).metadata();
+		if (typeof meta.width === "number" && typeof meta.height === "number") return {
+			width: meta.width,
+			height: meta.height
+		};
+		return;
+	} catch {
+		return;
+	}
+}
+/**
+* The image on the system clipboard, or undefined when it holds none.
+*
+* `CODSH_CLIPBOARD_IMAGE_CMD` overrides the platform reader with a shell
+* command whose stdout is the image bytes — the seam the tests use, exactly
+* as `CODSH_CLIPBOARD=osc52` keeps the write path off the real clipboard.
+* @param env - the environment, for the override and the display probes.
+* @returns the image with its sniffed type and dimensions, or undefined.
+*/
+async function readClipboardImage(env) {
+	const override = env.CODSH_CLIPBOARD_IMAGE_CMD;
+	const data = override !== void 0 && override !== "" ? await run$1(env.SHELL ?? "/bin/sh", ["-c", override]) : process.platform === "darwin" ? await readDarwin() : process.platform === "win32" ? await readWin32() : await readLinux(env);
+	if (data === void 0) return void 0;
+	const mediaType = sniffImageType(data);
+	if (mediaType === void 0) return void 0;
+	return {
+		data,
+		mediaType,
+		...await probeDimensions(data)
+	};
+}
+
 //#endregion
 //#region src/editor.ts
 /** Longest run of history the editor keeps for one session. */
@@ -2451,9 +2605,11 @@ var Editor = class {
 	backspace() {
 		if (this.column > 0) {
 			const cells = points(this.line());
-			cells.splice(this.column - 1, 1);
+			const token = /\[Image #\d+\]$/u.exec(cells.slice(0, this.column).join(""));
+			const width = token === null ? 1 : points(token[0]).length;
+			cells.splice(this.column - width, width);
 			this.setLine(cells.join(""));
-			this.column -= 1;
+			this.column -= width;
 		} else if (this.row > 0) {
 			const previous = this.lines[this.row - 1] ?? "";
 			const current = this.line();
@@ -2991,6 +3147,15 @@ var Prompt = class {
 	* not be lost; the queue is what a line reader provides for free.
 	*/
 	queued = [];
+	/** Images pasted into the box, by the number their `[Image #N]` token wears. */
+	pendingImages = /* @__PURE__ */ new Map();
+	/** Numbers are never reused within a session: a recalled token must not
+	* silently pick up a different image. */
+	imageCounter = 0;
+	/** The images belonging to the line the last read handed out. */
+	submittedImages = [];
+	/** Whether a clipboard read is already in flight; a second Ctrl+V waits. */
+	pastingImage = false;
 	/** The working indicator shown under the box. */
 	hint;
 	/** A short-lived notice that borrows the hint row, e.g. the copy toast. */
@@ -3150,7 +3315,10 @@ var Prompt = class {
 	read(signal) {
 		if (!this.console.readsKeys) return this.console.readLine(signal);
 		const typedAhead = this.queued.shift();
-		if (typedAhead !== void 0) return Promise.resolve(typedAhead);
+		if (typedAhead !== void 0) {
+			this.submittedImages = typedAhead.images;
+			return Promise.resolve(typedAhead.text);
+		}
 		if (this.console.finished) return Promise.resolve(void 0);
 		this.reading = true;
 		this.render();
@@ -3158,6 +3326,7 @@ var Prompt = class {
 			const settle = (text) => {
 				this.pending = void 0;
 				this.reading = false;
+				this.submittedImages = text === void 0 ? [] : this.claimImages(text);
 				resolve(text);
 			};
 			const onAbort = () => {
@@ -3297,12 +3466,19 @@ var Prompt = class {
 			this.render();
 			return;
 		}
+		if (key.kind === "paste-image") {
+			this.pasteImage();
+			return;
+		}
 		const action = this.editor.handle(key);
 		switch (action.kind) {
 			case "submit": {
 				const waiting = this.pending;
 				if (waiting === void 0) {
-					this.queued.push(action.text);
+					this.queued.push({
+						text: action.text,
+						images: this.claimImages(action.text)
+					});
 					break;
 				}
 				waiting.dispose();
@@ -3327,6 +3503,81 @@ var Prompt = class {
 		this.render();
 	}
 	/**
+	* Read the clipboard and attach its image behind an `[Image #N]` token.
+	*
+	* The read shells out and takes real time, so it runs off the key handler;
+	* a second Ctrl+V during it is dropped rather than raced. Numbers count up
+	* for the whole session — a token in a recalled line must never quietly
+	* name a different image than the one it was minted for.
+	*/
+	async pasteImage() {
+		const read = this.handlers.readClipboardImage;
+		if (read === void 0 || this.pastingImage) return;
+		this.pastingImage = true;
+		try {
+			const found = await read();
+			if (found === void 0) {
+				this.setFlash(this.theme.dim("  no image in the clipboard"));
+				return;
+			}
+			this.imageCounter += 1;
+			const id = this.imageCounter;
+			const pending = {
+				id,
+				image: {
+					mediaType: found.mediaType,
+					data: found.data.toString("base64"),
+					name: `Pasted image #${id}`
+				}
+			};
+			if (found.width !== void 0) pending.width = found.width;
+			if (found.height !== void 0) pending.height = found.height;
+			this.pendingImages.set(id, pending);
+			this.editor.handle({
+				kind: "paste",
+				text: `[Image #${id}]`
+			});
+			const size = found.width !== void 0 && found.height !== void 0 ? ` (${found.width}×${found.height} ${found.mediaType.slice(6)})` : "";
+			this.setFlash(this.theme.dim(`  ✓ image #${id} attached${size}`));
+		} finally {
+			this.pastingImage = false;
+			this.render();
+		}
+	}
+	/**
+	* The images a submitted line actually references, in token order.
+	*
+	* The tokens are the source of truth: a token the person deleted drops its
+	* image, a token duplicated by editing still names one attachment once.
+	* Claimed images leave the pending pool, so a token recalled from history
+	* later submits as plain text rather than resurrecting consumed bytes.
+	* @param text - the submitted line.
+	* @returns the referenced images, ready to ride the submission.
+	*/
+	claimImages(text) {
+		const images = [];
+		for (const match of text.matchAll(/\[Image #(\d+)\]/gu)) {
+			const id = Number(match[1]);
+			const pending = this.pendingImages.get(id);
+			if (pending === void 0) continue;
+			this.pendingImages.delete(id);
+			images.push(pending);
+		}
+		return images;
+	}
+	/**
+	* The images belonging to the line the last read returned.
+	*
+	* A drain, in the transcript's `take*` idiom: the caller reads the line,
+	* then takes its images exactly once.
+	* @returns the images in token order, empty for a plain line.
+	*/
+	takeAttachments() {
+		const images = this.submittedImages;
+		this.submittedImages = [];
+		return images;
+	}
+	/**
 	* The todo readout's rows: the one in flight, or the whole list once opened.
 	* @param columns - display columns available.
 	* @returns the rows, empty when no list is live.
@@ -3365,7 +3616,7 @@ var Prompt = class {
 			rows.push(...box.rows);
 		}
 		if (this.queued.length > 0) {
-			const preview = this.queued[0] ?? "";
+			const preview = this.queued[0]?.text ?? "";
 			const more = this.queued.length > 1 ? ` (+${this.queued.length - 1} more)` : "";
 			rows.push(this.theme.dim(truncate(`  ↳ queued: ${preview.split("\n")[0] ?? ""}${more}`, columns)));
 		}
@@ -3888,6 +4139,13 @@ var TerminalQuestions = class {
 * from idea to shipped, verified code — a research-grounded interview, a
 * confirmed spec (gate 1), an approved plan (gate 2), then autonomous landing
 * until the spec's acceptance criteria pass.
+*
+* The spec FILE is the workflow's memory, not the conversation: the approved
+* plan is written into it, its Status line names the phase, its checkboxes
+* are the progress, and a bare /ship offers to resume whatever it finds
+* unfinished. Conversations get interrupted, compacted, and cleared; the file
+* survives all three, which is what makes the landing reliable rather than
+* merely well-intentioned.
 */
 /** The `/ship` prompt body; `$ARGUMENTS` is the typed one-sentence requirement. */
 const SHIP_PROMPT = `Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:
@@ -3896,17 +4154,17 @@ const SHIP_PROMPT = `Run the /ship workflow: take the one-sentence requirement b
 $ARGUMENTS
 </idea>
 
-If the idea between the <idea> tags is empty, that is not an error: before anything else, ask for the one-sentence requirement with ask_user_question, and use the answer as the idea for the rest of this workflow.
+If the idea between the <idea> tags is empty, that is not an error. First look for unfinished work: scan the repository's spec directory (docs/specs/, or the repo's own design-document convention) for a spec whose Status line is not \`shipped\` — a bare /ship most likely means "carry on", so offer through ask_user_question to resume that spec from the phase its Status names, with everything below applying from that phase onward. Only when there is nothing to resume, ask for the one-sentence requirement with ask_user_question and use the answer as the idea. Images accompanying the command — [Image #N] tokens, <pasted-image> context, attached image blocks — are part of the requirement: a mockup or a screenshot is requirements material, so read it and cite what it shows in the interview.
 
 Phase 1 — grounded interview. Research before you ask: read the repository layout, the docs, and the code paths the idea touches, so every question is informed by what actually exists. Then interrogate the idea with ask_user_question, one focused question per call, never a batch. Cover, as far as they are genuinely open: who this is for and what success looks like, scope and explicit non-goals, constraints (compatibility, performance, security, dependencies), edge cases and failure behavior, and how the result should be verified. Prefer concrete options grounded in what you found over open-ended prompts. Do not ask what inspection can answer — where code lives or how current behavior works is yours to find out. Stop when answers stop changing the design; do not pad the interview to look thorough.
 
-Phase 2 — the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion is objectively checkable — named tests, commands with expected output, observable behavior. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.
+Phase 2 — the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion names the exact command that proves it and the output that counts as passing — the final phase runs those commands verbatim, so a criterion without a command is not finished. Give the file a \`Status:\` line (interviewing, confirmed, planned, landing, shipped) and keep it current at every phase change: it is what lets an interrupted /ship resume instead of starting over. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.
 
-Phase 3 — the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Write no implementation code before this gate passes, and do not use todo_write before it either — it tracks landing, not the interview.
+Phase 3 — the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Once approved, write the plan into the spec file as a \`## Plan\` section with one checkbox per milestone — an approved plan lives on disk, not in a conversation that can be compacted or lost. Then, still before any implementation code, establish the ground: check the working tree is clean (uncommitted unrelated changes are the user's to decide about — ask), and run the plan's proof commands once, recording the baseline in the spec. A baseline that is already red changes what "green" will mean, so surface it here rather than discovering it under your own diff. Write no implementation code before this gate passes, and do not use todo_write before it either — it tracks landing, not the interview.
 
-Phase 4 — landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, and fix until green before moving on. If it is larger — four or more substantially independent milestones, or work you expect to exceed what one session can hold — the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the durable source of truth, instructs each round to read the spec and plan from disk, pick up the next unfinished milestone, implement and test it, and record progress in the workspace, and defines completion as every acceptance criterion in the spec passing.
+Phase 4 — landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Either way the spec file — not this conversation — is the working memory: re-read it before starting each milestone, tick the milestone's checkbox and update Status as you go, and commit after each milestone turns green — small commits are the progress that survives a crash and the history a reviewer can walk. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, fix until green, then commit before moving on. If it is larger — four or more substantially independent milestones, or work you expect to exceed what one session can hold — the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the single source of truth, instructs each round to read the spec from disk (plan, checkboxes, baseline), pick the first unchecked milestone, implement and test it, then commit and tick its checkbox, and defines completion as every acceptance criterion in the spec passing. Bound the loop: budget about three rounds per milestone, and instruct it to stop and report rather than continue past two consecutive rounds that tick nothing.
 
-Phase 5 — done means verified. The workflow ends only when every acceptance criterion passes with you actually running the named tests and commands and reading their real output. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Close with a short honest report: what shipped, what was verified and how, and anything left open.
+Phase 5 — done means verified. The workflow ends only when every acceptance criterion passes with you actually running its named command and reading the real output. After a Ralph loop returns, run every proof command again yourself — the loop's word is a report, not a verification. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Set Status to shipped only after that final run, and close with an honest report listing each criterion, the command that proved it, and what it printed — plus anything left open.
 
 If the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.`;
 
@@ -3994,6 +4252,166 @@ var Spinner = class {
 	}
 };
 
+//#endregion
+//#region src/vision.ts
+/** How long one description may take before the paste falls back to file-only. */
+const VISION_TIMEOUT_MS = 3e4;
+/**
+* The one instruction the sidecar gets.
+*
+* It is the eyes for a model that has none, so completeness beats brevity and
+* verbatim beats summary: a truncated error message or a paraphrased line of
+* code is exactly the part the coding agent needed.
+*/
+const VISION_PROMPT = "You are the eyes for a text-only coding agent. Describe this image precisely and completely. Transcribe ALL visible text, code, commands, error messages, numbers and labels verbatim. When it shows a UI, terminal, diagram or chart, describe its structure and layout so the agent can reason about it. Do not speculate beyond what is visible.";
+/**
+* The sidecar from the environment, or undefined when none is configured.
+* @param env - the process environment.
+* @returns the config when both the base URL and the model are set.
+*/
+function visionConfigFromEnv(env) {
+	const baseUrl = env.CODSH_VISION_BASE_URL;
+	const model = env.CODSH_VISION_MODEL;
+	if (baseUrl === void 0 || baseUrl === "" || model === void 0 || model === "") return void 0;
+	const config = {
+		baseUrl: baseUrl.replace(/\/$/u, ""),
+		model
+	};
+	const key = env.CODSH_VISION_API_KEY;
+	if (key !== void 0 && key !== "") config.apiKey = key;
+	return config;
+}
+/**
+* Ask the sidecar what an image shows.
+* @param image - the encoded image.
+* @param config - which endpoint and model to ask.
+* @param signal - cancels the request, on top of the built-in timeout.
+* @returns the description.
+* @throws on timeout, a non-2xx answer, or an answer with no text.
+*/
+async function describeImage(image, config, signal) {
+	const timeout = AbortSignal.timeout(VISION_TIMEOUT_MS);
+	const response = await fetch(`${config.baseUrl}/chat/completions`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...config.apiKey === void 0 ? {} : { authorization: `Bearer ${config.apiKey}` }
+		},
+		body: JSON.stringify({
+			model: config.model,
+			messages: [{
+				role: "user",
+				content: [{
+					type: "image_url",
+					image_url: { url: `data:${image.mediaType};base64,${image.data}` }
+				}, {
+					type: "text",
+					text: VISION_PROMPT
+				}]
+			}]
+		}),
+		signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout])
+	});
+	if (!response.ok) throw new Error(`vision endpoint answered ${response.status}`);
+	const text = (await response.json()).choices?.[0]?.message?.content?.trim();
+	if (text === void 0 || text === "") throw new Error("vision endpoint answered without text");
+	return text;
+}
+/**
+* The upstream store's default admission limits, for use when no store is
+* mounted: the sidecar payload is bounded by the same line either way.
+*/
+const DEFAULT_IMAGE_LIMITS = {
+	maxImageBytes: 3.5 * 1024 * 1024,
+	maxImagesPerMessage: 20,
+	maxMessageImageBytes: 100 * 1024 * 1024,
+	maxImagePixels: 4e7,
+	maxImageDimension: 2e3,
+	mediaTypes: [
+		"image/png",
+		"image/jpeg",
+		"image/webp",
+		"image/gif"
+	]
+};
+/** File extension per media type, for the saved copy's name. */
+const EXTENSIONS = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif"
+};
+/**
+* Save a pasted image where the agent's tools can reach it.
+*
+* The original bytes, never a downscaled copy — the person may want the asset
+* itself committed. Content-addressed under the dsh home so a repeated paste
+* dedupes, nothing lands in the workspace uninvited, and the path stays valid
+* for `--resume`.
+* @param image - the encoded image.
+* @returns the absolute path of the saved file.
+*/
+async function savePastedImage(image) {
+	const data = Buffer.from(image.data, "base64");
+	const digest = createHash("sha256").update(data).digest("hex").slice(0, 12);
+	const dir = dshHomePath("attachments", "pasted");
+	await mkdir(dir, { recursive: true });
+	const path = join(dir, `${digest}.${EXTENSIONS[image.mediaType]}`);
+	await writeFile(path, data);
+	return path;
+}
+/**
+* The context block a pasted image contributes on a text-only route.
+*
+* The same XMLish convention the `!` passthrough uses: the model reads the
+* path (its tools can open the file), the dimensions, and — when the sidecar
+* ran — the description standing in for sight.
+* @param id - the `[Image #N]` number the person's text references.
+* @param image - the encoded image.
+* @param at - where the file was saved and what is known about it.
+* @returns the block text.
+*/
+function pastedImageBlock(id, image, at) {
+	const size = at.width !== void 0 && at.height !== void 0 ? ` dimensions="${at.width}x${at.height}"` : "";
+	const body = at.description === void 0 ? "" : `\n<description>\n${at.description}\n</description>`;
+	return `<pasted-image id="${id}" media="${image.mediaType}"${size} path="${at.path}">${body}\n</pasted-image>`;
+}
+/**
+* Shrink an image until the attachment store will admit it.
+*
+* Retina screenshots exceed the deployed routes' 2000-pixel side limit as a
+* matter of course, and refusing them would make the feature useless on the
+* machines most likely to use it. The downscale re-encodes as PNG; a copy
+* still over the byte limit falls back to JPEG, which is what a photograph
+* that big actually is.
+* @param image - the encoded image.
+* @param limits - the store's admission limits.
+* @returns the image, downscaled only when it had to be.
+*/
+async function fitWithinLimits(image, limits) {
+	const data = Buffer.from(image.data, "base64");
+	const { default: sharp } = await import("sharp");
+	const meta = await sharp(data).metadata();
+	if (!(Math.max(meta.width ?? 0, meta.height ?? 0) > limits.maxImageDimension || data.length > limits.maxImageBytes || (meta.width ?? 0) * (meta.height ?? 0) > limits.maxImagePixels)) return image;
+	const png = await sharp(data).resize({
+		width: limits.maxImageDimension,
+		height: limits.maxImageDimension,
+		fit: "inside",
+		withoutEnlargement: true
+	}).png().toBuffer();
+	if (png.length <= limits.maxImageBytes) return {
+		...image,
+		mediaType: "image/png",
+		data: png.toString("base64")
+	};
+	const jpeg = await sharp(png).jpeg({ quality: 80 }).toBuffer();
+	return {
+		...image,
+		mediaType: "image/jpeg",
+		data: jpeg.toString("base64")
+	};
+}
+
 //#endregion
 //#region src/streaming.ts
 /** Accumulates assistant text deltas into rendered lines. */
@@ -4088,6 +4506,32 @@ function visibleText(content) {
 	return content.filter((block) => block.type === "text").map((block) => block.text).join("");
 }
 /**
+* One dim line per image a user message carried, in place of pixels.
+*
+* An image block's bytes cannot render here, and a `<pasted-image>` context
+* block is the pipeline talking to the model — pages of description would
+* bury the words the person typed. Either becomes a line saying what rode
+* along and what became of it.
+* @param content - the message's blocks.
+* @param theme - styling for the meta lines.
+* @returns the lines, empty for a text-only message.
+*/
+function imageMetaLines(content, theme) {
+	const lines = [];
+	for (const block of content) if (block.type === "image") {
+		const { width, height, mediaType } = block.attachment;
+		lines.push(theme.dim(`  [image · ${width}×${height} ${mediaType.slice(6)} · sent to the model]`));
+	} else if (block.type === "text" && block.text.startsWith("<pasted-image ")) {
+		const id = /id="(\d+)"/u.exec(block.text)?.[1] ?? "?";
+		const dims = /dimensions="(\d+)x(\d+)"/u.exec(block.text);
+		const media = /media="image\/(\w+)"/u.exec(block.text)?.[1] ?? "image";
+		const size = dims === null ? "" : ` · ${dims[1]}×${dims[2]}`;
+		const fate = block.text.includes("<description>") ? "described" : "saved to file";
+		lines.push(theme.dim(`  [image #${id}${size} ${media} · ${fate}]`));
+	}
+	return lines;
+}
+/**
 * The left rules the transcript draws down a block's edge, one per kind.
 *
 * A rule is how a segment shows where it starts and ends without a frame or a
@@ -4261,10 +4705,12 @@ var Transcript = class {
 			case "user/message": {
 				if (event.data.source.kind !== "user") return [];
 				this.rule = rules.user;
-				const [first = "", ...rest] = visibleText(event.data.content).split("\n");
+				const [first = "", ...rest] = event.data.content.filter((block) => block.type === "text").filter((block) => !block.text.startsWith("<pasted-image ")).map((block) => block.text).join("").split("\n");
+				const meta = imageMetaLines(event.data.content, theme);
 				return [
 					`${theme.user("›")} ${first}`,
 					...rest.map((line) => `  ${line}`),
+					...meta,
 					""
 				];
 			}
@@ -4656,20 +5102,16 @@ function replay(session, transcript, io, theme) {
 		if (summary !== void 0) io.console.foldRecent(lines.length, summary, FOLD_LABELS.answer);
 	}
 }
-/**
-* Run one conversation turn and wait for the agent to go idle.
-* @param agent - the live agent.
-* @param text - the person's message.
-* @param working - the indicator to run while the turn does.
-* @param source - the message source; a canned prompt is plugin-sourced so the
-*   transcript echoes the command that ran it, not its whole body.
-*/
-async function turn(agent, text, working, source = { kind: "user" }) {
+async function turn(agent, text, working, source = { kind: "user" }, extra) {
 	agent.followup(createUserMessage({
-		content: [{
-			type: "text",
-			text
-		}],
+		content: [
+			...extra?.leading ?? [],
+			{
+				type: "text",
+				text
+			},
+			...extra?.trailing ?? []
+		],
 		source
 	}));
 	working?.start();
@@ -4688,7 +5130,7 @@ async function turn(agent, text, working, source = { kind: "user" }) {
 * @param theme - styling for the command's report.
 * @param signal - cancels the command when the person interrupts.
 */
-async function runCommand(ctx, agent, line, io, theme, signal) {
+async function runCommand(ctx, agent, line, io, theme, signal, images = []) {
 	const commands = ctx.get("commands");
 	if (commands === void 0) {
 		io.console.write(theme.error("  commands are unavailable in this composition"));
@@ -4701,7 +5143,7 @@ async function runCommand(ctx, agent, line, io, theme, signal) {
 		io.console.write("");
 		return;
 	}
-	const execution = await commands.execute(agent, line, [], signal);
+	const execution = await commands.execute(agent, line, images, signal);
 	if (execution === void 0) {
 		io.console.write(theme.error(`  unknown command: ${line}`));
 		return;
@@ -4918,11 +5360,33 @@ async function run(ctx, config, io) {
 		}))).flat().map((entry) => ({
 			provider: entry.provider,
 			id: entry.id,
-			name: entry.name
+			name: entry.name,
+			...entry.inputModalities === void 0 ? {} : { inputModalities: entry.inputModalities }
 		}));
 	};
 	refreshModelCatalog();
 	/**
+	* Whether the current route explicitly accepts image input.
+	*
+	* Exact-model metadata, not the advisory catalog, owns this decision. The
+	* catalog is fetched in the background and can be empty or stale while a
+	* saved route is already usable. The same explicit-true test the adapter
+	* applies before throwing UNSUPPORTED_CONTENT remains fail-closed: absent
+	* modalities or a failed resolution get the text fallback, which degrades,
+	* where the block path would crash the turn.
+	*/
+	const routeAcceptsImages = async () => {
+		const current = selection.current;
+		if (current === void 0) return false;
+		const llm = ctx.get("llm");
+		if (llm === void 0) return false;
+		try {
+			return (await llm.resolveModelInfo(current.provider, current.model)).inputModalities?.includes("image") === true;
+		} catch {
+			return false;
+		}
+	};
+	/**
 	* Resolve a /model argument to a selection.
 	* @param typed - a bare model id, or an explicit `provider/model`.
 	* @returns the selection, or an error message naming what is available.
@@ -5036,7 +5500,8 @@ async function run(ctx, config, io) {
 		},
 		expandOutput: () => {
 			if (!io.console.toggleFolds()) prompt.write(theme.dim("  nothing to expand"));
-		}
+		},
+		readClipboardImage: () => readClipboardImage(process.env)
 	}, "Ask anything · / for commands · @ for files · ⇧Tab plan mode");
 	let turnBaseTokens = 0;
 	const spinner = new Spinner({
@@ -5497,13 +5962,70 @@ async function run(ctx, config, io) {
 	* than only in the status line.
 	* @param text - the person's message.
 	*/
-	const answer = async (text, source) => {
+	/**
+	* Turn pasted images into what this turn's message can carry.
+	*
+	* Three exits, decided by the route. An image-capable model gets the images
+	* as first-class blocks through the durable store — the runtime's own path.
+	* A text-only model gets each image saved as a file plus, when the vision
+	* sidecar is configured, a description standing in for sight; both ride the
+	* same message so they persist for `--resume`. A failure never loses the
+	* turn: it flashes, and the text still goes.
+	* @param images - the submission's pasted images, in token order.
+	* @returns blocks around the text, or undefined when there is nothing extra.
+	*/
+	const prepareImages = async (images) => {
+		if (images.length === 0) return void 0;
+		const store = ctx.get("attachments");
+		const limits = store?.imageLimits ?? DEFAULT_IMAGE_LIMITS;
+		if (await routeAcceptsImages() && store !== void 0) try {
+			return {
+				leading: (await admitEncodedImages(store, await Promise.all(images.map((pending) => fitWithinLimits(pending.image, limits))))).map((attachment) => ({
+					type: "image",
+					attachment
+				})),
+				trailing: []
+			};
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			prompt.setFlash(theme.error(truncate(`  image dropped: ${reason}`, io.console.columns)));
+			if (!isImageAdmissionError(error)) return void 0;
+		}
+		const vision = visionConfigFromEnv(process.env);
+		const trailing = [];
+		for (const pending of images) {
+			const at = { path: await savePastedImage(pending.image) };
+			if (pending.width !== void 0) at.width = pending.width;
+			if (pending.height !== void 0) at.height = pending.height;
+			if (vision !== void 0) {
+				prompt.setHint(theme.dim(`  ✻ describing image #${pending.id} with ${vision.model}…`));
+				try {
+					at.description = await describeImage(await fitWithinLimits(pending.image, limits), vision);
+				} catch (error) {
+					const reason = error instanceof Error ? error.message : String(error);
+					prompt.setFlash(theme.error(truncate(`  image #${pending.id}: description failed (${reason}) — attached as file only`, io.console.columns)));
+				} finally {
+					prompt.setHint(void 0);
+				}
+			}
+			trailing.push({
+				type: "text",
+				text: pastedImageBlock(pending.id, pending.image, at)
+			});
+		}
+		return {
+			leading: [],
+			trailing
+		};
+	};
+	const answer = async (text, source, images = []) => {
+		const extra = await prepareImages(images);
 		const before = totalTokens(facts(branch).usage) ?? 0;
 		turnBaseTokens = before;
 		const started = performance.now();
 		io.console.setTitle(`⚡ dsh code — ${basename(cwd)}`);
 		try {
-			await turn(live.agent, text, spinner, source);
+			await turn(live.agent, text, spinner, source, extra);
 		} finally {
 			io.console.setTitle(`dsh code — ${basename(cwd)}`);
 		}
@@ -5581,11 +6103,13 @@ async function run(ctx, config, io) {
 		}
 		const line = await prompt.read();
 		if (line === void 0) break;
+		const images = prompt.takeAttachments();
 		io.console.collapseFolds();
 		const trimmed = line.trim();
 		if (trimmed === "") continue;
 		if (trimmed === "/exit" || trimmed === "/quit") break;
 		if (trimmed.startsWith("!")) {
+			if (images.length > 0) prompt.setFlash(theme.dim("  images do not ride ! commands — send them with a prompt"));
 			const command = trimmed.slice(1).trim();
 			if (command !== "") await passthrough(command);
 			continue;
@@ -5597,14 +6121,14 @@ async function run(ctx, config, io) {
 				await answer(INIT_PROMPT, {
 					kind: "plugin",
 					plugin: "coding-cli"
-				});
+				}, images);
 				continue;
 			}
 			if (name$1 === "ship") {
 				await answer(expandTemplate(SHIP_PROMPT, rest.trim()), {
 					kind: "plugin",
 					plugin: "coding-cli"
-				});
+				}, images);
 				continue;
 			}
 			const canned = customByName.get(name$1);
@@ -5612,18 +6136,23 @@ async function run(ctx, config, io) {
 				await answer(expandTemplate(canned.template, rest.trim()), {
 					kind: "plugin",
 					plugin: "coding-cli"
-				});
+				}, images);
 				continue;
 			}
+			let batch = [];
+			if (images.length > 0) if (await routeAcceptsImages()) {
+				const limits = ctx.get("attachments")?.imageLimits ?? DEFAULT_IMAGE_LIMITS;
+				batch = await Promise.all(images.map((pending) => fitWithinLimits(pending.image, limits)));
+			} else prompt.setFlash(theme.error("  this model does not accept images with commands — they were dropped"));
 			running = new AbortController();
 			try {
-				await runCommand(ctx, live.agent, trimmed, io, theme, running.signal);
+				await runCommand(ctx, live.agent, trimmed, io, theme, running.signal, batch);
 			} finally {
 				running = void 0;
 			}
 			continue;
 		}
-		await answer(trimmed);
+		await answer(trimmed, void 0, images);
 	}
 	await sessions.flush(live.agent.session);
 	try {

package/lib/types/clipboard-image.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Reading an image off the system clipboard.
+ *
+ * An image never arrives through the terminal: bracketed paste is text by
+ * construction, and a screenshot sitting on the clipboard has no byte channel
+ * into stdin at all. So — exactly as Claude Code does — Ctrl+V asks the
+ * platform for the clipboard's image directly: `osascript` on macOS,
+ * `wl-paste`/`xclip` on Linux, PowerShell on Windows. A machine without the
+ * helper, or a clipboard holding text, reads as "no image" rather than an
+ * error, the same silent tolerance the clipboard WRITE path has.
+ * @module codsh-bundle/src/clipboard-image
+ */
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment/types';
+/** An image read off the clipboard, plus what the flash line wants to say. */
+export interface ClipboardImage {
+    /** The raw bytes. */
+    data: Buffer;
+    /** The type the bytes actually are, sniffed rather than trusted. */
+    mediaType: ImageMediaType;
+    /** Pixel width, when the header could be read. */
+    width?: number;
+    /** Pixel height, when the header could be read. */
+    height?: number;
+}
+/**
+ * What image type these bytes are, from their magic numbers.
+ *
+ * Sniffed rather than taken from the reader's word: the store verifies the
+ * declared type against the decoded bytes and refuses a mismatch, so lying
+ * here would only defer the failure to a worse moment.
+ * @param data - the bytes.
+ * @returns the media type, or undefined for anything that is not an image.
+ */
+export declare function sniffImageType(data: Buffer): ImageMediaType | undefined;
+/**
+ * The image on the system clipboard, or undefined when it holds none.
+ *
+ * `CODSH_CLIPBOARD_IMAGE_CMD` overrides the platform reader with a shell
+ * command whose stdout is the image bytes — the seam the tests use, exactly
+ * as `CODSH_CLIPBOARD=osc52` keeps the write path off the real clipboard.
+ * @param env - the environment, for the override and the display probes.
+ * @returns the image with its sniffed type and dimensions, or undefined.
+ */
+export declare function readClipboardImage(env: Record<string, string | undefined>): Promise<ClipboardImage | undefined>;

package/lib/types/keys.d.ts

@@ -71,6 +71,8 @@ export type Key = {
 } | {
     kind: 'paste';
     text: string;
+} | {
+    kind: 'paste-image';
 } | {
     kind: 'mouse-down';
     row: number;

package/lib/types/prompt.d.ts

@@ -8,6 +8,8 @@
  * pipe and draws nothing. Callers ask for the next submission either way.
  * @module codsh-bundle/src/prompt
  */
+import type { EncodedImageAttachment } from '@deepseek-ai/dsh-attachment/types';
+import type { ClipboardImage } from './clipboard-image.ts';
 import type { TerminalConsole } from './console.ts';
 import type { EditorSources } from './editor.ts';
 import type { SelectOutcome, SelectSpec } from './selector.ts';
@@ -25,6 +27,27 @@ export interface PromptHandlers {
     shiftTab?(): void;
     /** Ctrl-O: show the last clipped tool output in full. */
     expandOutput?(): void;
+    /**
+     * Ctrl-V: the system clipboard's image, or undefined for none.
+     *
+     * Injected rather than imported so the pure-module tests can hand the
+     * prompt a fixture instead of a machine's clipboard.
+     */
+    readClipboardImage?(): Promise<ClipboardImage | undefined>;
+}
+/**
+ * One pasted image awaiting its submission.
+ *
+ * The wire form the runtime admits, plus the dimensions the paste already
+ * probed — the submission pipeline says them back without re-decoding.
+ */
+export interface PendingImage {
+    /** The number the `[Image #N]` token wears, for context that names it back. */
+    id: number;
+    /** Base64 bytes and their sniffed media type. */
+    image: EncodedImageAttachment;
+    width?: number;
+    height?: number;
 }
 /** Drives the input box and answers reads and selections. */
 export declare class Prompt {
@@ -43,6 +66,15 @@ export declare class Prompt {
      * not be lost; the queue is what a line reader provides for free.
      */
     private readonly queued;
+    /** Images pasted into the box, by the number their `[Image #N]` token wears. */
+    private readonly pendingImages;
+    /** Numbers are never reused within a session: a recalled token must not
+     * silently pick up a different image. */
+    private imageCounter;
+    /** The images belonging to the line the last read handed out. */
+    private submittedImages;
+    /** Whether a clipboard read is already in flight; a second Ctrl+V waits. */
+    private pastingImage;
     /** The working indicator shown under the box. */
     private hint;
     /** A short-lived notice that borrows the hint row, e.g. the copy toast. */
@@ -164,6 +196,34 @@ export declare class Prompt {
      * @param key - the decoded keystroke.
      */
     private onKey;
+    /**
+     * Read the clipboard and attach its image behind an `[Image #N]` token.
+     *
+     * The read shells out and takes real time, so it runs off the key handler;
+     * a second Ctrl+V during it is dropped rather than raced. Numbers count up
+     * for the whole session — a token in a recalled line must never quietly
+     * name a different image than the one it was minted for.
+     */
+    private pasteImage;
+    /**
+     * The images a submitted line actually references, in token order.
+     *
+     * The tokens are the source of truth: a token the person deleted drops its
+     * image, a token duplicated by editing still names one attachment once.
+     * Claimed images leave the pending pool, so a token recalled from history
+     * later submits as plain text rather than resurrecting consumed bytes.
+     * @param text - the submitted line.
+     * @returns the referenced images, ready to ride the submission.
+     */
+    private claimImages;
+    /**
+     * The images belonging to the line the last read returned.
+     *
+     * A drain, in the transcript's `take*` idiom: the caller reads the line,
+     * then takes its images exactly once.
+     * @returns the images in token order, empty for a plain line.
+     */
+    takeAttachments(): PendingImage[];
     /**
      * The todo readout's rows: the one in flight, or the whole list once opened.
      * @param columns - display columns available.

package/lib/types/ship.d.ts

@@ -3,6 +3,13 @@
  * from idea to shipped, verified code — a research-grounded interview, a
  * confirmed spec (gate 1), an approved plan (gate 2), then autonomous landing
  * until the spec's acceptance criteria pass.
+ *
+ * The spec FILE is the workflow's memory, not the conversation: the approved
+ * plan is written into it, its Status line names the phase, its checkboxes
+ * are the progress, and a bare /ship offers to resume whatever it finds
+ * unfinished. Conversations get interrupted, compacted, and cleared; the file
+ * survives all three, which is what makes the landing reliable rather than
+ * merely well-intentioned.
  */
 /** The `/ship` prompt body; `$ARGUMENTS` is the typed one-sentence requirement. */
-export declare const SHIP_PROMPT = "Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:\n\n<idea>\n$ARGUMENTS\n</idea>\n\nIf the idea between the <idea> tags is empty, that is not an error: before anything else, ask for the one-sentence requirement with ask_user_question, and use the answer as the idea for the rest of this workflow.\n\nPhase 1 \u2014 grounded interview. Research before you ask: read the repository layout, the docs, and the code paths the idea touches, so every question is informed by what actually exists. Then interrogate the idea with ask_user_question, one focused question per call, never a batch. Cover, as far as they are genuinely open: who this is for and what success looks like, scope and explicit non-goals, constraints (compatibility, performance, security, dependencies), edge cases and failure behavior, and how the result should be verified. Prefer concrete options grounded in what you found over open-ended prompts. Do not ask what inspection can answer \u2014 where code lives or how current behavior works is yours to find out. Stop when answers stop changing the design; do not pad the interview to look thorough.\n\nPhase 2 \u2014 the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion is objectively checkable \u2014 named tests, commands with expected output, observable behavior. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.\n\nPhase 3 \u2014 the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Write no implementation code before this gate passes, and do not use todo_write before it either \u2014 it tracks landing, not the interview.\n\nPhase 4 \u2014 landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, and fix until green before moving on. If it is larger \u2014 four or more substantially independent milestones, or work you expect to exceed what one session can hold \u2014 the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the durable source of truth, instructs each round to read the spec and plan from disk, pick up the next unfinished milestone, implement and test it, and record progress in the workspace, and defines completion as every acceptance criterion in the spec passing.\n\nPhase 5 \u2014 done means verified. The workflow ends only when every acceptance criterion passes with you actually running the named tests and commands and reading their real output. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Close with a short honest report: what shipped, what was verified and how, and anything left open.\n\nIf the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.";
+export declare const SHIP_PROMPT = "Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:\n\n<idea>\n$ARGUMENTS\n</idea>\n\nIf the idea between the <idea> tags is empty, that is not an error. First look for unfinished work: scan the repository's spec directory (docs/specs/, or the repo's own design-document convention) for a spec whose Status line is not `shipped` \u2014 a bare /ship most likely means \"carry on\", so offer through ask_user_question to resume that spec from the phase its Status names, with everything below applying from that phase onward. Only when there is nothing to resume, ask for the one-sentence requirement with ask_user_question and use the answer as the idea. Images accompanying the command \u2014 [Image #N] tokens, <pasted-image> context, attached image blocks \u2014 are part of the requirement: a mockup or a screenshot is requirements material, so read it and cite what it shows in the interview.\n\nPhase 1 \u2014 grounded interview. Research before you ask: read the repository layout, the docs, and the code paths the idea touches, so every question is informed by what actually exists. Then interrogate the idea with ask_user_question, one focused question per call, never a batch. Cover, as far as they are genuinely open: who this is for and what success looks like, scope and explicit non-goals, constraints (compatibility, performance, security, dependencies), edge cases and failure behavior, and how the result should be verified. Prefer concrete options grounded in what you found over open-ended prompts. Do not ask what inspection can answer \u2014 where code lives or how current behavior works is yours to find out. Stop when answers stop changing the design; do not pad the interview to look thorough.\n\nPhase 2 \u2014 the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion names the exact command that proves it and the output that counts as passing \u2014 the final phase runs those commands verbatim, so a criterion without a command is not finished. Give the file a `Status:` line (interviewing, confirmed, planned, landing, shipped) and keep it current at every phase change: it is what lets an interrupted /ship resume instead of starting over. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.\n\nPhase 3 \u2014 the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Once approved, write the plan into the spec file as a `## Plan` section with one checkbox per milestone \u2014 an approved plan lives on disk, not in a conversation that can be compacted or lost. Then, still before any implementation code, establish the ground: check the working tree is clean (uncommitted unrelated changes are the user's to decide about \u2014 ask), and run the plan's proof commands once, recording the baseline in the spec. A baseline that is already red changes what \"green\" will mean, so surface it here rather than discovering it under your own diff. Write no implementation code before this gate passes, and do not use todo_write before it either \u2014 it tracks landing, not the interview.\n\nPhase 4 \u2014 landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Either way the spec file \u2014 not this conversation \u2014 is the working memory: re-read it before starting each milestone, tick the milestone's checkbox and update Status as you go, and commit after each milestone turns green \u2014 small commits are the progress that survives a crash and the history a reviewer can walk. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, fix until green, then commit before moving on. If it is larger \u2014 four or more substantially independent milestones, or work you expect to exceed what one session can hold \u2014 the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the single source of truth, instructs each round to read the spec from disk (plan, checkboxes, baseline), pick the first unchecked milestone, implement and test it, then commit and tick its checkbox, and defines completion as every acceptance criterion in the spec passing. Bound the loop: budget about three rounds per milestone, and instruct it to stop and report rather than continue past two consecutive rounds that tick nothing.\n\nPhase 5 \u2014 done means verified. The workflow ends only when every acceptance criterion passes with you actually running its named command and reading the real output. After a Ralph loop returns, run every proof command again yourself \u2014 the loop's word is a report, not a verification. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Set Status to shipped only after that final run, and close with an honest report listing each criterion, the command that proved it, and what it printed \u2014 plus anything left open.\n\nIf the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.";

package/lib/types/vision.d.ts

@@ -0,0 +1,84 @@
+/**
+ * What a pasted image becomes when the model cannot see.
+ *
+ * DeepSeek Vision routes receive first-class image blocks before this module
+ * is involved. For text-only routes such as Flash and Pro, codsh gives an
+ * image two honest lives: it is always saved to a stable file the agent's
+ * tools can touch — inspect, commit, embed. And when a vision sidecar is
+ * configured (`CODSH_VISION_*`: any OpenAI-compatible multimodal endpoint),
+ * the image is also described into text the model can actually read: everything in it
+ * transcribed, structure narrated. Both ride the same message the person
+ * sent, so they persist in durable history and survive `--resume`.
+ * @module codsh-bundle/src/vision
+ */
+import type { EncodedImageAttachment, ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment/types';
+/** A vision sidecar: an OpenAI-compatible endpoint that can see. */
+export interface VisionConfig {
+    /** The API base, e.g. `https://open.bigmodel.cn/api/paas/v4`. */
+    baseUrl: string;
+    /** Bearer token; absent for endpoints that need none (local ollama). */
+    apiKey?: string;
+    /** The multimodal model to ask. */
+    model: string;
+}
+/**
+ * The sidecar from the environment, or undefined when none is configured.
+ * @param env - the process environment.
+ * @returns the config when both the base URL and the model are set.
+ */
+export declare function visionConfigFromEnv(env: Record<string, string | undefined>): VisionConfig | undefined;
+/**
+ * Ask the sidecar what an image shows.
+ * @param image - the encoded image.
+ * @param config - which endpoint and model to ask.
+ * @param signal - cancels the request, on top of the built-in timeout.
+ * @returns the description.
+ * @throws on timeout, a non-2xx answer, or an answer with no text.
+ */
+export declare function describeImage(image: EncodedImageAttachment, config: VisionConfig, signal?: AbortSignal): Promise<string>;
+/**
+ * The upstream store's default admission limits, for use when no store is
+ * mounted: the sidecar payload is bounded by the same line either way.
+ */
+export declare const DEFAULT_IMAGE_LIMITS: ImageAttachmentLimits;
+/**
+ * Save a pasted image where the agent's tools can reach it.
+ *
+ * The original bytes, never a downscaled copy — the person may want the asset
+ * itself committed. Content-addressed under the dsh home so a repeated paste
+ * dedupes, nothing lands in the workspace uninvited, and the path stays valid
+ * for `--resume`.
+ * @param image - the encoded image.
+ * @returns the absolute path of the saved file.
+ */
+export declare function savePastedImage(image: EncodedImageAttachment): Promise<string>;
+/**
+ * The context block a pasted image contributes on a text-only route.
+ *
+ * The same XMLish convention the `!` passthrough uses: the model reads the
+ * path (its tools can open the file), the dimensions, and — when the sidecar
+ * ran — the description standing in for sight.
+ * @param id - the `[Image #N]` number the person's text references.
+ * @param image - the encoded image.
+ * @param at - where the file was saved and what is known about it.
+ * @returns the block text.
+ */
+export declare function pastedImageBlock(id: number, image: EncodedImageAttachment, at: {
+    path: string;
+    width?: number;
+    height?: number;
+    description?: string;
+}): string;
+/**
+ * Shrink an image until the attachment store will admit it.
+ *
+ * Retina screenshots exceed the deployed routes' 2000-pixel side limit as a
+ * matter of course, and refusing them would make the feature useless on the
+ * machines most likely to use it. The downscale re-encodes as PNG; a copy
+ * still over the byte limit falls back to JPEG, which is what a photograph
+ * that big actually is.
+ * @param image - the encoded image.
+ * @param limits - the store's admission limits.
+ * @returns the image, downscaled only when it had to be.
+ */
+export declare function fitWithinLimits(image: EncodedImageAttachment, limits: ImageAttachmentLimits): Promise<EncodedImageAttachment>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codsh-bundle",
   "description": "The codsh runtime: the interactive TTY surface and code-cli agent preset, installed into a dsh profile. Users install codsh-cli (the launcher) — this package is what it registers.",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "license": "MIT",
   "main": "lib/index.js",
@@ -38,59 +38,61 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/dsh-agent-instructions": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-command-compact": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-compaction-basic": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-lsp": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-lsp-stdio": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-persona": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-terminal": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-terminal-bash": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-ask-user": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-bash": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-fs": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-fs-search": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-goal": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-jobs": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-lsp": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-pwsh": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-ralph": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-skill": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-subagent": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-subagent-control": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-terminal": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-todo": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-web": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tool-workflow": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-workflow-worker-thread": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-agent-instructions": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-cmdline": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-command-compact": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-lsp": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-lsp-stdio": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-persona": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-plan-mode": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-terminal": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-terminal-bash": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-ask-user": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-bash": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-fs-search": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-goal": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-jobs": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-lsp": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-pwsh": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-ralph": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-skill": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-subagent-control": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-terminal": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-todo": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-web": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-workflow": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-workflow-worker-thread": "^0.1.1-rc.2",
     "@deepseek-ai/schemastery": "^3.18.1",
     "commander": "^15.0.0",
     "diff": "^9.0.0",
+    "sharp": "^0.35.3",
     "string-width": "^8.2.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-query": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-user-questions": "^0.1.1-rc.2"
   },
   "engines": {
     "node": ">=22.19"