one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/skill-scan.ts

@@ -3,22 +3,26 @@
  * command registration (pure fs). (The /plugins Installed tab builds its rows
  * from discoverPlugins directly and no longer calls this.)
  *
- * Scans the SAME directories claude-compat feeds to pi, in pi's order —
- * `~/.claude/skills`, `~/.agents/skills`, `<cwd>/.claude/skills`,
- * `<cwd>/.agents/skills`, `<agentDir>/skills`, then the bundled catalog last
- * (so it loses a name collision, as it does in pi) — and merges the plugin
- * skills the caller resolved. Rows carry the SKILL.md path (for the ~token
+ * Scans the SAME directories pi loads, in pi's order — `<agentDir>/skills`
+ * (pi's own), then the ones claude-compat feeds it: `~/.claude/skills`,
+ * `~/.agents/skills`, `<cwd>/.claude/skills`, `<cwd>/.agents/skills`, and the
+ * bundled catalog last — and merges the plugin skills the caller resolved.
+ * As in pi, a name loads once (the first wins, so the bundled catalog loses a
+ * collision) and a file reached twice through a link counts once, so the
+ * banner, `/skills` and `/doctor` count the skills pi actually loads. Rows carry the SKILL.md path (for the ~token
  * size estimate) and the scope used by skill-overrides keys. Before the first
  * turn this scan is the only skill list One Code has (pi resolves skills per
  * turn), so a root missing here is a skill with no `/name` command at startup.
  */
 
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PluginSkill } from "./plugins.ts";
 import type { SkillScope } from "./skill-overrides.ts";
-import { claudeUserDir } from "./paths.ts";
+import { claudeSourcesOn, projectConfigDir, userConfigDir } from "./config-mode.ts";
+import { claudeUserDir, isPathAtOrUnder, tryRealpath } from "./paths.ts";
+import { parseFrontmatterLoosely } from "./frontmatter.ts";
 
 /** The skill catalog shipped in this package: `<package>/skills` (Claude Code's self-contained built-in skills). */
 export const BUNDLED_SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
@@ -31,16 +35,38 @@ export interface ScannedSkill {
 
 /**
  * The one scope-classification rule for a skill path — user skills live under
- * `~/.claude/skills` AND `<agentDir>/skills`; everything else is project
+ * `~/.claude/skills`, `~/.agents/skills` and `<agentDir>/skills`; everything else is project
  * scope. Both the scanner and the skill extension classify through this, so a
  * skill never shows different scopes in /plugins vs the skill tool.
  */
 export function scopeForPath(path: string, home: string, agentDir: string): SkillScope {
-	if (path.startsWith(join(claudeUserDir(home), "skills")) || path.startsWith(join(agentDir, "skills"))) return "user";
-	return "project";
+	const roots = [join(claudeUserDir(home), "skills"), join(home, ".agents", "skills"), join(agentDir, "skills")];
+	return roots.some((root) => isPathAtOrUnder(path, root)) ? "user" : "project";
 }
 
-function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>): void {
+/**
+ * The skill folders One Code adds to pi's own (`<agentDir>/skills`, which pi
+ * scans itself), in load order: Claude Code's two only in Claude-compatible
+ * mode (lib/config-mode.ts), the cross-tool `.agents` pair in both. `claudeDir`
+ * defaults to `~/.claude` (`CLAUDE_CONFIG_DIR`); `~/.agents` is never moved.
+ */
+export function skillSourceDirs(cwd: string, home: string, claudeDir: string = claudeUserDir(home)): Array<{ dir: string; scope: SkillScope }> {
+	const claude = claudeSourcesOn();
+	const dirs: Array<{ dir: string; scope: SkillScope } | false> = [
+		claude && { dir: join(claudeDir, "skills"), scope: "user" },
+		{ dir: join(home, ".agents", "skills"), scope: "user" },
+		claude && { dir: join(cwd, ".claude", "skills"), scope: "project" },
+		{ dir: join(cwd, ".agents", "skills"), scope: "project" },
+	];
+	return dirs.filter((d): d is { dir: string; scope: SkillScope } => d !== false);
+}
+
+/** The prompt-template folders: `~/.claude/commands` and `.claude/commands`, or their `.onecode` twins in independent mode. */
+export function commandDirs(cwd: string, home: string, claudeDir: string = claudeUserDir(home)): string[] {
+	return [join(claudeSourcesOn() ? claudeDir : userConfigDir(home), "commands"), join(projectConfigDir(cwd), "commands")];
+}
+
+function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>, seenFiles: Set<string>): void {
 	if (!existsSync(dir)) return;
 	let entries: string[];
 	try {
@@ -51,9 +77,18 @@ function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>
 	for (const entry of entries) {
 		const skillFile = join(dir, entry, "SKILL.md");
 		// existsSync follows symlinked skill directories, which isDirectory() would miss.
-		if (existsSync(skillFile) && !into.has(`${scope}:${entry}`)) {
-			into.set(`${scope}:${entry}`, { name: entry, path: skillFile, scope });
+		if (!existsSync(skillFile)) continue;
+		let name = entry;
+		try {
+			const declared = parseFrontmatterLoosely(readFileSync(skillFile, "utf-8")).frontmatter.name;
+			if (typeof declared === "string" && declared) name = declared;
+		} catch {
+			continue;
 		}
+		const real = tryRealpath(skillFile) ?? skillFile;
+		if (into.has(name) || seenFiles.has(real)) continue;
+		seenFiles.add(real);
+		into.set(name, { name, path: skillFile, scope });
 	}
 }
 
@@ -65,12 +100,10 @@ export function scanSkills(
 	bundledSkillsDir?: string,
 ): ScannedSkill[] {
 	const skills = new Map<string, ScannedSkill>();
-	scanDir(join(claudeUserDir(home), "skills"), "user", skills);
-	scanDir(join(home, ".agents", "skills"), "user", skills);
-	scanDir(join(cwd, ".claude", "skills"), "project", skills);
-	scanDir(join(cwd, ".agents", "skills"), "project", skills);
-	scanDir(join(agentDir, "skills"), "user", skills);
-	if (bundledSkillsDir) scanDir(bundledSkillsDir, scopeForPath(bundledSkillsDir, home, agentDir), skills);
+	const seenFiles = new Set<string>();
+	scanDir(join(agentDir, "skills"), "user", skills, seenFiles);
+	for (const { dir, scope } of skillSourceDirs(cwd, home)) scanDir(dir, scope, skills, seenFiles);
+	if (bundledSkillsDir) scanDir(bundledSkillsDir, scopeForPath(bundledSkillsDir, home, agentDir), skills, seenFiles);
 	for (const skill of pluginSkills) {
 		skills.set(`plugin:${skill.name}`, { name: skill.name, path: skill.path, scope: "plugin" });
 	}
@@ -80,14 +113,20 @@ export function scanSkills(
 /**
  * Names of the `.claude/commands` prompt templates (`<name>.md`) pi will expose
  * as `/<name>` — the same dirs claude-compat feeds pi (`~/.claude/commands`,
- * `<cwd>/.claude/commands`) plus pi's own `<agentDir>/prompts`. pi resolves
+ * `<cwd>/.claude/commands`, or their `.onecode` twins in independent mode)
+ * plus pi's own `<agentDir>/prompts`. pi resolves
  * templates per turn, after `session_start`, so a bare skill command registered
  * then would silently shadow a same-named template for the whole session;
  * this pre-scan lets the registration skip those names.
  */
 export function promptTemplateNames(cwd: string, home: string, agentDir: string): string[] {
-	const names = new Set<string>();
-	for (const dir of [join(claudeUserDir(home), "commands"), join(cwd, ".claude", "commands"), join(agentDir, "prompts")]) {
+	return [...new Set(promptTemplateFiles(cwd, home, agentDir).map((file) => file.name))];
+}
+
+/** Every prompt-template file pi will resolve, with the command name each gives. */
+export function promptTemplateFiles(cwd: string, home: string, agentDir: string): { name: string; path: string }[] {
+	const files: { name: string; path: string }[] = [];
+	for (const dir of [...commandDirs(cwd, home), join(agentDir, "prompts")]) {
 		if (!existsSync(dir)) continue;
 		let entries: string[];
 		try {
@@ -95,9 +134,9 @@ export function promptTemplateNames(cwd: string, home: string, agentDir: string)
 		} catch {
 			continue;
 		}
-		for (const entry of entries) if (entry.endsWith(".md")) names.add(entry.slice(0, -3));
+		for (const entry of entries) if (entry.endsWith(".md")) files.push({ name: entry.slice(0, -3), path: join(dir, entry) });
 	}
-	return [...names];
+	return files;
 }
 
 /** Rough token estimate from the SKILL.md byte size (~4 bytes/token). */

package/extensions/lib/spill-file.ts

@@ -0,0 +1,140 @@
+/**
+ * Keep pi's foreground shell spill file readable.
+ *
+ * When a foreground `bash` or `powershell` run prints more than pi keeps, pi
+ * writes the whole output to `<os.tmpdir()>/pi-<shell>-<16 hex>.log` and ends
+ * the text with `[… Full output: <path>]`, on success and on a failure: a
+ * non-zero exit is an error result from pi 0.99 on and a thrown error before
+ * it, and a timeout or an abort is always thrown. `os.tmpdir()` is outside
+ * every root the permission gate treats as readable, so the "full output is
+ * one read away" promise held only where outside reads skip the gate. So the
+ * file is moved into the session's persisted-results dir (a readable root)
+ * and the path in the text is rewritten to match.
+ *
+ * Only a file pi produced is moved: the path must sit directly in the temp
+ * dir and carry pi's name shape, so a command that prints a look-alike line
+ * cannot make the harness move some other file.
+ *
+ * The output is also cut Claude Code's way instead of pi's. pi
+ * keeps the last 2,000 lines or 50 KB and drops the head, so a batched
+ * command lost its first commands' output. Claude Code keeps the head: the
+ * whole output up to its inline cap, past it the persisted block naming the
+ * file, with the first 2 KB as the preview. pi's spill file holds the whole
+ * output, so the block names it and nothing is copied.
+ */
+
+import { copyFileSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { persistedFilePreview, persistIfLarge } from "./persisted-output.ts";
+
+const MARKER = "Full output: ";
+const PI_SPILL_NAME = /^pi-[a-z]+-[0-9a-f]{16}\.log$/;
+/** The note pi ends a cut output with: `\n\n[Showing lines …` or `\n\n[Showing last …`. */
+const PI_NOTE = "\n\n[Showing ";
+/** pi's status after the output of a run that did not exit 0. */
+const PI_STATUS = /(?:^|\n\n)Command (?:exited with code -?\d+|timed out after \S+ seconds|aborted|terminated without an exit code)$/;
+
+/** How a shell's output is cut: whole up to `inlineMax` bytes, past it persisted as `<id>.txt` when pi did not spill it. */
+export interface OutputBound {
+	inlineMax: number;
+	id: string;
+}
+
+/** The spill path pi named at the end of `text`, when it is one pi produced in `tmp`. Pure. */
+export function piSpillPath(text: string, tmp: string = tmpdir()): string | undefined {
+	const at = text.lastIndexOf(MARKER);
+	if (at === -1) return undefined;
+	const close = text.indexOf("]", at + MARKER.length);
+	if (close === -1) return undefined;
+	const path = text.slice(at + MARKER.length, close);
+	if (!PI_SPILL_NAME.test(basename(path))) return undefined;
+	if (resolve(dirname(path)) !== resolve(tmp)) return undefined;
+	return path;
+}
+
+/** Move `from` into `dir`, keeping its name; the new path, or undefined when it could not move. */
+function moveInto(from: string, dir: string): string | undefined {
+	const to = join(dir, basename(from));
+	try {
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		try {
+			renameSync(from, to);
+		} catch {
+			// A different filesystem: copy, then drop the original.
+			copyFileSync(from, to);
+			unlinkSync(from);
+		}
+		return to;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * `text` with its spill file moved and pi's tail cut replaced by Claude
+ * Code's head-first one. A spill file that cannot be moved keeps pi's text;
+ * one that cannot be read, or a text not in pi's shape, keeps pi's text with
+ * only the path rewritten.
+ */
+export function boundSpillIn(text: string, resultsDir: string, bound: OutputBound, failed = true, tmp: string = tmpdir()): string {
+	// pi appends a status only to a run that did not exit 0; a successful
+	// command's own last line can look like one.
+	const status = failed ? PI_STATUS.exec(text) : null;
+	const end = status ? status.index : text.length;
+	const output = text.slice(0, end);
+	const from = piSpillPath(output, tmp);
+	if (!from) return persistIfLarge(output, { dir: resultsDir, id: bound.id, maxBytes: bound.inlineMax }) + text.slice(end);
+	const to = moveInto(from, resultsDir);
+	if (!to) return text;
+	// pi's note ends the output; anything else keeps pi's text.
+	const whole = output.includes(PI_NOTE) && output.endsWith(`${from}]`) ? wholeOutput(to, bound.inlineMax) : undefined;
+	return whole === undefined ? text.split(from).join(to) : whole + text.slice(end);
+}
+
+/** The spill file inline while it fits `inlineMax`, past it the persisted block; undefined when unreadable. */
+function wholeOutput(path: string, inlineMax: number): string | undefined {
+	try {
+		return statSync(path).size <= inlineMax ? readFileSync(path, "utf8") : persistedFilePreview(path);
+	} catch {
+		return undefined;
+	}
+}
+
+type TextResult = { content: Array<{ type: string; text?: string }>; details?: unknown };
+
+/**
+ * Run a foreground shell execute and keep its spill file readable: on a
+ * returned result the text and `details.fullOutputPath` are rewritten, and a
+ * thrown error is rethrown with its message rewritten, the output cut
+ * Claude Code's way (`bound`).
+ */
+export async function keepSpillReadable<R extends TextResult>(run: () => Promise<R>, resultsDir: string, bound: OutputBound): Promise<R> {
+	const rewrite = (text: string, failed: boolean) => boundSpillIn(text, resultsDir, bound, failed);
+	let result: R;
+	try {
+		result = await run();
+	} catch (error) {
+		if (error instanceof Error) {
+			const message = rewrite(error.message, true);
+			if (message !== error.message) {
+				const moved = new Error(message);
+				moved.stack = error.stack;
+				throw moved;
+			}
+		}
+		throw error;
+	}
+	const details = result.details as { fullOutputPath?: unknown } | undefined;
+	const text = result.content.find((block) => block.type === "text" && typeof block.text === "string");
+	if (!text?.text) return result;
+	const rewritten = rewrite(text.text, (result as { isError?: boolean }).isError === true);
+	if (rewritten === text.text) return result;
+	const from = piSpillPath(text.text);
+	const to = from ? join(resultsDir, basename(from)) : undefined;
+	return {
+		...result,
+		content: result.content.map((block) => (block === text ? { ...block, text: rewritten } : block)),
+		details: details && typeof details === "object" && to ? { ...details, fullOutputPath: to } : result.details,
+	};
+}

package/extensions/lib/subagent-handback.ts

@@ -0,0 +1,112 @@
+/**
+ * Claude Code's `SubagentHandback`: the tool every child session (an Agent
+ * run, a fork, a workflow agent) returns its result through, and the closing
+ * reminder that tells it so (decisions/subagents-workflows.md, "Every child
+ * hands back through SubagentHandback"). Claude Code gives it to Opus and
+ * Sonnet children only; One Code gives it to every child on every model.
+ *
+ * The tool records the report in the run's `HandbackSlot` and ends the run
+ * (`terminate`, so no further request goes out after a batch of hand-backs).
+ * The runner then reports the recorded text as the child's result, and falls
+ * back to the child's final message when the tool was never called.
+ *
+ * The tool keeps Claude Code's exact name, like `Agent` and `SendMessage`,
+ * because the harness frames that carry its report already name it ("its
+ * SubagentHandback call", lib/notifications.ts). It is harness plumbing: the
+ * child permission and hook gates never gate it, and an agent file's `tools`
+ * allowlist keeps it.
+ *
+ * In a fork the tool is deferred: a fork sends the parent's tool list so it
+ * reads the parent's prompt cache (subagents/fork-cache.ts), and an eager tool
+ * of its own would be dropped from that list. A deferred one reaches the
+ * request through a `tool_search` load, as the fork's `SendMessage` does.
+ */
+
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { DEFER_CHANNEL } from "./deferred.ts";
+import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
+
+export const SUBAGENT_HANDBACK = "SubagentHandback";
+
+/** Claude Code's description of the tool. */
+export const SUBAGENT_HANDBACK_DESCRIPTION =
+	"Deliver your final report to the agent that spawned you (your caller). Use it once, for that hand-off only: when your work is complete, call SubagentHandback({message: <your full report>}). The call ends your run, so do everything else first and put everything your caller needs in that one report. It is not a messaging channel: do not use it for progress updates or questions.\n\nOnly a report delivered through SubagentHandback reaches your caller; plain text you write at the end of your run is NOT delivered. There is no recipient parameter: the report can only go to your caller.";
+
+/** Claude Code's closing reminder on the child's task message. */
+export const SUBAGENT_HANDBACK_REMINDER =
+	"Your final report is delivered through SubagentHandback: when your work is complete, call SubagentHandback({message: <your full report>}). The call ends your run, so make it your last step. Only a SubagentHandback call reaches your caller as your result; plain text you write at the end is not delivered.";
+
+/**
+ * One Code's line before the reminder in a fork, where the tool is deferred
+ * (the fork sends its parent's tool list): it names the load step, which the
+ * frozen deferred listing it inherits does not.
+ */
+export const SUBAGENT_HANDBACK_LOAD_FIRST =
+	'SubagentHandback is deferred here: load it first with tool_search (query "select:SubagentHandback").';
+
+/** Claude Code's result texts for the call. */
+export const HANDBACK_DELIVERED = "Report delivered to your caller.";
+export const HANDBACK_ALREADY_DELIVERED =
+	"Nothing was sent: your report was already delivered (SubagentHandback delivers one report). Use SendMessage for anything further, then stop.";
+export const HANDBACK_EMPTY = "message must not be empty: pass your full report as `message`.";
+
+/** Where a run keeps the report its child handed back. */
+export interface HandbackSlot {
+	/** Record the report; false when this turn already delivered one. */
+	recordHandback(message: string): boolean;
+}
+
+/** A slot for a one-turn run (a workflow agent): the first report wins. */
+export function oneTurnHandbackSlot(): HandbackSlot & { report?: string } {
+	const slot: HandbackSlot & { report?: string } = {
+		report: undefined,
+		recordHandback(message) {
+			if (slot.report !== undefined) return false;
+			slot.report = message;
+			return true;
+		},
+	};
+	return slot;
+}
+
+export function subagentHandbackTool(slot: HandbackSlot): ToolDefinition {
+	return {
+		name: SUBAGENT_HANDBACK,
+		label: "Hand back",
+		description: SUBAGENT_HANDBACK_DESCRIPTION,
+		parameters: Type.Object({ message: Type.String({ description: "Your full report for your caller" }) }, { additionalProperties: false }) as never,
+		async execute(_toolCallId: string, params: unknown) {
+			const message = (params as { message?: unknown } | undefined)?.message;
+			// Fail loud (decisions/tools.md): an empty report would end the run with nothing for the caller.
+			if (typeof message !== "string" || !message.trim()) {
+				return { content: [{ type: "text" as const, text: HANDBACK_EMPTY }], details: {}, isError: true };
+			}
+			if (!slot.recordHandback(message)) {
+				return { content: [{ type: "text" as const, text: HANDBACK_ALREADY_DELIVERED }], details: {}, isError: true };
+			}
+			return { content: [{ type: "text" as const, text: HANDBACK_DELIVERED }], details: { handback: true }, terminate: true };
+		},
+	} as ToolDefinition;
+}
+
+/**
+ * The inline extension a child session loads for the hand-back: the tool,
+ * deferred in a fork, and the closing reminder. The reminder is a standing
+ * block (`sticky-append`) switched on at session start, so it rides the
+ * child's task message and every later message of the run (a resident's
+ * next turns hand back too), and never an inherited message of a fork.
+ */
+export function subagentHandbackExtension(slot: HandbackSlot, options: { deferred?: boolean } = {}) {
+	return (pi: ExtensionAPI) => {
+		pi.registerTool(subagentHandbackTool(slot));
+		if (options.deferred) pi.events.emit(DEFER_CHANNEL, { name: SUBAGENT_HANDBACK, keywords: ["handback", "report", "result", "final", "caller"] });
+		pi.on("session_start", () => {
+			pi.events.emit(REMINDER_CHANNEL, {
+				text: options.deferred ? `${SUBAGENT_HANDBACK_LOAD_FIRST}\n${SUBAGENT_HANDBACK_REMINDER}` : SUBAGENT_HANDBACK_REMINDER,
+				key: "subagent-handback",
+				placement: "sticky-append",
+			} satisfies ReminderPayload);
+		});
+	};
+}

package/extensions/lib/system-role.ts

@@ -0,0 +1,156 @@
+/**
+ * Which models get Claude Code's mid-conversation `role: "system"` message,
+ * and in which wire shape (pure). One function for the system-prompt builder,
+ * the reminder hook and the tool hook, so all three agree on every request.
+ *
+ * The gate is pi's model catalog flag `compat.supportsMidConvoSystemMessages`
+ * alone, no list of our own: pi owns the per-model facts and adds models as it
+ * confirms them (`working-docs/decisions/tools.md`, "Claude Code's request
+ * shape, on every model pi flags for it"). Haiku before 5 is never in it:
+ * Anthropic rejects the role there (findings §52); Haiku 5.5 takes it
+ * (findings §67). Every unflagged model keeps the context in the first user
+ * message.
+ */
+
+import { parseClaudeId } from "./claude-id.ts";
+
+/** The wire shape a system message takes: Anthropic `system`, OpenAI Responses `input`, or Chat Completions `messages`. */
+export type SystemRoleLayout = "anthropic" | "responses" | "completions";
+
+/** The fields of a pi `Model` the gate reads. */
+export interface SystemRoleModel {
+	id: string;
+	api: string;
+	compat?: unknown;
+}
+
+/** pi-ai's Responses APIs: requests carry `input` items and flat `{ type, name }` tools. */
+export const RESPONSES_APIS: ReadonlySet<string> = new Set(["openai-responses", "azure-openai-responses", "openai-codex-responses"]);
+
+/** The wire shape of a pi API, for the three shapes One Code rewrites; undefined for the rest (Google, Bedrock). */
+export function wireShape(api: string): SystemRoleLayout | undefined {
+	if (api === "anthropic-messages") return "anthropic";
+	if (RESPONSES_APIS.has(api)) return "responses";
+	if (api === "openai-completions") return "completions";
+	return undefined;
+}
+
+/** The payload field that holds the conversation for a wire shape. */
+export function messagesKey(shape: SystemRoleLayout): "input" | "messages" {
+	return shape === "responses" ? "input" : "messages";
+}
+
+export function systemRoleLayout(model: SystemRoleModel | undefined): SystemRoleLayout | undefined {
+	if (!model) return undefined;
+	const compat = model.compat as { supportsMidConvoSystemMessages?: unknown } | undefined;
+	if (compat?.supportsMidConvoSystemMessages !== true) return undefined;
+	if (model.api === "anthropic-messages" && isHaikuBeforeFive(model.id)) return undefined;
+	return wireShape(model.api);
+}
+
+/** A Haiku older than Haiku 5 in any provider's spelling; the old `claude-3-5-haiku` order parses as none. */
+function isHaikuBeforeFive(id: string): boolean {
+	const claude = parseClaudeId(id);
+	return claude ? claude.family === "haiku" && claude.major < 5 : id.includes("haiku");
+}
+
+/** One context block that moves: its text as injected on the user message, and its text inside the system message. */
+export interface MovedBlock {
+	/** The block exactly as the user message carries it (`<system-reminder>` frame and suffix included). */
+	framed: string;
+	/** The unwrapped text, as Claude Code's system message joins it. */
+	inner: string;
+}
+
+/**
+ * The role a system message takes on the OpenAI APIs: pi's own rule per API
+ * (`developer` for a reasoning model that accepts it, else `system`).
+ */
+export function instructionRole(layout: SystemRoleLayout, model: { reasoning?: boolean; compat?: unknown }): "system" | "developer" {
+	if (layout === "anthropic") return "system";
+	const developer = (model.compat as { supportsDeveloperRole?: boolean } | undefined)?.supportsDeveloperRole;
+	const accepts = layout === "responses" ? developer !== false : developer === true;
+	return model.reasoning && accepts ? "developer" : "system";
+}
+
+/** A wire message and content part, as far as the payload rewrites read them. */
+export type WireMessage = { role?: unknown; type?: unknown; content?: unknown; output?: unknown; call_id?: unknown; tool_call_id?: unknown };
+export type WirePart = { type?: unknown; text?: unknown; content?: unknown; tool_use_id?: unknown; cache_control?: unknown };
+
+/**
+ * The parts with those `drop` accepts removed, keeping pi's cache mark: when a
+ * removed part carried it, it moves to the new last part. Undefined when every
+ * part would go (a message cannot be left empty) or nothing is removed.
+ */
+export function withoutParts(parts: readonly WirePart[], drop: (part: WirePart, index: number) => boolean): WirePart[] | undefined {
+	let mark: unknown;
+	const kept = parts.filter((part, index) => {
+		if (!drop(part, index)) return true;
+		if (part?.cache_control !== undefined) mark = part.cache_control;
+		return false;
+	});
+	if (kept.length === parts.length || kept.length === 0) return undefined;
+	if (mark === undefined || kept[kept.length - 1].cache_control !== undefined) return kept;
+	return [...kept.slice(0, -1), { ...kept[kept.length - 1], cache_control: mark }];
+}
+
+/**
+ * The value stored under a pi call id for the id a request carries: the same
+ * id, the Responses call id before pi's `|item` suffix, or the id pi-ai's
+ * Anthropic conversion rewrote (any other character to `_`, at most 64), as it
+ * does for a call made on another provider before a model switch.
+ */
+export function byWireCallId<V>(stored: ReadonlyMap<string, V>, wireId: string): V | undefined {
+	if (stored.has(wireId)) return stored.get(wireId);
+	for (const [id, value] of stored) {
+		if (id.split("|")[0] === wireId || id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) === wireId) return value;
+	}
+	return undefined;
+}
+
+/** A system message with `text` in the API's own shape. */
+export function systemMessage(layout: SystemRoleLayout, role: "system" | "developer", text: string): WireMessage {
+	return layout === "anthropic" ? { role: "system", content: [{ type: "text", text }] } : { role, content: text };
+}
+
+/**
+ * The payload with the moved context blocks lifted off the user message that
+ * carries them and joined, unwrapped and a blank line apart, into one system
+ * message placed right after it, in the API's own shape (Claude Code's layout,
+ * `decisions/tools.md`). Blocks are found by their exact text, never by
+ * position: a fork's request drops the parent's first message, and then nothing
+ * moves. The cache mark is reseated afterwards (anthropic-payload.ts
+ * reseatMessageMark). Undefined when nothing changes.
+ */
+export function withSystemRoleContext(
+	payload: Record<string, unknown>,
+	layout: SystemRoleLayout,
+	moved: readonly MovedBlock[],
+	role: "system" | "developer",
+): Record<string, unknown> | undefined {
+	if (moved.length === 0) return undefined;
+	const key = messagesKey(layout);
+	const messages = payload[key];
+	if (!Array.isArray(messages)) return undefined;
+	const wanted = new Set(moved.map((block) => block.framed));
+	const index = messages.findIndex(
+		(message: WireMessage) => message?.role === "user" && Array.isArray(message.content) && (message.content as WirePart[]).some((part) => wanted.has(part?.text as string)),
+	);
+	if (index === -1) return undefined;
+
+	const carrier = messages[index] as WireMessage & { content: WirePart[] };
+	const found = new Set<string>();
+	const kept = carrier.content.filter((part) => {
+		const text = part?.text;
+		if (typeof text !== "string" || !wanted.has(text) || found.has(text)) return true;
+		found.add(text);
+		return false;
+	});
+	const text = moved
+		.filter((block) => found.has(block.framed))
+		.map((block) => block.inner)
+		.join("\n\n");
+
+	const user: WireMessage = { ...carrier, content: kept };
+	return { ...payload, [key]: [...messages.slice(0, index), user, systemMessage(layout, role, text), ...messages.slice(index + 1)] };
+}