one-code-extension 0.5.0 → 0.6.0

package/extensions/lib/notifications.ts

@@ -31,10 +31,11 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionContext, VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
 import { withKeepAlive } from "../lsp/keep-alive.ts";
 import { ONE_SHOT_COMMAND_FAILED_CHANNEL, RunOutcomeLatch } from "./interrupt.ts";
 import { escapeXml } from "./local-command.ts";
+import { piFiresBeforeAgentStartForCustomRuns } from "./pi-version.ts";
 import { isUserRun, PROMPT_OPTIONS_CHANNEL } from "./prompt-options.ts";
 import { wrapReminder } from "./reminders.ts";
 
@@ -481,11 +482,6 @@ export const NOTIFICATION_ID_KEY = "notificationId";
 /** `details` key on a coalesced message: the `{customType, details}` of each notification it carries, in arrival order. */
 export const NOTIFICATION_BATCH_KEY = "notifications";
 
-/** True for the `details` of a message the notifier sent (one notification or a coalesced batch). */
-export function isNotificationDetails(details: unknown): boolean {
-	return typeof details === "object" && details !== null && (NOTIFICATION_ID_KEY in details || NOTIFICATION_BATCH_KEY in details);
-}
-
 /** Inject a harness notification (a task/agent completion, a monitor event, a review note) into the conversation. */
 export interface TaskNotifier {
 	(customType: string, text: string, details?: Record<string, unknown>): void;
@@ -533,6 +529,25 @@ export interface TaskNotifierOptions {
 	 * report, so its hand-back would only repeat it.
 	 */
 	withdrawOnDelivery?: boolean;
+	/**
+	 * Whether pi fires `before_agent_start` for a run `sendMessage` opens from
+	 * idle (pi 1.2.0 and later). Then such a run builds One Code's system
+	 * prompt like a typed one, and no notification needs the user-message
+	 * path (see "First turn of a session"). Defaults to the running pi's
+	 * version; tests set it to model an older pi.
+	 */
+	customRunsFireBeforeAgentStart?: boolean;
+	/**
+	 * Runs once a notification this notifier sent reaches the conversation,
+	 * with its customType and the details it was sent with: at its
+	 * `message_end`, or at the send for one delivered as a user message (see
+	 * "First turn of a session"), whose message carries no details for pi to
+	 * hand back. A producer whose message makes something true for the model
+	 * (a `/loop` fire's instructions) records that here, not when it calls the
+	 * notifier: the notifier may still hold the message, and a `/reload`
+	 * drops it.
+	 */
+	onDelivered?: (customType: string, details: Record<string, unknown>) => void;
 }
 
 /**
@@ -619,9 +634,10 @@ export const DEFAULT_COALESCE_MS = 250;
  * anything dispatched afterwards; a throwing `sendMessage` is swallowed as a
  * second line.
  *
- * First turn of a session: pi's idle `sendMessage(…, {triggerTurn: true})`
- * calls `_runAgentPrompt` directly and skips the `prompt()` preamble, so no
- * `before_agent_start` fires — and our system prompt is set from that hook.
+ * First turn of a session, on pi before 1.2.0: pi's idle
+ * `sendMessage(…, {triggerTurn: true})` calls `_runAgentPrompt` directly and
+ * skips the `prompt()` preamble, so no `before_agent_start` fires — and our
+ * system prompt is set from that hook.
  * A session whose first input was `/loop …` therefore ran its first request on
  * pi's stock system prompt with no reminder stack (review H1, measured). Until
  * no `prompt()` has run in this process, an idle notification is delivered as a
@@ -636,6 +652,15 @@ export const DEFAULT_COALESCE_MS = 250;
  * so the system-prompt extension installs the prompt for it from
  * `context_with_system` (`system-prompt/idle-turn.ts`). Upstream ask:
  * working-docs/upstream_prs.md #17.
+ *
+ * pi 1.2.0 fires `before_agent_start` for that run too, so there every
+ * notification goes the custom-message way from the start. Before, the
+ * fallback ran on every pi, and a `/reload` re-runs the factory, which starts
+ * over as if no prompt had run: a re-armed `/loop` wakeup went out as a plain
+ * user message and lost its customType and no-op fold (lifecycle grid
+ * R3-M17). On an older pi the fallback is still right after a reload: the
+ * system-prompt extension has lost the options too, and the user-message
+ * path is the only one that rebuilds the prompt.
  */
 export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOptions = {}): TaskNotifier {
 	interface Pending {
@@ -652,6 +677,7 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 		details: Record<string, unknown>;
 	}
 	const coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS;
+	const customRunsPrompt = options.customRunsFireBeforeAgentStart ?? piFiresBeforeAgentStartForCustomRuns(PI_VERSION);
 	const pending = new Map<string, Pending>();
 	// Every notifier hears every message_end; simultaneous producers must not share an outbox id.
 	const producerId = randomUUID();
@@ -660,11 +686,12 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 	/** False once the session this notifier belongs to has shut down. */
 	let active = true;
 	/**
-	 * True once an idle turn can be built without `prompt()`: a prompt has run
-	 * (the only path that emits before_agent_start), or a command announced
-	 * pi's prompt options.
+	 * True once an idle turn can be built without `prompt()`: always on pi
+	 * 1.2.0 and later; before it, once a prompt has run (the only path that
+	 * emits before_agent_start there) or a command announced pi's prompt
+	 * options.
 	 */
-	let prompted = false;
+	let prompted = customRunsPrompt;
 	/** True between agent_start and agent_settled. */
 	let busy = false;
 	/** True from a turn settling aborted/errored until the next turn starts: hold, do not start turns. */
@@ -698,6 +725,7 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 				// followUp: pi 1.2.0 counts a starting run as busy and rejects a
 				// bare send there; when idle, the option changes nothing.
 				pi.sendUserMessage(frameForDelivery(entry.text, "opens-turn"), { deliverAs: "followUp" });
+				options.onDelivered?.(entry.customType, entry.details);
 				return;
 			}
 			pi.sendMessage(
@@ -805,10 +833,14 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 	};
 
 	pi.on("message_end", (event) => {
-		const message = event.message as { role?: string; details?: unknown };
+		const message = event.message as { role?: string; customType?: string; details?: unknown };
 		if (message.role !== "custom") return;
-		const id = (message.details as Record<string, unknown> | undefined)?.[NOTIFICATION_ID_KEY];
-		if (typeof id === "string") pending.delete(id);
+		const details = message.details as Record<string, unknown> | undefined;
+		const id = details?.[NOTIFICATION_ID_KEY];
+		if (typeof id !== "string") return;
+		pending.delete(id);
+		// Every notifier hears every message_end: only its own ids are its deliveries.
+		if (details && id.startsWith(`${producerId}-`)) options.onDelivered?.(message.customType ?? "", details);
 	});
 	pi.on("agent_end", (event, ctx) => {
 		outcome.record(event.messages, ctx.signal?.aborted);
@@ -847,7 +879,7 @@ export function createTaskNotifier(pi: TaskNotifierApi, options: TaskNotifierOpt
 		clearBatch();
 		held = [];
 		active = true;
-		prompted = false;
+		prompted = customRunsPrompt;
 		busy = false;
 		interrupted = false;
 	});
@@ -930,6 +962,14 @@ export function oneShotSessionNote(): string {
 	].join("\n");
 }
 
+/**
+ * The notice that a session whose first message said it was one-shot runs
+ * interactively now (a `-p` session continued in the TUI). One Code's own text.
+ */
+export function interactiveSessionNote(): string {
+	return "This session is interactive now, although its first message said it was one-shot: a user can reply, background work notifies you when it ends, scheduled jobs fire, and questions and plan approvals reach the user.";
+}
+
 function assertNever(mode: never): never {
 	throw new Error(`Unhandled session mode: ${String(mode)}`);
 }

package/extensions/lib/pi-version.ts

@@ -9,16 +9,16 @@
  * never blocking — when outside it. The bundled `one-code` app pins pi inside
  * the range, so it never warns.
  *
- * The minimum is the oldest pi the extension set loads on: 0.84.3 first
- * exports `createPowerShellToolDefinition`, and on anything older the
- * PowerShell extension fails at load, which stops pi before any warning can
- * show. The peer range in package.json and the guide name the same floor
- * (pi-version.test.ts), and CI runs `test/e2e/pi-floor-smoke.mjs` against it.
+ * The minimum is 1.0.0: the record-once request path (extensions/ledger)
+ * builds on pi 1.0's session entries, transcript system messages and request
+ * pipeline (decisions/distribution.md). The peer range in package.json and the
+ * guide name the same floor (pi-version.test.ts), and CI runs
+ * `test/e2e/pi-floor-smoke.mjs` against it.
  */
 
 /** Inclusive minimum and exclusive maximum pi version this release is tested against. */
-export const TESTED_PI_MIN = "0.84.3";
-export const TESTED_PI_MAX_EXCLUSIVE = "1.4.0";
+export const TESTED_PI_MIN = "1.0.0";
+export const TESTED_PI_MAX_EXCLUSIVE = "1.5.0";
 
 /** Dotted-numeric parse; undefined for anything that is not plain x.y.z numbers. */
 export function parseVersion(version: string): number[] | undefined {
@@ -59,6 +59,18 @@ export function piVersionWarning(runningPiVersion: string | undefined): string |
 	);
 }
 
+/**
+ * Whether the running pi fires `before_agent_start` for a run an extension
+ * opens from idle with `sendMessage(…, { triggerTurn: true })`. pi 1.2.0
+ * added it (its changelog, "before_agent_start for extension-triggered
+ * runs"); before, only `prompt()` fired the event. A version check, not a
+ * feature test: nothing tells the two apart before such a run starts, and an
+ * unparseable version reads as no, the older and safer behavior.
+ */
+export function piFiresBeforeAgentStartForCustomRuns(runningPiVersion: string | undefined): boolean {
+	return piAtLeast(runningPiVersion, "1.2.0");
+}
+
 /**
  * Whether the running pi ships built-in extensions that can replace ours'
  * names (`builtin:tool-search`, `builtin:mcp`; lib/replaced-builtins.mjs).
@@ -67,7 +79,12 @@ export function piVersionWarning(runningPiVersion: string | undefined): string |
  * as no.
  */
 export function piHasBuiltinExtensions(runningPiVersion: string | undefined, firstVersion: string): boolean {
+	return piAtLeast(runningPiVersion, firstVersion);
+}
+
+/** Whether the running pi is `min` or later; a missing or unparseable version reads as no. */
+function piAtLeast(runningPiVersion: string | undefined, min: string): boolean {
 	if (!runningPiVersion) return false;
-	const order = compareVersions(runningPiVersion, firstVersion);
+	const order = compareVersions(runningPiVersion, min);
 	return order !== undefined && order >= 0;
 }

package/extensions/lib/plan-mode-channels.ts

@@ -11,16 +11,38 @@
 export const MODE_CHANNEL = "one-code:set-permission-mode";
 /** Announces plan mode's one writable file (`{ path }`); the permissions matcher consumes it. */
 export const PLAN_FILE_CHANNEL = "one-code:plan-file-path";
-/** Session entry type persisting plan mode's allocated path across resume/branch (`{ path }`). */
+/**
+ * Session entry type persisting plan mode's allocated path across resume/branch
+ * (`{ path, sessionId?, copiedFrom? }`): the session that allocated it, and the
+ * plan a fork's copy was taken from.
+ */
 export const PLAN_FILE_ENTRY = "one-code:plan-mode-file";
 
-/** The plan file the branch's latest plan-file entry records, if any. */
-export function planFileOnBranch(entries: readonly { type: string; customType?: string; data?: unknown }[]): string | undefined {
-	let path: string | undefined;
+export interface PlanFileRecord {
+	path: string;
+	sessionId?: string;
+	copiedFrom?: string;
+}
+
+type EntryLike = { type: string; customType?: string; data?: unknown };
+
+/** Every plan-file record in `entries`, oldest first. */
+export function planFileRecords(entries: readonly EntryLike[]): PlanFileRecord[] {
+	const records: PlanFileRecord[] = [];
 	for (const entry of entries) {
 		if (entry.type !== "custom" || entry.customType !== PLAN_FILE_ENTRY) continue;
-		const recorded = (entry.data as { path?: unknown } | undefined)?.path;
-		if (typeof recorded === "string") path = recorded;
+		const data = entry.data as { path?: unknown; sessionId?: unknown; copiedFrom?: unknown } | undefined;
+		if (typeof data?.path !== "string") continue;
+		records.push({
+			path: data.path,
+			...(typeof data.sessionId === "string" ? { sessionId: data.sessionId } : {}),
+			...(typeof data.copiedFrom === "string" ? { copiedFrom: data.copiedFrom } : {}),
+		});
 	}
-	return path;
+	return records;
+}
+
+/** The plan file the branch's latest plan-file entry records, if any. */
+export function planFileOnBranch(entries: readonly EntryLike[]): string | undefined {
+	return planFileRecords(entries).at(-1)?.path;
 }

package/extensions/lib/previous-mark.ts

@@ -0,0 +1,101 @@
+/**
+ * Keep the previous request's conversation breakpoint (pure).
+ *
+ * Anthropic finds an earlier cache entry only a limited way back from a
+ * breakpoint, about 20 content blocks, and pi moves the one conversation
+ * breakpoint to each request's tail. A request that adds many blocks since the
+ * last one (a large parallel tool batch), or a long run of `tool_addition`
+ * blocks after the session-facts system message, then cannot reach the entry
+ * the previous request wrote and re-caches the whole conversation (findings
+ * §72: a live pair read 11,707 of 24,837 tokens, and 24,837 with this mark).
+ * Marking the block the previous request marked again lets the server match
+ * that entry directly. It costs nothing: the entry exists, so the mark reads.
+ */
+
+import { appendPoint } from "./ledger/wire.ts";
+import { MAX_CACHE_MARKERS } from "./request-replay.ts";
+
+type Block = Record<string, unknown> & { cache_control?: unknown };
+type Message = { role?: unknown; content?: unknown };
+
+/** Where a request's last conversation breakpoint sat, and the block it marked. */
+export interface MessageMark {
+	message: number;
+	block: number;
+	marker: unknown;
+	/** The marked block itself: pi builds each request afresh but reuses large strings (an image's data), so a structural compare short-circuits on them. */
+	content: Block;
+}
+
+const blocksOf = (message: unknown): Block[] =>
+	Array.isArray((message as Message | null)?.content) ? ((message as Message).content as Block[]) : [];
+
+/** Equal JSON values, ignoring a top-level `cache_control`. */
+function sameBlock(a: Block, b: Block): boolean {
+	const keys = (block: Block) => Object.keys(block).filter((key) => key !== "cache_control");
+	const left = keys(a);
+	return left.length === keys(b).length && left.every((key) => sameValue(a[key], b[key]));
+}
+function sameValue(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return false;
+	const left = Object.keys(a);
+	return left.length === Object.keys(b).length && left.every((key) => sameValue((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]));
+}
+
+/** The last breakpoint in `messages`, or undefined when none carries one. */
+export function lastMessageMark(messages: unknown): MessageMark | undefined {
+	if (!Array.isArray(messages)) return undefined;
+	for (let message = messages.length - 1; message >= 0; message--) {
+		const blocks = blocksOf(messages[message]);
+		for (let block = blocks.length - 1; block >= 0; block--) {
+			const marker = blocks[block]?.cache_control;
+			if (marker !== undefined) return { message, block, marker, content: blocks[block] };
+		}
+	}
+	return undefined;
+}
+
+function marksIn(value: unknown): number {
+	if (!Array.isArray(value)) return 0;
+	return value.reduce((sum: number, entry) => {
+		const own = (entry as Block | null)?.cache_control !== undefined ? 1 : 0;
+		return sum + own + blocksOf(entry).filter((block) => block?.cache_control !== undefined).length;
+	}, 0);
+}
+
+/**
+ * The payload with `previous` marked again: only when that block is still
+ * there with the same bytes, no later block already took its place as the
+ * tail mark, and a breakpoint slot is free. Otherwise the payload unchanged.
+ */
+export function withPreviousMark<T extends Record<string, unknown>>(payload: T, previous: MessageMark | undefined): T {
+	if (!previous || !Array.isArray(payload.messages)) return payload;
+	const messages = payload.messages as Message[];
+	const blocks = blocksOf(messages[previous.message]);
+	const target = blocks[previous.block];
+	if (!target || target.cache_control !== undefined || !sameBlock(target, previous.content)) return payload;
+	if (marksIn(payload.tools) + marksIn(payload.system) + marksIn(messages) >= MAX_CACHE_MARKERS) return payload;
+	const copy = [...messages];
+	const content = [...blocks];
+	content[previous.block] = { ...target, cache_control: previous.marker };
+	copy[previous.message] = { ...messages[previous.message], content };
+	return { ...payload, messages: copy };
+}
+
+/**
+ * The breakpoint the base request carried, located in `messages` (the request
+ * that extends it, spliced): the last block of the base's last element before
+ * its trailing directives, with the marker this request's own tail mark uses.
+ * Undefined when the request has no tail mark or the base is empty.
+ */
+export function baseMark(messages: unknown, baseList: readonly unknown[], api: string): MessageMark | undefined {
+	if (!Array.isArray(messages)) return undefined;
+	const end = appendPoint(baseList, api);
+	const tail = lastMessageMark(messages);
+	if (end === 0 || !tail || tail.message < end) return undefined;
+	const blocks = blocksOf(messages[end - 1]);
+	const block = blocks.length - 1;
+	if (block < 0) return undefined;
+	return { message: end - 1, block, marker: tail.marker, content: blocks[block] };
+}

package/extensions/lib/process-state.ts

@@ -0,0 +1,48 @@
+/**
+ * Process state: what lives as long as the One Code process and no longer
+ * (lifecycle-grid-hunt plan, part D). Every piece of state an extension holds
+ * is one of three kinds:
+ *
+ * - branch state follows the conversation: a resume, `/reload`, `/fork` and
+ *   `/tree` each read it back from the branch (a `one-code:state` entry,
+ *   lib/ledger/state.ts, or a fold of the branch's own entries);
+ * - process state survives `/reload` and the session swaps of `/clear`,
+ *   `/new`, `/resume` and `/fork`, and ends with the process (a grant the
+ *   user gave "for this session", a notice owed to the next session): this
+ *   module;
+ * - resources (a timer, a child process, a connection) end with the instance
+ *   that opened them, in `session_shutdown`.
+ *
+ * Module scope is none of them: pi re-evaluates every extension module at a
+ * `/reload` and at a `/resume` into another directory (findings §8), so a
+ * module-level value is lost there and kept everywhere else. The store here
+ * is a `globalThis` slot, which no re-evaluation resets.
+ *
+ * Pure: no pi imports.
+ */
+
+const SLOT = Symbol.for("one-code:process-state");
+
+type Store = Map<string, unknown>;
+
+function store(): Store {
+	const slot = globalThis as { [SLOT]?: Store };
+	return (slot[SLOT] ??= new Map());
+}
+
+/**
+ * The process's value for `key`, created by `init` on first use. Keys are
+ * namespaced by their owner (`"permissions:grants"`); the value is shared by
+ * every instance of that owner in the process, so it must be mutated, not
+ * replaced.
+ */
+export function processState<T>(key: string, init: () => T): T {
+	const values = store();
+	if (!values.has(key)) values.set(key, init());
+	return values.get(key) as T;
+}
+
+/** Forget every process value: a test's fresh process. */
+export function resetProcessStateForTest(): void {
+	store().clear();
+}

package/extensions/lib/process-tree.ts

@@ -165,8 +165,9 @@ function terminateRememberedGroups(): void {
  * Remember a detached background tree from spawn until its group becomes empty.
  * Register before awaiting its leader, so even immediate process exit covers
  * running work. The unref'd reaper cannot keep a print run alive. No session
- * shutdown handler touches this set; process listeners keep its module instance
- * alive even when jiti builds a new extension instance after /clear.
+ * shutdown handler touches this set; the process listeners keep this module
+ * instance alive, and reach its set, even after pi evaluates the module again
+ * (a /reload, a /resume into another directory: findings §8).
  */
 export function rememberProcessGroup(child: ChildProcess): void {
 	if (child.pid == null || rememberedGroups.has(child)) return;