one-code-extension 0.1.3 → 0.3.0

package/extensions/branding/startup.ts

@@ -15,22 +15,37 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { findGitRoot } from "../lib/git.ts";
-import { discoverPlugins } from "../lib/plugins.ts";
+import { defaultDiscoverRoots, discoverPlugins } from "../lib/plugins.ts";
+import { claudeUserDir } from "../lib/paths.ts";
 
 export interface StartupSection {
 	label: string;
 	items: string[];
 }
 
-/** CLAUDE.md / CLAUDE.local.md / AGENTS.md from cwd up to the git root (or just cwd outside a repo). */
+/**
+ * The project context files One Code actually gathers, from cwd up to the git
+ * root (or just cwd outside a repo), for the startup banner. Mirrors what the
+ * blocks send: a directory's CLAUDE.md, or its AGENTS.md when it has no CLAUDE.md
+ * (CLAUDE.md > AGENTS.md), plus CLAUDE.local.md and ONECODE.md when present — so
+ * AGENTS.md is listed only when it's really in play, not whenever it exists.
+ */
 export function contextFileNames(cwd: string): string[] {
 	const stop = findGitRoot(cwd) ?? cwd;
 	const found: string[] = [];
 	let dir = cwd;
 	while (true) {
-		for (const name of ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]) {
-			const path = join(dir, name);
-			if (existsSync(path)) found.push(relative(cwd, path) || name);
+		const rel = (name: string) => relative(cwd, join(dir, name)) || name;
+		const present = (name: string) => existsSync(join(dir, name));
+		// CLAUDE.md is primary; AGENTS.md stands in only when there is no CLAUDE.md.
+		if (present("CLAUDE.md")) found.push(rel("CLAUDE.md"));
+		else if (present("AGENTS.md")) found.push(rel("AGENTS.md"));
+		if (present("CLAUDE.local.md")) found.push(rel("CLAUDE.local.md"));
+		for (const name of ["ONECODE.md", "onecode.md", "One Code.md"]) {
+			if (present(name)) {
+				found.push(rel(name));
+				break;
+			}
 		}
 		if (dir === stop) break;
 		const parent = dirname(dir);
@@ -49,7 +64,7 @@ export function contextFileNames(cwd: string): string[] {
 export function skillNames(cwd: string, home: string, agentDir: string): string[] {
 	const dirs = [
 		join(cwd, ".claude", "skills"),
-		join(home, ".claude", "skills"),
+		join(claudeUserDir(home), "skills"),
 		join(agentDir, "skills"),
 	];
 	const names = new Set<string>();
@@ -63,7 +78,7 @@ export function skillNames(cwd: string, home: string, agentDir: string): string[
 			// Unreadable dir: skip, same as pi would.
 		}
 	}
-	for (const skill of discoverPlugins(join(home, ".claude")).skills) {
+	for (const skill of discoverPlugins(defaultDiscoverRoots(agentDir, cwd, home)).skills) {
 		names.add(skill.name);
 	}
 	return [...names].sort((a, b) => a.localeCompare(b));
@@ -72,7 +87,7 @@ export function skillNames(cwd: string, home: string, agentDir: string): string[
 /** Saved workflow names from the Claude Code layout dirs (project shadows user). */
 export function workflowNames(cwd: string, home: string): string[] {
 	const names = new Set<string>();
-	for (const dir of [join(cwd, ".claude", "workflows"), join(home, ".claude", "workflows")]) {
+	for (const dir of [join(cwd, ".claude", "workflows"), join(claudeUserDir(home), "workflows")]) {
 		if (!existsSync(dir)) continue;
 		try {
 			for (const entry of readdirSync(dir)) {

package/extensions/claude-compat/index.ts

@@ -8,6 +8,12 @@
  *   ~/.claude/commands, <project>/.claude/commands → slash commands (prompt templates;
  *                                                    Claude Code's $ARGUMENTS works as-is)
  *
+ * It also points discovery at the catalog of skills bundled with this package
+ * (`<package>/skills`) — Claude Code's self-contained built-in skills, which
+ * ship inside its binary rather than on disk, so nothing else would surface
+ * them. See docs/decisions/skills-plugins.md and docs/findings (the extraction
+ * process is recorded in .claude/skills/extract-cc-skills/).
+ *
  * CLAUDE.md needs no handling — pi discovers it natively alongside AGENTS.md.
  */
 
@@ -16,6 +22,9 @@ import os from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { claudeConfigDir } from "../lib/paths.ts";
+import { claudeUserDir } from "../lib/paths.ts";
+
+import { BUNDLED_SKILLS_DIR } from "../lib/skill-scan.ts";
 
 /**
  * `claudeDir` is Claude Code's config dir (honours CLAUDE_CONFIG_DIR), defaulting
@@ -26,7 +35,8 @@ import { claudeConfigDir } from "../lib/paths.ts";
 export function claudeResourcePaths(
 	cwd: string,
 	home: string,
-	claudeDir: string = join(home, ".claude"),
+	claudeDir: string = claudeUserDir(home),
+	bundledSkillsDir?: string,
 ): { skillPaths: string[]; promptPaths: string[] } {
 	const candidates = {
 		skillPaths: [
@@ -34,6 +44,11 @@ export function claudeResourcePaths(
 			join(home, ".agents", "skills"),
 			join(cwd, ".claude", "skills"),
 			join(cwd, ".agents", "skills"),
+			// The bundled catalog is listed LAST so it loses a name collision:
+			// pi keeps the first-loaded skill for a given name, so a user or
+			// project skill of the same name wins and the bundled one is the
+			// fallback (see docs/decisions/skills-plugins.md).
+			...(bundledSkillsDir ? [bundledSkillsDir] : []),
 		],
 		promptPaths: [join(claudeDir, "commands"), join(cwd, ".claude", "commands")],
 	};
@@ -45,6 +60,6 @@ export function claudeResourcePaths(
 
 export default function claudeCompatExtension(pi: ExtensionAPI) {
 	pi.on("resources_discover", (event) => {
-		return claudeResourcePaths(event.cwd, os.homedir(), claudeConfigDir());
+		return claudeResourcePaths(event.cwd, os.homedir(), claudeConfigDir(), BUNDLED_SKILLS_DIR);
 	});
 }

package/extensions/claude-context/index.ts

@@ -10,6 +10,11 @@
  * pi's `context` event), so it never persists to the session and never doubles up
  * on resume.
  *
+ * When ONECODE.md files exist, this extension also emits a separate `# oneCodeMd`
+ * block at CONTEXT_ORDER.oneCodeMd — after # claudeMd, so One Code-specific
+ * instructions take precedence over CLAUDE.md. Keeping them out of # claudeMd
+ * leaves that block byte-exact with Claude Code.
+ *
  * Paths are re-derived from home/cwd here rather than shared with the memory
  * extension (jiti gives each extension its own module instance). CLAUDE.md is no
  * longer put in the system prompt, and MEMORY.md is no longer a separate reminder
@@ -21,12 +26,13 @@ import { readFileSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { buildClaudeMdBlock, discoverContextFiles } from "../lib/claude-context.ts";
+import { buildClaudeMdBlock, buildOneCodeBlock, discoverContextFiles, discoverOneCodeFiles } from "../lib/claude-context.ts";
 import { projectMemoryDir, truncateIndex } from "../lib/memory.ts";
-import { claudeConfigDir } from "../lib/paths.ts";
+import { claudeConfigDir, oneCodeStateDir } from "../lib/paths.ts";
 import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
 
 const REMINDER_KEY = "claude-context";
+const ONECODE_REMINDER_KEY = "one-code-context";
 
 /** The account email Claude Code stamps as `# userEmail`. git config is our proxy. */
 function resolveEmail(cwd: string): string | null {
@@ -53,10 +59,17 @@ function readMemoryIndex(cwd: string): { path: string; content: string } | null
 
 export default function claudeContextExtension(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
+		// The # claudeMd block carries the CLAUDE.md family, falling back to a
+		// directory's AGENTS.md when it has no CLAUDE.md (CLAUDE.md > AGENTS.md). It
+		// stays byte-exact with Claude Code wherever CLAUDE.md is present, since
+		// AGENTS.md only fills in for a missing one. ONECODE.md rides its own
+		// higher-precedence block below.
 		const inner = buildClaudeMdBlock({
 			contextFiles: discoverContextFiles({
 				cwd: ctx.cwd,
 				homeClaudeDir: claudeConfigDir(),
+				agentsFallback: true,
+				home: os.homedir(),
 			}),
 			memoryIndex: readMemoryIndex(ctx.cwd),
 			email: resolveEmail(ctx.cwd),
@@ -64,16 +77,32 @@ export default function claudeContextExtension(pi: ExtensionAPI) {
 			// block changes only across days too.
 			date: new Date().toISOString().slice(0, 10),
 		});
-		if (!inner) return;
+		if (inner) {
+			pi.events.emit(REMINDER_CHANNEL, {
+				text: inner,
+				scope: "every-turn",
+				key: REMINDER_KEY,
+				placement: "first-prepend",
+				order: CONTEXT_ORDER.claudeMd,
+				// Claude Code's claudeMd block ends `</system-reminder>\n\n` on the wire.
+				suffix: "\n\n",
+			});
+		}
 
-		pi.events.emit(REMINDER_CHANNEL, {
-			text: inner,
-			scope: "every-turn",
-			key: REMINDER_KEY,
-			placement: "first-prepend",
-			order: CONTEXT_ORDER.claudeMd,
-			// Claude Code's claudeMd block ends `</system-reminder>\n\n` on the wire.
-			suffix: "\n\n",
-		});
+		// One Code's own instructions ride in a separate block AFTER # claudeMd, so
+		// they take precedence over CLAUDE.md (higher order = closer to the user text).
+		const oneCode = buildOneCodeBlock(
+			discoverOneCodeFiles({ cwd: ctx.cwd, homeOneCodeDir: oneCodeStateDir(), home: os.homedir() }),
+		);
+		if (oneCode) {
+			pi.events.emit(REMINDER_CHANNEL, {
+				text: oneCode,
+				scope: "every-turn",
+				key: ONECODE_REMINDER_KEY,
+				placement: "first-prepend",
+				order: CONTEXT_ORDER.oneCodeMd,
+				suffix: "\n\n",
+			});
+		}
 	});
 }

package/extensions/clear/index.ts

@@ -0,0 +1,27 @@
+/**
+ * clear extension — Claude Code's `/clear`.
+ *
+ * Claude Code's `/clear` wipes the conversation and starts fresh in the same
+ * working directory. pi's nearest primitive is `newSession()` (its built-in
+ * command is `/new`). A user coming from Claude Code types `/clear` out of
+ * habit; without this it isn't a command, so the word goes to the model as a
+ * message instead of resetting context. This registers `/clear` alongside pi's
+ * `/new`, routed through the same `newSession()` call.
+ *
+ * Nuance vs. Claude Code: CC clears history in place; pi starts a new session
+ * file (same cwd, extensions, config). The user-facing effect is identical —
+ * a clean context — which is what a `/clear` habit wants. Like `/exit`→`/quit`,
+ * we cannot fold this into pi's `/new` palette entry (pi has no command
+ * aliases), so `/clear` and `/new` are two entries that both reset.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function clearExtension(pi: ExtensionAPI) {
+	pi.registerCommand("clear", {
+		description: "Clear the conversation and start fresh (same as /new)",
+		handler: async (_args, ctx) => {
+			await ctx.newSession();
+		},
+	});
+}

package/extensions/compaction/fit.ts

@@ -0,0 +1,121 @@
+/**
+ * Which request shape a compaction takes, and how a standalone one is made to
+ * fit the window. Pure: no pi extension API, only pi-ai's own estimator.
+ *
+ * Two shapes exist:
+ *
+ * - **Replay**: the session's last real request (captured from the `context`
+ *   event) plus the instruction. Cache-aligned, so the call is mostly cache
+ *   reads — the reason the extension compacts on the session model at all.
+ *   It only works while the request leaves room for the summary: pi clamps
+ *   `max_tokens` to what the window has left (`clampMaxTokensToContext`), so a
+ *   request at or over the window is sent with `max_tokens` 1, or the provider
+ *   rejects it outright. Both return nothing usable. An overflow-triggered
+ *   compaction is *by definition* in that state (review H2: every overflow
+ *   fell through to pi's summary).
+ *
+ * - **Standalone**: the doomed span alone (what pi is about to discard,
+ *   reconstructed from `preparation`), no tools, a one-line system prompt, and
+ *   the instruction. It cannot hit the cache, which is moot on an overflowing
+ *   request anyway; what it keeps is One Code's summary: the nine sections,
+ *   the continuation preamble, and the transcript pointer. Even the doomed
+ *   span may not fit — pi keeps only ~20k tokens after the cut, so on an
+ *   overflow the span is nearly the whole window — so `fitToBudget` clears
+ *   the largest tool results first until the request has room. Their full
+ *   text is in the session transcript the summary points at (Claude Code's
+ *   own microcompact clears old tool results the same way).
+ *
+ * Both decisions ask pi-ai's `clampMaxTokensToContext` — the very function
+ * `completeSimple` applies to the request — rather than re-deriving its
+ * arithmetic, so they can never disagree with the clamp they predict. One
+ * trap in that estimator: it anchors on the last assistant message's
+ * `usage` total when there is one (`withoutUsage`).
+ */
+
+import { type Api, type Context, contentText, type Message, type Model } from "@earendil-works/pi-ai";
+import { PREVIEW_BYTES } from "../lib/persisted-output.ts";
+// Vendored from pi-ai: importing its deep subpaths directly breaks under the
+// bundled app's library loader (distribution review 2026-09-09, H1).
+import { clampMaxTokensToContext, estimateMessageTokens } from "../lib/pi-ai-estimate.ts";
+
+/**
+ * The least output room a replay must leave for the summary. Below it the
+ * clamp truncates the reply (or the request is rejected) and pi's summary
+ * would serve instead. With pi's default `reserveTokens` (16 384) a threshold
+ * compaction leaves ~12k, comfortably above; an overflow leaves nothing.
+ */
+export const MIN_REPLAY_SUMMARY_TOKENS = 4096;
+
+/** The output room a standalone request is trimmed to leave for the summary. */
+export const STANDALONE_SUMMARY_TOKENS = 8192;
+
+/** How much of a cleared tool result's text is kept as a landmark (persisted-output's preview size). */
+export const CLEARED_RESULT_HEAD_CHARS = PREVIEW_BYTES;
+
+/**
+ * True when replaying the captured request would leave room for the summary:
+ * the `max_tokens` pi will actually send, given this request, is at least the
+ * floor. An overflow never replays — the request that just failed *is* the
+ * capture, whatever the estimate says.
+ */
+export function replayFits(reason: "manual" | "threshold" | "overflow", model: Model<Api>, request: Context, maxTokens: number): boolean {
+	if (reason === "overflow") return false;
+	return clampMaxTokensToContext(model, request, maxTokens) >= MIN_REPLAY_SUMMARY_TOKENS;
+}
+
+/**
+ * Clears the largest tool results (oldest first on a tie) until pi's clamp
+ * would leave `STANDALONE_SUMMARY_TOKENS` of output room, or none are left to
+ * clear (then the provider's verdict decides, and pi's summary serves on
+ * failure). Nothing but tool results is touched. Returns a new context with
+ * new messages — the inputs are never mutated.
+ */
+export function fitToBudget(model: Model<Api>, request: Context, maxTokens: number): { request: Context; cleared: number } {
+	const messages = [...request.messages];
+	const fitted: Context = { ...request, messages };
+	const candidates = messages
+		.map((message, index) => ({ index, tokens: message.role === "toolResult" ? estimateMessageTokens(message) : -1 }))
+		.filter(({ tokens }) => tokens >= 0)
+		.sort((a, b) => b.tokens - a.tokens || a.index - b.index);
+
+	let cleared = 0;
+	for (const { index } of candidates) {
+		if (clampMaxTokensToContext(model, fitted, maxTokens) >= STANDALONE_SUMMARY_TOKENS) break;
+		messages[index] = clearToolResult(messages[index]);
+		cleared++;
+	}
+	return { request: fitted, cleared };
+}
+
+/**
+ * The messages with every assistant `usage` zeroed. pi-ai's estimator anchors
+ * on the *last assistant message's usage total* plus the messages after it
+ * (`estimateContextTokens`), and a usage total describes the request it came
+ * from — the session's, with its ~20k of system prompt and tools, the
+ * messages before the span, and on an overflow a total already past the
+ * window. Anchored on it, a standalone request that fit by content was still
+ * clamped to `max_tokens` 1 (measured). Zero usage is skipped by the
+ * estimator (it needs a positive total), so the clamp counts what is actually
+ * sent. The replay path keeps its usage: there the numbers describe the very
+ * prefix being replayed. Copies; the inputs are untouched.
+ */
+export function withoutUsage(messages: readonly Message[]): Message[] {
+	return messages.map((message) =>
+		message.role === "assistant" && message.usage
+			? { ...message, usage: { ...message.usage, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 } }
+			: message,
+	);
+}
+
+/** A tool result reduced to its opening text and a note; images are dropped. */
+export function clearToolResult(message: Message): Message {
+	if (message.role !== "toolResult") return message;
+	const text = contentText(message.content);
+	const head = text.slice(0, CLEARED_RESULT_HEAD_CHARS);
+	const omitted = text.length - head.length;
+	const images = message.content.filter((block) => block.type !== "text").length;
+	const note = `[Tool result cleared to fit the compaction request: ${omitted} more characters${
+		images > 0 ? ` and ${images} image${images === 1 ? "" : "s"}` : ""
+	} omitted. The full result is in the session transcript.]`;
+	return { ...message, content: [{ type: "text", text: head ? `${head}\n${note}` : note }] };
+}