one-code-extension 0.4.1 → 0.6.0

package/extensions/model-default/index.ts

@@ -21,12 +21,24 @@
  * sessions", and since persisting is what this extension does, the claim is
  * true here too (a failed write announces the switch without it). pi handles
  * `/model` before any extension sees the text, so `model_select` — which also
- * covers ctrl+p cycling — is the one signal; the debounce means only the model
- * the user settles on is announced.
+ * covers ctrl+p cycling — is the one signal.
+ *
+ * The write and the breadcrumb wait for the model the user settles on: the
+ * quiet period after the last switch, or the next prompt, whichever comes
+ * first. So a ctrl+p cycle through ten models writes the settings once and
+ * queues one breadcrumb, which names the write's real outcome. A quit,
+ * /reload, /new or /resume inside the quiet period still writes the settings,
+ * but cannot queue the breadcrumb: system-reminder stops persisting one-shots
+ * in its `session_shutdown` handler, which runs before this extension's. The
+ * choice is recorded on the branch instead, and the next session on that
+ * branch (the reload, a resume) announces it while its model is still the
+ * one chosen.
  */
 
 import { join } from "node:path";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isObject } from "../lib/ledger/records.ts";
+import { readState, recordState } from "../lib/ledger/state.ts";
 import { announceLocalCommand } from "../lib/local-command.ts";
 import { readSettingsForWrite, writeSettings } from "../lib/one-code-settings.ts";
 
@@ -44,34 +56,65 @@ export function modelSwitchStdout(displayName: string, saved: boolean): string {
 	return `Set model to \`${displayName}\`${saved ? " and saved as your default for new sessions" : ""}`;
 }
 
-/** Quiet period after the last switch before it is written (ctrl+p cycles fire one event per step). */
+/** Quiet period after the last switch before it is written and announced (ctrl+p cycles fire one event per step). */
 export const PERSIST_DEBOUNCE_MS = 400;
 
+/** The `/model` breadcrumb's pending-entry key: a later switch's breadcrumb replaces an undelivered one. */
+const BREADCRUMB_KEY = "local-command:model";
+
+/**
+ * The `one-code:state` key of a switch not yet announced: recorded at every
+ * switch (`saved` unset until the settings write), so the branch, not this
+ * process's timer, says a breadcrumb is owed; null once announced or dropped.
+ */
+const UNANNOUNCED_STATE = "model-breadcrumb";
+
+/** A settled switch, as announced. */
+interface Settled {
+	provider: string;
+	id: string;
+	name: string;
+	saved: boolean;
+}
+
+/** A switch the branch records, as `model_select` or a shutdown left it. */
+type Unannounced = Omit<Settled, "saved"> & { saved?: boolean };
+
 export default function modelDefaultExtension(pi: ExtensionAPI) {
 	let pending: { provider: string; id: string; name: string; notify: (message: string) => void } | undefined;
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	const announce = (name: string, saved: boolean) => announceLocalCommand(pi, { name: "model", stdout: modelSwitchStdout(name, saved), key: BREADCRUMB_KEY });
 
-	const flush = () => {
-		if (timer !== undefined) clearTimeout(timer);
-		timer = undefined;
-		const choice = pending;
-		pending = undefined;
-		if (!choice) return;
+	/** Save `provider/id` as the default model, and say whether it was saved. */
+	const save = (provider: string, id: string, notify: (message: string) => void): boolean => {
 		const path = join(getAgentDir(), "settings.json");
-		let saved = true;
 		try {
-			writeSettings(path, applyDefaultModel(readSettingsForWrite(path), choice.provider, choice.id));
+			writeSettings(path, applyDefaultModel(readSettingsForWrite(path), provider, id));
+			return true;
 		} catch (error) {
 			// Persisting a preference must not break the model switch itself, but
-			// say why it will be forgotten (typically a malformed settings.json).
-			saved = false;
-			choice.notify(`Could not save ${choice.provider}/${choice.id} as the default model: ${(error as Error).message}`);
+			// say why it will be forgotten.
+			notify(`Could not save ${provider}/${id} as the default model: ${(error as Error).message}`);
+			return false;
 		}
-		announceLocalCommand(pi, { name: "model", stdout: modelSwitchStdout(choice.name, saved) });
 	};
 
-	// Debounced: a ctrl+p cycle emits model_select per step, and only the model
-	// the user settles on should hit the disk (last one wins).
+	/** Write the switch the user settled on, if any, and say whether it was saved. */
+	const settle = (): Settled | undefined => {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+		const choice = pending;
+		pending = undefined;
+		if (!choice) return undefined;
+		return { provider: choice.provider, id: choice.id, name: choice.name, saved: save(choice.provider, choice.id, choice.notify) };
+	};
+	const flush = () => {
+		const settled = settle();
+		if (!settled) return;
+		announce(settled.name, settled.saved);
+		recordState(pi, UNANNOUNCED_STATE, null);
+	};
+
 	pi.on("model_select", (event, ctx) => {
 		const model = event.model as { provider?: string; id?: string; name?: string } | undefined;
 		if (!model?.provider || !model.id) return;
@@ -83,11 +126,35 @@ export default function modelDefaultExtension(pi: ExtensionAPI) {
 				if (ctx.hasUI) ctx.ui.notify(message, "warning");
 			},
 		};
+		// Owed from now on, whatever happens to this process: a fresh one on a
+		// copy of the branch owes the same breadcrumb (lifecycle-grid-hunt oracle).
+		recordState(pi, UNANNOUNCED_STATE, { provider: model.provider, id: model.id, name: pending.name } satisfies Unannounced);
 		if (timer !== undefined) clearTimeout(timer);
 		timer = setTimeout(flush, PERSIST_DEBOUNCE_MS);
 		timer.unref?.();
 	});
 
-	// A quit inside the quiet period must not lose the choice.
-	pi.on("session_shutdown", () => flush());
+	// A prompt sent inside the quiet period carries the switch's breadcrumb, not the request after it.
+	pi.on("before_agent_start", () => flush());
+
+	// A quit inside the quiet period must not lose the choice: the write happens
+	// now, and the breadcrumb waits on the branch for the next session.
+	pi.on("session_shutdown", () => {
+		const settled = settle();
+		if (settled) recordState(pi, UNANNOUNCED_STATE, settled);
+	});
+	// A switch the branch still owes a breadcrumb: announced here when the
+	// session runs that model, saved first if its own process never got to it.
+	pi.on("session_start", (_event, ctx) => {
+		const stored = readState(ctx, UNANNOUNCED_STATE);
+		if (!isObject(stored)) return;
+		recordState(pi, UNANNOUNCED_STATE, null);
+		const { provider, id, name, saved } = stored;
+		if (typeof provider !== "string" || typeof id !== "string" || typeof name !== "string") return;
+		if (ctx.model?.provider !== provider || ctx.model?.id !== id) return;
+		const notify = (message: string) => {
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+		};
+		announce(name, typeof saved === "boolean" ? saved : save(provider, id, notify));
+	});
 }

package/extensions/newer-model/index.ts

@@ -0,0 +1,31 @@
+/** User-only model-upgrade advice. No reminders, transcript entries, or request hooks. */
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { modelSpec } from "../lib/model-policy.ts";
+import { MODEL_UNUSABLE_CHANNEL, type ModelUnusableEvent, withoutUnusable } from "../lib/model-unusable.ts";
+import { newerModelSuggestion } from "../lib/newer-model.ts";
+import { queueNotice } from "../lib/notices.ts";
+import { sessionOutlivesTurn } from "../lib/notifications.ts";
+import { readSuggestNewerModels } from "../lib/one-code-settings.ts";
+
+export default function newerModelExtension(pi: ExtensionAPI) {
+	const shown = new Set<string>();
+	const unusable = new Set<string>();
+	pi.events.on(MODEL_UNUSABLE_CHANNEL, (data) => unusable.add((data as ModelUnusableEvent).model));
+
+	const suggest = (ctx: ExtensionContext, model = ctx.model) => {
+		if (!sessionOutlivesTurn(ctx.mode) || !ctx.hasUI || !model || !readSuggestNewerModels(homedir())) return;
+		const key = JSON.stringify([ctx.sessionManager.getSessionId(), modelSpec(model)]);
+		if (shown.has(key)) return;
+		const suggestion = newerModelSuggestion(withoutUnusable(ctx.modelRegistry.getAvailable(), unusable), model);
+		if (!suggestion) return;
+		// Joined with the other extensions' startup and model-switch notices (lib/notices.ts).
+		queueNotice(pi.events, ctx, "info", `${suggestion.text} ${suggestion.fix}`);
+		shown.add(key);
+	};
+
+	// Local catalog/cache reads only. Never await a network refresh at startup.
+	// Session ids also handle RPC's duplicate session_start for a new session.
+	pi.on("session_start", (_event, ctx) => suggest(ctx));
+	pi.on("model_select", (event, ctx) => suggest(ctx, event.model));
+}

package/extensions/notebook/description.ts

@@ -0,0 +1,18 @@
+/**
+ * notebook_edit's model-facing description: Claude Code's NotebookEdit text
+ * with One Code's extras (pure).
+ *
+ * Claude Code addresses a cell by the id its Read tool prints; pi's read
+ * returns the notebook's JSON, so a cell is named by its own `id` or by its
+ * position (`cell-0`). The path may be relative and is `path` or
+ * `notebook_path`; `append` and the cleared outputs are One Code's.
+ */
+
+export const NOTEBOOK_EDIT_DESCRIPTION = `Replaces, inserts, or deletes a single cell in a Jupyter notebook (.ipynb file).
+
+Usage:
+- You must use the read tool on the notebook in this conversation before editing — this tool will fail otherwise.
+- \`path\` (or \`notebook_path\`) is the notebook, absolute or relative to the working directory.
+- \`cell_id\` is the cell's own \`id\` or, for a notebook whose cells have none, its position: \`cell-0\` is the first cell. It is required for \`replace\` and \`delete\`.
+- \`edit_mode\` defaults to \`replace\`. Use \`insert\` to add a new cell after the cell with the given \`cell_id\` (or at the beginning of the notebook if \`cell_id\` is omitted) — \`cell_type\` is required when inserting. Use \`delete\` to remove the cell. Use \`append\` to add a cell at the end without naming one.
+- Editing a code cell clears its outputs.`;

package/extensions/notebook/index.ts

@@ -1,26 +1,26 @@
 /**
- * notebook extension — Claude Code's NotebookEdit, deferred behind tool_search
+ * notebook extension — Claude Code's NotebookEdit (its text: description.ts), deferred behind tool_search
  * (most sessions never touch a notebook, so its schema stays out of the prompt
  * until needed).
  */
 
 import { randomUUID } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
 import { applyEdit, type EditMode, type Notebook, notebookErrorHint, parseNotebook } from "./notebook.ts";
+import { resolveToolPath } from "../lib/tool-path.ts";
+import { NOTEBOOK_EDIT_DESCRIPTION } from "./description.ts";
 
 export default function notebookExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "notebook_edit",
 		label: "Notebook Edit",
 		...ccToolRenderers("Notebook Edit"),
-		description:
-			"Edit a Jupyter notebook (.ipynb): replace a cell's source, insert or append a new cell, or delete a cell. Read the notebook first — like the other file tools, this one refuses to edit a file you have not read. Cells are addressed by their `id` or, for a notebook whose cells have none, by position — `cell-0` is the first cell. Use edit_mode `append` to add a cell at the end without naming one. Editing a code cell clears its outputs.",
+		description: NOTEBOOK_EDIT_DESCRIPTION,
 		parameters: Type.Object({
 			path: Type.Optional(Type.String({ description: "Absolute or workspace-relative path to the .ipynb file" })),
 			// Claude Code's NotebookEdit spells the path `notebook_path` and defaults
@@ -52,7 +52,8 @@ export default function notebookExtension(pi: ExtensionAPI) {
 				};
 			}
 			const editMode = (params.edit_mode ?? "replace") as EditMode;
-			const path = isAbsolute(rawPath) ? rawPath : resolve(ctx.cwd, rawPath);
+			// The file tracker guards this path with the same resolution (lib/tool-path.ts).
+			const path = resolveToolPath(rawPath, ctx.cwd);
 			// Held outside the try so a failure raised AFTER the parse can name the
 			// ids the notebook actually has — a bare "cell_id is required" left both
 			// weak tiers patching ids in by hand with bash (review M4).

package/extensions/notebook/notebook.ts

@@ -93,7 +93,7 @@ export function findCellIndex(notebook: Notebook, cellId: string): number {
 
 /**
  * The "fail loud, name the fix" error for an id that resolves to nothing
- * (docs/decisions/tools.md): which ids exist, and the two ways to add a cell
+ * (working-docs/decisions/tools.md): which ids exist, and the two ways to add a cell
  * without naming one.
  */
 export function noSuchCellError(notebook: Notebook, cellId: string): Error {