Skip to content

Stop paying the multimodal tax. Your AI agent keeps every image it has seen but only sends the ones it needs: lighter chats, no endless reconnecting, no starting over. Works with Codex, Claude Code, Cline, Gemini CLI, OpenCode, WorkBuddy and more. Install once, forget it.

feat(platforms): WorkBuddy, OpenCode, Gemini CLI, pi and DeepSeek Harness on the core alone

chipfighter8a0a04d3b2ea
diff --git a/plugin/src/adapters/dsh/plugin.ts b/plugin/src/adapters/dsh/plugin.ts
new file mode 100644
index 0000000..9234bd4
--- /dev/null
+++ b/plugin/src/adapters/dsh/plugin.ts
@@ -0,0 +1,84 @@
+// Purpose: v0.11 — DeepSeek Harness (dsh): automatic selection as a dsh plugin, mounted in place of dsh's own
+// `@deepseek-ai/dsh-compaction-image-offload` (docs/v0.11/plan.md 3.9). dsh keeps an image's offload as a durable mark
+// in the session log (an `image/offload` event); every later request shows that image to the model as text naming the
+// attachment and a read-only path it can read the image back from. dsh's plugin marks the oldest images only when a
+// route refuses a request as over its image budget. This one does the same, and also, as a new turn starts, marks every
+// image of the turns before it — what automatic selection does on the other platforms. The model reads an image back
+// through its path when it needs it; what it reads is a new occurrence, kept for that turn and marked when the next one
+// starts. Marks never revert, so the provider's cached prefix only moves forward. No request goes through the engine.
+// Written against dsh's docs and the source of its image-offload plugin (agent/pre-step, agent/request-error,
+// compaction/summary-error, image/offload); not tested live.
+// Use (dsh composition config): replace `- name: '@deepseek-ai/dsh-compaction-image-offload'` with
+// `- name: '<path to this file>'`.
+// Input: dsh's events. Output: image/offload events in the session log.
+
+import { IMAGE_OFFLOAD_REQUIRED_CODE, LlmError } from "@deepseek-ai/dsh-llm";
+import { imageOffloadProjection } from "@deepseek-ai/dsh-compaction-image-offload/projection";
+
+type Seq = number;
+type Block = { type: string; offloaded?: true };
+type Session = {
+ eventAt(seq: Seq): { type: string } | undefined;
+ deriveEventMessage(event: { type: string }): { content: Block[] } | undefined;
+ append(type: "image/offload", payload: { targets: Array<{ seq: Seq; imageIndexes: number[] }> }): void;
+ surface: { nodes: readonly Seq[] };
+};
+type Agent = { session: Session };
+type Context = {
+ sessions: { registerMessageProjection(projection: unknown): void };
+ on(event: string, listener: (payload: any, next: () => any) => any): void;
+};
+
+export const name = "context-attachment-manager";
+export const inject = ["agents", "sessions"];
+
+// Marks up to `count` retained input images, in request order (assistant messages hold no input images). Image indexes
+// count every image of a message, marked ones included, as dsh's own plugin does. False when none was left.
+export function offloadImages(session: Session, seqs: readonly Seq[], count: number): boolean {
+ const targets: Array<{ seq: Seq; imageIndexes: number[] }> = [];
+ for (const seq of seqs) {
+ if (count <= 0) break;
+ const event = session.eventAt(seq);
+ if (!event || (event.type !== "user/message" && event.type !== "tool/result")) continue;
+ const message = session.deriveEventMessage(event);
+ if (!message) continue;
+ const imageIndexes: number[] = [];
+ let index = 0;
+ for (const block of message.content) {
+ if (count <= 0) break;
+ if (block.type !== "image") continue;
+ if (block.offloaded !== true) { imageIndexes.push(index); count--; }
+ index++;
+ }
+ if (imageIndexes.length) targets.push({ seq, imageIndexes });
+ }
+ if (!targets.length) return false;
+ session.append("image/offload", { targets });
+ return true;
+}
+
+export function apply(ctx: Context): void {
+ ctx.sessions.registerMessageProjection(imageOffloadProjection);
+ // The turn each agent was last in: a different one means a new turn starts, and its user messages are not on the
+ // surface yet, so every image there belongs to an earlier turn (on a resumed session too).
+ const turnOf = new WeakMap<object, number>();
+ ctx.on("agent/pre-step", ({ agent, turn, signal }: { agent: Agent; turn: number; signal: AbortSignal }, next) => {
+ if (!signal.aborted && turnOf.get(agent) !== turn) {
+ turnOf.set(agent, turn);
+ offloadImages(agent.session, agent.session.surface.nodes, Number.POSITIVE_INFINITY);
+ }
+ return next();
+ });
+ // As dsh's own plugin: a route that refuses the request as over its image budget names how many more to mark.
+ ctx.on("agent/request-error", ({ agent, failure, signal }: { agent: Agent; failure: { code: string; offloadImages?: number }; signal: AbortSignal }, next) => {
+ if (failure.code !== IMAGE_OFFLOAD_REQUIRED_CODE || failure.offloadImages === undefined || signal.aborted) return next();
+ if (!offloadImages(agent.session, agent.session.surface.nodes, failure.offloadImages)) return next();
+ return Promise.resolve({ kind: "retry" });
+ });
+ ctx.on("compaction/summary-error", ({ session, sourceEventSeqs, error, signal }: { session: Session; sourceEventSeqs: readonly Seq[]; error: unknown; signal?: AbortSignal }, next) => {
+ if (!(error instanceof LlmError) || (error as any).code !== IMAGE_OFFLOAD_REQUIRED_CODE || (error as any).failure?.offloadImages === undefined) return next();
+ signal?.throwIfAborted();
+ if (!offloadImages(session, sourceEventSeqs, (error as any).failure.offloadImages)) return next();
+ return true;
+ });
+}
diff --git a/plugin/src/adapters/gemini-cli/platform.ts b/plugin/src/adapters/gemini-cli/platform.ts
new file mode 100644
index 0000000..3f9053e
--- /dev/null
+++ b/plugin/src/adapters/gemini-cli/platform.ts
@@ -0,0 +1,20 @@
+// Purpose: v0.11 — Gemini CLI: the core alone, no panel. Signed in with an API key it sends Gemini generateContent
+// requests to GOOGLE_GEMINI_BASE_URL (by default https://generativelanguage.googleapis.com); signed in with Google, the
+// same contents wrapped in `request` to CODE_ASSIST_ENDPOINT (by default https://cloudcode-pa.googleapis.com), which
+// takes a route of its own (`cam connect gemini-cli --base-url https://cloudcode-pa.googleapis.com`). Its requests name
+// no session the engine knows, so sessions are told apart by their first prompt. MCP servers go under "mcpServers" in
+// ~/.gemini/settings.json. Not tested live.
+// Input: none. Output: the platform's entry for the engine (core/platform.ts).
+
+import type { CorePlatform } from "../../core/platform.ts";
+
+export const geminiCli: CorePlatform = {
+ name: "gemini-cli",
+ title: "Gemini CLI",
+ upstream: "https://generativelanguage.googleapis.com",
+ connect: ({ url, mcp }) => [
+ `In ~/.gemini/.env, set GOOGLE_GEMINI_BASE_URL=${url} (signed in with Google instead: CODE_ASSIST_ENDPOINT, with a route made by --base-url https://cloudcode-pa.googleapis.com)`,
+ `In ~/.gemini/settings.json, add: "mcpServers": { "context-attachment-manager": { "command": ${JSON.stringify(mcp.command)}, "args": ${JSON.stringify(mcp.args)}, "env": ${JSON.stringify(mcp.env)} } }`,
+ "Restart Gemini CLI.",
+ ],
+};
diff --git a/plugin/src/adapters/opencode/platform.ts b/plugin/src/adapters/opencode/platform.ts
new file mode 100644
index 0000000..f97a179
--- /dev/null
+++ b/plugin/src/adapters/opencode/platform.ts
@@ -0,0 +1,19 @@
+// Purpose: v0.11 — OpenCode: the core alone, no panel. Each provider in opencode.json takes its own base URL
+// (`options.baseURL`), so the route is registered for the provider the user picks, with that provider's address; the
+// request format follows the provider (Anthropic Messages, OpenAI Responses or Chat Completions, Gemini). Its requests
+// name no session the engine knows, so sessions are told apart by their first prompt; a plugin of OpenCode's own could
+// add `x-cam-session` in its `model.request` hook. MCP servers go under "mcp" in opencode.json. Not tested live.
+// Input: none. Output: the platform's entry for the engine (core/platform.ts).
+
+import type { CorePlatform } from "../../core/platform.ts";
+
+export const opencode: CorePlatform = {
+ name: "opencode",
+ title: "OpenCode",
+ upstream: null,
+ connect: ({ url, mcp }) => [
+ `In opencode.json, set your provider's base URL: "provider": { "<provider id>": { "options": { "baseURL": "${url}" } } }`,
+ `Add the MCP server: "mcp": { "context-attachment-manager": { "type": "local", "command": ${JSON.stringify([mcp.command, ...mcp.args])}, "environment": ${JSON.stringify(mcp.env)} } }`,
+ "Restart OpenCode.",
+ ],
+};
diff --git a/plugin/src/adapters/pi/extension.ts b/plugin/src/adapters/pi/extension.ts
new file mode 100644
index 0000000..8b0acc1
--- /dev/null
+++ b/plugin/src/adapters/pi/extension.ts
@@ -0,0 +1,26 @@
+// Purpose: v0.11 — the pi extension (loaded by pi, not by the engine; docs/v0.11/plan.md 3.8). Two jobs: each model
+// request names its pi session in `x-cam-session`, which the engine takes as the session (it never goes further: the
+// engine drops x-cam- headers), and the plugin's MCP service is registered, so the model has cam_view_image and the
+// engine keeps running while pi does. The model requests reach the engine through the provider's baseUrl in
+// ~/.pi/agent/models.json (`cam connect pi`). Written against pi's extension docs (before_provider_headers,
+// registerMcpServer); not tested live.
+// Input: pi's extension API. Output: a header on each request, one MCP server for the session.
+
+import { fileURLToPath } from "node:url";
+
+type Pi = {
+ on(event: "before_provider_headers", handler: (event: { headers: Record<string, string | null> }, ctx: { sessionManager: { getSessionId(): string } }) => void): void;
+ registerMcpServer(name: string, config: { command: string; args: string[]; env?: Record<string, string> }): void;
+};
+
+export default function contextAttachmentManager(pi: Pi): void {
+ pi.on("before_provider_headers", (event, ctx) => {
+ const id = ctx.sessionManager.getSessionId();
+ if (id) event.headers["x-cam-session"] = id;
+ });
+ pi.registerMcpServer("context_attachment_manager", {
+ command: "node",
+ args: [fileURLToPath(new URL("../../plugin-server.ts", import.meta.url))],
+ env: { CAM_HOST: "pi" },
+ });
+}
diff --git a/plugin/src/adapters/pi/platform.ts b/plugin/src/adapters/pi/platform.ts
new file mode 100644
index 0000000..048da97
--- /dev/null
+++ b/plugin/src/adapters/pi/platform.ts
@@ -0,0 +1,19 @@
+// Purpose: v0.11 — pi (earendil-works/pi): the core alone, no panel. Each provider in ~/.pi/agent/models.json takes
+// its own `baseUrl`, so the route is registered for the provider the user picks, with that provider's address; the
+// request format follows the provider. Our pi extension (extension.ts) names each request's session in
+// `x-cam-session` and registers the plugin's MCP service, so pi needs no other setting. Not tested live.
+// Input: none. Output: the platform's entry for the engine (core/platform.ts).
+
+import { fileURLToPath } from "node:url";
+import type { CorePlatform } from "../../core/platform.ts";
+
+export const pi: CorePlatform = {
+ name: "pi",
+ title: "pi",
+ upstream: null,
+ connect: ({ url }) => [
+ `In ~/.pi/agent/models.json, set your provider's "baseUrl": "${url}"`,
+ `Load the extension: pi -e ${JSON.stringify(fileURLToPath(new URL("./extension.ts", import.meta.url)))} (or copy it to ~/.pi/agent/extensions/)`,
+ "Restart pi.",
+ ],
+};
diff --git a/plugin/src/adapters/protocols/any.ts b/plugin/src/adapters/protocols/any.ts
new file mode 100644
index 0000000..fda2b60
--- /dev/null
+++ b/plugin/src/adapters/protocols/any.ts
@@ -0,0 +1,155 @@
+// Purpose: v0.11 — the rewrite for a platform that uses the core alone, without a panel (docs/v0.11/plan.md 3.8),
+// whatever request format it speaks: the format is told by the path, the images and their turns by the format's
+// translator, their ids by the session's request index (core/request-index.ts). Automatic selection is always on there:
+// the images of earlier turns go out as placeholders, and the model fetches what it needs with cam_view_image; a copy
+// it fetched is sent in its own turn only. Feature lines stay off: the model's record lines would show as text in a
+// terminal.
+// Input: the request path and body, the platform, the session its headers name (if any). Output: the body to send, a
+// report, the session.
+
+import { createHash } from "node:crypto";
+import { decodeBody, encodeBody, hasUnsafeInteger } from "../../core/engine/transport.ts";
+import { fetchedIdIn, type ImageDigest, type ImageKind } from "../../core/images.ts";
+import type { Lang } from "../../core/lang.ts";
+import type { RewriteReport } from "../../core/plan.ts";
+import { pixelHashOfData } from "../../core/pixels.ts";
+import { markLatest, openRequestIndex, remember, saveRequestIndex, type RequestIndex } from "../../core/request-index.ts";
+import { sessionKeyOf } from "../../core/selection.ts";
+import type { Described } from "../../core/words.ts";
+import { imageBlocks, rewriteBlocks, type RequestImage } from "./anthropic-messages/rewrite.ts";
+import { geminiContents, geminiImages, rewriteGemini, withContents, type GeminiImage } from "./gemini/rewrite.ts";
+import { chatImages, rewriteChat, type ChatImage } from "./openai-chat/rewrite.ts";
+import { findImages, type ImageRef } from "./openai-responses/images.ts";
+import { rewriteItems } from "./openai-responses/rewrite.ts";
+
+type Json = Record<string, any>;
+export type FormatName = "openai-responses" | "anthropic-messages" | "openai-chat" | "gemini";
+
+export function formatOf(path: string): FormatName | null {
+ if (/\/chat\/completions$/.test(path)) return "openai-chat";
+ if (/\/responses$/.test(path)) return "openai-responses";
+ if (/\/messages$/.test(path)) return "anthropic-messages";
+ if (/:(stream)?[Gg]enerateContent$/.test(path)) return "gemini";
+ return null;
+}
+
+// What every format's reader gives: each image with its key, turn and data, and the first prompt (to tell sessions
+// apart when the platform names none).
+type AnyImage = ImageDigest & { key: string; kind: ImageKind; replaceable: boolean; turn: number; fetchedOf: string | null; data: string | null };
+type Rewrite = (describe: (image: AnyImage) => Described | undefined, leaveOut: Set<string>, pixels: (image: AnyImage) => string | null, options: { lang: Lang; copies: Map<string, string>; auto: { currentTurn: number }; fetched: (image: AnyImage) => boolean }) => { body: Json; report: RewriteReport };
+type Read = { images: AnyImage[]; turns: number; first: string; conversation: boolean; rewrite: Rewrite };
+
+const hasTools = (json: Json) => (Array.isArray(json.tools) && json.tools.length > 0) || (Array.isArray(json.request?.tools) && json.request.tools.length > 0);
+const DATA_URL = /^data:[^;,]+;base64,(.*)$/s;
+
+function readRequest(format: FormatName, json: Json): Read | null {
+ const conversation = hasTools(json);
+ if (format === "openai-chat") {
+ if (!Array.isArray(json.messages)) return null;
+ const found = chatImages(json.messages);
+ return { ...found, conversation, rewrite: (describe, leaveOut, pixels, options) => {
+ const out = rewriteChat(json.messages, found.images, describe as (image: ChatImage) => Described | undefined, leaveOut, pixels as (image: ChatImage) => string | null, options as never);
+ return { body: { ...json, messages: out.messages }, report: out.report };
+ } };
+ }
+ if (format === "gemini") {
+ const contents = geminiContents(json);
+ if (!contents) return null;
+ const found = geminiImages(contents);
+ return { ...found, conversation, rewrite: (describe, leaveOut, pixels, options) => {
+ const out = rewriteGemini(contents, found.images, describe as (image: GeminiImage) => Described | undefined, leaveOut, pixels as (image: GeminiImage) => string | null, options as never);
+ return { body: withContents(json, out.contents), report: out.report };
+ } };
+ }
+ if (format === "anthropic-messages") {
+ if (!Array.isArray(json.messages)) return null;
+ const messages: Json[] = json.messages;
+ // A turn starts with each user message that has text and is not only tool results.
+ const prompts: number[] = [];
+ messages.forEach((message, msg) => {
+ const content = message?.content;
+ const own = typeof content === "string" ? content.trim() !== "" : Array.isArray(content) && content.some((block: Json) => block?.type === "text" && String(block.text ?? "").trim() !== "");
+ if (message?.role === "user" && own && !(Array.isArray(content) && content.some((block: Json) => block?.type === "tool_result"))) prompts.push(msg);
+ });
+ const turnAt = (msg: number) => Math.max(prompts.filter((at) => at <= msg).length, 1);
+ const refs = imageBlocks(messages).map((ref) => {
+ const list: Json[] = ref.sub === null ? messages[ref.msg].content : messages[ref.msg].content[ref.part].content;
+ const before = list[(ref.sub ?? ref.part) - 1];
+ const fetchedOf = before?.type === "text" ? fetchedIdIn(String(before.text ?? "")) : null;
+ return Object.assign(ref, { key: ref.key ?? `m${ref.msg}:p${ref.part}`, turn: turnAt(ref.msg), fetchedOf, data: String(ref.block.source.data) });
+ });
+ const first = prompts.length ? textOfAnthropic(messages[prompts[0]].content) : "";
+ return { images: refs, turns: Math.max(prompts.length, 1), first, conversation, rewrite: (describe, leaveOut, pixels, options) => {
+ const out = rewriteBlocks(messages, refs as RequestImage[], describe as (ref: RequestImage) => Described | undefined, leaveOut, pixels as (ref: RequestImage) => string | null, options as never);
+ return { body: { ...json, messages: out.messages }, report: out.report };
+ } };
+ }
+ if (!Array.isArray(json.input)) return null;
+ const items: Json[] = json.input;
+ const prompts = items.flatMap((item, at) => (item?.type === "message" && item.role === "user" && Array.isArray(item.content) && item.content.some((part: Json) => part?.type === "input_text" && String(part.text ?? "").trim() !== "") ? [at] : []));
+ const turnAt = (at: number) => Math.max(prompts.filter((prompt) => prompt <= at).length, 1);
+ const refs = findImages(items);
+ const dataOf = (ref: ImageRef): string | null => {
+ const item = items[ref.item];
+ if (ref.part === null) return typeof item.result === "string" ? item.result : null;
+ const part = (item.type === "message" ? item.content : item.output)?.[ref.part];
+ const url = typeof part?.image_url === "string" ? part.image_url : "";
+ return DATA_URL.exec(url)?.[1] ?? null;
+ };
+ const images: AnyImage[] = refs.map((ref) => ({ ...ref, turn: turnAt(ref.item), fetchedOf: ref.fetchedId, data: dataOf(ref) }));
+ const byKey = new Map(images.map((image) => [image.key, image]));
+ const first = prompts.length ? items[prompts[0]].content.filter((part: Json) => part?.type === "input_text").map((part: Json) => String(part.text)).join("\n") : "";
+ return { images, turns: Math.max(prompts.length, 1), first, conversation, rewrite: (describe, leaveOut, pixels, options) => {
+ // The translator finds the images again; the same keys name them.
+ const out = rewriteItems(items, (ref) => { const image = byKey.get(ref.key); return image ? describe(image) : undefined; }, leaveOut, (ref) => { const image = byKey.get(ref.key); return image ? pixels(image) : null; }, { lang: options.lang, copies: options.copies, auto: options.auto });
+ return { body: { ...json, input: out.items }, report: out.report };
+ } };
+}
+
+const textOfAnthropic = (content: unknown): string => (typeof content === "string" ? content : Array.isArray(content) ? content.filter((block: Json) => block?.type === "text").map((block: Json) => String(block.text)).join("\n") : "");
+
+// The session a request belongs to: the one its headers name, else its first prompt (the same first prompt on the same
+// platform counts as the same session; ids go by content anyway).
+export function sessionOfRequest(platform: string, named: string | null, first: string): string | null {
+ if (named) return sessionKeyOf(`${platform}\n${named}`);
+ if (!first.trim()) return null;
+ return createHash("sha256").update(`${platform}\nfirst prompt\n${first}`).digest("hex").slice(0, 32);
+}
+
+export type PlatformRewrite = { body: Buffer; report: Json; session: string | null };
+
+export function rewritePlatformRequest(platform: string, path: string, original: Buffer, encoding: string | undefined, named: string | null, root: string, lang: Lang): PlatformRewrite {
+ const asIs = (report: Json, session: string | null = null): PlatformRewrite => ({ body: original, report, session });
+ const format = formatOf(path);
+ if (!format) return asIs({ skipped: "not a model request" });
+ const decoded = decodeBody(original, encoding);
+ if (!decoded) return asIs({ skipped: "undecodable body" });
+ const text = decoded.toString("utf8");
+ let json: Json;
+ try { json = JSON.parse(text); } catch { return asIs({ skipped: "unparsable body" }); }
+ if (hasUnsafeInteger(text)) return asIs({ skipped: "integer beyond 2^53 would change when re-serialized" });
+ const read = readRequest(format, json);
+ if (!read) return asIs({ skipped: `no ${format} history` });
+ const session = sessionOfRequest(platform, named, read.first);
+ if (!session) return asIs({ skipped: "no session" });
+ let index: RequestIndex;
+ try { index = openRequestIndex(platform, session, root); } catch (error) { return asIs({ skipped: `request index: ${String(error)}` }, session); }
+ const current = read.turns;
+ const ids = new Map<string, Described>();
+ for (const image of read.images) {
+ if (image.fetchedOf || image.data === null) continue;
+ const seen = remember(index, image, image.data, image.turn, root);
+ ids.set(image.key, { id: seen.id, name: null, label: null, kind: image.kind, turn: image.turn, width: image.width, height: image.height });
+ }
+ try { saveRequestIndex(index, root); } catch { /* the ids are given again next time */ }
+ if (read.conversation) { try { markLatest(platform, session, root); } catch { /* a fetch then finds the session before */ } }
+ const copies = new Map(read.images.filter((image) => image.fetchedOf && image.turn < current).map((image) => [image.key, image.fetchedOf!]));
+ const leaveOut = new Set(read.images.filter((image) => image.replaceable && !image.fetchedOf && image.turn < current && ids.has(image.key)).map((image) => image.key));
+ const out = read.rewrite((image) => ids.get(image.key), leaveOut, (image) => (image.data === null ? null : pixelHashOfData(image, image.data)), { lang, copies, auto: { currentTurn: current }, fetched: (image) => !!image.fetchedOf });
+ const { report } = out;
+ const summary: Json = { format, auto: true, images: report.images, replaced: report.replaced.map(({ key: _key, ...rest }) => rest), sentImageHashes: report.sentContentIds.map((id) => id.slice(0, 16)), ...(report.copies.length ? { copies: report.copies } : {}) };
+ if (!report.replaced.length && !report.copies.length) return asIs(summary, session);
+ const next = Buffer.from(JSON.stringify(out.body), "utf8");
+ const body = encodeBody(next, encoding);
+ return { body, report: { ...summary, decodedBefore: decoded.length, decodedAfter: next.length, encodedBefore: original.length, encodedAfter: body.length }, session };
+}
diff --git a/plugin/src/adapters/protocols/gemini/rewrite.ts b/plugin/src/adapters/protocols/gemini/rewrite.ts
new file mode 100644
index 0000000..f444770
--- /dev/null
+++ b/plugin/src/adapters/protocols/gemini/rewrite.ts
@@ -0,0 +1,84 @@
+// Purpose: v0.11 — the Gemini generateContent request format (Gemini CLI, and the Google provider of other clients;
+// docs/v0.11/plan.md 3.8): where its images are, which turn each belongs to, and the core's plan put into the contents.
+// Images are `inlineData` parts of user contents (a file reference is left alone); the user content that answers a
+// function call holds no prompt. A turn starts with each user content that has text and answers no call. Gemini takes
+// no system text in mid-conversation, so the text for the model goes in as text parts of the content that held the
+// images. Gemini CLI signed in with Google sends the same contents inside `request` (Code Assist).
+// Input: the request's contents. Output: its images with their turns; new contents and a report.
+
+import { fetchedIdIn, imageDigest, type ImageDigest, type ImageKind } from "../../../core/images.ts";
+import { planRewrite, type PlanOptions, type RewriteReport } from "../../../core/plan.ts";
+import { autoNote, featureNote, omissionNote, type Described } from "../../../core/words.ts";
+
+type Json = Record<string, any>;
+export type GeminiImage = ImageDigest & { key: string; kind: ImageKind; name: null; label: null; replaceable: true; msg: number; part: number; turn: number; fetchedOf: string | null; data: string };
+
+const textOf = (part: Json): string => (typeof part?.text === "string" && !part.thought ? part.text : "");
+const isPrompt = (content: Json) => content?.role === "user" && Array.isArray(content.parts) && content.parts.some((part: Json) => textOf(part).trim() !== "") && !content.parts.some((part: Json) => part?.functionResponse);
+
+// Where the contents are: at the top, or inside `request` (Code Assist).
+export function geminiContents(body: Json): Json[] | null {
+ if (Array.isArray(body?.contents)) return body.contents;
+ if (Array.isArray(body?.request?.contents)) return body.request.contents;
+ return null;
+}
+export function withContents(body: Json, contents: Json[]): Json {
+ return Array.isArray(body?.contents) ? { ...body, contents } : { ...body, request: { ...body.request, contents } };
+}
+
+export function geminiImages(contents: Json[]): { images: GeminiImage[]; turns: number; first: string } {
+ const images: GeminiImage[] = [];
+ let turns = 0;
+ let first = "";
+ contents.forEach((content, msg) => {
+ const prompt = isPrompt(content);
+ if (prompt) {
+ turns++;
+ if (turns === 1) first = content.parts.map(textOf).join("\n");
+ }
+ if (content?.role !== "user" || !Array.isArray(content.parts)) return;
+ content.parts.forEach((part: Json, at: number) => {
+ const inline = part?.inlineData;
+ if (!inline || typeof inline.data !== "string" || !/^image\//.test(String(inline.mimeType ?? ""))) return;
+ const before = at > 0 ? textOf(content.parts[at - 1]) : "";
+ images.push({ ...imageDigest(part, inline.data, inline.mimeType), key: `c${msg}:p${at}`, kind: prompt ? "upload" : "tool", name: null, label: null, replaceable: true, msg, part: at, turn: Math.max(turns, 1), fetchedOf: before ? fetchedIdIn(before) : null, data: inline.data });
+ });
+ });
+ return { images, turns: Math.max(turns, 1), first };
+}
+
+export function rewriteGemini(
+ contents: Json[],
+ images: GeminiImage[],
+ describe: (image: GeminiImage) => Described | undefined,
+ leaveOut: Set<string>,
+ pixelHash: (image: GeminiImage) => string | null,
+ options: PlanOptions<GeminiImage> = {},
+): { contents: Json[]; report: RewriteReport } {
+ const { lang = "zh", auto } = options;
+ const plan = planRewrite(images, describe, leaveOut, pixelHash, options);
+ const { report } = plan;
+ if (!plan.changed) return { contents, report };
+ const edits = new Map<number, Array<{ at: number; remove: number; text: string }>>();
+ for (const { slot, what, text } of plan.actions) {
+ const image = images[slot];
+ edits.set(image.msg, [...(edits.get(image.msg) ?? []), { at: image.part, remove: what === "label" ? 0 : 1, text }]);
+ }
+ // The note on omitted images goes first in the content holding the first of them; the feature line note (v0.8), first
+ // in the prompt of the turn holding the first image the index knows.
+ const noteIn = plan.plain.length ? images[plan.plain[0].slot].msg : null;
+ const prompts = contents.flatMap((content, msg) => (isPrompt(content) ? [msg] : []));
+ const featureIn = plan.first !== null ? prompts[images[plan.first].turn - 1] ?? images[plan.first].msg : null;
+ const next = contents.map((content, msg) => {
+ const list = edits.get(msg);
+ if (!list && msg !== featureIn) return content;
+ const parts: Json[] = [...content.parts];
+ for (const { at, remove, text } of (list ?? []).sort((a, b) => b.at - a.at || b.remove - a.remove)) parts.splice(at, remove, { text });
+ if (msg === noteIn) parts.unshift({ text: auto ? autoNote(lang) : omissionNote(lang) });
+ if (msg === featureIn) parts.unshift({ text: featureNote(lang) });
+ return { ...content, parts };
+ });
+ if (noteIn !== null) report.noteAt = noteIn;
+ if (featureIn !== null) report.featureAt = featureIn;
+ return { contents: next, report };
+}
diff --git a/plugin/src/adapters/protocols/openai-chat/rewrite.ts b/plugin/src/adapters/protocols/openai-chat/rewrite.ts
new file mode 100644
index 0000000..4a7cf3c
--- /dev/null
+++ b/plugin/src/adapters/protocols/openai-chat/rewrite.ts
@@ -0,0 +1,81 @@
+// Purpose: v0.11 — the OpenAI Chat Completions request format (WorkBuddy, and OpenAI-compatible providers of OpenCode,
+// pi, …; docs/v0.11/plan.md 3.8): where its images are, which turn each belongs to, and the core's plan put into the
+// messages. Images are `image_url` parts with a data URL (a link to elsewhere is left alone), in user messages and, for
+// clients that send them there, in tool messages. A turn starts with each user message that has text of its own. The
+// text for the model goes in as text parts of the messages that held the images: every Chat Completions server takes
+// that, while a system message in mid-conversation is not taken everywhere.
+// Input: the request's messages. Output: its images with their turns; new messages and a report.
+
+import { fetchedIdIn, imageDigest, type ImageDigest, type ImageKind } from "../../../core/images.ts";
+import { planRewrite, type PlanOptions, type RewriteReport } from "../../../core/plan.ts";
+import { autoNote, featureNote, omissionNote, type Described } from "../../../core/words.ts";
+
+type Json = Record<string, any>;
+// msg: the message; part: the part in its content. turn: 1 for the first prompt's turn. fetchedOf: the id our fetch
+// tool's line right before it names. data: raw base64.
+export type ChatImage = ImageDigest & { key: string; kind: ImageKind; name: null; label: null; replaceable: true; msg: number; part: number; turn: number; fetchedOf: string | null; data: string };
+
+const DATA_URL = /^data:([^;,]+);base64,(.*)$/s;
+const urlOf = (part: Json): string | null => (typeof part?.image_url === "string" ? part.image_url : typeof part?.image_url?.url === "string" ? part.image_url.url : null);
+const textOf = (part: Json): string => (part?.type === "text" && typeof part.text === "string" ? part.text : "");
+const hasOwnText = (message: Json) => (typeof message?.content === "string" ? message.content.trim() !== "" : Array.isArray(message?.content) && message.content.some((part: Json) => textOf(part).trim() !== ""));
+
+// turns: how many prompts the request has (the current turn). first: the first prompt's text.
+export function chatImages(messages: Json[]): { images: ChatImage[]; turns: number; first: string } {
+ const images: ChatImage[] = [];
+ let turns = 0;
+ let first = "";
+ messages.forEach((message, msg) => {
+ if (message?.role === "user" && hasOwnText(message)) {
+ turns++;
+ if (turns === 1) first = typeof message.content === "string" ? message.content : message.content.map(textOf).join("\n");
+ }
+ if ((message?.role !== "user" && message?.role !== "tool") || !Array.isArray(message.content)) return;
+ message.content.forEach((part: Json, at: number) => {
+ const found = part?.type === "image_url" ? DATA_URL.exec(urlOf(part) ?? "") : null;
+ if (!found) return;
+ const before = at > 0 ? textOf(message.content[at - 1]) : "";
+ const kind: ImageKind = message.role === "user" && hasOwnText(message) ? "upload" : "tool";
+ images.push({ ...imageDigest(part, found[2], found[1]), key: `m${msg}:p${at}`, kind, name: null, label: null, replaceable: true, msg, part: at, turn: Math.max(turns, 1), fetchedOf: before ? fetchedIdIn(before) : null, data: found[2] });
+ });
+ });
+ return { images, turns: Math.max(turns, 1), first };
+}
+
+export function rewriteChat(
+ messages: Json[],
+ images: ChatImage[],
+ describe: (image: ChatImage) => Described | undefined,
+ leaveOut: Set<string>,
+ pixelHash: (image: ChatImage) => string | null,
+ options: PlanOptions<ChatImage> = {},
+): { messages: Json[]; report: RewriteReport } {
+ const { lang = "zh", auto } = options;
+ const plan = planRewrite(images, describe, leaveOut, pixelHash, options);
+ const { report } = plan;
+ if (!plan.changed) return { messages, report };
+ // Each edit puts one text part at `at`, in place of `remove` parts (none for a label).
+ const edits = new Map<number, Array<{ at: number; remove: number; text: string }>>();
+ for (const { slot, what, text } of plan.actions) {
+ const image = images[slot];
+ edits.set(image.msg, [...(edits.get(image.msg) ?? []), { at: image.part, remove: what === "label" ? 0 : 1, text }]);
+ }
+ // The note on omitted images goes first in the message holding the first of them; the feature line note (v0.8), first
+ // in the prompt of the turn holding the first image the index knows.
+ const noteIn = plan.plain.length ? images[plan.plain[0].slot].msg : null;
+ const prompts = messages.flatMap((message, msg) => (message?.role === "user" && hasOwnText(message) ? [msg] : []));
+ const featureIn = plan.first !== null ? prompts[images[plan.first].turn - 1] ?? images[plan.first].msg : null;
+ const next = messages.map((message, msg) => {
+ const list = edits.get(msg);
+ if (!list && msg !== featureIn) return message;
+ const parts: Json[] = typeof message.content === "string" ? [{ type: "text", text: message.content }] : [...message.content];
+ // Later positions first; at one position, a replacement before the label that goes in front of it.
+ for (const { at, remove, text } of (list ?? []).sort((a, b) => b.at - a.at || b.remove - a.remove)) parts.splice(at, remove, { type: "text", text });
+ if (msg === noteIn) parts.unshift({ type: "text", text: auto ? autoNote(lang) : omissionNote(lang) });
+ if (msg === featureIn) parts.unshift({ type: "text", text: featureNote(lang) });
+ return { ...message, content: parts };
+ });
+ if (noteIn !== null) report.noteAt = noteIn;
+ if (featureIn !== null) report.featureAt = featureIn;
+ return { messages: next, report };
+}
diff --git a/plugin/src/adapters/protocols/openai-responses/images.ts b/plugin/src/adapters/protocols/openai-responses/images.ts
index 5102940..4b11860 100644
--- a/plugin/src/adapters/protocols/openai-responses/images.ts
+++ b/plugin/src/adapters/protocols/openai-responses/images.ts
@@ -7,7 +7,7 @@
// (core/images.ts). The names and captions it reads are Codex's own; for another client they simply do not match.
// Input: items as parsed JSON. Output: ImageRef[] in item order (pure, no I/O).
-import { baseName, FETCHED_STATE, imageDigest, type ImageDigest, type ImageKind, type ImageSource } from "../../../core/images.ts";
+import { baseName, fetchedIdIn, imageDigest, type ImageDigest, type ImageKind, type ImageSource } from "../../../core/images.ts";
type Json = Record<string, any>;
@@ -34,8 +34,6 @@ export type ImageRef = ImageDigest & {
fetchedId: string | null;
};
-const FETCHED_LINE = new RegExp(`^\\[(?:图片|Image) (IMG-\\d{3,}) (?:${FETCHED_STATE.zh}|${FETCHED_STATE.en})(?:|| \\|)`);
-
const OPEN_TAG = /^<image name=(\[Image #\d+\]) path="(.*)">$/s;
// Codex desktop 26.924's own wording: the caption right before a comment's screenshot, and the line naming the PDF in
// the comment's text. Worded otherwise, a screenshot counts as an upload, as it did before v0.2.
@@ -143,7 +141,7 @@ function toolContext(call: Json | undefined, output: Json[]): { kind: ImageKind;
// order only when each call brought one image, otherwise which image is which is unknown.
const views = [...source.matchAll(/(?<![\w$])view_image\s*\(/g)].map((m) => viewName(source, m.index + m[0].length));
if (views.length || source.includes("view_image")) {
- const viewed = output.flatMap((part, i) => (part?.type === "input_image" || part?.type === "output_image" ? [!FETCHED_LINE.test(output[i - 1]?.type === "input_text" ? String(output[i - 1].text) : "")] : []));
+ const viewed = output.flatMap((part, i) => (part?.type === "input_image" || part?.type === "output_image" ? [!fetchedIdIn(output[i - 1]?.type === "input_text" ? String(output[i - 1].text) : "")] : []));
if (views.length !== viewed.filter(Boolean).length) return { kind: "view", names: [] };
let next = 0;
return { kind: "view", names: viewed.map((own) => (own ? views[next++] : null)) };
@@ -213,7 +211,7 @@ export function findImages(items: Json[]): ImageRef[] {
source,
pdfPage: pdf?.[1] ? Number(pdf[1]) : null,
pdfName: pdf ? pdfName ?? null : null,
- fetchedId: context && before !== null ? FETCHED_LINE.exec(before)?.[1] ?? null : null,
+ fetchedId: context && before !== null ? fetchedIdIn(before) : null,
});
n++;
});
diff --git a/plugin/src/adapters/workbuddy/platform.ts b/plugin/src/adapters/workbuddy/platform.ts
new file mode 100644
index 0000000..22f0e2b
--- /dev/null
+++ b/plugin/src/adapters/workbuddy/platform.ts
@@ -0,0 +1,21 @@
+// Purpose: v0.11 — WorkBuddy (Tencent's desktop agent, CodeBuddy Code inside; docs/v0.11/plan.md 4): the core alone, no
+// panel. Its agent sends OpenAI Chat Completions requests to CODEBUDDY_BASE_URL + /chat/completions, which by default
+// is WorkBuddy's own service under /v2 (a capture on 2026-11-02: without /v2 the service answers 405). Each request
+// names its conversation in `x-conversation-id`; side requests (prompt enhancement and the like) say
+// `x-agent-type: auxiliary`. `env` in ~/.workbuddy/settings.json reaches the agent's environment. Not tested live.
+// Input: request headers. Output: the platform's entry for the engine (core/platform.ts).
+
+import { headerOf, type CorePlatform } from "../../core/platform.ts";
+
+export const workbuddy: CorePlatform = {
+ name: "workbuddy",
+ title: "WorkBuddy",
+ upstream: "https://www.workbuddy.cn/v2",
+ sessionOf: (headers) => headerOf(headers, "x-conversation-id"),
+ sideRequest: (headers) => headerOf(headers, "x-agent-type") === "auxiliary",
+ connect: ({ url, mcp }) => [
+ `In ~/.workbuddy/settings.json, add to "env": "CODEBUDDY_BASE_URL": "${url}"`,
+ `Add an MCP server in WorkBuddy (stdio): command ${JSON.stringify(mcp.command)}, args ${JSON.stringify(mcp.args)}, env ${JSON.stringify(mcp.env)}`,
+ "Restart WorkBuddy.",
+ ],
+};
diff --git a/plugin/src/cam.ts b/plugin/src/cam.ts
index f7e9ca9..f3743a5 100644
--- a/plugin/src/cam.ts
+++ b/plugin/src/cam.ts
@@ -7,7 +7,9 @@
// v0.1-5: setup, run from the copy Codex installed (the install scripts do this after Codex's own command line added
// the plugin), points Codex at the engine and starts it. The settings themselves are switched in setup.ts.
// v0.1-14: it speaks the system language (messages.ts); status shows the language the panel reported.
-// Input: install [--port N] | setup [--port N] | uninstall | status | list|uncheck|check|check-all <thread id> [IMG-…].
+// v0.11: connect <platform> [--base-url URL], for a platform using the core alone (ADAPTERS.md).
+// Input: install [--port N] | setup [--port N] | uninstall | status | connect <platform> [--base-url URL] |
+// list|uncheck|check|check-all <thread id> [IMG-…].
// Output: config.toml (copied to <data dir>/config-backup/ before every change), ~/.codex/.env (never copied or
// printed: it may hold credentials), the plugin cache (through Codex's command line), the selection files, and a
// summary on stdout. Rollouts are only read.
@@ -30,6 +32,8 @@ import type { PanelState } from "./panel/panel-state.ts";
import { dataDir, selectionDirOf } from "./core/paths.ts";
import { preservingPluginCache } from "./adapters/codex/plugin-cache.ts";
import { backupConfig, connectDirectly, planEngine, readConfig, readEnv, useEngine } from "./adapters/codex/setup.ts";
+import { registerRoute, routeBaseUrl, validateBaseUrl } from "./core/routes.ts";
+import { CORE_PLATFORMS, corePlatformOf } from "./platforms.ts";
type Json = Record<string, any>;
const lang = systemLang();
@@ -215,7 +219,21 @@ async function main(): Promise<void> {
}, null, 2));
return;
}
- if (!command || !threadId) throw new Error("usage: cam.ts install [--port N] | setup [--port N] | uninstall | status | list|uncheck|check|check-all <thread id> [IMG-…]");
+ // v0.11: a platform using the core alone (platforms.ts, ADAPTERS.md): registers the route from the engine to where its
+ // requests go, and says what to set in the platform. Changes no file of the platform's.
+ if (command === "connect") {
+ const platform = corePlatformOf(threadId);
+ if (!platform) throw new Error(`usage: cam.ts connect <${CORE_PLATFORMS.map((one) => one.name).join("|")}> [--base-url URL]`);
+ const baseUrl = process.argv.includes("--base-url") ? process.argv[process.argv.indexOf("--base-url") + 1] : platform.upstream;
+ if (!baseUrl) throw new Error(`${platform.title}: give the address its requests go to now, with --base-url (e.g. https://api.anthropic.com/v1)`);
+ try { validateBaseUrl(baseUrl, port); } catch (error) { throw localized(error); }
+ const route = registerRoute({ platform: platform.name, baseUrl });
+ const url = routeBaseUrl(port, route.id).replace("localhost", "127.0.0.1");
+ const mcp = { command: process.execPath, args: [join(import.meta.dirname, "plugin-server.ts")], env: { CAM_HOST: platform.name } };
+ console.log(JSON.stringify({ command, platform: platform.name, upstream: baseUrl, url, steps: platform.connect({ url, mcp }) }, null, 2));
+ return;
+ }
+ if (!command || !threadId) throw new Error("usage: cam.ts install [--port N] | setup [--port N] | uninstall | status | connect <platform> [--base-url URL] | list|uncheck|check|check-all <thread id> [IMG-…]");
const options = { sessionsDir: join(codexHome(), "sessions") };
if (command === "list") console.log(table(loadPanelState(threadId, options)));
else if (command === "uncheck") console.log(table(applySelection(threadId, { uncheck: ids }, options)));
diff --git a/plugin/src/core/images.ts b/plugin/src/core/images.ts
index 9b87ccd..12c6e42 100644
--- a/plugin/src/core/images.ts
+++ b/plugin/src/core/images.ts
@@ -15,6 +15,9 @@ export type ImageDigest = { contentId: string; mime: string | null; base64Chars:
// v0.3 — the state our fetch tool (cam_view_image) writes in the line before each image it returns, in either
// language, so the image is known as a copy of that id. The rest of the line is the usual heading (words.ts).
export const FETCHED_STATE = { zh: "取回的原图", en: "fetched original" } as const;
+const FETCHED_LINE = new RegExp(`^\\[(?:图片|Image) (IMG-\\d{3,}) (?:${FETCHED_STATE.zh}|${FETCHED_STATE.en})(?:|| \\|)`);
+// The id our fetch tool's line names, when `text` is one.
+export const fetchedIdIn = (text: string): string | null => FETCHED_LINE.exec(text)?.[1] ?? null;
export function baseName(path: string): string {
return path.split(/[\\/]/).filter(Boolean).pop() ?? path;
diff --git a/plugin/src/core/platform.ts b/plugin/src/core/platform.ts
new file mode 100644
index 0000000..e12a821
--- /dev/null
+++ b/plugin/src/core/platform.ts
@@ -0,0 +1,33 @@
+// Purpose: v0.11 — what a platform's adapter tells the engine when the platform uses the core alone, without a panel
+// (docs/v0.11/plan.md 3.8; ADAPTERS.md): its name, where its requests go, how its requests name their session, which
+// of them are on the side, and what the user does to connect it. Everything else — which request format, which images,
+// what is left out — the core and the request-format translators work out from the requests themselves.
+// Input: none (types only). Output: the contract each adapters/<name>/platform.ts fills in.
+
+import type { IncomingHttpHeaders } from "node:http";
+
+export type ConnectInfo = {
+ // The local address the platform is pointed at, and the command that starts the plugin's MCP service for it.
+ url: string;
+ mcp: { command: string; args: string[]; env: Record<string, string> };
+};
+
+export type CorePlatform = {
+ // As in routes and data folders: lowercase letters, digits, hyphens.
+ name: string;
+ title: string;
+ // Where its model requests go without the plugin, unless the user names another (`cam connect <name> --base-url`).
+ upstream: string | null;
+ // The session a request belongs to, from the platform's own headers. Without one the engine takes the `x-cam-session`
+ // header a shim of ours may add, else tells sessions apart by their first prompt.
+ sessionOf?: (headers: IncomingHttpHeaders) => string | null;
+ // Requests the platform sends on the side (a title, a prompt suggestion): passed on as they are.
+ sideRequest?: (headers: IncomingHttpHeaders) => boolean;
+ // What the user does to connect it, one step per line (English, as in ADAPTERS.md).
+ connect: (info: ConnectInfo) => string[];
+};
+
+export const headerOf = (headers: IncomingHttpHeaders, name: string): string | null => {
+ const value = headers[name];
+ return (Array.isArray(value) ? value[0] : value) || null;
+};
diff --git a/plugin/src/core/request-index.ts b/plugin/src/core/request-index.ts
new file mode 100644
index 0000000..2b08dc7
--- /dev/null
+++ b/plugin/src/core/request-index.ts
@@ -0,0 +1,94 @@
+// Purpose: v0.11 — what the core keeps of a session on a platform that shows no panel (docs/v0.11/plan.md 3.8): an id
+// for each image its requests carried, in the order they first appeared, and the image itself, so the model can fetch
+// it back by id (cam_view_image). The platform's own records are never read: everything comes from its requests, which
+// send the whole conversation every time. Ids go by content, so the same picture keeps its id wherever it appears.
+// Input/Output: under <data dir>/platforms/<platform>/: sessions/<key>.json, e.g. { "images": { "<content id>":
+// { "id": "IMG-001", "mime": "image/png", "turn": 1, "kind": "upload", "width": 640, "height": 480 } } }; images/<content
+// id>, the image as it was sent; latest.json, the session whose conversation went out last (the one a fetch is about).
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ImageKind } from "./images.ts";
+import { PLATFORM_NAME } from "./routes.ts";
+import { SESSION_KEY } from "./selection.ts";
+
+export type Seen = { id: string; mime: string | null; turn: number; kind: ImageKind; width: number | null; height: number | null };
+export type RequestIndex = { platform: string; key: string; images: Map<string, Seen>; changed: boolean };
+
+const CONTENT_ID = /^[0-9a-f]{64}$/;
+
+export function platformDirOf(root: string, platform: string): string {
+ if (!PLATFORM_NAME.test(platform)) throw new Error(`not a platform name: ${platform}`);
+ return join(root, "platforms", platform);
+}
+
+const sessionFile = (root: string, platform: string, key: string) => {
+ if (!SESSION_KEY.test(key)) throw new Error(`not a session key: ${key}`);
+ return join(platformDirOf(root, platform), "sessions", `${key}.json`);
+};
+
+const writeWhole = (file: string, text: string) => {
+ writeFileSync(`${file}.tmp`, text);
+ renameSync(`${file}.tmp`, file);
+};
+
+export function openRequestIndex(platform: string, key: string, root: string): RequestIndex {
+ const file = sessionFile(root, platform, key);
+ let images = new Map<string, Seen>();
+ try { images = new Map(Object.entries(JSON.parse(readFileSync(file, "utf8")).images ?? {})); } catch { /* a new session */ }
+ return { platform, key, images, changed: false };
+}
+
+// The image's id, given the first time its content is seen (with the turn it was seen in), and the image kept once.
+// `data` is raw base64.
+export function remember(index: RequestIndex, image: { contentId: string; mime: string | null; kind: ImageKind; width: number | null; height: number | null }, data: string, turn: number, root: string): Seen {
+ const known = index.images.get(image.contentId);
+ if (known) return known;
+ const seen: Seen = { id: `IMG-${String(index.images.size + 1).padStart(3, "0")}`, mime: image.mime, turn, kind: image.kind, width: image.width, height: image.height };
+ index.images.set(image.contentId, seen);
+ index.changed = true;
+ if (CONTENT_ID.test(image.contentId)) {
+ const dir = join(platformDirOf(root, index.platform), "images");
+ const file = join(dir, image.contentId);
+ if (!existsSync(file)) {
+ mkdirSync(dir, { recursive: true });
+ writeWhole(file, data);
+ }
+ }
+ return seen;
+}
+
+export function saveRequestIndex(index: RequestIndex, root: string): void {
+ if (!index.changed) return;
+ const file = sessionFile(root, index.platform, index.key);
+ mkdirSync(join(platformDirOf(root, index.platform), "sessions"), { recursive: true });
+ writeWhole(file, JSON.stringify({ images: Object.fromEntries(index.images) }, null, 2));
+ index.changed = false;
+}
+
+// An image by its id: what is known of it and its base64 data (null once its file is gone).
+export function seenImage(index: RequestIndex, id: string, root: string): { seen: Seen; data: string | null } | null {
+ for (const [contentId, seen] of index.images) {
+ if (seen.id !== id) continue;
+ let data: string | null = null;
+ try { data = CONTENT_ID.test(contentId) ? readFileSync(join(platformDirOf(root, index.platform), "images", contentId), "utf8") : null; } catch { /* gone */ }
+ return { seen, data };
+ }
+ return null;
+}
+
+// The session whose conversation request went out last, for the model's fetch (its call follows that request).
+export function markLatest(platform: string, key: string, root: string, now = new Date()): void {
+ const dir = platformDirOf(root, platform);
+ mkdirSync(dir, { recursive: true });
+ writeWhole(join(dir, "latest.json"), JSON.stringify({ key, at: now.toISOString() }));
+}
+
+export function latestSession(platform: string, root: string): string | null {
+ try {
+ const key = JSON.parse(readFileSync(join(platformDirOf(root, platform), "latest.json"), "utf8")).key;
+ return typeof key === "string" && SESSION_KEY.test(key) ? key : null;
+ } catch {
+ return null;
+ }
+}
diff --git a/plugin/src/platforms.ts b/plugin/src/platforms.ts
new file mode 100644
index 0000000..dd9e217
--- /dev/null
+++ b/plugin/src/platforms.ts
@@ -0,0 +1,18 @@
+// Purpose: v0.11 — the platforms the plugin connects (docs/v0.11/plan.md 3.8; ADAPTERS.md). Codex and Claude Code have
+// adapters of their own, with the panel (adapters/codex, adapters/claude). The others use the core alone: their entry
+// (core/platform.ts) is all the engine, the plugin's MCP service and `cam connect` need. A new platform adds its
+// adapters/<name>/platform.ts and one line here. DeepSeek Harness is a dsh plugin of its own (adapters/dsh/plugin.ts),
+// no route, so it is not listed.
+// Input: none. Output: the registry.
+
+import { geminiCli } from "./adapters/gemini-cli/platform.ts";
+import { opencode } from "./adapters/opencode/platform.ts";
+import { pi } from "./adapters/pi/platform.ts";
+import { workbuddy } from "./adapters/workbuddy/platform.ts";
+import type { CorePlatform } from "./core/platform.ts";
+
+export const CORE_PLATFORMS: CorePlatform[] = [workbuddy, opencode, geminiCli, pi];
+export const PANEL_PLATFORMS = ["codex", "claude"] as const;
+
+export const corePlatformOf = (name: string | null | undefined): CorePlatform | null => CORE_PLATFORMS.find((platform) => platform.name === name) ?? null;
+export const isPlatform = (name: unknown): name is string => typeof name === "string" && ((PANEL_PLATFORMS as readonly string[]).includes(name) || !!corePlatformOf(name));
diff --git a/plugin/src/plugin-server.ts b/plugin/src/plugin-server.ts
index 891016a..8eb5757 100644
--- a/plugin/src/plugin-server.ts
+++ b/plugin/src/plugin-server.ts
@@ -49,6 +49,8 @@ import { connectDirectly, useEngine, usesEngine } from "./adapters/codex/setup.t
import { hasRollout, loadThreadIndex, readThreadHistory, sessionMetaOf, sideChatOrigin } from "./adapters/codex/thread-index.ts";
import { setPixelCache } from "./core/pixels.ts";
import { threadTitle } from "./adapters/codex/thread-names.ts";
+import { latestSession, openRequestIndex, seenImage } from "./core/request-index.ts";
+import { corePlatformOf } from "./platforms.ts";
type Json = Record<string, any>;
// Kept fixed: Codex Desktop on Windows may show a blank panel after a resource URI changes (openai/codex#47512).
@@ -113,7 +115,9 @@ export const TOOLS = toolsFor("zh");
// v0.4: under Claude Code only the model's fetch tool is listed. The Claude panel (the mod) reads and changes a
// session's state through the engine (proxy.ts, claudePanelApi): a mod reaches an MCP server only through Claude Code's
// tool permissions, a prompt for every call, and Claude Code registers no app-only tool at all.
-export const HOST: "codex" | "claude" = process.env.CAM_HOST === "claude" ? "claude" : "codex";
+// v0.11: or a platform using the core alone (platforms.ts), named by its MCP configuration (CAM_HOST=workbuddy, …):
+// only the model's fetch tool too.
+export const HOST: string = corePlatformOf(process.env.CAM_HOST) ? process.env.CAM_HOST! : process.env.CAM_HOST === "claude" ? "claude" : "codex";
export const claudeToolsFor = (lang: Lang) => toolsFor(lang).filter((tool) => tool.name === "cam_view_image");
// A stack of pictures, drawn for light and dark themes (Codex takes https or data URLs only).
@@ -287,6 +291,32 @@ export function callClaudeTool(name: string, args: Json, options: ClaudePanelOpt
throw new Error(`unknown tool ${name}`);
}
+// v0.11: the model's fetch tool on a platform using the core alone. The images are the ones the engine kept from the
+// session's requests (core/request-index.ts); the session is the one whose conversation went out last, the request the
+// model's call came from. Automatic selection is always on there.
+export function callPlatformTool(platform: string, name: string, args: Json, root = dataDir()): Json {
+ const lang = langOf(args.lang) ?? currentLang();
+ if (name !== "cam_view_image") throw new Error(`unknown tool ${name}`);
+ const words = fetchWords(lang);
+ const ids: string[] = Array.isArray(args.ids) ? args.ids.map(String) : typeof args.id === "string" ? [args.id] : [];
+ const session = latestSession(platform, root);
+ if (!session) throw new Error(say(lang, "call.noThread"));
+ const index = openRequestIndex(platform, session, root);
+ const content: Json[] = [];
+ const found: string[] = [];
+ for (const asked of ids) {
+ const id = asked.trim().toUpperCase();
+ const image = seenImage(index, id, root);
+ if (!image) { content.push({ type: "text", text: words.missing(asked) }); continue; }
+ if (!image.data) { content.push({ type: "text", text: words.unavailable(id) }); continue; }
+ const { seen } = image;
+ content.push({ type: "text", text: fetchedLabel({ id: seen.id, name: null, label: null, kind: seen.kind, turn: seen.turn, width: seen.width, height: seen.height }, lang) }, { type: "image", data: image.data, mimeType: seen.mime ?? "image/png" });
+ found.push(id);
+ }
+ log({ event: "fetch", host: platform, session, ids, found });
+ return { content, isError: ids.length > 0 && !found.length };
+}
+
function main(): void {
migrateDataOnce(); // v0.1-15: Windows moved the data folder
// v0.6: the panel may read a selection before the engine has started: the same start for both (selection.ts).
@@ -320,7 +350,7 @@ function main(): void {
if (method === "initialize") {
send({ id, result: { protocolVersion: params.protocolVersion ?? "2025-06-18", capabilities: { tools: {}, resources: {} }, serverInfo: serverInfo(currentLang()) } });
} else if (method === "tools/list") {
- send({ id, result: { tools: HOST === "claude" ? claudeToolsFor(currentLang()) : toolsFor(currentLang()) } });
+ send({ id, result: { tools: HOST === "codex" ? toolsFor(currentLang()) : claudeToolsFor(currentLang()) } });
} else if (method === "resources/list") {
send({ id, result: { resources: [{ uri: PANEL_URI, name: say(currentLang(), "resource.name"), mimeType: PANEL_MIME }] } });
} else if (method === "resources/templates/list") {
@@ -335,7 +365,7 @@ function main(): void {
} else if (method === "tools/call") {
const started = performance.now();
try {
- const result = HOST === "claude" ? callClaudeTool(params.name, params.arguments ?? {}) : callTool(params.name, params.arguments ?? {}, params._meta);
+ const result = HOST === "claude" ? callClaudeTool(params.name, params.arguments ?? {}) : HOST === "codex" ? callTool(params.name, params.arguments ?? {}, params._meta) : callPlatformTool(HOST, params.name, params.arguments ?? {});
const ms = Math.round(performance.now() - started);
// The open panel reads its state every few seconds and loads each image once; only changes, and slow calls
// (v0.1-11), are worth a line.
diff --git a/plugin/src/proxy.ts b/plugin/src/proxy.ts
index 351abce..ac96bdd 100644
--- a/plugin/src/proxy.ts
+++ b/plugin/src/proxy.ts
@@ -45,6 +45,9 @@ import { readRoute, registerRoute, routeBaseUrl, routingPort, validateBaseUrl, t
import { buildOf, DEFAULT_PORT, ENGINE_SERVICE, engineHealth, versionOf, watchForClients } from "./engine.ts";
import { currentLang } from "./adapters/codex/language.ts";
import { say } from "./core/messages.ts";
+import { headerOf } from "./core/platform.ts";
+import { formatOf, rewritePlatformRequest } from "./adapters/protocols/any.ts";
+import { corePlatformOf, isPlatform } from "./platforms.ts";
import { ensureAutoDefault, ensureStableIds, selectionDir, stableIdsSince } from "./core/selection.ts";
type Json = Record<string, any>;
@@ -82,10 +85,11 @@ export function routeOf(url: string, headers: IncomingHttpHeaders, root = dataDi
return { host: UPSTREAM_HOST, url };
}
+// v0.11: a platform other than Codex and Claude Code keeps every header but the engine's own (x-cam-).
export function forwardHeaders(headers: IncomingHttpHeaders, upstream = UPSTREAM_HOST, platform?: Platform): Record<string, string | string[]> {
const out: Record<string, string | string[]> = {};
const client = platform ?? (upstream === CLAUDE_HOST ? "claude" : "codex");
- const removed = new Set(client === "claude" ? ["chatgpt-account-id"] : ["anthropic-beta", "anthropic-version", "x-claude-code-session-id", "x-claude-code-agent-id", ...(!platform ? ["x-api-key"] : [])]);
+ const removed = new Set(client === "claude" ? ["chatgpt-account-id"] : client === "codex" ? ["anthropic-beta", "anthropic-version", "x-claude-code-session-id", "x-claude-code-agent-id", ...(!platform ? ["x-api-key"] : [])] : []);
for (const [name, value] of Object.entries(headers)) if (value !== undefined && !HOP_BY_HOP.has(name) && !removed.has(name) && !name.startsWith("x-cam-")) out[name] = value;
out.host = upstream;
return out;
@@ -284,6 +288,7 @@ async function main(): Promise<void> {
try {
if (size > 8192) { res.writeHead(413); res.end(); return; }
const input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+ if (!isPlatform(input.platform)) throw new Error("unknown platform");
validateBaseUrl(input.baseUrl, port);
const route = registerRoute(input);
res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
@@ -350,6 +355,12 @@ async function main(): Promise<void> {
const thinking = claudeSession ? thinkingOf(claudeSession) : null;
const claudeRewrite = claudeNeedsRewrite(claudeSession) || !!thinking?.edited;
const claudeFields = claude ? { claudeSessionId: claude.sessionId, claudeAgentId: claude.agentId } : {};
+ // v0.11: a platform using the core alone (platforms.ts): every model request but its side requests, automatic
+ // selection always on (adapters/protocols/any.ts).
+ const core = corePlatformOf(route.platform);
+ const coreRewrite = !!core && req.method === "POST" && formatOf(path) !== null && !core.sideRequest?.(req.headers);
+ const coreSession = core ? core.sessionOf?.(req.headers) ?? headerOf(req.headers, "x-cam-session") : null;
+ const coreFields = core ? { platform: core.name } : {};
const chunks: Buffer[] = [];
let requestBytes = 0;
let responseBytes = 0;
@@ -382,7 +393,7 @@ async function main(): Promise<void> {
}
} catch { details = { kind: "unparsed" }; }
}
- const entry = { at: new Date(started).toISOString(), id, transport: "http", method: req.method, path, ...(upstream === OPENAI_API_HOST ? { upstream } : {}), status, requestBytes, decodedBytes: decoded?.length ?? null, contentEncoding: req.headers["content-encoding"] ?? null, responseBytes, ms: Date.now() - started, ...identity, ...claudeFields, ...details, ...extra, error: error ?? null };
+ const entry = { at: new Date(started).toISOString(), id, transport: "http", method: req.method, path, ...(upstream === OPENAI_API_HOST ? { upstream } : {}), status, requestBytes, decodedBytes: decoded?.length ?? null, contentEncoding: req.headers["content-encoding"] ?? null, responseBytes, ms: Date.now() - started, ...identity, ...claudeFields, ...coreFields, ...details, ...extra, error: error ?? null };
log(entry);
// Image keys go to the per-thread statistics only, not to the log.
if (/\/responses$/.test(path)) {
@@ -482,13 +493,13 @@ async function main(): Promise<void> {
}
finish(String(error));
}); };
- if (!rewrite && !claudeRewrite) { send([{ body: null, report: null, edited: false }]); return; }
+ if (!rewrite && !claudeRewrite && !coreRewrite) { send([{ body: null, report: null, edited: false }]); return; }
collect();
req.on("end", async () => {
const original = Buffer.concat(chunks);
const encoding = req.headers["content-encoding"] as string | undefined;
const rewriteNow = (): { body: Buffer; report: Json; attempts?: ClaudeAttempt[]; prefix?: SentPrefix } => {
- try { return claudeRewrite ? rewriteClaudeBody(original, encoding, claudeSession!, undefined, undefined, undefined, thinking, sentPrefixes.get(claudeSession!) ?? [], currentLang()) : rewriteBody(original, encoding, identity.threadId!, sessionsDir, selectionDir, identity.turnId, identity.forkedFrom); }
+ try { return coreRewrite ? rewritePlatformRequest(core!.name, path, original, encoding, coreSession, dataDir(), currentLang()) : claudeRewrite ?rewriteClaudeBody(original, encoding, claudeSession!, undefined, undefined, undefined, thinking, sentPrefixes.get(claudeSession!) ?? [], currentLang()) : rewriteBody(original, encoding, identity.threadId!, sessionsDir, selectionDir, identity.turnId, identity.forkedFrom); }
catch (error) { return { body: original, report: { skipped: `rewrite failed: ${String(error)}` } }; }
};
let out = rewriteNow();
diff --git a/spike/src/contract.test.ts b/spike/src/contract.test.ts
index 3e51ec1..ebbf665 100644
--- a/spike/src/contract.test.ts
+++ b/spike/src/contract.test.ts
@@ -8,6 +8,8 @@ import test from "node:test";
import { imageBlocks, rewriteBlocks, type RequestImage } from "../../plugin/src/adapters/protocols/anthropic-messages/rewrite.ts";
import { findImages, type ImageRef } from "../../plugin/src/adapters/protocols/openai-responses/images.ts";
import { rewriteItems } from "../../plugin/src/adapters/protocols/openai-responses/rewrite.ts";
+import { chatImages, rewriteChat } from "../../plugin/src/adapters/protocols/openai-chat/rewrite.ts";
+import { geminiImages, rewriteGemini } from "../../plugin/src/adapters/protocols/gemini/rewrite.ts";
import type { RewriteReport } from "../../plugin/src/core/plan.ts";
import { featureNote, type Described } from "../../plugin/src/core/words.ts";
import { image, pngA, pngB, text, usualRequest } from "./claude-fixtures.ts";
@@ -66,6 +68,39 @@ const TRANSLATORS: Translator[] = [
},
images: (body) => count(body, (node) => node.type === "image"),
},
+ {
+ name: "openai-chat",
+ sample: () => [
+ { role: "system", content: "instructions" },
+ { role: "user", content: [{ type: "text", text: "两张图" }, { type: "image_url", image_url: { url: url(red), detail: "high" } }, { type: "image_url", image_url: { url: url(blue) } }] },
+ { role: "assistant", content: "收到", tool_calls: [{ id: "c1", type: "function", function: { name: "look", arguments: "{}" } }] },
+ { role: "tool", tool_call_id: "c1", content: [{ type: "text", text: "done" }, { type: "image_url", image_url: { url: url(png(4, 4, () => [9, 9, 9])) } }] },
+ ],
+ keys: (body) => chatImages(body).images.map((image) => image.key),
+ rewrite: (body, leaveOut, { lang, features }) => {
+ const { images } = chatImages(body);
+ const describe = describedBy(images.map((image) => image.key), (key) => { const image = images.find((one) => one.key === key)!; return { name: null, label: null, kind: image.kind, width: image.width, height: image.height }; });
+ const out = rewriteChat(body, images, (image) => describe(image.key), leaveOut, () => null, { lang, features });
+ return { body: out.messages, report: out.report };
+ },
+ images: (body) => count(body, (node) => node.type === "image_url"),
+ },
+ {
+ name: "gemini",
+ sample: () => [
+ { role: "user", parts: [{ text: "两张图" }, { inlineData: { mimeType: "image/png", data: red.toString("base64") } }, { inlineData: { mimeType: "image/png", data: blue.toString("base64") } }] },
+ { role: "model", parts: [{ text: "收到" }, { functionCall: { name: "look", args: {} } }] },
+ { role: "user", parts: [{ functionResponse: { name: "look", response: { output: "done" } } }, { inlineData: { mimeType: "image/png", data: png(4, 4, () => [9, 9, 9]).toString("base64") } }] },
+ ],
+ keys: (body) => geminiImages(body).images.map((image) => image.key),
+ rewrite: (body, leaveOut, { lang, features }) => {
+ const { images } = geminiImages(body);
+ const describe = describedBy(images.map((image) => image.key), (key) => { const image = images.find((one) => one.key === key)!; return { name: null, label: null, kind: image.kind, width: image.width, height: image.height }; });
+ const out = rewriteGemini(body, images, (image) => describe(image.key), leaveOut, () => null, { lang, features });
+ return { body: out.contents, report: out.report };
+ },
+ images: (body) => count(body, (node) => !!node.inlineData),
+ },
];
for (const translator of TRANSLATORS) {
@@ -94,7 +129,7 @@ for (const translator of TRANSLATORS) {
const { body: out } = translator.rewrite(marked(), all(marked()), { lang: "en", features: true });
const original = marked();
for (const entry of original) {
- const same = out.find((candidate) => JSON.stringify({ ...candidate, content: null, output: null }) === JSON.stringify({ ...entry, content: null, output: null }));
+ const same = out.find((candidate) => JSON.stringify({ ...candidate, content: null, output: null, parts: null }) === JSON.stringify({ ...entry, content: null, output: null, parts: null }));
assert.ok(same, "every entry is still there with its other fields");
}
});
diff --git a/spike/src/platforms.test.ts b/spike/src/platforms.test.ts
new file mode 100644
index 0000000..51e246f
--- /dev/null
+++ b/spike/src/platforms.test.ts
@@ -0,0 +1,181 @@
+// Purpose: v0.11 — platforms that use the core alone, without a panel (docs/v0.11/plan.md 3.8): the engine's rewrite
+// of their requests in each format (automatic selection always on, ids that stay from request to request, a fetched copy
+// sent in its own turn only), the session a request belongs to, the model's fetch tool, the registry and routes.
+// Input: synthetic requests in a temporary data folder. Output: test results.
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { formatOf, rewritePlatformRequest, sessionOfRequest } from "../../plugin/src/adapters/protocols/any.ts";
+import { workbuddy } from "../../plugin/src/adapters/workbuddy/platform.ts";
+import { latestSession } from "../../plugin/src/core/request-index.ts";
+import { readRoute, registerRoute } from "../../plugin/src/core/routes.ts";
+import { corePlatformOf, isPlatform } from "../../plugin/src/platforms.ts";
+import { callPlatformTool } from "../../plugin/src/plugin-server.ts";
+import { forwardHeaders } from "../../plugin/src/proxy.ts";
+import { png } from "./testkit.ts";
+
+type Json = Record<string, any>;
+const red = png(4, 4, () => [255, 0, 0]).toString("base64");
+const blue = png(4, 4, () => [0, 0, 255]).toString("base64");
+const green = png(4, 4, () => [0, 255, 0]).toString("base64");
+const root = () => mkdtempSync(join(tmpdir(), "cam-platforms-"));
+const send = (platform: string, path: string, body: Json, data: string, session: string | null = "conv-1") => {
+ const out = rewritePlatformRequest(platform, path, Buffer.from(JSON.stringify(body)), undefined, session, data, "en");
+ return { json: JSON.parse(out.body.toString("utf8")) as Json, report: out.report, session: out.session };
+};
+const texts = (value: unknown): string[] => {
+ if (Array.isArray(value)) return value.flatMap(texts);
+ if (!value || typeof value !== "object") return [];
+ const node = value as Json;
+ return [...(typeof node.text === "string" ? [node.text] : []), ...Object.values(node).flatMap(texts)];
+};
+
+// Chat Completions, as WorkBuddy sends it.
+const chatUrl = (data: string) => ({ type: "image_url", image_url: { url: `data:image/png;base64,${data}` } });
+const chatTurns = (n: number): Json[] => {
+ const turns: Json[][] = [
+ [{ role: "user", content: [{ type: "text", text: "first look" }, chatUrl(red)] }, { role: "assistant", content: "a red square" }],
+ [{ role: "user", content: [{ type: "text", text: "and this" }, chatUrl(blue)] }, { role: "assistant", content: "a blue square" }],
+ [{ role: "user", content: [{ type: "text", text: "compare with the first" }] }, { role: "assistant", content: null, tool_calls: [{ id: "f1", type: "function", function: { name: "cam_view_image", arguments: "{\"ids\":[\"IMG-001\"]}" } }] },
+ { role: "tool", tool_call_id: "f1", content: [{ type: "text", text: "[Image IMG-001 fetched original | user upload | turn 1 | 4×4]" }, chatUrl(red)] }, { role: "assistant", content: "same red" }],
+ [{ role: "user", content: [{ type: "text", text: "thanks" }, chatUrl(green)] }],
+ ];
+ return [{ role: "system", content: "rules" }, ...turns.slice(0, n).flat()];
+};
+const chat = (n: number) => ({ model: "m", stream: true, tools: [{ type: "function", function: { name: "cam_view_image" } }], messages: chatTurns(n) });
+
+test("the format is told by the path", () => {
+ assert.equal(formatOf("/v2/chat/completions"), "openai-chat");
+ assert.equal(formatOf("/v1/messages"), "anthropic-messages");
+ assert.equal(formatOf("/v1/responses"), "openai-responses");
+ assert.equal(formatOf("/v1beta/models/gemini-3-pro:streamGenerateContent"), "gemini");
+ assert.equal(formatOf("/v1internal:generateContent"), "gemini");
+ assert.equal(formatOf("/v1/models"), null);
+});
+
+test("chat completions: earlier turns' images become placeholders; this turn's stay; the ids stay from request to request", () => {
+ const data = root();
+ const one = send("workbuddy", "/v2/chat/completions", chat(1), data);
+ assert.deepEqual(one.report.replaced, [], "nothing earlier yet");
+ assert.equal(JSON.stringify(one.json), JSON.stringify(chat(1)), "the request goes out as it came");
+ const two = send("workbuddy", "/v2/chat/completions", chat(2), data);
+ assert.deepEqual(two.report.replaced.map((entry: Json) => entry.id), ["IMG-001"]);
+ const turn1 = two.json.messages[1].content;
+ assert.ok(turn1.every((part: Json) => part.type === "text"), "the red image is gone");
+ assert.ok(turn1.some((part: Json) => /IMG-001/.test(part.text) && /omitted/.test(part.text)), "its placeholder names it");
+ assert.ok(turn1.some((part: Json) => /cam_view_image/.test(part.text)), "the note says how to fetch it");
+ assert.equal(two.json.messages[3].content[1].type, "image_url", "this turn's image is sent");
+ const four = send("workbuddy", "/v2/chat/completions", chat(4), data);
+ assert.deepEqual(four.report.replaced.map((entry: Json) => entry.id), ["IMG-001", "IMG-002"], "the same ids as before");
+ assert.deepEqual(four.report.copies, ["IMG-001"], "the copy fetched in turn 3 is a short note now");
+ const tool = four.json.messages.find((message: Json) => message.role === "tool");
+ assert.ok(tool.content.every((part: Json) => part.type === "text"), "no image left in the tool result");
+ assert.equal(four.json.messages.at(-1).content[1].type, "image_url", "the new green image is sent");
+});
+
+test("chat completions: a copy the model fetched is sent in its own turn", () => {
+ const data = root();
+ send("workbuddy", "/v2/chat/completions", chat(2), data);
+ const three = send("workbuddy", "/v2/chat/completions", chat(3), data);
+ const tool = three.json.messages.find((message: Json) => message.role === "tool");
+ assert.equal(tool.content[1].type, "image_url", "the fetched copy goes out");
+ assert.deepEqual(three.report.replaced.map((entry: Json) => entry.id), ["IMG-001", "IMG-002"]);
+});
+
+test("the fetch tool returns the image by id from the session sent last", () => {
+ const data = root();
+ send("workbuddy", "/v2/chat/completions", chat(2), data);
+ assert.ok(latestSession("workbuddy", data));
+ const result = callPlatformTool("workbuddy", "cam_view_image", { ids: ["IMG-001", "img-002", "IMG-009"], lang: "en" }, data);
+ assert.equal(result.isError, false);
+ const images = result.content.filter((part: Json) => part.type === "image");
+ assert.deepEqual(images.map((part: Json) => part.data), [red, blue]);
+ assert.ok(/^\[Image IMG-001 fetched original/.test(result.content[0].text), "each after the line naming it, so the next request knows it as a copy");
+ assert.ok(result.content.some((part: Json) => part.type === "text" && /IMG-009/.test(part.text)), "an unknown id is said so");
+ assert.throws(() => callPlatformTool("opencode", "cam_view_image", { ids: ["IMG-001"] }, data), "another platform has no session there");
+});
+
+test("a request without tools (a side request) does not move the session a fetch is about", () => {
+ const data = root();
+ send("workbuddy", "/v2/chat/completions", chat(2), data, "conv-1");
+ const before = latestSession("workbuddy", data);
+ send("workbuddy", "/v2/chat/completions", { model: "m", messages: chatTurns(1) }, data, "conv-2");
+ assert.equal(latestSession("workbuddy", data), before);
+});
+
+test("sessions: named by the platform's header, else by the first prompt", () => {
+ assert.equal(workbuddy.sessionOf!({ "x-conversation-id": "0199-abc" }), "0199-abc");
+ assert.equal(workbuddy.sideRequest!({ "x-agent-type": "auxiliary" }), true);
+ assert.equal(workbuddy.sideRequest!({ "x-agent-type": "main" }), false);
+ assert.notEqual(sessionOfRequest("workbuddy", "a", ""), sessionOfRequest("opencode", "a", ""), "each platform its own");
+ assert.equal(sessionOfRequest("opencode", null, "hello"), sessionOfRequest("opencode", null, "hello"));
+ assert.notEqual(sessionOfRequest("opencode", null, "hello"), sessionOfRequest("opencode", null, "other"));
+ assert.equal(sessionOfRequest("opencode", null, " "), null);
+ const data = root();
+ const first = send("opencode", "/v1/chat/completions", chat(2), data, null);
+ const later = send("opencode", "/v1/chat/completions", chat(4), data, null);
+ assert.equal(first.session, later.session, "the same conversation, longer");
+});
+
+// Gemini, as Gemini CLI sends it (and wrapped in `request` when signed in with Google).
+const inline = (data: string) => ({ inlineData: { mimeType: "image/png", data } });
+const gemini = () => ({
+ contents: [
+ { role: "user", parts: [{ text: "first look" }, inline(red)] },
+ { role: "model", parts: [{ text: "a red square" }, { functionCall: { name: "read", args: {} } }] },
+ { role: "user", parts: [{ functionResponse: { name: "read", response: { ok: true } } }, inline(blue)] },
+ { role: "model", parts: [{ text: "and a blue one" }] },
+ { role: "user", parts: [{ text: "which was first?" }] },
+ ],
+ tools: [{ functionDeclarations: [{ name: "read" }] }],
+});
+
+test("gemini: the images of turn 1, a tool's one included, become placeholders in turn 2; Code Assist's wrapping too", () => {
+ for (const wrap of [(body: Json) => body, (body: Json) => ({ model: "m", project: "p", request: body })]) {
+ const data = root();
+ const out = send("gemini-cli", "/v1beta/models/gemini-3-pro:streamGenerateContent", wrap(gemini()), data);
+ assert.deepEqual(out.report.replaced.map((entry: Json) => entry.id), ["IMG-001", "IMG-002"]);
+ const contents = out.json.contents ?? out.json.request.contents;
+ assert.equal(contents.flatMap((content: Json) => content.parts).filter((part: Json) => part.inlineData).length, 0);
+ assert.ok(contents[2].parts[0].functionResponse, "the function response stays first");
+ }
+});
+
+test("anthropic messages and responses: the same rule on a platform without a panel", () => {
+ const data = root();
+ const image = (b64: string) => ({ type: "image", source: { type: "base64", media_type: "image/png", data: b64 } });
+ const messages = { model: "m", tools: [{ name: "t" }], messages: [
+ { role: "user", content: [{ type: "text", text: "look" }, image(red)] },
+ { role: "assistant", content: [{ type: "text", text: "red" }] },
+ { role: "user", content: [{ type: "text", text: "and now" }, image(blue)] },
+ ] };
+ const m = send("opencode", "/v1/messages", messages, data, "s1");
+ assert.deepEqual(m.report.replaced.map((entry: Json) => entry.id), ["IMG-001"]);
+ assert.equal(m.json.messages.filter((message: Json) => message.role !== "system").at(-1).content[1].type, "image");
+ const url = (b64: string) => `data:image/png;base64,${b64}`;
+ const responses = { model: "m", tools: [{ type: "function", name: "t" }], input: [
+ { type: "message", role: "user", content: [{ type: "input_text", text: "look" }, { type: "input_image", image_url: url(red) }] },
+ { type: "message", role: "assistant", content: [{ type: "output_text", text: "red" }] },
+ { type: "message", role: "user", content: [{ type: "input_text", text: "and now" }, { type: "input_image", image_url: url(blue) }] },
+ ] };
+ const r = send("pi", "/v1/responses", responses, data, "s2");
+ assert.deepEqual(r.report.replaced.map((entry: Json) => entry.id), ["IMG-001"]);
+});
+
+test("registry, routes and headers for a platform without a panel", () => {
+ assert.equal(isPlatform("workbuddy"), true);
+ assert.equal(isPlatform("codex"), true);
+ assert.equal(isPlatform("antigravity"), false);
+ assert.equal(corePlatformOf("codex"), null, "Codex has its own adapter");
+ const data = root();
+ const route = registerRoute({ platform: "workbuddy", baseUrl: "https://www.workbuddy.cn/v2" }, data);
+ assert.equal(readRoute(route.id, data)?.platform, "workbuddy");
+ assert.throws(() => registerRoute({ platform: "Not A Name", baseUrl: "https://x.example" }, data));
+ const headers = forwardHeaders({ "anthropic-version": "2023-06-01", "x-api-key": "k", "x-cam-session": "s", "x-conversation-id": "c" }, "api.anthropic.com", "opencode");
+ assert.equal(headers["anthropic-version"], "2023-06-01", "kept: the platform's provider may need it");
+ assert.equal(headers["x-api-key"], "k");
+ assert.equal(headers["x-cam-session"], undefined, "the engine's own header stops here");
+ assert.equal(headers["x-conversation-id"], "c");
+});