one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/local-command.ts

@@ -7,7 +7,7 @@
  * of the next user message, after the reminder stack and before the user's own
  * text —
  *
- *   <local-command-caveat>Caveat: …</local-command-caveat>\n
+ *   <local-command-caveat>The command below was run directly in …</local-command-caveat>\n
  *   <command-name>/model</command-name>\n
  *               <command-message>model</command-message>\n
  *               <command-args></command-args>\n
@@ -16,19 +16,25 @@
  * (twelve-space indent on the second and third command lines, verbatim from
  * CC's `formatCommandInputTags`; stdout XML-escaped like CC's `escapeXml`, `&
  * < >` only). `/clear` carries an EMPTY stdout block and opens the new
- * conversation. The caveat tells the model not to act on any of it.
+ * conversation. The caveat tells the model the command was the user's, not a
+ * request to it, kept as context.
  *
  * One Code emits these through the reminder queue's `user-prepend` placement
  * (`lib/reminders.ts`): pi dispatches an extension command BEFORE its `input`
  * event fires and handles its own built-ins (`/model`, `/name`, …) before
  * either, so there is no single interception point — every One Code local
  * command is registered through `registerLocalCommand`, which announces before
- * the handler runs, and `/model` is announced from the `model_select` event by
- * the extension that persists the choice. pi built-ins we cannot see
- * (`/compact`, `/settings`, …) stay silent. The blocks are pinned in process
- * memory, not written to the session file as CC does — a `--resume` drops them.
+ * the handler runs (or, with `reportsResult`, after it, carrying the handler's
+ * returned text as the stdout, as CC's `onDone(result)` does), and `/model` is
+ * announced from the `model_select` event by the extension that persists the
+ * choice. pi built-ins we cannot see
+ * (`/compact`, `/settings`, …) stay silent. The blocks are persisted when
+ * announced, as pending entries the next prompt's request carries and records
+ * (lib/reminders.ts `user-prepend`), so a `/reload` or a resume before that
+ * prompt keeps them, as CC's transcript does.
  */
 
+import { announceArgumentHint, type HintEmitter, withoutExactMatch } from "./argument-hints.ts";
 import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
 
 /** The slice of pi's ExtensionAPI the announcer needs (its event bus). */
@@ -43,8 +49,9 @@ export interface ReminderEmitter {
  */
 export const LOCAL_COMMAND_TAG_PREFIXES = ["<local-command-caveat>", "<command-name>", "<command-message>", "<local-command-stdout>"] as const;
 
+/** Claude Code 2.1.288's caveat, naming the harness the command ran in. */
 export const LOCAL_COMMAND_CAVEAT =
-	"<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>\n";
+	"<local-command-caveat>The command below was run directly in One Code, not sent to you as a request, and its output goes straight to the user. It's recorded here as context for later messages.</local-command-caveat>\n";
 
 /** CC's `escapeXml` (utils/xml.ts): `& < >` only. */
 export function escapeXml(s: string): string {
@@ -58,6 +65,12 @@ export interface LocalCommand {
 	args?: string;
 	/** The command's printed result; "" (the default) is what `/clear` shows. */
 	stdout?: string;
+	/**
+	 * Keys the breadcrumb's pending entries (`<key>:caveat`, `<key>:command`,
+	 * `<key>:stdout`), so a later announcement under the same key replaces an
+	 * undelivered one instead of joining it.
+	 */
+	key?: string;
 }
 
 /** CC's `formatCommandInputTags` — the command breadcrumb, indentation included. */
@@ -70,43 +83,82 @@ export function commandStdoutBlock(stdout = ""): string {
 	return `<local-command-stdout>${escapeXml(stdout)}</local-command-stdout>\n`;
 }
 
+/** The pending-entry key suffix of each block, in `localCommandBlocks` order. */
+const BLOCK_KEYS = ["caveat", "command", "stdout"] as const;
+
 /** The three bare text blocks a local command leaves for the model, in CC's order. */
 export function localCommandBlocks(command: LocalCommand): string[] {
 	return [LOCAL_COMMAND_CAVEAT, commandInputBlock(command.name, (command.args ?? "").trim()), commandStdoutBlock(command.stdout ?? "")];
 }
 
 /**
- * Tell the model a local command ran. Call it from the command's handler
- * (before a `/clear` resets the session — the queue survives `newSession()`,
- * so the breadcrumb opens the new conversation exactly as in CC).
+ * Tell the model a local command ran. Call it from the command's handler; a
+ * command that replaces the session (`/clear`) announces from the new
+ * session's `session_start` instead, so the breadcrumb opens the new
+ * conversation exactly as in CC.
  */
 export function announceLocalCommand(pi: ReminderEmitter, command: LocalCommand): void {
 	localCommandBlocks(command).forEach((text, index) => {
 		// The caveat heads a RUN of commands: a second command before the next
 		// prompt joins the first caveat instead of repeating it.
-		const payload: ReminderPayload = { text, placement: "user-prepend", raw: true, ...(index === 0 ? { once: true } : {}) };
+		const payload: ReminderPayload = {
+			text,
+			placement: "user-prepend",
+			raw: true,
+			...(index === 0 ? { once: true } : {}),
+			...(command.key ? { key: `${command.key}:${BLOCK_KEYS[index]}` } : {}),
+		};
 		pi.events.emit(REMINDER_CHANNEL, payload);
 	});
 }
 
 type CommandOptions = { handler: (args: string, ctx: any) => Promise<void> | void } & Record<string, unknown>;
 
+/**
+ * What a local command passes: pi's options, plus `reportsResult` when its
+ * handler returns the stdout (a returned string is never silently dropped).
+ */
+type LocalCommandOptions<O extends CommandOptions> = Omit<O, "handler"> & { argumentHint?: string } & (
+		| { reportsResult: true; handler: (args: string, ctx: Parameters<O["handler"]>[1]) => Promise<string | void> | string | void }
+		| { reportsResult?: false; handler: (args: string, ctx: Parameters<O["handler"]>[1]) => Promise<void> | void }
+	);
+
 /**
  * `pi.registerCommand` for a One Code local command: the breadcrumb is
- * announced before the handler runs, so no command can forget it. `/clear`
+ * announced before the handler runs, so no command can forget it. With
+ * `reportsResult`, it is announced once the handler settles instead, its
+ * stdout the string the handler returned (CC's `onDone(result)`; "" for none
+ * or a throw). Only a command that never starts a turn of its own may opt in:
+ * a breadcrumb queued after `sendUserMessage` would miss that message. `/clear`
  * is the one exception — it announces from the NEW session's `session_start`
- * (see clear/index.ts) and registers plainly.
+ * (see clear/index.ts) and registers plainly. `argumentHint` is the prompt's
+ * dim placeholder for the command's argument (lib/argument-hints.ts). Its
+ * completions leave out an exact match, so a fully typed argument runs on the
+ * first Enter (`withoutExactMatch`).
  */
 export function registerLocalCommand<O extends CommandOptions>(
-	pi: ReminderEmitter & { registerCommand(name: string, options: O): void },
+	pi: ReminderEmitter & HintEmitter & { registerCommand(name: string, options: O): void },
 	name: string,
-	options: O,
+	options: LocalCommandOptions<O>,
 ): void {
+	const { argumentHint, reportsResult, ...rest } = options;
+	if (argumentHint) announceArgumentHint(pi, name, argumentHint);
+	const complete = (rest as { getArgumentCompletions?: Parameters<typeof withoutExactMatch>[0] }).getArgumentCompletions;
 	pi.registerCommand(name, {
-		...options,
-		handler: (args: string, ctx: unknown) => {
-			announceLocalCommand(pi, { name, args });
-			return options.handler(args, ctx);
+		...(rest as unknown as O),
+		...(complete ? { getArgumentCompletions: withoutExactMatch(complete) } : {}),
+		handler: async (args: string, ctx: Parameters<O["handler"]>[1]) => {
+			if (!reportsResult) {
+				announceLocalCommand(pi, { name, args });
+				await options.handler(args, ctx);
+				return;
+			}
+			let stdout = "";
+			try {
+				stdout = (await options.handler(args, ctx)) ?? "";
+			} finally {
+				announceLocalCommand(pi, { name, args, stdout });
+			}
 		},
 	});
 }

package/extensions/lib/mcp-overrides.ts

@@ -4,7 +4,7 @@
  * The /mcp panel's Disable/Enable action persists across sessions here rather
  * than by mutating the user's `~/.claude.json` or a plugin's `.mcp.json`: those
  * are Claude Code's / a plugin's config, which One Code only ever reads (the
- * "own state, borrowed config" rule — docs/decisions/memory-state.md). A
+ * "own state, borrowed config" rule — working-docs/decisions/memory-state.md). A
  * disabled server is still discovered and listed; the mcp extension just skips
  * connecting it, and the panel offers Enable to bring it back.
  *

package/extensions/lib/mcp-share.ts

@@ -23,3 +23,49 @@ export interface McpToolsPayload {
 	 */
 	settled?: boolean;
 }
+
+/** How long a child spawned while MCP is still connecting waits for the settled set. */
+export const MCP_SETTLE_CAP_MS = 10_000;
+
+/** The events slice `watchMcpTools` needs. */
+export interface McpToolsEvents {
+	on(channel: string, handler: (data: unknown) => void): unknown;
+}
+
+/**
+ * Track the parent's live MCP tool definitions for in-process children (the
+ * subagent runner and the workflow runner). Subscribe at extension load; the
+ * getter resolves to the current set. The parent's MCP connect runs in the
+ * background, so a child spawned in the first seconds of a session waits for
+ * the settled publish, capped so a hung server cannot stall spawns, instead of
+ * baking in a still-connecting (possibly empty) snapshot. Empty when no MCP
+ * servers are configured.
+ */
+export function watchMcpTools(events: McpToolsEvents, settleCapMs = MCP_SETTLE_CAP_MS): () => Promise<ToolDefinition[]> {
+	let tools: ToolDefinition[] = [];
+	let settled = false;
+	let resolveSettled: (() => void) | undefined;
+	const settledPromise = new Promise<void>((resolve) => {
+		resolveSettled = resolve;
+	});
+	events.on(MCP_TOOLS_CHANNEL, (data) => {
+		const payload = data as McpToolsPayload | undefined;
+		tools = payload?.tools ?? [];
+		if (payload?.settled) {
+			settled = true;
+			resolveSettled?.();
+		}
+	});
+	return async () => {
+		if (!settled) {
+			await Promise.race([
+				settledPromise,
+				new Promise<void>((resolve) => {
+					const timer = setTimeout(resolve, settleCapMs);
+					timer.unref?.();
+				}),
+			]);
+		}
+		return tools;
+	};
+}

package/extensions/lib/memory-content.ts

@@ -0,0 +1,146 @@
+/**
+ * MEMORY.md and memory-file content: Claude Code's index load limits and
+ * truncation, and the frontmatter stamp written into memory files. Kept apart
+ * from `memory.ts`, whose path helpers most extensions import, so only the
+ * memory and doctor extensions load the YAML and instruction parsers.
+ */
+
+import { isMap, isScalar, parseDocument, visit } from "yaml";
+import { parseRule } from "./claude-rules.ts";
+
+/**
+ * Claude Code loads only the first 200 lines or 25,000 characters of
+ * MEMORY.md, whichever comes first, and tells the model what it cut (see
+ * `truncateIndex`). Mirror that so an overgrown index behaves identically
+ * here. The limits are measured against what actually loads: YAML frontmatter
+ * and block-level HTML comments are stripped first, and surrounding
+ * whitespace does not count. Claude Code measures string length, not UTF-8
+ * bytes.
+ */
+export const INDEX_MAX_LINES = 200;
+export const INDEX_MAX_CHARS = 25_000;
+
+/** The index uses Claude Code's instruction parser before applying its load limits. */
+export function loadableIndexContent(content: string): string {
+	return parseRule(content).content;
+}
+
+/** Line and character counts of the index as the limits measure it. */
+function indexSize(loadable: string): { trimmed: string; lines: number; chars: number } {
+	const trimmed = loadable.trim();
+	return { trimmed, lines: trimmed.split("\n").length, chars: trimmed.length };
+}
+
+/**
+ * The index as it loads. Within the limits it is the loadable content as is.
+ * Past either limit it is cut the way Claude Code cuts it: to the first 200
+ * lines, then back to the last line break within 25,000 characters, followed
+ * by Claude Code's warning line naming what was cut, so the model knows the
+ * index goes on. The result ends in a newline, so the next section of the
+ * context block starts on a line of its own.
+ */
+export function truncateIndex(content: string): string {
+	const loadable = loadableIndexContent(content);
+	const { trimmed, lines, chars } = indexSize(loadable);
+	const overLines = lines > INDEX_MAX_LINES;
+	const overChars = chars > INDEX_MAX_CHARS;
+	if (!overLines && !overChars) return loadable;
+
+	let kept = overLines ? trimmed.split("\n").slice(0, INDEX_MAX_LINES).join("\n") : trimmed;
+	if (kept.length > INDEX_MAX_CHARS) {
+		const lastBreak = kept.lastIndexOf("\n", INDEX_MAX_CHARS);
+		kept = kept.slice(0, lastBreak > 0 ? lastBreak : INDEX_MAX_CHARS);
+	}
+	const keptLines = trimmed[kept.length] === "\n" ? kept.split("\n").length : 0;
+	const nextStart = kept.length + 1;
+	const nextEnd = trimmed.indexOf("\n", nextStart);
+	const nextLine = trimmed.slice(nextStart, nextEnd < 0 ? undefined : nextEnd).trim();
+	const cut =
+		keptLines === 0
+			? `everything after the first ${kept.length} characters of line 1 was cut off`
+			: `${lines - keptLines} of ${lines} lines were cut off, starting at line ${keptLines + 1}${nextLine ? ` ("${shortenLine(nextLine, 80)}")` : ""}`;
+	const size =
+		overChars && !overLines
+			? `${formatSize(chars)} (limit: ${formatSize(INDEX_MAX_CHARS)}) \u2014 index entries are too long`
+			: overLines && !overChars
+				? `${lines} lines (limit: ${INDEX_MAX_LINES})`
+				: `${lines} lines and ${formatSize(chars)}`;
+	return `${kept}\n\n> WARNING: MEMORY.md is ${size}. Only part of it was loaded: ${cut}. Keep index entries to one line under ~200 chars; move detail into topic files.\n`;
+}
+
+/** A size the way Claude Code prints it: `N bytes`, else `N.NKB`/`MB` with a trailing `.0` dropped. */
+function formatSize(n: number): string {
+	const units = ["KB", "MB", "GB"];
+	let value = n / 1024;
+	if (value < 1) return `${n} bytes`;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit++;
+	}
+	return `${value.toFixed(1).replace(/\.0$/, "")}${units[unit]}`;
+}
+
+/** Claude Code's quote of the first cut line: at most `max` characters, cut at a word when that keeps over half. */
+function shortenLine(text: string, max: number): string {
+	if (text.length <= max) return text;
+	const head = [...text].slice(0, max - 1).join("");
+	const lastSpace = head.search(/\s\S*$/);
+	const atWord = lastSpace === -1 ? "" : head.slice(0, lastSpace).trimEnd();
+	return `${atWord.length > max / 2 ? atWord : head.trimEnd()}\u2026`;
+}
+
+/**
+ * Where the index stands against its load limits, checked after each write so
+ * the model hears about an overgrown index while it can still fix it (Claude
+ * Code behaves the same: near-limit reminder, over-limit error — the write
+ * itself always succeeds).
+ */
+export function indexLimitStatus(content: string): "ok" | "near" | "over" {
+	const { lines, chars } = indexSize(loadableIndexContent(content));
+	if (lines > INDEX_MAX_LINES || chars > INDEX_MAX_CHARS) return "over";
+	if (lines >= INDEX_MAX_LINES * 0.9 || chars >= INDEX_MAX_CHARS * 0.9) return "near";
+	return "ok";
+}
+
+export const INDEX_NEAR_LIMIT_REMINDER = `MEMORY.md is approaching its load limit (only the first ${INDEX_MAX_LINES} lines or 25KB are loaded each session). Shorten it now: keep one line per entry, move detail into topic files in the memory directory, and merge or drop stale entries.`;
+
+export const INDEX_OVER_LIMIT_ERROR = `MEMORY.md is over its load limit (${INDEX_MAX_LINES} lines / 25KB): everything past the limit is dropped the next time it is loaded. The write succeeded, but rewrite the index now — one line per entry, move detail into topic files, merge or drop stale entries.`;
+
+/**
+ * Stamp safe YAML memory headers, retaining the originating session on updates.
+ * Claude Code's ue/Mt preserve originSessionId; Dn declines unsafe rewrites.
+ * Keep comments, flow mappings, BOM/CRLF and the body; leave malformed headers,
+ * aliases and non-mapping metadata untouched rather than losing user content.
+ */
+export function stampFrontmatter(content: string, sessionId: string, modifiedIso: string): string {
+	if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/.test(content)) return content;
+	const match = content.match(/^(\uFEFF?---[ \t]*\r?\n)([\s\S]*?)(\r?\n---[ \t]*(?:\r?\n|$))/);
+	if (!match) return content;
+
+	// Claude Code checks its permissive parser against strict delimiters before
+	// rewriting: a quoted value containing "---" can make the header ambiguous.
+	const parsedBoundary = content.replace(/^\uFEFF/, "").match(/^---\s*\n([\s\S]*?)---\s*\n?/);
+	if (parsedBoundary?.[1].trim() !== match[2].trim()) return content;
+
+	const document = parseDocument(match[2]);
+	if (document.errors.length || document.warnings.length || !isMap(document.contents)) return content;
+	let hasAlias = false;
+	visit(document, { Alias: () => { hasAlias = true; } });
+	if (hasAlias) return content;
+
+	if (document.get("metadata") == null) document.set("metadata", document.createNode({}));
+	const metadata = document.get("metadata", true);
+	if (!isMap(metadata)) return content;
+
+	metadata.set("node_type", "memory");
+	const nodeIndex = metadata.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === "node_type");
+	metadata.items.unshift(...metadata.items.splice(nodeIndex, 1));
+	const origin = metadata.get("originSessionId");
+	if (typeof origin !== "string" || !origin) metadata.set("originSessionId", sessionId);
+	metadata.set("modified", modifiedIso);
+
+	let yaml = document.toString().replace(/\n$/, "");
+	if (match[1].endsWith("\r\n")) yaml = yaml.replaceAll("\n", "\r\n");
+	return match[1] + yaml + match[3] + content.slice(match[0].length);
+}

package/extensions/lib/memory-index.ts

@@ -0,0 +1,18 @@
+/** Read the startup/compaction memory index without loading excluded or non-text files. */
+import os from "node:os";
+import { join } from "node:path";
+import { isClaudeLocation, readFileIfPresent } from "./claude-context.ts";
+import { autoMemoryEnabled } from "./auto-memory.ts";
+import { claudeSourcesOn } from "./config-mode.ts";
+import { projectMemoryDir } from "./memory.ts";
+import { truncateIndex } from "./memory-content.ts";
+import { claudeUserDir } from "./paths.ts";
+
+export function readMemoryIndex(cwd: string, home: string = os.homedir()): { path: string; content: string } | null {
+	if (!autoMemoryEnabled(cwd)) return null;
+	const path = join(projectMemoryDir(cwd, home), "MEMORY.md");
+	if (!claudeSourcesOn() && isClaudeLocation(path, claudeUserDir(home))) return null;
+	const raw = readFileIfPresent(path);
+	if (!raw?.trim() || raw.includes("\0")) return null;
+	return { path, content: truncateIndex(raw) };
+}