@possumtech/rummy 2.0.1 → 2.2.0

package/src/plugins/file/file.js

@@ -1,20 +1,11 @@
 import { isAbsolute, relative } from "node:path";
 
-/**
- * File plugin: projections and constraints for filesystem entries.
- *
- * Bare file paths (src/app.js) have scheme=NULL in the DB because
- * schemeOf() only recognizes "://" patterns. The schemes table has
- * a "file" entry so v_model_context can JOIN via COALESCE(scheme, 'file').
- * This is the one exception to "every scheme has a plugin owner" —
- * the file plugin owns the NULL scheme through the "file" registry entry.
- */
+// Owns NULL scheme (bare paths) via the "file" registry entry; see plugin README.
 export default class File {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		// "file" scheme covers bare paths (scheme IS NULL in DB)
 		core.registerScheme({ category: "data" });
 		core.on("visible", this.full.bind(this));
 		core.on("summarized", this.summary.bind(this));
@@ -28,11 +19,7 @@ export default class File {
 		return "";
 	}
 
-	/**
-	 * Set a project-level file constraint. Backbone operation —
-	 * constraints are project config, not tool dispatch.
-	 */
-	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;
 
@@ -45,9 +32,6 @@ export default class File {
 		return path;
 	}
 
-	/**
-	 * Remove a project-level file constraint.
-	 */
 	static async dropConstraint(db, projectId, pattern) {
 		const path = await normalizePath(db, projectId, pattern);
 		if (!path) return null;
@@ -60,14 +44,10 @@ export default class File {
 		return path;
 	}
 
-	/**
-	 * True if `path` is covered by any readonly constraint for the project.
-	 * Constraints can be globs; hedberg.match provides the pattern engine.
-	 * Called from AgentLoop set-accept to refuse writes to protected paths.
-	 */
+	// 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,34 +19,36 @@ 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) {
-			// Route through the unified error channel so the message lands
-			// as `<error>` in <log> with a readable body AND the failure
-			// counts as a strike. The previous direct `store.set` wrote a
-			// blank-bodied failed entry whose `error` attribute was never
-			// rendered — model saw a vague 400 and repeated the mistake.
-			await rummy.hooks.error.log.emit({
-				store,
+			await store.set({
 				runId,
 				turn,
 				loopId,
-				message:
-					'Missing required "path" attribute on <get>. Use <get path="..."/>.',
-				status: 400,
+				path: entry.resultPath,
+				body: 'Missing required "path" attribute on <get>. Use <get path="..."/>.',
+				state: "failed",
+				outcome: "validation",
 			});
 			return;
 		}
 		const normalized = Entries.normalizePath(target);
-		// XmlParser passes attributes through; `body` attr is optional.
 		const bodyFilter = entry.attributes.body;
-		const preview = entry.attributes.preview !== undefined;
-		const isPattern = bodyFilter || normalized.includes("*");
+		const manifest = entry.attributes.manifest !== undefined;
+		const wantedTags = tagsAttr
+			? tagsAttr
+					.split(",")
+					.map((t) => t.trim().toLowerCase())
+					.filter(Boolean)
+			: null;
+		const isPattern = bodyFilter || normalized.includes("*") || !!wantedTags;
 
-		// Negative `line` is idiomatic tail-from-end: `line="-50"` means
-		// "start 50 lines from the end," enabling `tail -n N` behavior.
-		// Positive `line` is 1-indexed from start (classic). `limit` is
-		// always a positive count.
+		// Negative line = tail-from-end (line=-50 starts 50 from end).
 		const lineRaw = entry.attributes.line;
 		const line = lineRaw != null ? parseInt(lineRaw, 10) : null;
 		const limit =
@@ -54,18 +56,26 @@ 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));
+			});
+		}
 
-		// Preview — list matches with their full-body token costs. No promotion,
-		// no visibility change, no Token Budget spent. Model uses this to plan
-		// which entries to actually promote. getDoc promises this behavior; the
-		// prior implementation silently promoted anyway, burning the Token Budget
-		// on entries the model thought it was only inspecting.
-		if (preview) {
+		// Manifest: list matches + full-body token costs; no promotion.
+		if (manifest) {
 			await storePatternResult(
 				store,
 				runId,
@@ -74,26 +84,17 @@ export default class Get {
 				target,
 				bodyFilter,
 				matches,
-				{ preview: true, loopId, attributes: { path: target } },
+				{ manifest: true, loopId, attributes: { path: target } },
 			);
 			return;
 		}
 
-		// Partial read — no visibility promotion, returns a line slice as the log item.
+		// 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,
@@ -106,38 +107,25 @@ export default class Get {
 				});
 				return;
 			}
-			const allLines = matches[0].body.split("\n");
-			const total = allLines.length;
-			// Negative line offsets from the end: line=-50 starts 50 lines
-			// before the end. Clamped to 1 if the offset exceeds total.
-			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;
-			// Body leads with the source path so the model can re-issue
-			// a full or different-range read without guessing the URL.
-			// lineStart/lineEnd/totalLines ride attrs so renderLogTag can
-			// surface `lines="a-b/total"` without parsing the body.
-			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;
 		}
@@ -188,10 +176,7 @@ export default class Get {
 				attributes: { path: target },
 			});
 		} else {
-			// Log a concise record of the promotion. The promoted entry
-			// itself is visible in <context>; this log line is the model's
-			// proof in <log> that the get has already been done so it
-			// doesn't re-issue the same fetch on a later turn.
+			// Log line in <log> proves the promotion happened so the model doesn't re-fetch.
 			await store.set({
 				runId,
 				turn,
@@ -212,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,36 +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" preview>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. -->
-
-* `preview` lists the paths and token budget impact of an operation without performing it.
-<!-- Partial read is safe: context budget unaffected. Tail idiom enables watching growing entries. -->
-
-* Remember to <set path="..." visibility="summarize"/> when entries or log events are no longer relevant.
+<!-- 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;
+	}
+}

package/src/plugins/hedberg/hedberg.js

@@ -1,91 +1,25 @@
-import { parseEditContent } from "./edits.js";
-import HeuristicMatcher, { generatePatch } from "./matcher.js";
-import { parseJsonEdit } from "./normalize.js";
-import { hedmatch, hedsearch } from "./patterns.js";
-import { parseSed } from "./sed.js";
-
-/**
- * Hedberg: the interpretation boundary between stochastic model output
- * and deterministic system operations.
- *
- * Registers its functions on core.hedberg so any plugin can call them:
- *   core.hedberg.match(pattern, string)
- *   core.hedberg.search(pattern, string)
- *   core.hedberg.replace(body, search, replacement, options?)
- *   core.hedberg.parseSed(input)
- *   core.hedberg.parseEdits(content)
- *   core.hedberg.generatePatch(path, old, new)
- */
-export default class Hedberg {
+// Hedberg plugin shim. The library lives at `src/lib/hedberg/`; this
+// shim's only job is to expose the same surface as `core.hooks.hedberg`
+// for external plugins (e.g. rummy.repo's FileScanner) that can't
+// reach into rummy/main's internals via direct import.
+//
+// Internal plugins should import from `src/lib/hedberg/` directly —
+// the hook namespace is for plugins shipped in separate packages.
+
+import Hedberg from "../../lib/hedberg/hedberg.js";
+import { generatePatch } from "../../lib/hedberg/matcher.js";
+import { hedmatch, hedsearch } from "../../lib/hedberg/patterns.js";
+
+export default class HedbergPlugin {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-
 		core.hooks.hedberg = {
 			match: hedmatch,
 			search: hedsearch,
 			replace: Hedberg.replace,
-			parseSed,
-			parseEdits: parseEditContent,
-			parseJsonEdit,
 			generatePatch,
 		};
-
-		// Patterns documentation distributed to individual tool docs.
-		// Hedberg has no model-facing docs of its own.
-	}
-
-	/**
-	 * Apply a replacement to text. Handles sed regex, literal match,
-	 * and heuristic fuzzy match — in that order.
-	 *
-	 * Returns { patch, searchText, replaceText, warning, error }
-	 */
-	static replace(body, search, replacement, { sed = false, flags = "" } = {}) {
-		let patch = null;
-		let warning = null;
-		let error = null;
-		const searchText = search;
-		const replaceText = replacement;
-
-		if (sed) {
-			try {
-				const re = new RegExp(
-					searchText,
-					flags.includes("g") ? flags : `${flags}g`,
-				);
-				// Unescape regex metacharacter escapes in the replacement string.
-				// The model writes `\[x\]` meaning literal `[x]` in both search
-				// and replace. RegExp handles this in search; in the replacement
-				// string we must strip the backslashes ourselves since
-				// String.replace only interprets `$` sequences, not `\`.
-				const unescaped = replaceText.replace(/\\([[\](){}.*+?^$|\\])/g, "$1");
-				patch = body.replace(re, unescaped);
-				if (patch === body) patch = null;
-			} catch {
-				// Invalid regex — fall through to literal/heuristic interpretation
-			}
-		}
-
-		if (!patch && body.includes(searchText)) {
-			patch = body.replaceAll(searchText, replaceText);
-		}
-
-		if (!patch) {
-			const matched = HeuristicMatcher.matchAndPatch(
-				"",
-				body,
-				searchText,
-				replaceText,
-			);
-			patch = matched.newContent;
-			warning = matched.warning;
-			error = matched.error;
-		}
-
-		return { patch, searchText, replaceText, warning, error };
 	}
 }
-
-export { generatePatch };

package/src/plugins/helpers.js

@@ -2,13 +2,48 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/**
- * Read a sibling tooldoc markdown file and return its model-facing text.
- * Strips HTML comments (rationale stays in source, never reaches the model)
- * and collapses any blank-line runs left behind. Each plugin's Doc.js is a
- * one-liner that defers to this so authors edit normal markdown instead of
- * a JS array of [text, rationale] pairs.
- */
+// Hard system ceiling on the size of any summarized projection. Single
+// source of truth — every plugin's `summarized` view must produce output
+// ≤ this many characters; materializeContext's defensive cap fires when
+// a plugin breaks the contract. Change this number, everything downstream
+// stays consistent (no "450 here, 480 there, 500 over yonder" drift).
+export const SUMMARY_MAX_CHARS = 500;
+
+// Render a single entry as a heredoc-fenced block. Replaces the prior
+// per-plugin XML tag rendering (`<known path="..." ...>body</known>`).
+//
+// Why heredoc, not XML: the model emits XML for actions (`<set>`,
+// `<get>`, `<sh>`). When entries were ALSO XML, the inner tag could
+// look indistinguishable from a tool call — a file containing a
+// `<set>` example, an env streamed-stdout containing tool-shaped text,
+// or the model's own `<known>` body containing accidental tag-shaped
+// content could leak into the model's emit pattern. Heredoc fences
+// have zero training prior in tool-emission position, so they're
+// structurally separate from the action grammar.
+//
+// Format: `{json-meta} <<:::{path}\n{body}\n:::{path}`. The path is the
+// terminator — collision requires the body to literally contain its own
+// URI on a line by itself, which is vanishingly rare without active
+// malice. JSON metadata is sorted-key stringified for prefix-cache
+// stability (different field order = different bytes = cache miss).
+export function renderEntry(path, metadata, body) {
+	const meta = canonicalJson(metadata);
+	if (!body) {
+		return `${meta} <<:::${path}\n:::${path}`;
+	}
+	const trailingNewline = body.endsWith("\n") ? "" : "\n";
+	return `${meta} <<:::${path}\n${body}${trailingNewline}:::${path}`;
+}
+
+// JSON.stringify with sorted top-level keys for byte-stable output.
+function canonicalJson(obj) {
+	const keys = Object.keys(obj).sort();
+	const sorted = {};
+	for (const k of keys) sorted[k] = obj[k];
+	return JSON.stringify(sorted);
+}
+
+// Read sibling tooldoc .md; strips HTML comments (rationale stays out of the model packet).
 export function loadDoc(metaUrl, name) {
 	const dir = dirname(fileURLToPath(metaUrl));
 	return readFileSync(join(dir, name), "utf8")
@@ -17,23 +52,50 @@ export function loadDoc(metaUrl, name) {
 		.trim();
 }
 
-/**
- * Translate a log entry path into its companion data-scheme base path.
- * `log://turn_N/{action}/{rest}` → `{action}://turn_N/{rest}`.
- * Streaming producers (sh, env) create data channel entries under the
- * producer scheme while the audit record lives in the log scheme; this
- * helper bridges the two namespaces. Returns null for non-log paths.
- */
+// log://turn_N/{action}/{rest} → {action}://turn_N/{rest}; null if not a log path.
 export function logPathToDataBase(logPath) {
 	const m = logPath?.match(/^log:\/\/turn_(\d+)\/([^/]+)\/(.+)$/);
 	if (!m) return null;
 	return `${m[2]}://turn_${m[1]}/${m[3]}`;
 }
 
-/**
- * Shared helper for pattern-based tool results.
- * Used by get, set, store, and rm tools.
- */
+// env/sh stdout/stderr summary projection: line-tail with a final hard
+// truncation to SUMMARY_MAX_CHARS. The line cap is the natural unit
+// when the program emits text; the final size cap is the contract floor
+// (see materializeContext) and protects against few-newline output like
+// terminal-control programs (cmatrix, htop) emitting one giant ANSI line.
+//
+// Output stays as a flat string (not a renderEntry block) because the
+// caller (log.assembleLog) wraps each log entry in renderEntry with its
+// own metadata; this is the BODY of that block. Effectively double
+// fencing — `<<:::log://turn_3/sh/foo` outer, then this header inside —
+// but that's correct: the outer fence labels "this is sh activity at
+// turn 3", and the body inside is the slice of stdout the model sees.
+export function streamSummary(label, entry, MAX_LINES = 20) {
+	if (!entry.body) return "";
+	const { body, attributes } = entry;
+	const command = attributes.command;
+	const channel = attributes.channel === 2 ? "stderr" : "stdout";
+	const trailingNewline = body.endsWith("\n");
+	const lines = trailingNewline
+		? body.slice(0, -1).split("\n")
+		: body.split("\n");
+	const total = lines.length;
+	const lineTail =
+		total <= MAX_LINES
+			? body
+			: lines.slice(-MAX_LINES).join("\n") + (trailingNewline ? "\n" : "");
+
+	const header =
+		total <= MAX_LINES
+			? `# ${label} ${command} (${channel}, ${total}L)`
+			: `# ${label} ${command} (${channel}, lines ${total - MAX_LINES + 1} through ${total} of ${total}; <get line="1" limit="N"/> for head)`;
+
+	const out = `${header}\n${lineTail}`;
+	return out.length > SUMMARY_MAX_CHARS ? out.slice(0, SUMMARY_MAX_CHARS) : out;
+}
+
+// Pattern-result log entry shared by get/set/store/rm.
 export async function storePatternResult(
 	store,
 	runId,
@@ -42,13 +104,13 @@ export async function storePatternResult(
 	path,
 	bodyFilter,
 	matches,
-	{ preview = false, loopId = null, attributes = null } = {},
+	{ manifest = false, loopId = null, attributes = null } = {},
 ) {
 	const logSlug = await store.logPath(runId, turn, scheme, path);
 	const filter = bodyFilter ? ` body="${bodyFilter}"` : "";
 	const total = matches.reduce((s, m) => s + m.tokens, 0);
 	const listing = matches.map((m) => `${m.path} (${m.tokens})`).join("\n");
-	const prefix = preview ? "PREVIEW " : "";
+	const prefix = manifest ? "MANIFEST " : "";
 	const body = `${prefix}${scheme} path="${path}"${filter}: ${matches.length} matched (${total} tokens)\n${listing}`;
 	await store.set({
 		runId,