pi-freeflow 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.19.0
+
+### Minor Changes
+
+- Every tool your agent can use now works on every free model: the proxy translates tool definitions between chat, responses, and messages formats automatically, so built-in tools, MCP server tools, and custom tools all pass through intact on all request types. Strict tool schemas are preserved, and requests sent in one format to another endpoint are converted instead of rejected.
+
 ## 1.18.0
 
 ### Minor Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -10,11 +10,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import {
-	getAliveCatalog,
-	mergeCatalog,
-	readCatalogCache,
-	refreshCatalog,
-	setAliveCatalog,
+ getAliveCatalog,
+ mergeCatalog,
+ readCatalogCache,
+ refreshCatalog,
+ setAliveCatalog,
 } from "./catalog.ts";
 import { ensureDaemon as ensureClientDaemon, ensureProxyReady, getClientPort, hasFallbackServer, stopHeartbeat } from "./client.ts";
 import { createCommandSpec, stopLogsFollow, updateStatusBar } from "./commands.ts";
@@ -23,20 +23,20 @@ import { logInfo, logWarn } from "./logger.ts";
 import { ALL_MODELS, KILO_MODEL_IDS, MODEL_MAP, resolveCanonicalModelId } from "./models.ts";
 import { checkForUpdateInBackground } from "./update-checker.ts";
 import {
-	ensureRelay,
-	getActiveRelayState,
-	resolveRelayState,
-	setActiveRelayState,
-	setStatusUi,
-	setFreeFlowModelActive,
-	shortRelayLabel,
+ ensureRelay,
+ getActiveRelayState,
+ resolveRelayState,
+ setActiveRelayState,
+ setStatusUi,
+ setFreeFlowModelActive,
+ shortRelayLabel,
 } from "./relay-state.ts";
 import type {
-	ExtensionAPI,
-	ExtensionContext,
-	ExtensionUIContext,
-	ProviderConfig,
-	RegisteredModel,
+ ExtensionAPI,
+ ExtensionContext,
+ ExtensionUIContext,
+ ProviderConfig,
+ RegisteredModel,
 } from "./types.ts";
 
 // Re-export all sub-modules for clean library and programmatic usage
@@ -50,6 +50,7 @@ export * from "./relay.ts";
 export * from "./deploy.ts";
 export * from "./stream-pipe.ts";
 export * from "./proxy.ts";
+export * from "./tool-translation.ts";
 export * from "./commands.ts";
 /**
  * Bind widget click to relay picker when host supports it.
@@ -57,48 +58,48 @@ export * from "./commands.ts";
  * Falls back to no-op; status hint already tells user to use `/freeflow use`.
  */
 export function bindWidgetClick(ui: ExtensionUIContext): void {
-	const anyUi = ui as unknown as Record<string, unknown>;
-	const candidates = ["onStatusClick", "onStatusBarClick", "onWidgetClick"] as const;
-	let clickFn: ((h: () => void | Promise<void>) => unknown) | undefined;
-	for (const name of candidates) {
-		const v = anyUi[name];
-		if (typeof v === "function") {
-			clickFn = v as (h: () => void | Promise<void>) => unknown;
-			break;
-		}
-	}
-	if (!clickFn) return;
-	try {
-		clickFn.call(anyUi, async () => {
-			try {
-				const state = getActiveRelayState();
-				if (!state.relays.length) {
-					ui.notify("Use /freeflow use — no relays saved. Add one with /freeflow add <URL>", "info");
-					return;
-				}
-				const fmt = (r: { url: string; label?: string }, idx: number) => {
-					const isAct = r.url === state.url ? "★ " : "  ";
-					const lbl = r.label ? `[${r.label}] ` : `[${shortRelayLabel(r.url, state.relays)}] `;
-					return `${isAct}[${idx + 1}] ${lbl}→ ${r.url}`;
-				};
-				const opts = state.relays.map(fmt);
-				const choice = await ui.select("Switch active relay", opts);
-				if (!choice) return;
-				const idx = opts.indexOf(choice);
-				const match = idx >= 0 ? state.relays[idx] : undefined;
-				// Fallback find by formatting match
-				const resolved = match ?? state.relays.find((r, i) => fmt(r, i) === choice);
-				if (!resolved) return;
-				state.enabled = true;
-				state.url = resolved.url;
-				ensureRelay(state, resolved.url, resolved.label);
-				setActiveRelayState(state);
-				setStatusUi(ui);
-				updateStatusBar(ui);
-				ui.notify(`Relay active: ${resolved.label || shortRelayLabel(resolved.url, state.relays)}`, "info");
-			} catch {}
-		});
-	} catch {}
+ const anyUi = ui as unknown as Record<string, unknown>;
+ const candidates = ["onStatusClick", "onStatusBarClick", "onWidgetClick"] as const;
+ let clickFn: ((h: () => void | Promise<void>) => unknown) | undefined;
+ for (const name of candidates) {
+  const v = anyUi[name];
+  if (typeof v === "function") {
+   clickFn = v as (h: () => void | Promise<void>) => unknown;
+   break;
+  }
+ }
+ if (!clickFn) return;
+ try {
+  clickFn.call(anyUi, async () => {
+   try {
+    const state = getActiveRelayState();
+    if (!state.relays.length) {
+     ui.notify("Use /freeflow use — no relays saved. Add one with /freeflow add <URL>", "info");
+     return;
+    }
+    const fmt = (r: { url: string; label?: string }, idx: number) => {
+     const isAct = r.url === state.url ? "★ " : "  ";
+     const lbl = r.label ? `[${r.label}] ` : `[${shortRelayLabel(r.url, state.relays)}] `;
+     return `${isAct}[${idx + 1}] ${lbl}→ ${r.url}`;
+    };
+    const opts = state.relays.map(fmt);
+    const choice = await ui.select("Switch active relay", opts);
+    if (!choice) return;
+    const idx = opts.indexOf(choice);
+    const match = idx >= 0 ? state.relays[idx] : undefined;
+    // Fallback find by formatting match
+    const resolved = match ?? state.relays.find((r, i) => fmt(r, i) === choice);
+    if (!resolved) return;
+    state.enabled = true;
+    state.url = resolved.url;
+    ensureRelay(state, resolved.url, resolved.label);
+    setActiveRelayState(state);
+    setStatusUi(ui);
+    updateStatusBar(ui);
+    ui.notify(`Relay active: ${resolved.label || shortRelayLabel(resolved.url, state.relays)}`, "info");
+   } catch { }
+  });
+ } catch { }
 }
 
 
@@ -106,249 +107,249 @@ export function bindWidgetClick(ui: ExtensionUIContext): void {
  * Construct standard ProviderConfig for pi-ai / OMP registration.
  */
 export function buildProviderConfig(
-	models: RegisteredModel[],
-	port: number = PORT,
+ models: RegisteredModel[],
+ port: number = PORT,
 ): ProviderConfig {
-	return {
-		baseUrl: `http://${HOST}:${port}/v1`,
-		apiKey: "public",
-		api: "openai-completions",
-		compat: { supportsDeveloperRole: false },
-		models: models.map((m) => {
-			const efforts = m.thinkingLevelMap
-				? (Object.keys(m.thinkingLevelMap) as (keyof typeof m.thinkingLevelMap)[]).filter(
-						(k) => m.thinkingLevelMap![k] !== null && k !== "off",
-					)
-				: ["minimal", "low", "medium", "high", "xhigh"];
+ return {
+  baseUrl: `http://${HOST}:${port}/v1`,
+  apiKey: "public",
+  api: "openai-completions",
+  compat: { supportsDeveloperRole: false },
+  models: models.map((m) => {
+   const efforts = m.thinkingLevelMap
+    ? (Object.keys(m.thinkingLevelMap) as (keyof typeof m.thinkingLevelMap)[]).filter(
+     (k) => m.thinkingLevelMap![k] !== null && k !== "off",
+    )
+    : ["minimal", "low", "medium", "high", "xhigh"];
 
-			return {
-				id: m.id,
-				name: m.name,
-				api: m.api,
-				reasoning: m.reasoning,
-				thinking: m.reasoning
-					? {
-							mode: "effort",
-							efforts: efforts.length > 0 ? efforts : ["low", "high", "max"],
-						}
-					: undefined,
-				thinkingLevelMap: m.thinkingLevelMap,
-				input: m.input ?? ["text"],
-				contextWindow: m.contextWindow,
-				maxTokens: m.maxTokens,
-				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-				compat: m.thinkingFormat
-					? {
-							supportsDeveloperRole: false,
-							thinkingFormat: m.thinkingFormat,
-						}
-					: m.api === "openai-responses"
-						? { sessionAffinityFormat: "openai-nosession" }
-						: m.source === "kilo"
-							? {
-									supportsDeveloperRole: false,
-									supportsReasoningEffort: !!m.thinkingLevelMap,
-								}
-							: {
-									supportsDeveloperRole: false,
-									supportsReasoningEffort: true,
-								},
-			};
-		}),
-	};
+   return {
+    id: m.id,
+    name: m.name,
+    api: m.api,
+    reasoning: m.reasoning,
+    thinking: m.reasoning
+     ? {
+      mode: "effort",
+      efforts: efforts.length > 0 ? efforts : ["low", "high", "max"],
+     }
+     : undefined,
+    thinkingLevelMap: m.thinkingLevelMap,
+    input: m.input ?? ["text"],
+    contextWindow: m.contextWindow,
+    maxTokens: m.maxTokens,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: m.thinkingFormat
+     ? {
+      supportsDeveloperRole: false,
+      thinkingFormat: m.thinkingFormat,
+     }
+     : m.api === "openai-responses"
+      ? { sessionAffinityFormat: "openai-nosession" }
+      : m.source === "kilo"
+       ? {
+        supportsDeveloperRole: false,
+        supportsReasoningEffort: !!m.thinkingLevelMap,
+       }
+       : {
+        supportsDeveloperRole: false,
+        supportsReasoningEffort: true,
+       },
+   };
+  }),
+ };
 }
 /**
  * Main extension entrypoint
  */
-export default async function (pi: ExtensionAPI): Promise<void> {
-	logInfo("pi-freeflow extension initializing...");
+export default async function(pi: ExtensionAPI): Promise<void> {
+ logInfo("pi-freeflow extension initializing...");
 
-	let actualPort: number;
-	try {
-		actualPort = await ensureClientDaemon();
-	} catch (e) {
-		logWarn("daemon ensure failed — using configured port", { error: String(e) });
-		actualPort = getClientPort();
-	}
-	// Register static models immediately on boot so Pi/OMP picker is populated with zero latency!
-	const registeredCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
-		...m,
-		source: KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode",
-	}));
-	setAliveCatalog(registeredCatalog);
-	const registerCatalog = (models: RegisteredModel[]): void => {
+ let actualPort: number;
+ try {
+  actualPort = await ensureClientDaemon();
+ } catch (e) {
+  logWarn("daemon ensure failed — using configured port", { error: String(e) });
+  actualPort = getClientPort();
+ }
+ // Register static models immediately on boot so Pi/OMP picker is populated with zero latency!
+ const registeredCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
+  ...m,
+  source: KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode",
+ }));
+ setAliveCatalog(registeredCatalog);
+ const registerCatalog = (models: RegisteredModel[]): void => {
 
-		pi.registerProvider(
-			"freeflow",
-			buildProviderConfig(models, actualPort),
-		);
-	};
-	const ensureDaemon = async (ui?: ExtensionUIContext): Promise<void> => {
-		const reattach = (port: number): void => {
-			if (port !== actualPort) {
-				actualPort = port;
-				registerCatalog(getAliveCatalog());
-				logInfo(`Re-attached to proxy daemon on http://${HOST}:${port}`);
-			}
-		};
-		try {
-			reattach(await ensureClientDaemon());
-			// Health probe before requests: one bounded respawn retry, then an
-			// explicit proxy-down notice instead of per-model connect failures.
-			const ready = await ensureProxyReady(actualPort);
-			if (!ready.ok) {
-				logWarn(ready.reason);
-				try {
-					ui?.notify?.(ready.reason, "error");
-				} catch {}
-			} else {
-				reattach(ready.port);
-			}
-		} catch (e) {
-			logWarn("proxy daemon re-attach failed", { error: String(e) });
-		}
-	};
+  pi.registerProvider(
+   "freeflow",
+   buildProviderConfig(models, actualPort),
+  );
+ };
+ const ensureDaemon = async (ui?: ExtensionUIContext): Promise<void> => {
+  const reattach = (port: number): void => {
+   if (port !== actualPort) {
+    actualPort = port;
+    registerCatalog(getAliveCatalog());
+    logInfo(`Re-attached to proxy daemon on http://${HOST}:${port}`);
+   }
+  };
+  try {
+   reattach(await ensureClientDaemon());
+   // Health probe before requests: one bounded respawn retry, then an
+   // explicit proxy-down notice instead of per-model connect failures.
+   const ready = await ensureProxyReady(actualPort);
+   if (!ready.ok) {
+    logWarn(ready.reason);
+    try {
+     ui?.notify?.(ready.reason, "error");
+    } catch { }
+   } else {
+    reattach(ready.port);
+   }
+  } catch (e) {
+   logWarn("proxy daemon re-attach failed", { error: String(e) });
+  }
+ };
 
-	// 4. Background Catalog Refresh
-	// Asynchronously probe live upstreams and update the provider if alive model list changes
-	refreshCatalog(false)
-		.then((aliveModels) => {
-			if (aliveModels.length > 0) {
-				setAliveCatalog(aliveModels);
-				registerCatalog(mergeCatalog(registeredCatalog, aliveModels));
-				logInfo(
-					`Catalog refreshed: ${aliveModels.length} models verified active`,
-				);
-			}
-		})
-		.catch((err) => {
-			logWarn("Background catalog refresh failed; retaining static catalog", {
-				error: String(err),
-			});
-		});
+ // 4. Background Catalog Refresh
+ // Asynchronously probe live upstreams and update the provider if alive model list changes
+ refreshCatalog(false)
+  .then((aliveModels) => {
+   if (aliveModels.length > 0) {
+    setAliveCatalog(aliveModels);
+    registerCatalog(mergeCatalog(registeredCatalog, aliveModels));
+    logInfo(
+     `Catalog refreshed: ${aliveModels.length} models verified active`,
+    );
+   }
+  })
+  .catch((err) => {
+   logWarn("Background catalog refresh failed; retaining static catalog", {
+    error: String(err),
+   });
+  });
 
-	// 5. Register slash command
-	const commandSpec = createCommandSpec(pi, (updatedModels) => {
-		registerCatalog(updatedModels);
-	});
-	pi.registerCommand("freeflow", commandSpec);
+ // 5. Register slash command
+ const commandSpec = createCommandSpec(pi, (updatedModels) => {
+  registerCatalog(updatedModels);
+ });
+ pi.registerCommand("freeflow", commandSpec);
 
-	// 6. Lifecycle Listeners
-	function isFreeFlowModelMatch(provider?: string, modelId?: string): boolean {
-		if (provider === "freeflow") return true;
-		if (typeof modelId === "string" && modelId.trim()) {
-			const clean = modelId.trim();
-			const canonical = resolveCanonicalModelId(clean);
-			return (
-				MODEL_MAP.has(clean) ||
-				MODEL_MAP.has(canonical) ||
-				getAliveCatalog().some((m) => m.id === clean || m.id === canonical)
-			);
-		}
-		// When provider and modelId are not yet populated on session_start,
-		// default to true so the widget is present when starting with freeflow
-		if (!provider && !modelId) {
-			return true;
-		}
-		return false;
-	}
+ // 6. Lifecycle Listeners
+ function isFreeFlowModelMatch(provider?: string, modelId?: string): boolean {
+  if (provider === "freeflow") return true;
+  if (typeof modelId === "string" && modelId.trim()) {
+   const clean = modelId.trim();
+   const canonical = resolveCanonicalModelId(clean);
+   return (
+    MODEL_MAP.has(clean) ||
+    MODEL_MAP.has(canonical) ||
+    getAliveCatalog().some((m) => m.id === clean || m.id === canonical)
+   );
+  }
+  // When provider and modelId are not yet populated on session_start,
+  // default to true so the widget is present when starting with freeflow
+  if (!provider && !modelId) {
+   return true;
+  }
+  return false;
+ }
 
-	pi.on?.("session_start", async (_event, ctx: ExtensionContext) => {
-		await ensureDaemon(ctx.ui);
-		const freshRelayState = resolveRelayState();
-		setStatusUi(ctx.ui);
-		try { bindWidgetClick(ctx.ui); } catch {}
+ pi.on?.("session_start", async (_event, ctx: ExtensionContext) => {
+  await ensureDaemon(ctx.ui);
+  const freshRelayState = resolveRelayState();
+  setStatusUi(ctx.ui);
+  try { bindWidgetClick(ctx.ui); } catch { }
 
-		// First-run onboarding: write the flag before notifying so a crash can
-		// never re-fire the message; never block session start.
-		try {
-			if (!fs.existsSync(ONBOARDED_FLAG_FILE)) {
-				fs.mkdirSync(path.dirname(ONBOARDED_FLAG_FILE), { recursive: true });
-				fs.writeFileSync(ONBOARDED_FLAG_FILE, "1", "utf8");
-				const hint =
-					freshRelayState.relays.length > 0
-						? `Relay pool ready: ${freshRelayState.relays.length} relay(s). Run /freeflow for pool management.`
-						: "Relay pool empty — direct mode. Run /freeflow deploy to add your own egress.";
-				ctx.ui?.notify?.(
-					`freeflow ready: ${ALL_MODELS.length} free models via local proxy 127.0.0.1:28180. ${hint}`,
-					"info",
-				);
-			}
-		} catch {}
+  // First-run onboarding: write the flag before notifying so a crash can
+  // never re-fire the message; never block session start.
+  try {
+   if (!fs.existsSync(ONBOARDED_FLAG_FILE)) {
+    fs.mkdirSync(path.dirname(ONBOARDED_FLAG_FILE), { recursive: true });
+    fs.writeFileSync(ONBOARDED_FLAG_FILE, "1", "utf8");
+    const hint =
+     freshRelayState.relays.length > 0
+      ? `Relay pool ready: ${freshRelayState.relays.length} relay(s). Run /freeflow for pool management.`
+      : "Relay pool empty — direct mode. Run /freeflow deploy to add your own egress.";
+    ctx.ui?.notify?.(
+     `freeflow ready: ${ALL_MODELS.length} free models via local proxy 127.0.0.1:28180. ${hint}`,
+     "info",
+    );
+   }
+  } catch { }
 
-		let provider: string | undefined;
-		let modelId: string | undefined;
-		if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {
-			const m = ctx.model;
-			if ("provider" in m && typeof m.provider === "string") {
-				provider = m.provider;
-			}
-			if ("id" in m && typeof m.id === "string") {
-				modelId = m.id;
-			}
-		}
-		const isFreeFlow = isFreeFlowModelMatch(provider, modelId);
-		setFreeFlowModelActive(isFreeFlow);
+  let provider: string | undefined;
+  let modelId: string | undefined;
+  if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {
+   const m = ctx.model;
+   if ("provider" in m && typeof m.provider === "string") {
+    provider = m.provider;
+   }
+   if ("id" in m && typeof m.id === "string") {
+    modelId = m.id;
+   }
+  }
+  const isFreeFlow = isFreeFlowModelMatch(provider, modelId);
+  setFreeFlowModelActive(isFreeFlow);
 
-		if (freshRelayState.mode !== "off") {
-			freshRelayState.enabled = freshRelayState.relays.length > 0;
-			setActiveRelayState(freshRelayState, false);
-		}
+  if (freshRelayState.mode !== "off") {
+   freshRelayState.enabled = freshRelayState.relays.length > 0;
+   setActiveRelayState(freshRelayState, false);
+  }
 
-		if (isFreeFlow) {
-			updateStatusBar(ctx.ui);
-		} else {
-			ctx.ui?.setStatus?.("freeflow", undefined);
-		}
-		try { checkForUpdateInBackground(ctx.ui as unknown as ExtensionUIContext); } catch {}
-	});
-	pi.on?.("model_select", async (event, ctx: ExtensionContext) => {
-		await ensureDaemon(ctx.ui);
-		const freshRelayState = resolveRelayState();
-		setStatusUi(ctx.ui);
-		try { bindWidgetClick(ctx.ui); } catch {}
-		let provider: string | undefined;
-		let modelId: string | undefined;
-		if (event && typeof event === "object" && "model" in event && event.model && typeof event.model === "object") {
-			const m = event.model;
-			if ("provider" in m && typeof m.provider === "string") {
-				provider = m.provider;
-			}
-			if ("id" in m && typeof m.id === "string") {
-				modelId = m.id;
-			}
-		} else if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {
-			const m = ctx.model;
-			if ("provider" in m && typeof m.provider === "string") {
-				provider = m.provider;
-			}
-			if ("id" in m && typeof m.id === "string") {
-				modelId = m.id;
-			}
-		}
-		const isFreeFlow = isFreeFlowModelMatch(provider, modelId);
-		setFreeFlowModelActive(isFreeFlow);
+  if (isFreeFlow) {
+   updateStatusBar(ctx.ui);
+  } else {
+   ctx.ui?.setStatus?.("freeflow", undefined);
+  }
+  try { checkForUpdateInBackground(ctx.ui as unknown as ExtensionUIContext); } catch { }
+ });
+ pi.on?.("model_select", async (event, ctx: ExtensionContext) => {
+  await ensureDaemon(ctx.ui);
+  const freshRelayState = resolveRelayState();
+  setStatusUi(ctx.ui);
+  try { bindWidgetClick(ctx.ui); } catch { }
+  let provider: string | undefined;
+  let modelId: string | undefined;
+  if (event && typeof event === "object" && "model" in event && event.model && typeof event.model === "object") {
+   const m = event.model;
+   if ("provider" in m && typeof m.provider === "string") {
+    provider = m.provider;
+   }
+   if ("id" in m && typeof m.id === "string") {
+    modelId = m.id;
+   }
+  } else if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {
+   const m = ctx.model;
+   if ("provider" in m && typeof m.provider === "string") {
+    provider = m.provider;
+   }
+   if ("id" in m && typeof m.id === "string") {
+    modelId = m.id;
+   }
+  }
+  const isFreeFlow = isFreeFlowModelMatch(provider, modelId);
+  setFreeFlowModelActive(isFreeFlow);
 
-		if (freshRelayState.mode !== "off") {
-			freshRelayState.enabled = freshRelayState.relays.length > 0;
-			setActiveRelayState(freshRelayState, false);
-		}
+  if (freshRelayState.mode !== "off") {
+   freshRelayState.enabled = freshRelayState.relays.length > 0;
+   setActiveRelayState(freshRelayState, false);
+  }
 
-		if (isFreeFlow) {
-			updateStatusBar(ctx.ui);
-		} else {
-			ctx.ui?.setStatus?.("freeflow", undefined);
-		}
-	});
-	pi.on?.("session_shutdown", () => {
-		stopLogsFollow();
-		if (hasFallbackServer()) {
-			stopHeartbeat();
-		}
-	});
-	process.once("exit", () => {
-		try {
-			stopHeartbeat();
-		} catch {}
-	});
+  if (isFreeFlow) {
+   updateStatusBar(ctx.ui);
+  } else {
+   ctx.ui?.setStatus?.("freeflow", undefined);
+  }
+ });
+ pi.on?.("session_shutdown", () => {
+  stopLogsFollow();
+  if (hasFallbackServer()) {
+   stopHeartbeat();
+  }
+ });
+ process.once("exit", () => {
+  try {
+   stopHeartbeat();
+  } catch { }
+ });
 }

package/src/opencode-fingerprint.ts

@@ -1,9 +1,10 @@
 /**
  * OpenCode Zen free-tier client fingerprint enforcement & SSE stream aggregator.
  *
- * Upstream OpenCode Zen (/zen/v1/chat/completions and /zen/v1/responses) validates
- * requests against the official OpenCode agentic client fingerprint. If any of the
- * following 4 axes are missing, upstream answers HTTP 403 FreeTierError:
+ * Upstream OpenCode Zen (/zen/v1/chat/completions, /zen/v1/responses and
+ * /zen/v1/messages) validates requests against the official OpenCode agentic
+ * client fingerprint. If any of the following 4 axes are missing, upstream
+ * answers HTTP 403 FreeTierError:
  * 1. User-Agent (opencode/1.18.31, >= 1.17.0)
  * 2. x-opencode-session (canonical ses_[0-9a-f]{12}[0-9A-Za-z]{14} format)
  * 3. Tools: must declare the file-search tool quartet {bash, glob, grep, read}
@@ -13,11 +14,19 @@
  * bidirectional streaming conversion: if the client requested non-streaming
  * (stream: false), upstream is still sent stream: true to pass the gate, and the
  * resulting SSE stream is accumulated and converted back to a single JSON response.
+ *
+ * freeflow serves ONLY OMP and Pi hosts. Either host may send any of its tools
+ * (see src/tool-translation.ts for the canonical inventories) in any wire shape,
+ * so enforcement first translates caller tools to the target path's shape and
+ * only then injects the missing quartet. Caller tools are never dropped.
  */
+import {
+ OPENCODE_FINGERPRINT_TOOLS,
+ translateToolsForPath,
+} from "./tool-translation.ts";
 
-export const OPENCODE_FINGERPRINT_TOOLS = ["bash", "glob", "grep", "read"] as const;
-
-export type FingerprintToolName = (typeof OPENCODE_FINGERPRINT_TOOLS)[number];
+export { OPENCODE_FINGERPRINT_TOOLS };
+export type { FingerprintToolName } from "./tool-translation.ts";
 
 /**
  * Safely extract the tool name whether formatted in Chat Completions style
@@ -90,8 +99,37 @@ export function ensureResponsesFingerprintTools(body: Record<string, unknown>):
  }
 }
 
+/**
+ * Merge missing {bash, glob, grep, read} tool declarations into Anthropic
+ * Messages bodies. Uses the Anthropic tool shape ({ name, description,
+ * input_schema }).
+ */
+export function ensureMessagesFingerprintTools(body: Record<string, unknown>): void {
+ if (!body || typeof body !== "object") return;
+ const present = new Set<string>();
+ if (Array.isArray(body.tools)) {
+  for (const tool of body.tools) {
+   const name = toolNameOf(tool);
+   if (name) present.add(name);
+  }
+ } else {
+  body.tools = [];
+ }
+ for (const name of OPENCODE_FINGERPRINT_TOOLS) {
+  if (present.has(name)) continue;
+  (body.tools as unknown[]).push({
+   name,
+   description: "Do not call this tool. It exists only for API compatibility and must never be invoked.",
+   input_schema: { type: "object", properties: {} },
+  });
+  present.add(name);
+ }
+}
+
 /**
  * Enforce the full OpenCode free-tier client fingerprint on a parsed request body.
+ * Caller tools are first translated to the target path's wire shape (see
+ * src/tool-translation.ts), then the missing quartet is injected in that shape.
  * Returns whether the client originally requested streaming.
  */
 export function enforceOpencodeFingerprint(
@@ -103,11 +141,17 @@ export function enforceOpencodeFingerprint(
  // Upstream Zen free tier mandates stream: true for all free requests
  body.stream = true;
 
+ if (Array.isArray(body.tools)) {
+  body.tools = translateToolsForPath(body.tools, pathname);
+ }
+
  if (pathname.endsWith("/responses")) {
   ensureResponsesFingerprintTools(body);
   if (body.store === undefined) {
    body.store = false;
   }
+ } else if (pathname.endsWith("/messages")) {
+  ensureMessagesFingerprintTools(body);
  } else {
   ensureChatFingerprintTools(body);
  }
@@ -289,6 +333,116 @@ export function sseToResponsesJson(
  };
 }
 
+/**
+ * Convert an SSE stream from an Anthropic Messages endpoint into a single
+ * standard non-streaming message object. Aggregates content_block deltas
+ * (text + tool_use input_json) into content blocks.
+ */
+export function sseToMessagesJson(
+ sseText: string,
+ callerHadTools = true,
+): Record<string, unknown> {
+ const events = parseSseEvents(sseText);
+ let id = "msg_freeflow";
+ let model = "";
+ let stopReason: string | null = null;
+ let usage: unknown = undefined;
+ const textByIndex = new Map<number, string>();
+ const toolByIndex = new Map<number, { id: string; name: string; inputJson: string }>();
+
+ for (const ev of events) {
+  if (ev.data === "[DONE]") continue;
+  let parsed: Record<string, unknown>;
+  try {
+   parsed = JSON.parse(ev.data) as Record<string, unknown>;
+  } catch {
+   continue;
+  }
+  const type = typeof parsed.type === "string" ? parsed.type : "";
+  if (type === "message_start") {
+   const msg = parsed.message as Record<string, unknown> | undefined;
+   if (msg) {
+    if (typeof msg.id === "string") id = msg.id;
+    if (typeof msg.model === "string") model = msg.model;
+   }
+   continue;
+  }
+  if (type === "content_block_start") {
+   const index = typeof parsed.index === "number" ? parsed.index : 0;
+   const block = parsed.content_block as Record<string, unknown> | undefined;
+   const blockType = block && typeof block.type === "string" ? block.type : "";
+   if (blockType === "tool_use") {
+    toolByIndex.set(index, {
+     id: typeof block?.id === "string" ? (block.id as string) : "",
+     name: typeof block?.name === "string" ? (block.name as string) : "",
+     inputJson: "",
+    });
+   } else if (!toolByIndex.has(index)) {
+    textByIndex.set(index, typeof block?.text === "string" ? (block.text as string) : "");
+   }
+   continue;
+  }
+  if (type === "content_block_delta") {
+   const index = typeof parsed.index === "number" ? parsed.index : 0;
+   const delta = parsed.delta as Record<string, unknown> | undefined;
+   const deltaType = delta && typeof delta.type === "string" ? delta.type : "";
+   if (deltaType === "text_delta" && typeof delta?.text === "string") {
+    textByIndex.set(index, (textByIndex.get(index) ?? "") + (delta.text as string));
+   } else if (deltaType === "input_json_delta" && typeof delta?.partial_json === "string") {
+    const existing = toolByIndex.get(index) ?? { id: "", name: "", inputJson: "" };
+    existing.inputJson += delta.partial_json as string;
+    toolByIndex.set(index, existing);
+   }
+   continue;
+  }
+  if (type === "message_delta") {
+   const delta = parsed.delta as Record<string, unknown> | undefined;
+   if (delta && typeof delta.stop_reason === "string") stopReason = delta.stop_reason as string;
+   if (parsed.usage !== undefined) usage = parsed.usage;
+   continue;
+  }
+  if (type === "message" && parsed.role !== undefined) {
+   return parsed;
+  }
+ }
+
+ const content: Record<string, unknown>[] = [];
+ const order = Array.from(new Set([...textByIndex.keys(), ...toolByIndex.keys()])).sort((a, b) => a - b);
+ for (const index of order) {
+  const tool = toolByIndex.get(index);
+  if (tool && (tool.id || tool.name)) {
+   if (callerHadTools) {
+    let input: unknown = {};
+    try {
+     input = tool.inputJson ? JSON.parse(tool.inputJson) : {};
+    } catch {
+     input = {};
+    }
+    content.push({ type: "tool_use", id: tool.id, name: tool.name, input });
+   }
+   continue;
+  }
+  const text = textByIndex.get(index) ?? "";
+  if (text) content.push({ type: "text", text });
+ }
+ if (!callerHadTools && content.length === 0 && toolByIndex.size > 0) {
+  const fallback = Array.from(toolByIndex.values())
+   .map((t) => t.inputJson || t.name)
+   .join("\n");
+  if (fallback) content.push({ type: "text", text: fallback });
+ }
+
+ return {
+  id,
+  type: "message",
+  role: "assistant",
+  model,
+  content,
+  stop_reason: stopReason ?? "end_turn",
+  ...(usage ? { usage } : {}),
+ };
+}
+
 /**
  * Universal SSE-to-JSON aggregator. If input is not SSE, returns it untouched.
  */
@@ -306,6 +460,9 @@ export function convertSseToJson(
   if (pathname.endsWith("/responses")) {
    return JSON.stringify(sseToResponsesJson(trimmed, callerHadTools));
   }
+  if (pathname.endsWith("/messages")) {
+   return JSON.stringify(sseToMessagesJson(trimmed, callerHadTools));
+  }
   return JSON.stringify(sseToChatCompletionJson(trimmed, callerHadTools));
  } catch {
   return sseText;

package/src/proxy.ts

@@ -726,13 +726,18 @@ export function startProxy(
    const isStream = clientRequestedStream;
 
    // Stale-registration guard: responses-only models (muse-spark-*) must
-   // reach upstream via /v1/responses. A chat/completions request for one
-   // means the host still holds a pre-fix provider registration (stale
-   // disk cache or no restart after upgrade) and upstream answers 500.
-   if (!isKilo && typeof parsedBody?.model === "string" && target.pathname.endsWith("/chat/completions")) {
+   // reach upstream via /v1/responses, and messages-only models (union-alpha)
+   // via /v1/messages. A request on the wrong path means the host still holds
+   // a pre-fix provider registration (stale disk cache or no restart after
+   // upgrade) and upstream answers 500.
+   if (!isKilo && typeof parsedBody?.model === "string") {
     const knownDef = MODEL_MAP.get(String(parsedBody.model));
-    if (knownDef?.api === "openai-responses") {
-     log("warn", `model ${String(parsedBody.model)} expects openai-responses but got ${target.pathname} — stale provider registration (restart Pi/OMP after upgrade)`, { model: String(parsedBody.model), path: target.pathname }, reqId);
+    if (target.pathname.endsWith("/chat/completions") && knownDef?.api && knownDef.api !== "openai-completions") {
+     log("warn", `model ${String(parsedBody.model)} expects ${knownDef.api} but got ${target.pathname} — stale provider registration (restart Pi/OMP after upgrade)`, { model: String(parsedBody.model), path: target.pathname }, reqId);
+    } else if (target.pathname.endsWith("/messages") && knownDef?.api && knownDef.api !== "anthropic-messages") {
+     log("warn", `model ${String(parsedBody.model)} expects ${knownDef.api} but got ${target.pathname} — stale provider registration (restart Pi/OMP after upgrade)`, { model: String(parsedBody.model), path: target.pathname }, reqId);
+    } else if (target.pathname.endsWith("/responses") && knownDef?.api && knownDef.api !== "openai-responses") {
+     log("warn", `model ${String(parsedBody.model)} expects ${knownDef.api} but got ${target.pathname} — stale provider registration (restart Pi/OMP after upgrade)`, { model: String(parsedBody.model), path: target.pathname }, reqId);
     }
    }
    try {

package/src/tool-translation.ts

@@ -0,0 +1,276 @@
+/**
+ * Tool translation across the three wire APIs pi-freeflow serves.
+ *
+ * freeflow is used ONLY by OMP and Pi hosts (never generic OpenAI clients),
+ * so the proxy must accept every tool either host can send and reshape it for
+ * whichever upstream API the request targets:
+ * - Chat Completions (`/v1/chat/completions`): { type: "function", function: { name, description, parameters } }
+ * - Responses (`/v1/responses`): { type: "function", name, description, parameters }
+ * - Anthropic Messages (`/v1/messages`): { name, description, input_schema }
+ *
+ * Canonical host inventories (grounded in the reference checkouts):
+ * - Pi: `ToolName` union in reference/pi/packages/coding-agent/src/core/tools/index.ts
+ * - OMP: `BUILTIN_TOOL_NAMES` in reference/oh-my-pi/packages/coding-agent/src/tools/builtin-names.ts
+ *
+ * Translation rules:
+ * - Function tools are normalized to { name, description, parameters } and
+ *   re-emitted in the target shape. Caller tools are NEVER dropped or renamed.
+ * - Non-function tools (e.g. Responses built-ins like { type: "web_search" })
+ *   pass through verbatim.
+ * - `parameters` and Anthropic `input_schema` are treated as the same schema.
+ * - First-seen wins on duplicate names.
+ */
+
+/** File-search tool quartet the upstream OpenCode Zen free tier mandates. */
+export const OPENCODE_FINGERPRINT_TOOLS = ["bash", "glob", "grep", "read"] as const;
+
+export type FingerprintToolName = (typeof OPENCODE_FINGERPRINT_TOOLS)[number];
+
+/** Pi host tools: ToolName union in reference/pi packages/coding-agent/src/core/tools/index.ts */
+export const PI_TOOL_NAMES = [
+ "read",
+ "bash",
+ "powershell",
+ "edit",
+ "write",
+ "grep",
+ "find",
+ "ls",
+] as const;
+
+/** OMP host built-ins: BUILTIN_TOOL_NAMES in reference/oh-my-pi packages/coding-agent/src/tools/builtin-names.ts */
+export const OMP_TOOL_NAMES = [
+ "read",
+ "bash",
+ "edit",
+ "ast_grep",
+ "ast_edit",
+ "ask",
+ "debug",
+ "eval",
+ "github",
+ "glob",
+ "grep",
+ "lsp",
+ "checkpoint",
+ "rewind",
+ "security_scan",
+ "task",
+ "hub",
+ "todo",
+ "web_search",
+ "write",
+ "memory_edit",
+ "retain",
+ "recall",
+ "reflect",
+ "learn",
+ "manage_skill",
+] as const;
+
+/** OMP hidden tools: HIDDEN_TOOL_NAMES in the same OMP module. */
+export const OMP_HIDDEN_TOOL_NAMES = ["yield", "goal", "think"] as const;
+
+/** Every tool name either host can send (MCP `mcp__*` and xd:// device names pass through as-is). */
+export const ALL_HOST_TOOL_NAMES: ReadonlySet<string> = new Set([
+ ...PI_TOOL_NAMES,
+ ...OMP_TOOL_NAMES,
+ ...OMP_HIDDEN_TOOL_NAMES,
+]);
+
+/** Placeholder description for injected compatibility tools: must never be invoked. */
+export const COMPAT_TOOL_DESCRIPTION =
+ "Do not call this tool. It exists only for API compatibility and must never be invoked.";
+
+export interface CanonicalTool {
+ name: string;
+ description: string;
+ parameters: Record<string, unknown>;
+}
+
+function nestedFn(t: Record<string, unknown>): Record<string, unknown> | null {
+ const fn = t.function;
+ return typeof fn === "object" && fn !== null && !Array.isArray(fn)
+  ? (fn as Record<string, unknown>)
+  : null;
+}
+
+function schemaOf(t: Record<string, unknown>, fn: Record<string, unknown> | null): Record<string, unknown> {
+ for (const key of ["parameters", "input_schema"]) {
+  const direct = t[key];
+  if (typeof direct === "object" && direct !== null && !Array.isArray(direct)) {
+   return direct as Record<string, unknown>;
+  }
+  if (fn) {
+   const nested = fn[key];
+   if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+    return nested as Record<string, unknown>;
+   }
+  }
+ }
+ return { type: "object", properties: {} };
+}
+
+/**
+ * Normalize one wire tool to canonical form. Returns null for entries that
+ * are not function tools (they must pass through verbatim, not be dropped).
+ */
+export function canonicalizeTool(tool: unknown): CanonicalTool | null {
+ if (typeof tool !== "object" || tool === null || Array.isArray(tool)) return null;
+ const t = tool as Record<string, unknown>;
+ const fn = nestedFn(t);
+ const rawName =
+  typeof t.name === "string" && t.name.trim()
+   ? t.name.trim()
+   : fn && typeof fn.name === "string"
+    ? fn.name.trim()
+    : "";
+ if (!rawName) return null;
+ const type = typeof t.type === "string" ? t.type : "";
+ // Function tools across all three APIs. Anything else (web_search,
+ // code_interpreter, custom MCP wrappers) is not ours to reshape.
+ if (type !== "" && type !== "function") return null;
+ return {
+  name: rawName,
+  description:
+   typeof t.description === "string"
+    ? t.description
+    : fn && typeof fn.description === "string"
+     ? fn.description
+     : "",
+  parameters: schemaOf(t, fn),
+ };
+}
+
+/** Canonical tool -> Chat Completions shape. */
+export function toChatTool(t: CanonicalTool): Record<string, unknown> {
+ return {
+  type: "function",
+  function: {
+   name: t.name,
+   description: t.description,
+   parameters: t.parameters,
+  },
+ };
+}
+
+/** Canonical tool -> Responses shape. */
+export function toResponsesTool(t: CanonicalTool): Record<string, unknown> {
+ return {
+  type: "function",
+  name: t.name,
+  description: t.description,
+  parameters: t.parameters,
+ };
+}
+
+/** Canonical tool -> Anthropic Messages shape. */
+export function toAnthropicTool(t: CanonicalTool): Record<string, unknown> {
+ return {
+  name: t.name,
+  description: t.description,
+  input_schema: t.parameters,
+ };
+}
+
+/** Which wire API does this proxy path target? */
+export function apiForPathname(pathname: string): "responses" | "messages" | "chat" {
+ if (pathname.endsWith("/responses")) return "responses";
+ if (pathname.endsWith("/messages")) return "messages";
+ return "chat";
+}
+
+function isChatShape(tool: Record<string, unknown>): boolean {
+ const fn = tool.function;
+ return typeof fn === "object" && fn !== null && !Array.isArray(fn) &&
+  typeof (fn as Record<string, unknown>).name === "string";
+}
+
+function isResponsesShape(tool: Record<string, unknown>): boolean {
+ return tool.type === "function" && typeof tool.name === "string";
+}
+
+function isAnthropicShape(tool: Record<string, unknown>): boolean {
+ // Anthropic tools carry input_schema and no type/function wrapper.
+ // A flat { name, parameters } tool is NOT anthropic shape: it still needs
+ // conversion (responses tools share the flat name field).
+ if (tool.type === "function" || isChatShape(tool)) return false;
+ if (typeof tool.name !== "string") return false;
+ const schema = tool.input_schema;
+ return typeof schema === "object" && schema !== null && !Array.isArray(schema);
+}
+
+function alreadyTargetShape(tool: Record<string, unknown>, api: "responses" | "messages" | "chat"): boolean {
+ return api === "responses" ? isResponsesShape(tool) : api === "messages" ? isAnthropicShape(tool) : isChatShape(tool);
+}
+
+/**
+ * Reshape a caller tool array for the target path. Tools already in the
+ * target shape pass through verbatim (every extra field intact); function
+ * tools in another shape are converted, carrying `strict` when the caller
+ * set it (all three APIs accept it). Every other entry passes through
+ * verbatim. Duplicates collapse first-seen-wins. Never returns null entries.
+ */
+export function translateToolsForPath(tools: unknown[], pathname: string): Record<string, unknown>[] {
+ const api = apiForPathname(pathname);
+ const seen = new Set<string>();
+ const out: Record<string, unknown>[] = [];
+ for (const tool of tools) {
+  if (typeof tool !== "object" || tool === null || Array.isArray(tool)) continue;
+  const rec = tool as Record<string, unknown>;
+  const canon = canonicalizeTool(tool);
+  if (!canon) {
+   // Non-function tool (or unparsable): keep verbatim so built-ins survive.
+   out.push(rec);
+   continue;
+  }
+  if (seen.has(canon.name)) continue;
+  seen.add(canon.name);
+  if (alreadyTargetShape(rec, api)) {
+   out.push(rec);
+   continue;
+  }
+  const converted =
+   api === "responses"
+    ? toResponsesTool(canon)
+    : api === "messages"
+     ? toAnthropicTool(canon)
+     : toChatTool(canon);
+  if (typeof rec.strict === "boolean") converted.strict = rec.strict;
+  out.push(converted);
+ }
+ return out;
+}
+
+/**
+ * Inject the missing fingerprint quartet into an already-translated tool
+ * array, using the target path's shape. Idempotent.
+ */
+export function injectFingerprintTools(
+ tools: Record<string, unknown>[],
+ pathname: string,
+): Record<string, unknown>[] {
+ const present = new Set<string>();
+ for (const tool of tools) {
+  const canon = canonicalizeTool(tool);
+  if (canon) present.add(canon.name);
+ }
+ const api = apiForPathname(pathname);
+ for (const name of OPENCODE_FINGERPRINT_TOOLS) {
+  if (present.has(name)) continue;
+  const canon: CanonicalTool = {
+   name,
+   description: COMPAT_TOOL_DESCRIPTION,
+   parameters: { type: "object", properties: {} },
+  };
+  tools.push(
+   api === "responses"
+    ? toResponsesTool(canon)
+    : api === "messages"
+     ? toAnthropicTool(canon)
+     : toChatTool(canon),
+  );
+  present.add(name);
+ }
+ return tools;
+}