one-code-extension 0.4.1 → 0.5.0

package/extensions/system-reminder/index.ts

@@ -2,22 +2,41 @@
  * system-reminder extension — injects queued <system-reminder> blocks into the
  * outgoing LLM request (pi `context` event), and writes one-shots into the tool
  * result they follow (pi `tool_result` event) so they persist in the session
- * the way Claude Code's mid-turn reminders do. Standing and context reminders
- * stay transient: the session file never contains them. This extension owns
+ * the way Claude Code's mid-turn reminders do. Context and sticky anchors are
+ * restored from hidden custom entries; rendered messages stay untouched. This extension owns
  * the one queue instance; every other extension reaches it over
  * `one-code:system-reminder` (lib/reminders.ts has the placement contract).
+ *
+ * On a model that takes a mid-conversation system message (lib/system-role.ts),
+ * its `before_provider_request` hook then lifts the session-fact blocks off the
+ * first user message into one system message after it, Claude Code's layout.
+ * It loads before tool-search and compaction, so replays and forks inherit it.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CLEAR_AT_BETA, MID_CONVERSATION_SYSTEM_BETA, reseatMessageMark, withBetas } from "../lib/anthropic-payload.ts";
 import {
 	appendReminderBlocks,
+	framedReminderText,
 	injectReminders,
+	movesToSystemRole,
 	openingUserAnchor,
 	REMINDER_CHANNEL,
 	ReminderQueue,
+	type ReminderEntry,
 	type ReminderPayload,
 	tailAnchor,
 } from "../lib/reminders.ts";
+import {
+	CONTEXT_BASELINE_CHANNEL, CONTEXT_RESTORE_CHANNEL, CONTEXT_STACK_ENTRY, CONTEXT_STATE_ENTRY, CONTEXT_FACTS_REFRESH_CHANNEL,
+	contextStackOnBranch, RESTORED_STACK_KEYS, LIVE_CONTEXT_KEYS,
+	type ContextBaseline, type ContextRestoreRequest, type ContextStackSnapshot, type ContextFactsRefresh,
+} from "../lib/context-stack.ts";
+import { CONTEXT_FACT_KEYS, DATE_CHANGE_KEY, RESUME_FACTS_KEY } from "../lib/context-facts.ts";
+import { claudeFamily } from "../lib/model-tier.ts";
+import { emptyToolResultContent } from "../lib/empty-tool-result.ts";
+import { instructionRole, messagesKey, type MovedBlock, systemRoleLayout, wireShape, withSystemRoleContext } from "../lib/system-role.ts";
+import { resolveCountdowns, withTurnBudgetMessages } from "../lib/turn-budget-layout.ts";
 
 /**
  * Roles a reminder can be attached to (see injectReminders). `custom` is a
@@ -30,6 +49,84 @@ const ANCHOR_ROLES = new Set(["user", "toolResult", "compactionSummary", "custom
 
 export default function systemReminderExtension(pi: ExtensionAPI) {
 	const reminderQueue = new ReminderQueue();
+	let restored: ContextStackSnapshot | undefined;
+	let stored = false;
+	let baselines: Record<string, unknown> = {};
+	let lastState = "";
+	let lastStack = "";
+	pi.events.on(CONTEXT_RESTORE_CHANNEL, (data) => {
+		if (data && restored) (data as ContextRestoreRequest).restored = structuredClone(restored);
+	});
+	pi.events.on(CONTEXT_BASELINE_CHANNEL, (data) => {
+		const baseline = data as ContextBaseline | undefined;
+		if (typeof baseline?.key === "string") {
+			baselines[baseline.key] = structuredClone(baseline.value);
+			baselineChanges++;
+		}
+	});
+	pi.on("session_start", (_event, ctx) => {
+		restored = contextStackOnBranch(ctx.sessionManager.getBranch());
+		stored = restored !== undefined;
+		baselines = restored ? structuredClone(restored.baselines) : {};
+		lastState = restored ? JSON.stringify({ version: 1, sticky: restored.sticky, pinned: restored.pinned ?? [], baselines }) : "";
+		lastStack = restored ? JSON.stringify(restored.stack) : "";
+		comparedQueue = -1;
+		if (restored) reminderQueue.restore(restored.stack, restored.sticky, RESTORED_STACK_KEYS, LIVE_CONTEXT_KEYS, restored.pinned);
+		else reminderQueue.releaseRestore();
+	});
+	// A /tree switch fires only session_tree (findings §3). The selected branch's
+	// messages were sent with its own facts, sticky blocks and pins: take them
+	// from its last snapshot, as a resume would, while live state and every
+	// emitter's baseline stay current (claude-context republishes its own).
+	pi.on("session_tree", (_event, ctx) => {
+		const branch = contextStackOnBranch(ctx.sessionManager.getBranch());
+		stored = branch !== undefined;
+		lastState = branch ? JSON.stringify({ version: 1, sticky: branch.sticky, pinned: branch.pinned ?? [], baselines: branch.baselines }) : "";
+		lastStack = branch ? JSON.stringify(branch.stack) : "";
+		comparedQueue = -1;
+		if (branch) reminderQueue.restoreBranch(branch, CONTEXT_FACT_KEYS);
+	});
+	/**
+	 * The queue version and baseline count the last comparison saw, or -1 when
+	 * it must run again. A stack taken before a drain that changed the queue
+	 * may not be the stack the queue holds after it, so that sets -1 too.
+	 */
+	let comparedQueue = -1;
+	let comparedBaselines = -1;
+	let baselineChanges = 0;
+	/** `capturedAt`: the queue version when `stack` was taken. Unchanged since the last comparison, the snapshot is too. */
+	const persistSnapshot = (stack: ReminderEntry[] = reminderQueue.persistentEntries("first-prepend"), capturedAt = reminderQueue.version) => {
+		const version = reminderQueue.version;
+		if (stored && capturedAt === version && version === comparedQueue && baselineChanges === comparedBaselines) return;
+		comparedQueue = capturedAt === version ? version : -1;
+		comparedBaselines = baselineChanges;
+		const state = { version: 1 as const, sticky: reminderQueue.persistentEntries("sticky-append"), pinned: reminderQueue.persistentPins(), baselines };
+		const serialized = JSON.stringify(state);
+		const serializedStack = JSON.stringify(stack);
+		if (!stored) {
+			pi.appendEntry(CONTEXT_STACK_ENTRY, structuredClone({ ...state, stack }));
+			stored = true;
+		} else if (serialized !== lastState || serializedStack !== lastStack) {
+			// Compaction and explicit capability switches start a new prefix.
+			pi.appendEntry(CONTEXT_STATE_ENTRY, structuredClone({ ...state, ...(serializedStack !== lastStack ? { stack } : {}) }));
+		}
+		lastState = serialized;
+		lastStack = serializedStack;
+	};
+	pi.events.on(CONTEXT_FACTS_REFRESH_CHANNEL, (data) => {
+		const refresh = data as ContextFactsRefresh;
+		reminderQueue.replaceFirstPrepend(CONTEXT_FACT_KEYS, refresh.entries);
+		reminderQueue.cancelPending([DATE_CHANGE_KEY, RESUME_FACTS_KEY]);
+		baselines["claude-context"] = structuredClone(refresh.baseline);
+		baselineChanges++;
+		// /compact may be the last action before exit. Persist now, not just on
+		// the next request, so a resume cannot revive the pre-compaction facts.
+		persistSnapshot();
+	});
+	/** The blocks the last `context` pass placed for the system message; the payload hook moves them. */
+	let moved: MovedBlock[] = [];
+	/** The tool results' countdowns the last `context` pass lifted, by call id (lib/turn-budget-layout.ts). */
+	let countdowns = new Map<string, number>();
 
 	pi.events.on(REMINDER_CHANNEL, (data) => {
 		const payload = data as ReminderPayload;
@@ -44,8 +141,11 @@ export default function systemReminderExtension(pi: ExtensionAPI) {
 				order: payload.order,
 				suffix: payload.suffix,
 				raw: payload.raw,
+				systemRoleOnly: payload.systemRoleOnly,
+				skipStackCarrier: payload.skipStackCarrier,
 				since: payload.since,
 				once: payload.once,
+				toolCallId: payload.toolCallId,
 			});
 		}
 	});
@@ -59,32 +159,94 @@ export default function systemReminderExtension(pi: ExtensionAPI) {
 	// the trailing reminder run when it applies a replacement (review M3,
 	// applyPostToolUseOutcome / isAppendedReminderText).
 	pi.on("tool_result", (event) => {
-		if (!reminderQueue.hasPendingOneShots) return;
-		const entries = reminderQueue.takeOneShots();
-		return { content: appendReminderBlocks(event.content, entries) };
+		// Normalize the tool's result before reminders make an empty result look
+		// nonempty. Read's raw bytes stay for file-tracker's empty-file warning.
+		const replacement = emptyToolResultContent(event.content, event.toolName);
+		const entries = reminderQueue.hasPendingOneShots ? reminderQueue.takeOneShots(event.toolCallId) : [];
+		if (!replacement && entries.length === 0) return;
+		const content = replacement ?? event.content;
+		return {
+			content: entries.length ? appendReminderBlocks(content, entries) : content,
+			...(event.structuredContent !== undefined ? { structuredContent: event.structuredContent } : {}),
+		};
 	});
 
-	pi.on("context", (event) => {
-		if (reminderQueue.size === 0) return;
+	/** The request's messages with the queued reminders placed, or the input when nothing can be placed. */
+	const withReminders = (messages: Parameters<typeof injectReminders>[0], layout: ReturnType<typeof systemRoleLayout>) => {
+		if (reminderQueue.size === 0 && !stored) return messages;
 		// injectReminders is a no-op when there is nothing to attach to. Only
 		// consume the queue once there is somewhere to put the reminders, so they
 		// survive to the next eligible request.
-		if (!event.messages.some((m) => ANCHOR_ROLES.has(m.role))) return;
+		if (!messages.some((m) => ANCHOR_ROLES.has(m.role))) return messages;
 		// A one-shot that arrived after the last tool result was stored (a mode
 		// change while idle, a deferred-tool miss whose call had no tool_result
 		// hook) rides this request's tail — and stays pinned there afterwards.
 		if (reminderQueue.hasPendingOneShots) {
-			const anchor = tailAnchor(event.messages);
-			if (anchor) reminderQueue.pin(anchor);
+			const anchor = tailAnchor(messages);
+			if (anchor) reminderQueue.pin(anchor, "last-append", messages);
 		}
 		// A local-command breadcrumb rides the prompt that opens a request, before
 		// the user's text (Claude Code's placement), and stays there. Mid-turn —
 		// the request ends in a tool result — it waits for the next prompt.
 		if (reminderQueue.hasPending("user-prepend")) {
-			const anchor = openingUserAnchor(event.messages);
+			const anchor = openingUserAnchor(messages);
 			if (anchor) reminderQueue.pin(anchor, "user-prepend");
 		}
-		const reminders = reminderQueue.drain(event.messages);
-		return { messages: injectReminders(event.messages, reminders) };
+		// Capture first-prepend before draining (one may be next-turn), then save
+		// after drain resolves sticky anchors. Store logical entries before layout,
+		// including systemRoleOnly blocks even on a model that cannot carry them.
+		reminderQueue.finishRestore();
+		const capturedAt = reminderQueue.version;
+		const stack = reminderQueue.persistentEntries("first-prepend");
+		const drained = reminderQueue.drain(messages);
+		persistSnapshot(stack, capturedAt);
+		// A block meant only for the system message is left out where there is none.
+		const reminders = drained.filter((entry) => layout || !entry.systemRoleOnly);
+		if (layout) {
+			moved = reminders
+				.filter((entry) => entry.placement === "first-prepend" && movesToSystemRole(entry.order))
+				.sort((a, b) => a.order - b.order)
+				.map((entry) => ({ framed: framedReminderText(entry), inner: entry.text }));
+		}
+		return injectReminders(messages, reminders);
+	};
+
+	pi.on("context", (event, ctx) => {
+		moved = [];
+		countdowns = new Map();
+		const layout = systemRoleLayout(ctx.model);
+		const messages = withReminders(event.messages, layout);
+		// Each tool result's stored <total_tokens> countdown, on every request so
+		// the layout never depends on the queue: lifted for a system message or
+		// framed, while the result's blocks are still separate (lib/turn-budget-layout.ts).
+		// With the budget off no result carries one, so a tool's own such line stays its output.
+		const budgetOn = process.env.CC_TOTAL_TOKENS !== "0";
+		const resolved = budgetOn && ctx.model && wireShape(ctx.model.api) ? resolveCountdowns(messages, layout !== undefined) : undefined;
+		if (resolved) countdowns = resolved.left;
+		const out = resolved?.messages ?? messages;
+		return out === event.messages ? undefined : { messages: out };
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const model = ctx.model;
+		const shape = model ? wireShape(model.api) : undefined;
+		if (!model || !shape) return undefined;
+		const layout = systemRoleLayout(model);
+		const role = instructionRole(shape, model);
+		let payload = event.payload as Record<string, unknown>;
+		if (layout) payload = withSystemRoleContext(payload, layout, moved, role) ?? payload;
+		// Claude Code's per-turn <total_tokens> shapes; first-party Fable also
+		// gets its clear_at nudge after each tool result.
+		const firstParty = model.provider === "anthropic";
+		const nudge = layout === "anthropic" && firstParty && claudeFamily(model.id) === "fable";
+		const markers = process.env.CC_TOTAL_TOKENS !== "0";
+		payload = withTurnBudgetMessages(payload, { shape, systemRole: layout !== undefined, role, left: countdowns, nudge, markers }) ?? payload;
+		if (payload === event.payload) return undefined;
+		if (shape === "anthropic") {
+			const key = messagesKey(shape);
+			payload = { ...payload, [key]: reseatMessageMark(payload[key] as Array<{ role?: unknown; content?: unknown }>) };
+		}
+		if (layout !== "anthropic" || !firstParty) return payload;
+		return withBetas(payload, nudge ? [MID_CONVERSATION_SYSTEM_BETA, CLEAR_AT_BETA] : [MID_CONVERSATION_SYSTEM_BETA]);
 	});
 }

package/extensions/tasks/descriptions.ts

@@ -0,0 +1,190 @@
+/**
+ * The task tools' model-facing texts: Claude Code's TaskCreate, TaskUpdate,
+ * TaskGet and TaskList descriptions and parameter texts, with One Code's tool
+ * names (pure). The schemas are the same on both sides.
+ */
+
+export const TASK_CREATE_DESCRIPTION = `Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements as tasks
+- When you start working on a task - Mark it as in_progress BEFORE beginning work
+- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: What needs to be done
+- **activeForm** (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.
+
+All tasks are created with status \`pending\`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- After creating tasks, use task_update to set up dependencies (blocks/blockedBy) if needed
+- Check task_list first to avoid creating duplicate tasks
+`;
+
+export const TASK_UPDATE_DESCRIPTION = `Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call task_list to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: \`pending\` → \`in_progress\` → \`completed\`
+
+Use \`deleted\` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using \`task_get\` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+\`\`\`json
+{"taskId": "1", "status": "in_progress"}
+\`\`\`
+
+Mark task as completed after finishing work:
+\`\`\`json
+{"taskId": "1", "status": "completed"}
+\`\`\`
+
+Delete a task:
+\`\`\`json
+{"taskId": "1", "status": "deleted"}
+\`\`\`
+
+Claim a task by setting owner:
+\`\`\`json
+{"taskId": "1", "owner": "my-name"}
+\`\`\`
+
+Set up task dependencies:
+\`\`\`json
+{"taskId": "2", "addBlockedBy": ["1"]}
+\`\`\`
+`;
+
+export const TASK_GET_DESCRIPTION = `Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', or 'completed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use task_list to see all tasks in summary form.
+`;
+
+export const TASK_LIST_DESCRIPTION = `Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with task_get, task_update)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', or 'completed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use task_get with a specific task ID to view full details including description and comments.
+`;
+
+export const TASK_CREATE_PARAMS = {
+	subject: `A brief title for the task`,
+	description: `What needs to be done`,
+	activeForm: `Present continuous form shown in spinner when in_progress (e.g., "Running tests")`,
+	metadata: `Arbitrary metadata to attach to the task`,
+} as const;
+
+export const TASK_UPDATE_PARAMS = {
+	taskId: `The ID of the task to update`,
+	subject: `New subject for the task`,
+	description: `New description for the task`,
+	activeForm: `Present continuous form shown in spinner when in_progress (e.g., "Running tests")`,
+	status: `New status for the task`,
+	addBlocks: `Task IDs that this task blocks`,
+	addBlockedBy: `Task IDs that block this task`,
+	owner: `New owner for the task`,
+	metadata: `Metadata keys to merge into the task. Set a key to null to delete it.`,
+} as const;
+
+export const TASK_GET_PARAMS = {
+	taskId: `The ID of the task to retrieve`,
+} as const;