one-code-extension 0.1.0

package/extensions/lib/pi-version.ts

@@ -0,0 +1,54 @@
+/**
+ * Tested-pi-version guard for the package install path.
+ *
+ * The package rides on whatever pi the user has installed, and pi renames
+ * settings/flags between minor versions (0.83→0.84 renamed `uiMode` to
+ * `tuiMode`, and 0.84 rejects the old flag). A user who floats onto an
+ * untested pi hits silent breakage, so startup compares the running pi
+ * version to the range this release was verified against and warns — softly,
+ * never blocking — when outside it. The bundled `one-code` app pins pi inside
+ * the range, so it never warns.
+ */
+
+/** Inclusive minimum and exclusive maximum pi version this release is tested against. */
+export const TESTED_PI_MIN = "0.83.0";
+export const TESTED_PI_MAX_EXCLUSIVE = "0.85.0";
+
+/** Dotted-numeric parse; undefined for anything that is not plain x.y.z numbers. */
+export function parseVersion(version: string): number[] | undefined {
+	const parts = version.trim().split(".");
+	if (parts.length === 0 || parts.length > 3) return undefined;
+	const nums = parts.map((p) => (/^\d+$/.test(p) ? Number(p) : Number.NaN));
+	return nums.some(Number.isNaN) ? undefined : nums;
+}
+
+/** Standard triple compare; undefined when either side is unparseable. */
+export function compareVersions(a: string, b: string): number | undefined {
+	const left = parseVersion(a);
+	const right = parseVersion(b);
+	if (!left || !right) return undefined;
+	for (let i = 0; i < 3; i++) {
+		const diff = (left[i] ?? 0) - (right[i] ?? 0);
+		if (diff !== 0) return diff < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
+/**
+ * A warning line when the running pi is outside the tested range, undefined
+ * when in range or the version cannot be parsed (fail silent — a guard must
+ * never take the session down).
+ */
+export function piVersionWarning(runningPiVersion: string | undefined): string | undefined {
+	if (!runningPiVersion) return undefined;
+	const belowMin = compareVersions(runningPiVersion, TESTED_PI_MIN);
+	const atOrAboveMax = compareVersions(runningPiVersion, TESTED_PI_MAX_EXCLUSIVE);
+	if (belowMin === undefined || atOrAboveMax === undefined) return undefined;
+	if (belowMin >= 0 && atOrAboveMax < 0) return undefined;
+	const tested = `${TESTED_PI_MIN} – <${TESTED_PI_MAX_EXCLUSIVE}`;
+	return (
+		`one-code-extension is tested against pi ${tested}; you are running pi ${runningPiVersion}. ` +
+		`Things may still work, but if tools or settings misbehave, update one-code-extension ` +
+		`(or pin pi inside the tested range).`
+	);
+}

package/extensions/lib/plugins.ts

@@ -0,0 +1,227 @@
+/**
+ * Claude Code plugin discovery (pure).
+ *
+ * On-disk reality, read from a real installation:
+ *
+ *   ~/.claude/plugins/installed_plugins.json
+ *     { "version": 2, "plugins": { "<name>@<marketplace>": [{ scope, installPath, version }] } }
+ *
+ *   <installPath>/.claude-plugin/plugin.json   { name, description, author }
+ *   <installPath>/agents/*.md                  agent definitions
+ *   <installPath>/commands/*.md                slash commands
+ *   <installPath>/skills/<name>/SKILL.md       skills
+ *   <installPath>/.mcp.json                    MCP servers
+ *
+ * Claude Code namespaces everything a plugin provides as `<plugin>:<name>`, so
+ * two plugins can both ship a `commit` command.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export interface PluginManifest {
+	name?: string;
+	description?: string;
+}
+
+export interface Plugin {
+	/** Plugin name, without the @marketplace suffix. */
+	name: string;
+	marketplace?: string;
+	path: string;
+	version?: string;
+	description?: string;
+}
+
+export interface PluginResources {
+	agentsDir?: string;
+	commandsDir?: string;
+	skillsDir?: string;
+	mcpConfig?: string;
+	/** <plugin>/hooks/hooks.json when present — consumed by extensions/hooks. */
+	hooksConfig?: string;
+}
+
+interface InstalledEntry {
+	scope?: string;
+	installPath?: string;
+	version?: string;
+	enabled?: boolean;
+}
+
+export function splitPluginKey(key: string): { name: string; marketplace?: string } {
+	const at = key.lastIndexOf("@");
+	if (at <= 0) return { name: key };
+	return { name: key.slice(0, at), marketplace: key.slice(at + 1) };
+}
+
+/** Read a file's raw contents, or `undefined` if it doesn't exist or can't be read. */
+export function tryReadFile(path: string): string | undefined {
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+function readJsonFile<T>(path: string): T | undefined {
+	if (!existsSync(path)) return undefined;
+	const raw = tryReadFile(path);
+	if (raw === undefined) return undefined;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Reads the installed-plugin registry; the newest entry per plugin wins. */
+export function loadInstalledPlugins(claudeDir: string): Plugin[] {
+	const registry = readJsonFile<{ plugins?: Record<string, InstalledEntry[]> }>(
+		join(claudeDir, "plugins", "installed_plugins.json"),
+	);
+	if (!registry?.plugins) return [];
+
+	const plugins: Plugin[] = [];
+	for (const [key, entries] of Object.entries(registry.plugins)) {
+		if (!Array.isArray(entries) || entries.length === 0) continue;
+		const entry = entries.find((e) => e.enabled !== false && e.installPath);
+		if (!entry?.installPath || !existsSync(entry.installPath)) continue;
+
+		const { name, marketplace } = splitPluginKey(key);
+		const manifest = readJsonFile<PluginManifest>(join(entry.installPath, ".claude-plugin", "plugin.json"));
+		plugins.push({
+			name: manifest?.name || name,
+			marketplace,
+			path: entry.installPath,
+			version: entry.version,
+			description: manifest?.description,
+		});
+	}
+	return plugins.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function pluginResources(plugin: Plugin): PluginResources {
+	const dirIfExists = (name: string) => {
+		const path = join(plugin.path, name);
+		return existsSync(path) && statSync(path).isDirectory() ? path : undefined;
+	};
+	const mcpConfig = join(plugin.path, ".mcp.json");
+	const hooksConfig = join(plugin.path, "hooks", "hooks.json");
+	return {
+		agentsDir: dirIfExists("agents"),
+		commandsDir: dirIfExists("commands"),
+		skillsDir: dirIfExists("skills"),
+		mcpConfig: existsSync(mcpConfig) ? mcpConfig : undefined,
+		hooksConfig: existsSync(hooksConfig) ? hooksConfig : undefined,
+	};
+}
+
+export interface PluginSkill {
+	/** Namespaced `<plugin>:<skill>`, as Claude Code presents it. */
+	name: string;
+	plugin: string;
+	path: string;
+}
+
+/** Each immediate subdirectory holding a SKILL.md is one skill. */
+export function findPluginSkills(plugin: Plugin, skillsDir: string): PluginSkill[] {
+	const skills: PluginSkill[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(skillsDir);
+	} catch {
+		return skills;
+	}
+	for (const entry of entries) {
+		const skillFile = join(skillsDir, entry, "SKILL.md");
+		if (existsSync(skillFile)) {
+			skills.push({ name: `${plugin.name}:${entry}`, plugin: plugin.name, path: skillFile });
+		}
+	}
+	return skills;
+}
+
+export interface PluginCommand {
+	/** Namespaced `<plugin>:<command>`. */
+	name: string;
+	plugin: string;
+	path: string;
+}
+
+export function findPluginCommands(plugin: Plugin, commandsDir: string): PluginCommand[] {
+	let entries: string[];
+	try {
+		entries = readdirSync(commandsDir);
+	} catch {
+		return [];
+	}
+	return entries
+		.filter((entry) => entry.endsWith(".md"))
+		.map((entry) => ({
+			name: `${plugin.name}:${basename(entry, ".md")}`,
+			plugin: plugin.name,
+			path: join(commandsDir, entry),
+		}));
+}
+
+/**
+ * Everything a plugin contributes, resolved in one pass.
+ *
+ * IMPORTANT: this is a function each consuming extension calls for itself, not a
+ * shared singleton. Under jiti every extension file gets its own module
+ * instance, so module-level state written by one extension is invisible to
+ * another — a shared registry silently read as empty. Re-deriving is cheap (one
+ * small JSON plus a few directory checks) and has no load-order constraints.
+ */
+export interface NamespacedDir {
+	dir: string;
+	namespace: string;
+}
+
+export interface DiscoveredPlugins {
+	plugins: Plugin[];
+	agentDirs: NamespacedDir[];
+	skills: PluginSkill[];
+	commands: PluginCommand[];
+	mcpConfigs: string[];
+	/** Per-plugin summary, for status output. */
+	byPlugin: Map<string, { agents: boolean; skills: number; commands: number; mcp: boolean }>;
+}
+
+let cache: { claudeDir: string; result: DiscoveredPlugins } | undefined;
+
+export function discoverPlugins(claudeDir: string): DiscoveredPlugins {
+	if (cache?.claudeDir === claudeDir) return cache.result;
+
+	const plugins = loadInstalledPlugins(claudeDir);
+	const result: DiscoveredPlugins = {
+		plugins,
+		agentDirs: [],
+		skills: [],
+		commands: [],
+		mcpConfigs: [],
+		byPlugin: new Map(),
+	};
+
+	for (const plugin of plugins) {
+		const resources = pluginResources(plugin);
+		const skills = resources.skillsDir ? findPluginSkills(plugin, resources.skillsDir) : [];
+		const commands = resources.commandsDir ? findPluginCommands(plugin, resources.commandsDir) : [];
+
+		if (resources.agentsDir) result.agentDirs.push({ dir: resources.agentsDir, namespace: plugin.name });
+		result.skills.push(...skills);
+		result.commands.push(...commands);
+		if (resources.mcpConfig) result.mcpConfigs.push(resources.mcpConfig);
+
+		result.byPlugin.set(plugin.name, {
+			agents: !!resources.agentsDir,
+			skills: skills.length,
+			commands: commands.length,
+			mcp: !!resources.mcpConfig,
+		});
+	}
+
+	cache = { claudeDir, result };
+	return result;
+}

package/extensions/lib/reminders.ts

@@ -0,0 +1,212 @@
+/**
+ * System-reminder queue — the steering mechanism shared by all One Code
+ * extensions. Reminders are injected transiently into the outgoing request via
+ * pi's `context` event; they are never written to the session file.
+ *
+ * Cross-extension contract: emit on the event bus channel
+ * `one-code:system-reminder` with `{ text, scope? }` to enqueue from any
+ * extension (including third-party ones). Extensions in this package can also
+ * import `reminderQueue` directly.
+ *
+ * Placement mirrors Claude Code's first-user-message reminder stack. Session
+ * context reminders (deferred tools, agent catalog, MCP instructions, skills,
+ * the `# claudeMd` block) are `first-prepend`: they ride at the front of the
+ * FIRST user message, before the user's text, ordered by `order`. Turn-steering
+ * reminders (file changed, mode cycled, memory near-limit) are `last-append`:
+ * appended to the LAST user message, the Claude Code default. See
+ * docs/decisions and the captured payloads (opus-4-8.json / latest-haiku.json).
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+
+export const REMINDER_CHANNEL = "one-code:system-reminder";
+
+/** "next-turn" fires once on the next LLM call; "every-turn" fires on every call until removed. */
+export type ReminderScope = "next-turn" | "every-turn";
+
+/**
+ * `first-prepend` → front of the first user message, before the user text,
+ * sorted by `order` (Claude Code's context stack). `last-append` → end of the
+ * last user message (Claude Code's steering default).
+ */
+export type ReminderPlacement = "first-prepend" | "last-append";
+
+/**
+ * `order` values for the `first-prepend` context stack, matching Claude Code's
+ * fixed sequence on the first user message: deferred tools → agent catalog → MCP
+ * instructions → skills → the `# claudeMd` block (last, just before the user's
+ * text). Gaps leave room for One Code-specific reminders (e.g. subagent models).
+ */
+export const CONTEXT_ORDER = {
+	deferredTools: 10,
+	subagentModels: 20,
+	agents: 21,
+	mcp: 30,
+	skills: 40,
+	claudeMd: 50,
+} as const;
+
+/** A drained reminder with everything the injector needs to place it. */
+export interface ReminderEntry {
+	text: string;
+	placement: ReminderPlacement;
+	order: number;
+	/**
+	 * Literal text appended AFTER the closing `</system-reminder>` tag. Claude
+	 * Code's `# claudeMd` block ends `</system-reminder>\n\n` on the wire; this
+	 * reproduces that byte-for-byte. Defaults to "".
+	 */
+	suffix?: string;
+}
+
+export interface ReminderPayload {
+	text?: string;
+	scope?: ReminderScope;
+	/** Key so a reminder can be replaced (next-turn) or replaced/removed (every-turn). */
+	key?: string;
+	/** Remove the every-turn reminder registered under `key` instead of enqueueing. */
+	remove?: boolean;
+	/** Where in the message stack this reminder lands. Defaults to `last-append`. */
+	placement?: ReminderPlacement;
+	/** Sort key among `first-prepend` reminders (Claude Code order). Defaults to 0. */
+	order?: number;
+	/** Literal text appended after the closing `</system-reminder>` tag. Defaults to "". */
+	suffix?: string;
+}
+
+interface StoredReminder extends ReminderEntry {
+	key?: string;
+}
+
+type EnqueueOptions = {
+	scope?: ReminderScope;
+	key?: string;
+	placement?: ReminderPlacement;
+	order?: number;
+	suffix?: string;
+};
+
+export class ReminderQueue {
+	private nextTurn: StoredReminder[] = [];
+	private everyTurn = new Map<string, StoredReminder>();
+
+	enqueue(text: string, opts?: EnqueueOptions): void {
+		if (!text.trim()) return;
+		const entry: StoredReminder = {
+			text,
+			placement: opts?.placement ?? "last-append",
+			order: opts?.order ?? 0,
+			suffix: opts?.suffix,
+			key: opts?.key,
+		};
+		if (opts?.scope === "every-turn") {
+			this.everyTurn.set(opts.key ?? text, entry);
+		} else {
+			// A keyed next-turn reminder replaces its predecessor, so a rapidly
+			// re-emitted state change (cycling permission modes) announces only
+			// where it settled.
+			if (opts?.key) this.nextTurn = this.nextTurn.filter((r) => r.key !== opts.key);
+			this.nextTurn.push(entry);
+		}
+	}
+
+	remove(key: string): void {
+		this.everyTurn.delete(key);
+	}
+
+	/** Returns pending reminders. Clears next-turn reminders; every-turn ones persist. */
+	drain(): ReminderEntry[] {
+		const drained: ReminderEntry[] = [
+			...[...this.everyTurn.values()].map(strip),
+			...this.nextTurn.map(strip),
+		];
+		this.nextTurn = [];
+		return drained;
+	}
+
+	get size(): number {
+		return this.everyTurn.size + this.nextTurn.length;
+	}
+}
+
+function strip(r: StoredReminder): ReminderEntry {
+	return { text: r.text, placement: r.placement, order: r.order, suffix: r.suffix };
+}
+
+/** Shared queue instance for extensions in this package. */
+export const reminderQueue = new ReminderQueue();
+
+export function wrapReminder(text: string): string {
+	return `<system-reminder>\n${text}\n</system-reminder>`;
+}
+
+type ContentBlock = TextContent | ImageContent;
+type UserMessage = AgentMessage & { content: string | ContentBlock[] };
+
+function toBlocks(content: string | ContentBlock[]): ContentBlock[] {
+	return typeof content === "string" ? [{ type: "text", text: content }] : [...content];
+}
+
+function reminderBlock(entry: ReminderEntry): TextContent {
+	return { type: "text", text: wrapReminder(entry.text) + (entry.suffix ?? "") };
+}
+
+/**
+ * Returns a copy of `messages` with reminder blocks injected (Claude Code
+ * convention: reminders ride inside user-message content blocks). `first-prepend`
+ * entries go to the front of the first user message, sorted by `order`, before
+ * the user's text; `last-append` entries go to the end of the last user message.
+ * A bare string is treated as `last-append` (back-compat). The input array and
+ * its messages are not mutated. With no user message, messages are returned
+ * unchanged and the caller re-enqueues as needed.
+ */
+export function injectReminders(
+	messages: AgentMessage[],
+	reminders: Array<string | ReminderEntry>,
+): AgentMessage[] {
+	if (reminders.length === 0) return messages;
+
+	const entries: ReminderEntry[] = reminders.map((r) =>
+		typeof r === "string" ? { text: r, placement: "last-append", order: 0 } : r,
+	);
+
+	const firstPrepend = entries
+		.filter((e) => e.placement === "first-prepend")
+		.map((e, i) => ({ e, i }))
+		.sort((a, b) => a.e.order - b.e.order || a.i - b.i)
+		.map((x) => x.e);
+	const lastAppend = entries.filter((e) => e.placement === "last-append");
+
+	const firstUserIndex = messages.findIndex((m) => m.role === "user");
+	if (firstUserIndex === -1) return messages;
+	const lastUserIndex = messages.findLastIndex((m) => m.role === "user");
+
+	const result = [...messages];
+
+	if (firstUserIndex === lastUserIndex) {
+		const target = result[firstUserIndex] as UserMessage;
+		const blocks = toBlocks(target.content);
+		result[firstUserIndex] = {
+			...target,
+			content: [...firstPrepend.map(reminderBlock), ...blocks, ...lastAppend.map(reminderBlock)],
+		} as AgentMessage;
+		return result;
+	}
+
+	if (firstPrepend.length > 0) {
+		const target = result[firstUserIndex] as UserMessage;
+		result[firstUserIndex] = {
+			...target,
+			content: [...firstPrepend.map(reminderBlock), ...toBlocks(target.content)],
+		} as AgentMessage;
+	}
+	if (lastAppend.length > 0) {
+		const target = result[lastUserIndex] as UserMessage;
+		result[lastUserIndex] = {
+			...target,
+			content: [...toBlocks(target.content), ...lastAppend.map(reminderBlock)],
+		} as AgentMessage;
+	}
+	return result;
+}

package/extensions/lib/scratchpad.ts

@@ -0,0 +1,68 @@
+/**
+ * Session scratchpad — Claude Code's designated temp-files directory.
+ *
+ * Claude Code puts one under `<tmp>/claude-<uid>/<project-slug>/<session-id>/scratchpad`
+ * and tells the model (via a system-prompt section) to use it for everything
+ * that would otherwise land in `/tmp` or leak into the project. The path is
+ * per-session, so parallel sessions on one project never collide.
+ *
+ * Three extensions need the same path (system-prompt renders the section,
+ * permissions and the workflow gate allow writes into it), and jiti isolates
+ * module state — so each re-derives it through `sessionScratchpadDir`.
+ */
+
+import { realpathSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { findGitRoot } from "./git.ts";
+import { projectSlug } from "./memory.ts";
+
+/** Pure core, testable: the Claude Code path shape. */
+export function scratchpadDir(
+	tmpRoot: string,
+	uid: number | undefined,
+	projectRoot: string,
+	sessionId: string,
+): string {
+	const owner = uid === undefined ? "claude" : `claude-${uid}`;
+	return join(tmpRoot, owner, projectSlug(projectRoot), sessionId, "scratchpad");
+}
+
+/**
+ * `/tmp` resolved through its symlink (macOS: `/private/tmp`), so the path in
+ * the prompt, the path the permission check compares, and the case-folded
+ * resolved subject all name the same real location. Falls back to os.tmpdir()
+ * where /tmp does not exist.
+ */
+export function resolveTmpRoot(): string {
+	try {
+		return realpathSync("/tmp");
+	} catch {
+		return os.tmpdir();
+	}
+}
+
+/** The session's scratchpad, derived the same way by every consumer. */
+export function sessionScratchpadDir(cwd: string, sessionId: string): string {
+	const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+	return scratchpadDir(resolveTmpRoot(), uid, findGitRoot(cwd) ?? cwd, sessionId);
+}
+
+/** Claude Code's Scratchpad Directory prompt section, verbatim (see payload.json). */
+export function scratchpadPromptSection(dir: string): string {
+	return `# Scratchpad Directory
+
+IMPORTANT: Always use this scratchpad directory for temporary files instead of \`/tmp\` or other system temp directories:
+\`${dir}\`
+
+Use this directory for ALL temporary file needs:
+- Storing intermediate results or data during multi-step tasks
+- Writing temporary scripts or configuration files
+- Saving outputs that don't belong in the user's project
+- Creating working files during analysis or processing
+- Any file that would otherwise go to \`/tmp\`
+
+Only use \`/tmp\` if the user explicitly requests it.
+
+The scratchpad directory is session-specific, isolated from the user's project, and can generally be used without permission prompts.`;
+}