Add active notebook topic system with set/clear and TUI indicator

Author: ofriw

handoff/compact.ts

@@ -7,6 +7,7 @@
 
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { AgenticodingState } from "../state.js";
+import { clearActiveNotebookTopic } from "../notebook/topic.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
 
 function getImpossibleKeptId(branchEntries: SessionEntry[]): string {
@@ -23,6 +24,7 @@ export function registerHandoffCompaction(pi: ExtensionAPI, state: AgenticodingS
 
 		state.pendingHandoff = null;
 		state.pendingRequestedHandoff = null;
+		clearActiveNotebookTopic(state);
 
 		// Clear the handoff progress indicator now that compaction is consuming it
 		if (ctx.hasUI) {

index.ts

@@ -25,12 +25,15 @@ import { CONTEXT_PRIMER } from "./system-prompt.js";
 import { buildNudge, registerWatchdog } from "./watchdog.js";
 import { registerNotebookTools } from "./notebook/tools.js";
 import { registerNotebookRehydration } from "./notebook/rehydration.js";
+import { registerNotebookTopicTool } from "./notebook/topic-tool.js";
+import { setActiveNotebookTopic } from "./notebook/topic.js";
 import { registerHandoffTool } from "./handoff/tool.js";
 import { registerHandoffCommand } from "./handoff/command.js";
 import { registerHandoffCompaction } from "./handoff/compact.js";
 import { registerSpawnTool } from "./spawn/index.js";
 import {
 	STATUS_KEY_HANDOFF,
+	STATUS_KEY_TOPIC,
 	WIDGET_KEY_WARNING,
 	updateIndicators,
 } from "./tui.js";
@@ -41,6 +44,7 @@ export default function (pi: ExtensionAPI): void {
 
 	// ── Register all tools ──────────────────────────────────────────
 	registerNotebookTools(pi, state);
+	registerNotebookTopicTool(pi, state);
 	registerHandoffTool(pi, state);
 	registerSpawnTool(pi, state);
 
@@ -54,8 +58,20 @@ export default function (pi: ExtensionAPI): void {
 
 	// ── /notebook command — interactive page selector ────────────────
 	pi.registerCommand("notebook", {
-		description: "Select a notebook page to preview",
-		handler: async (_args, ctx) => {
+		description: "Select a notebook page to preview, or set the active notebook topic with /notebook <topic>",
+		handler: async (args, ctx) => {
+			const topicArg = args.trim();
+			if (topicArg) {
+				const result = setActiveNotebookTopic(state, topicArg, "human");
+				if (ctx.hasUI) {
+					const message = result.boundaryHint
+						? `Active notebook topic changed: ${result.boundaryHint.from} → ${result.boundaryHint.to}. This is a likely task boundary; handoff is recommended before continuing.`
+						: `Active notebook topic: ${result.current}`;
+					ctx.ui.notify(message, result.boundaryHint ? "warning" : "info");
+				}
+				updateIndicators(ctx, state);
+				return;
+			}
 			if (!ctx.hasUI) {
 				return;
 			}
@@ -152,12 +168,25 @@ export default function (pi: ExtensionAPI): void {
 		// Inject context management primer at the end of the system prompt
 		parts.push("\n" + CONTEXT_PRIMER);
 
-		// Inject ledger listing so the LLM always knows what's available
-		const entryNames = Array.from(state.ledger.keys()).sort();
+		if (state.activeNotebookTopic) {
+			parts.push(
+				`\n## Active Notebook Topic\n` +
+				`Current topic: \`${state.activeNotebookTopic}\` (${state.activeNotebookTopicSource ?? "unknown"}-set).\n` +
+				`Treat this as the current semantic frame. If new work fits it, prefer spawn for isolated noisy subtasks. If it does not fit it, prefer handoff over dragging stale context forward.`,
+			);
+		} else {
+			parts.push(
+				`\n## Active Notebook Topic\n` +
+				`No active notebook topic is set. Early in the next substantive task, assign a short stable topic with \`notebook_topic_set\`. Human-set topics are authoritative.`,
+			);
+		}
+
+		// Inject notebook listing so the LLM always knows what's available
+		const entryNames = Array.from(state.notebookPages.keys()).sort();
 		if (entryNames.length > 0) {
 			const listing = entryNames
 				.map((name) => {
-					const content = state.ledger.get(name)!;
+					const content = state.notebookPages.get(name)!;
 					const firstLine = (content.split("\n")[0] ?? "").slice(0, 80);
 					return `  ${name}: ${firstLine}`;
 				})
@@ -201,6 +230,7 @@ export default function (pi: ExtensionAPI): void {
 			// Clear any stale TUI indicators from the previous session
 			if (ctx.hasUI) {
 				ctx.ui.setStatus(STATUS_KEY_HANDOFF, undefined);
+				ctx.ui.setStatus(STATUS_KEY_TOPIC, undefined);
 				ctx.ui.setWidget(WIDGET_KEY_WARNING, undefined);
 			}
 		}

notebook/topic-tool.ts

@@ -0,0 +1,53 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { AgenticodingState } from "../state.js";
+import { normalizeNotebookTopic, setActiveNotebookTopic } from "./topic.js";
+
+export function registerNotebookTopicTool(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+): void {
+	pi.registerTool({
+		name: "notebook_topic_set",
+		label: "Notebook Topic Set",
+		description:
+			"Set the active notebook topic for the current session. " +
+			"Use this to establish the current semantic frame when no topic is set yet. " +
+			"Human-set topics are authoritative and cannot be overridden by the agent.",
+		promptSnippet: "Set the active notebook topic for the current session",
+		promptGuidelines: [
+			"Use this early in a fresh session when no active notebook topic exists yet.",
+			"Do not use this to override a human-set topic. If the work no longer fits the current topic, prefer handoff instead.",
+		],
+		parameters: Type.Object({
+			topic: Type.String({
+				description: "Short stable notebook topic name for the current semantic frame.",
+			}),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const normalized = normalizeNotebookTopic(params.topic);
+			if (state.activeNotebookTopic) {
+				if (state.activeNotebookTopic !== normalized) {
+					throw new Error(
+						state.activeNotebookTopicSource === "human"
+							? "Human-set notebook topic is authoritative. Use handoff instead of overriding it."
+							: "Active notebook topic already exists. Use handoff instead of changing it mid-session.",
+					);
+				}
+				return {
+					content: [{ type: "text", text: `Notebook topic already set to \"${state.activeNotebookTopic}\".` }],
+					details: {
+						topic: state.activeNotebookTopic,
+						source: state.activeNotebookTopicSource,
+						changed: false,
+					},
+				};
+			}
+			const result = setActiveNotebookTopic(state, params.topic, "agent");
+			return {
+				content: [{ type: "text", text: `Active notebook topic: \"${result.current}\".` }],
+				details: { topic: result.current, source: "agent" as const, changed: result.changed },
+			};
+		},
+	});
+}

notebook/topic.ts

@@ -0,0 +1,52 @@
+import type { AgenticodingState } from "../state.js";
+
+export type NotebookTopicSource = "human" | "agent";
+
+export interface NotebookTopicBoundaryHint {
+	from: string | null;
+	to: string;
+	source: NotebookTopicSource;
+}
+
+export function normalizeNotebookTopic(input: string): string {
+	return input
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 80);
+}
+
+export function setActiveNotebookTopic(
+	state: AgenticodingState,
+	topic: string,
+	source: NotebookTopicSource,
+): { changed: boolean; previous: string | null; current: string; boundaryHint: NotebookTopicBoundaryHint | null } {
+	const normalized = normalizeNotebookTopic(topic);
+	if (!normalized) {
+		throw new Error("Notebook topic cannot be empty.");
+	}
+
+	const previous = state.activeNotebookTopic;
+	const changed = previous !== normalized;
+	state.activeNotebookTopic = normalized;
+	state.activeNotebookTopicSource = source;
+
+	const boundaryHint = changed && previous !== null
+		? { from: previous, to: normalized, source }
+		: null;
+	state.pendingTopicBoundaryHint = boundaryHint;
+
+	return {
+		changed,
+		previous,
+		current: normalized,
+		boundaryHint,
+	};
+}
+
+export function clearActiveNotebookTopic(state: AgenticodingState): void {
+	state.activeNotebookTopic = null;
+	state.activeNotebookTopicSource = null;
+	state.pendingTopicBoundaryHint = null;
+}

state.ts

@@ -14,6 +14,19 @@ export interface AgenticodingState {
 	/** Monotonically increasing epoch, set on first notebook_write */
 	epoch: number;
 
+	/** Current semantic frame for topic-aware spawn vs handoff decisions. */
+	activeNotebookTopic: string | null;
+
+	/** Whether the current topic came from the human or the agent. */
+	activeNotebookTopicSource: "human" | "agent" | null;
+
+	/** One-shot boundary cue consumed by the next LLM call after a topic change. */
+	pendingTopicBoundaryHint: {
+		from: string | null;
+		to: string;
+		source: "human" | "agent";
+	} | null;
+
 	/** Last context usage percent from getContextUsage() */
 	lastContextPercent: number | null;
 
@@ -59,6 +72,9 @@ export function createState(): AgenticodingState {
 	const state: AgenticodingState = {
 		notebookPages: new Map(),
 		epoch: 0,
+		activeNotebookTopic: null,
+		activeNotebookTopicSource: null,
+		pendingTopicBoundaryHint: null,
 		lastContextPercent: null,
 		pendingHandoff: null,
 		pendingRequestedHandoff: null,
@@ -89,6 +105,9 @@ export function resetState(state: AgenticodingState): void {
 	state.childSessionEpoch++;
 	state.notebookPages.clear();
 	state.epoch = 0;
+	state.activeNotebookTopic = null;
+	state.activeNotebookTopicSource = null;
+	state.pendingTopicBoundaryHint = null;
 	state.lastContextPercent = null;
 	state.pendingHandoff = null;
 	state.pendingRequestedHandoff = null;

tui.ts

@@ -22,7 +22,10 @@ export const STATUS_KEY_CTX = "agenticoding-ctx";
 /** Status bar key for notebook page count. */
 export const STATUS_KEY_NOTEBOOK = "agenticoding-notebook";
 
-/** Update TUI indicators: context usage, notebook count, warning widget. */
+/** Status bar key for the active notebook topic. */
+export const STATUS_KEY_TOPIC = "agenticoding-topic";
+
+/** Update TUI indicators: context usage, notebook count, topic, warning widget. */
 export function updateIndicators(ctx: ExtensionContext, state: AgenticodingState): void {
 	if (!ctx.hasUI) return;
 
@@ -45,11 +48,21 @@ export function updateIndicators(ctx: ExtensionContext, state: AgenticodingState
 		: theme.fg("dim", "\u{1F4D2} 0"),
 	);
 
+	// Active notebook topic — show a dim placeholder when unset so the frame is discoverable
+	ctx.ui.setStatus(
+		STATUS_KEY_TOPIC,
+		state.activeNotebookTopic
+			? `\u{1F9ED} ${state.activeNotebookTopic}`
+			: theme.fg("dim", "\u{1F9ED} -"),
+	);
+
 	// High-context warning widget (above editor)
 	if (usage && usage.percent !== null && usage.percent >= 70) {
+		const warning = state.activeNotebookTopic
+			? `Context at ${Math.round(usage.percent)}% — use topic fit: same topic → spawn, different topic → handoff`
+			: `Context at ${Math.round(usage.percent)}% — no active topic; handoff soon unless you can assign one cleanly`;
 		ctx.ui.setWidget(WIDGET_KEY_WARNING, [
-			theme.fg("error", "\u26A0 ") +
-				theme.fg("warning", `Context at ${Math.round(usage.percent)}% — consider handoff`),
+			theme.fg("error", "\u26A0 ") + theme.fg("warning", warning),
 		]);
 	} else {
 		ctx.ui.setWidget(WIDGET_KEY_WARNING, undefined);