@possumtech/rummy 2.1.0 → 2.2.0

package/src/plugins/cp/cp.js

@@ -1,4 +1,5 @@
 import Entries from "../../agent/Entries.js";
+import { storePatternResult } from "../helpers.js";
 import docs from "./cpDoc.js";
 
 export default class Cp {
@@ -24,25 +25,60 @@ export default class Cp {
 			? entry.attributes.visibility
 			: undefined;
 
+		// Manifest: list what would be copied without performing the cp.
+		if (entry.attributes.manifest !== undefined) {
+			const matches = await store.getEntriesByPattern(runId, path);
+			await storePatternResult(store, runId, turn, "cp", path, null, matches, {
+				manifest: true,
+				loopId,
+				attributes: { path, to },
+			});
+			return;
+		}
+
 		const source = await store.getBody(runId, path);
 		if (source === null) return;
+		// Tags propagate: explicit `tags=` on the cp wins; otherwise the
+		// destination inherits the source entry's tags. Same shape as
+		// visibility — explicit attr overrides, default inherits.
+		let destTags = null;
+		if (typeof entry.attributes.tags === "string") {
+			destTags = entry.attributes.tags;
+		} else {
+			const sourceAttrs = await store.getAttributes(runId, path);
+			if (sourceAttrs && typeof sourceAttrs.tags === "string") {
+				destTags = sourceAttrs.tags;
+			}
+		}
 
 		const destScheme = Entries.scheme(to);
 		const existing = await store.getBody(runId, to);
 		const warning =
-			existing !== null && destScheme !== null
-				? `Overwrote existing entry at ${to}`
-				: null;
+			existing !== null ? `Overwrote existing entry at ${to}` : null;
 
 		const body = `${path} ${to}`;
 		if (destScheme === null) {
+			// Bare-file destination: hand the shared materializer (set.js
+			// #materializeFile, gated on attrs.path + attrs.patched) the
+			// authoritative new body so it writes the source content to
+			// disk on accept. Without this the proposal accepted but no
+			// file landed — the model's "<cp src dest> then <set dest>
+			// SEARCH/REPLACE" sequence silently no-op'd at materialize.
 			await store.set({
 				runId,
 				turn,
 				path: entry.resultPath,
 				body,
 				state: "proposed",
-				attributes: { from: path, to, isMove: false, warning },
+				attributes: {
+					from: path,
+					to,
+					isMove: false,
+					warning,
+					path: to,
+					patched: source,
+					visibility,
+				},
 				loopId,
 			});
 		} else {
@@ -53,6 +89,7 @@ export default class Cp {
 				body: source,
 				state: "resolved",
 				visibility,
+				attributes: destTags ? { tags: destTags } : null,
 				loopId,
 			});
 			await store.set({

package/src/plugins/cp/cpDoc.md

@@ -1,7 +1,6 @@
-## <cp path="[source]">[destination]</cp> - Copy a file or entry
+## <cp path="[source]">[destination]</cp> - Copy an entry or file
 
-Example: <cp path="src/config.js">src/config.backup.js</cp>
-<!-- Simple file copy. Path = source, body = destination. -->
-
-Example: <cp path="known://plan_*">known://archive_</cp>
-<!-- Glob batch copy across known entries. -->
+Example: <cp path="known://server/handler_main">src/main.c</cp>
+<!-- Body is the destination path; cross-scheme copies are allowed. -->
+Example: <cp path="known://countries/france/*">known://archive/countries/france/</cp>
+<!-- Glob source + directory-shaped destination = batch copy preserving names. -->

package/src/plugins/engine/engine.sql

@@ -1,7 +1,7 @@
 -- PREP: get_promoted_entries
 SELECT
 	ke.path, ke.scheme, ke.state, ke.outcome, ke.visibility, ke.turn
-	, countTokens(ke.body) AS tokens, ke.refs
+	, ke.refs, countTokens(ke.body) AS tokens
 FROM known_entries AS ke
 JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
 WHERE

package/src/plugins/env/README.md

@@ -8,7 +8,7 @@ side effects.
 ## Registration
 
 - **Tool**: `env`
-- **Scheme**: `env` — `category: "data"` (channels only; see below)
+- **Scheme**: `env` — `category: "logging"` (channels are time-indexed activity, not state)
 - **Handler**: Upserts the proposal entry at status 202 (proposed).
 
 ## Two namespaces per invocation
@@ -16,9 +16,10 @@ side effects.
 - **Log entry**: `log://turn_N/env/{slug}` — scheme=`log`, category=`logging`.
   The audit record (renders inside `<log>` as `<env>`).
 - **Data channels**: `env://turn_N/{slug}_1` (stdout), `env://turn_N/{slug}_2`
-  (stderr) — scheme=`env`, category=`data`. The captured payload
-  (renders inside `<visible>` as `<env>` when promoted; otherwise listed
-  in `<summarized>`).
+  (stderr) — scheme=`env`, category=`logging` (time-indexed activity).
+  Render inside `<log>` adjacent to their parent `<env>` action entry;
+  visibility controls whether the body is full or compact, not which
+  block they appear in.
 
 The `env` scheme exists **only** for the data channels. See
 [scheme_category_split](#scheme_category_split).

package/src/plugins/env/env.js

@@ -9,7 +9,10 @@ export default class Env {
 	constructor(core) {
 		this.#core = core;
 		// env vs sh: env is read-only (allowed in ask-mode); see plugin README.
-		core.registerScheme({ category: "data" });
+		// Streaming stdout/stderr is time-indexed activity output, not
+		// topic-indexed state — category="logging" so it renders in <log>
+		// adjacent to its action entry, not in <summary>/<visible>.
+		core.registerScheme({ category: "logging" });
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
 		core.on("summarized", this.summary.bind(this));
@@ -25,7 +28,7 @@ export default class Env {
 		if (m?.[1] !== "env") return;
 		let command = "";
 		if (ctx.attrs?.command) command = ctx.attrs.command;
-		else if (ctx.attrs?.summary) command = ctx.attrs.summary;
+		else if (ctx.attrs?.tags) command = ctx.attrs.tags;
 		const turn = (await ctx.db.get_run_by_id.get({ id: ctx.runId })).next_turn;
 		const dataBase = logPathToDataBase(ctx.path);
 		for (const ch of [1, 2]) {
@@ -36,7 +39,7 @@ export default class Env {
 				body: "",
 				state: "streaming",
 				visibility: "summarized",
-				attributes: { command, summary: command, channel: ch },
+				attributes: { command, tags: command, channel: ch },
 			});
 		}
 		await ctx.entries.set({
@@ -55,7 +58,7 @@ export default class Env {
 			path: entry.resultPath,
 			body: "",
 			state: "proposed",
-			attributes: { ...entry.attributes, summary: entry.attributes.command },
+			attributes: { ...entry.attributes, tags: entry.attributes.command },
 			loopId,
 		});
 	}

package/src/plugins/env/envDoc.md

@@ -1,13 +1,12 @@
 ## <env>[command]</env> - Run an exploratory shell command
 
-Example: <env>npm --version</env>
-<!-- Version check. Safe, no side effects. -->
-
-Example: <env>git log --oneline -5</env>
-<!-- Git history. Shows env for read-only investigation. -->
+Example:
+	<env><<EOF
+	npm --version
+	node --version
+	git log --oneline -3
+	EOF</env>
+<!-- Heredoc body is opaque — embed multi-line scripts and special characters without escaping. Output co-locates at env://turn_N/<slug>. -->
 
 YOU MUST NOT use <env></env> to read or list files — use <get path="*"/> instead
-<!-- Prevents cat/ls through shell. Forces file access through get. -->
-
 YOU MUST NOT use <env></env> for commands with side effects
-<!-- Separates exploration from action. env = observe only. -->

package/src/plugins/error/error.js

@@ -1,8 +1,9 @@
-import config from "../../agent/config.js";
+import { SOFT_FAILURE_OUTCOMES } from "../../agent/errors.js";
+import { SUMMARY_MAX_CHARS } from "../helpers.js";
 
-const { MAX_STRIKES, MIN_CYCLES, MAX_CYCLE_PERIOD } = config;
-
-const CONTRACT_REMINDER = "Missing update";
+const MAX_STRIKES = Number(process.env.RUMMY_MAX_STRIKES);
+const MIN_CYCLES = Number(process.env.RUMMY_MIN_CYCLES);
+const MAX_CYCLE_PERIOD = Number(process.env.RUMMY_MAX_CYCLE_PERIOD);
 
 function fingerprint(entry) {
 	const parts = Object.keys(entry.attributes)
@@ -40,18 +41,27 @@ export default class ErrorPlugin {
 		this.#core = core;
 		core.registerScheme({ category: "logging" });
 		core.on("visible", (entry) => `# error\n${entry.body}`);
-		core.on("summarized", (entry) => entry.body);
+		core.on("summarized", (entry) => entry.body.slice(0, SUMMARY_MAX_CHARS));
 
 		core.hooks.error.log.on(this.#onErrorLog.bind(this));
 		core.hooks.loop.started.on(this.#onLoopStarted.bind(this));
 		core.hooks.loop.completed.on(this.#onLoopCompleted.bind(this));
 		core.hooks.turn.started.on(this.#onTurnStarted.bind(this));
 
-		core.hooks.error.verdict = this.#verdict.bind(this);
+		// Subscribe to the turn.verdict filter chain. Multi-plugin
+		// surface — strike streak, cycle detection, stagnation
+		// pressure all flow through here. Future voters (e.g. budget
+		// overflow termination, runaway-on-context-grow) participate
+		// via the same chain.
+		core.filter("turn.verdict", this.#verdict.bind(this));
 	}
 
 	#onLoopStarted({ loopId }) {
-		this.#loopState.set(loopId, { streak: 0, history: [], turnErrors: 0 });
+		this.#loopState.set(loopId, {
+			streak: 0,
+			history: [],
+			turnErrors: 0,
+		});
 	}
 
 	#onLoopCompleted({ loopId }) {
@@ -71,24 +81,43 @@ export default class ErrorPlugin {
 		message,
 		status,
 		attributes,
+		soft,
 	}) {
 		const statusValue = status ?? 400;
 		const path = await store.logPath(runId, turn, "error", message);
+		// Soft errors record but don't strike: the issue was already
+		// recovered (e.g. parser auto-corrected a closing-tag mismatch)
+		// and the entry exists only so the model can see what happened.
+		// state="resolved" keeps recordedFailed clean; skipping
+		// turnErrors++ keeps the strike machinery from firing. Per SPEC
+		// #entries, outcome is reserved for state ∈ {failed, cancelled}
+		// — soft entries land with outcome=null. Status carrier for
+		// rendering is attributes.status, consulted before outcome by
+		// log.js's renderLogTag.
 		await store.set({
 			runId,
 			turn,
 			path,
 			body: message,
-			state: "failed",
-			outcome: `status:${statusValue}`,
+			state: soft ? "resolved" : "failed",
+			outcome: soft ? null : `status:${statusValue}`,
 			loopId,
 			attributes: { ...attributes, status: statusValue },
 		});
+		if (soft) return;
 		const state = this.#loopState.get(loopId);
 		if (state) state.turnErrors++;
 	}
 
-	async #verdict({ store, runId, loopId, recorded, summaryText }) {
+	async #verdict(
+		_currentVerdict,
+		{ store, runId, loopId, recorded, summaryText, turn: _turn },
+	) {
+		// _currentVerdict is the upstream filter's result. Today this is
+		// the only voter so it's always { continue: true }. When other
+		// plugins join the chain, they can short-circuit by setting
+		// continue=false; this implementation could honor that via an
+		// early return. Left noop for now to preserve current semantics.
 		const state = this.#loopState.get(loopId);
 
 		let cycleReason = null;
@@ -102,10 +131,20 @@ export default class ErrorPlugin {
 			state.turnErrors++;
 		}
 
+		// Some failure outcomes are findings the model should adapt to,
+		// not contract violations. `not_found` (model tried to act on an
+		// entry that doesn't exist) and `conflict` (SEARCH text didn't
+		// match current body) are recoverable: the model reads the new
+		// state and tries again. Striking on these punishes legitimate
+		// state-discovery and accumulates 499s on otherwise productive
+		// runs. Hard outcomes (validation, permission, exit:N) still strike.
 		let recordedFailed = false;
 		for (const e of recorded) {
 			const current = await store.getState(runId, e.path);
-			if (current?.state === "failed") {
+			if (
+				current?.state === "failed" &&
+				!SOFT_FAILURE_OUTCOMES.has(current.outcome)
+			) {
 				recordedFailed = true;
 				break;
 			}
@@ -139,10 +178,12 @@ export default class ErrorPlugin {
 						`Abandoned after ${state.streak} consecutive strikes.`,
 				};
 			}
-			return {
-				continue: true,
-				reason: CONTRACT_REMINDER,
-			};
+			// No reason on continue: the model sees the actual failure
+			// entries directly in <log> next turn. Hardcoding "Missing
+			// update" mislabels strikes that fire on validation /
+			// permission / dispatch failures or cycles, when the update
+			// itself was emitted correctly.
+			return { continue: true };
 		}
 
 		state.streak = 0;

package/src/plugins/file/README.md

@@ -15,8 +15,17 @@ Static methods `setConstraint` and `dropConstraint` manage per-project
 file constraints in the database. Constraints are project-level config
 (backbone), not tool dispatch. See [file_constraints](../../../SPEC.md#file_constraints).
 
-- `active` / `readonly` — promoted into context (visibility=visible).
-- `ignore` — excluded from scans; summarizes existing entries.
+Constraint type governs **membership** and **write permission**, not
+in-context visibility. Visibility (visible / summarized / archived)
+is per-entry and model-controlled — files default to `archived` on
+ingestion; the model promotes via `<get>` / `<set visibility=...>`.
 
-Promotion/demotion from constraints goes through the standard tool
+- `add` — file is part of the project; ingested as an entry; model
+  may write. Default for `setConstraint`.
+- `readonly` — same ingestion; `<set>` is vetoed at the proposal-
+  accept gate.
+- `ignore` — excluded from scans entirely. The file remains on disk
+  for `<sh>` / `<env>` invocation but is not present as an entry.
+
+Promotion/demotion of an ingested file goes through the standard tool
 handler chain via `dispatchTool`.

package/src/plugins/file/file.js

@@ -19,7 +19,7 @@ export default class File {
 		return "";
 	}
 
-	static async setConstraint(db, projectId, pattern, visibility = "active") {
+	static async setConstraint(db, projectId, pattern, visibility = "add") {
 		const path = await normalizePath(db, projectId, pattern);
 		if (!path) return null;
 
@@ -47,7 +47,7 @@ export default class File {
 	// True if any readonly constraint matches; called from set-accept gate.
 	static async isReadonly(db, projectId, path) {
 		const rows = await db.get_file_constraints.all({ project_id: projectId });
-		const { hedmatch } = await import("./../hedberg/patterns.js");
+		const { hedmatch } = await import("../../lib/hedberg/patterns.js");
 		return rows.some(
 			(r) => r.visibility === "readonly" && hedmatch(r.pattern, path),
 		);

package/src/plugins/get/get.js

@@ -19,7 +19,12 @@ export default class Get {
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		const target = entry.attributes.path;
+		// Search-by-tags: same `tags` attribute that <set> writes onto
+		// entries. Same name on both ends — no in/out semantic split.
+		const tagsAttr = entry.attributes.tags;
+		// Tags-only get defaults path to "**" so the model can recall by
+		// folksonomic tags without remembering exact paths.
+		const target = entry.attributes.path || (tagsAttr ? "**" : null);
 		if (!target) {
 			await store.set({
 				runId,
@@ -35,7 +40,13 @@ export default class Get {
 		const normalized = Entries.normalizePath(target);
 		const bodyFilter = entry.attributes.body;
 		const manifest = entry.attributes.manifest !== undefined;
-		const isPattern = bodyFilter || normalized.includes("*");
+		const wantedTags = tagsAttr
+			? tagsAttr
+					.split(",")
+					.map((t) => t.trim().toLowerCase())
+					.filter(Boolean)
+			: null;
+		const isPattern = bodyFilter || normalized.includes("*") || !!wantedTags;
 
 		// Negative line = tail-from-end (line=-50 starts 50 from end).
 		const lineRaw = entry.attributes.line;
@@ -45,11 +56,23 @@ export default class Get {
 				? Math.max(1, parseInt(entry.attributes.limit, 10))
 				: null;
 
-		const matches = await store.getEntriesByPattern(
+		let matches = await store.getEntriesByPattern(
 			runId,
 			normalized,
 			bodyFilter,
 		);
+		if (wantedTags) {
+			matches = matches.filter((e) => {
+				if (!e.attributes) return false;
+				const attrs =
+					typeof e.attributes === "string"
+						? JSON.parse(e.attributes)
+						: e.attributes;
+				if (typeof attrs.tags !== "string") return false;
+				const tags = attrs.tags.toLowerCase();
+				return wantedTags.every((t) => tags.includes(t));
+			});
+		}
 
 		// Manifest: list matches + full-body token costs; no promotion.
 		if (manifest) {
@@ -67,20 +90,11 @@ export default class Get {
 		}
 
 		// Partial read: line slice in the log entry; no promotion.
+		// Per getDoc: "line/limit works on any scheme — files, sh
+		// stdout, knowns, urls." Multi-match (glob, tags, or body
+		// filter narrowing) emits one slice section per match —
+		// model can scope further with body filter or tighter path.
 		if (line !== null || limit !== null) {
-			if (isPattern) {
-				await store.set({
-					runId,
-					turn,
-					path: entry.resultPath,
-					body: "line/limit requires a single path, not a glob or body filter",
-					state: "failed",
-					outcome: "validation",
-					loopId,
-					attributes: { path: target },
-				});
-				return;
-			}
 			if (matches.length === 0) {
 				await store.set({
 					runId,
@@ -93,32 +107,25 @@ export default class Get {
 				});
 				return;
 			}
-			const allLines = matches[0].body.split("\n");
-			const total = allLines.length;
-			const startLine =
-				line == null
-					? 1
-					: line < 0
-						? Math.max(1, total + line + 1)
-						: Math.max(1, line);
-			const startIdx = startLine - 1;
-			const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
-			const slice = allLines.slice(startIdx, endIdx).join("\n");
-			const endLine = endIdx;
-			const header = `${target}\n[lines ${startLine}–${endLine} / ${total} total]`;
+			const sections = matches.map((match) => sliceSection(match, line, limit));
+			const body = sections.map((s) => s.text).join("\n\n");
+			const attributes = { path: target };
+			if (sections.length === 1) {
+				const only = sections[0];
+				attributes.lineStart = only.startLine;
+				attributes.lineEnd = only.endLine;
+				attributes.totalLines = only.total;
+			} else {
+				attributes.matchCount = sections.length;
+			}
 			await store.set({
 				runId,
 				turn,
 				path: entry.resultPath,
-				body: `${header}\n${slice}`,
+				body,
 				state: "resolved",
 				loopId,
-				attributes: {
-					path: target,
-					lineStart: startLine,
-					lineEnd: endLine,
-					totalLines: total,
-				},
+				attributes,
 			});
 			return;
 		}
@@ -190,3 +197,19 @@ export default class Get {
 		return "";
 	}
 }
+
+function sliceSection(match, line, limit) {
+	const allLines = match.body.split("\n");
+	const total = allLines.length;
+	const startLine =
+		line == null
+			? 1
+			: line < 0
+				? Math.max(1, total + line + 1)
+				: Math.max(1, line);
+	const startIdx = startLine - 1;
+	const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
+	const slice = allLines.slice(startIdx, endIdx).join("\n");
+	const text = `${match.path}\n[lines ${startLine}–${endIdx} / ${total} total]\n${slice}`;
+	return { text, startLine, endLine: endIdx, total };
+}

package/src/plugins/get/getDoc.md

@@ -1,38 +1,14 @@
-## <get path="[path/to/file]"/> - Promote an entry
-
-Example: <get path="src/app.js"/>
-<!-- Simplest form. Path attribute. Body is reserved for content filter. -->
+## <get path="[path]"/> - Promote an entry
 
 Example: <get path="known://*">auth</get>
-<!-- Keyword recall: glob in path, search term in body. -->
-
-Example: <get path="src/**/*.js">authentication</get>
-<!-- Full pattern: recursive glob + content filter. -->
-
-Example: <get path="src/**/*.js" manifest>authentication</get>
-<!-- Full pattern: recursive glob + content filter. -->
-
+<!-- Body is a content filter, not new content. Path glob + body keyword = filtered recall. -->
+Example: <get path="src/**/!(*.test).js" manifest>auth</get>
+<!-- Negation: !(pattern) excludes matches; combine with body filter for "auth in sources, not tests." -->
+Example: <get path="log://turn_*/sh/**" manifest/>
+<!-- ** crosses path separators (matches log://turn_5/sh/build_1, log://turn_5/sh/test/run_2); * matches one segment only. -->
 Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>
-<!-- Partial read. Returns lines 644–723 without promoting. -->
-
-Example: <get path="sh://turn_3/npm_test_1" line="-50"/>
-<!-- Tail: negative line reads the last 50 lines. Works on any growing entry — streaming sh output, logs, knowns. -->
-
+<!-- line/limit: read a slice without promoting. line=-50 tails the last 50 lines. -->
 Example: <get path="https://en.wikipedia.org/wiki/Long_Page" line="1" limit="200"/>
-<!-- URL partial read. When a page is too large to promote whole, read a slice. Pattern generalizes to every scheme. -->
-
-* Paths accept patterns: `src/**/*.js`, `known://api_*`
-<!-- Reinforces picomatch patterns work everywhere. -->
-
-* Body text filters results by content match (can use glob, regex, jsonpath, or xpath patterns)
-<!-- Body = filter, not just path. -->
-
-* `line` and `limit` read a slice without promoting the entry, which costs as many tokens as the slice contains. Negative `line` reads from the end (tail).
-<!-- Partial read is safe: context budget unaffected. Tail idiom enables watching growing entries. -->
-
-* `manifest` lists the paths and their token amounts instead of performing the operation; useful for bulk and pattern matching tasks.
-<!-- manifest = listing, not snippet. The natural-language reading of "preview" pulled small models toward content-sampling; for body samples use line/limit. -->
-
-* Remember to <set path="..." visibility="summarize"/> when entries or log events are no longer relevant.
-
-* Promotions don't appear until next turn — emit Stage Continuation (1xx), not Completion (200)
+<!-- URL slice. line/limit works on any scheme — files, sh stdout, knowns, urls. -->
+Example: <get path="*.md"/>
+<!-- One glob per call fans out. For unrelated paths, emit one `<get>` per path — `path` is a single entry or one pattern, not a space-separated list. -->

package/src/plugins/google/google.js

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import msg from "../../agent/messages.js";
+import { chatCompletionStream } from "../../llm/openaiStream.js";
+
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
+
+const PROVIDER = "google";
+const BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+const COMPAT_URL = `${BASE_URL}/openai`;
+
+// Repo-root-relative key file. Resolved relative to this source file so
+// CWD changes during runs (programbench/tbench cd into workspaces) don't
+// break the lookup. Plugin is inert if the file is missing. Tests may
+// override the path via `RUMMY_GEMINI_KEY_FILE` to point at a tmpdir
+// fixture; the env var is a path knob, not a runtime fallback.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function resolveKeyFile() {
+	return process.env.RUMMY_GEMINI_KEY_FILE
+		? process.env.RUMMY_GEMINI_KEY_FILE
+		: join(__dirname, "..", "..", "..", "gemini.key");
+}
+
+// Inert unless gemini.key exists in repo root; google/{model} aliases.
+//
+// Uses Google AI Studio's OpenAI-compatible endpoint
+// (`/v1beta/openai/chat/completions`) for completions so we share the
+// streaming SSE accumulator with the other OpenAI-shaped providers.
+// Context-size lookups go to the native endpoint
+// (`/v1beta/models/{model}`) because the OpenAI-compat /models response
+// drops `inputTokenLimit`.
+//
+// Auth is `Authorization: Bearer {key}` on both endpoints; the legacy
+// `?key={key}` query-param form is supported by Google but the bearer
+// form is consistent with our other plugins.
+export default class Google {
+	#apiKey;
+	#contextCache = new Map();
+
+	constructor(core) {
+		const keyFile = resolveKeyFile();
+		if (!existsSync(keyFile)) return;
+		const raw = readFileSync(keyFile, "utf8").trim();
+		if (!raw) return;
+		this.#apiKey = raw;
+
+		const wireModel = (alias) => alias.split("/").slice(1).join("/");
+
+		core.hooks.llm.providers.push({
+			name: PROVIDER,
+			matches: (model) => model.split("/")[0] === PROVIDER,
+			completion: (messages, model, options) =>
+				this.#completion(messages, wireModel(model), options),
+			getContextSize: (model) => this.#getContextSize(wireModel(model)),
+		});
+	}
+
+	async #completion(messages, model, options = {}) {
+		const body = { model, messages };
+		if (options.maxTokens !== undefined) body.max_tokens = options.maxTokens;
+		if (options.temperature !== undefined)
+			body.temperature = options.temperature;
+
+		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
+		const signal = options.signal
+			? AbortSignal.any([options.signal, timeoutSignal])
+			: timeoutSignal;
+
+		const headers = { Authorization: `Bearer ${this.#apiKey}` };
+
+		try {
+			return await chatCompletionStream({
+				url: `${COMPAT_URL}/chat/completions`,
+				headers,
+				body,
+				signal,
+			});
+		} catch (err) {
+			if (err.status === 401 || err.status === 403) {
+				throw new Error(
+					msg("error.google_auth", { status: `${err.status} - ${err.body}` }),
+				);
+			}
+			if (err.status) {
+				throw new Error(
+					msg("error.google_api", { status: `${err.status} - ${err.body}` }),
+				);
+			}
+			throw err;
+		}
+	}
+
+	async #getContextSize(model) {
+		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
+
+		// Native /v1beta/models/{model} requires API key as `?key=` query
+		// parameter — Bearer auth (which works on the OpenAI-compat layer)
+		// returns 401 here. Different auth surface, same key.
+		const url = `${BASE_URL}/models/${model}?key=${encodeURIComponent(this.#apiKey)}`;
+		const res = await fetch(url, {
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
+		});
+		if (!res.ok) {
+			throw new Error(
+				msg("error.google_models_failed", { model, status: res.status }),
+			);
+		}
+		const data = await res.json();
+		const ctx = data?.inputTokenLimit;
+		if (!ctx) throw new Error(msg("error.google_no_context_length", { model }));
+		this.#contextCache.set(model, ctx);
+		return ctx;
+	}
+}