one-code-extension 0.4.1 → 0.6.0

package/extensions/system-reminder/index.ts

@@ -1,90 +1,224 @@
 /**
- * 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 one queue instance; every other extension reaches it over
- * `one-code:system-reminder` (lib/reminders.ts has the placement contract).
+ * system-reminder extension, the renderer of the record-once request path
+ * (lib/reminders.ts has the placement contract, extensions/ledger the design).
+ * It owns the live reminder state every other extension feeds over
+ * `one-code:system-reminder`: the `first-prepend` stack and the open sticky
+ * states. A one-shot is persisted when emitted, as a `one-code:pending` entry,
+ * and delivered from the ledger's outbox.
+ *
+ * Its `context` hook runs right after the ledger's, which has cut the request
+ * to its tail and published the plan. It renders onto that tail only: the
+ * stack when the request opens an epoch, the sticky states, the pending
+ * one-shots, and the blocks capability owners add on RENDER_CHANNEL (live
+ * minus what the epoch told). It writes into the plan which pending items the
+ * request carries and what its new blocks tell, and the ledger records both
+ * with the request. Nothing is snapshotted or restored: everything above the
+ * tail is the record.
+ *
+ * On a model that takes a mid-conversation system message (lib/system-role.ts),
+ * its `before_provider_request` hook lifts the stack's session-fact blocks off
+ * the first user message into one system message after it (an epoch's request
+ * only), and shapes the tail's `<total_tokens>` lines (lib/turn-budget-layout.ts).
  */
 
+import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	appendReminderBlocks,
-	injectReminders,
-	openingUserAnchor,
-	REMINDER_CHANNEL,
-	ReminderQueue,
-	type ReminderPayload,
-	tailAnchor,
-} from "../lib/reminders.ts";
+import { CLEAR_AT_BETA, MID_CONVERSATION_SYSTEM_BETA, reseatMessageMark, withBetas } from "../lib/anthropic-payload.ts";
+import { emptyToolResultContent } from "../lib/empty-tool-result.ts";
+import { foldBranch } from "../lib/ledger/fold.ts";
+import { LEDGER_PLAN_CHANNEL, type RequestPlan } from "../lib/ledger/plan.ts";
+import { type EntryLike, makeRecord, type PendingRecordData, RECORD, stateOnBranch } from "../lib/ledger/records.ts";
+import { recordState } from "../lib/ledger/state.ts";
+import { contentHash } from "../lib/ledger/wire.ts";
+import { claudeFamily } from "../lib/model-tier.ts";
+import { extensionVersion } from "../lib/package-version.ts";
+import { LiveReminders, type OneShot, REMINDER_CHANNEL, RENDER_CHANNEL, type RenderRequest, renderReminders, type ReminderPayload, stickyFact } from "../lib/reminders.ts";
+import { sessionAlive } from "../lib/session-lifecycle.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
- * harness message (a task notification, a wakeup, hook context) that pi sends
- * to the model as a user message; a turn opened by one has no `user` message
- * of its own, so without it the model got no reminder stack at all
- * (STEERING-REVIEW-2026-09-05 H1).
- */
-const ANCHOR_ROLES = new Set(["user", "toolResult", "compactionSummary", "custom"]);
+/** Whether requests carry the `<total_tokens>` budget lines (`CC_TOTAL_TOKENS=0` turns them off). */
+const budgetMarkers = () => process.env.CC_TOTAL_TOKENS !== "0";
+
+/** A pending entry as a one-shot to place. */
+function oneShotOf(item: PendingRecordData): OneShot {
+	return {
+		id: item.id,
+		text: item.text,
+		placement: item.placement ?? "last-append",
+		...(item.raw ? { raw: true } : {}),
+		...(item.toolCallId ? { toolCallId: item.toolCallId } : {}),
+		...(item.promptTimestamp !== undefined ? { promptTimestamp: item.promptTimestamp } : {}),
+		...(item.once ? { once: true } : {}),
+		...(item.orTail ? { orTail: true } : {}),
+	};
+}
+
+/** The `one-code:state` key prefix of a sticky state's recorded start. */
+const STICKY_START_PREFIX = "sticky-start:";
 
 export default function systemReminderExtension(pi: ExtensionAPI) {
-	const reminderQueue = new ReminderQueue();
+	const alive = sessionAlive(pi);
+	const by = extensionVersion();
+	const live = new LiveReminders();
+	/** The plan the ledger published for the request being rendered. */
+	let plan: RequestPlan | undefined;
+	/** One-shots emitted before the session started (an extension's load): persisted at session_start. */
+	let early: ReminderPayload[] | undefined = [];
+	/** Without the ledger (a test harness, a session that does not load it): the pending ids this instance delivered. */
+	const deliveredHere = new Set<string>();
+
+	const persist = (payload: ReminderPayload) => {
+		const data = makeRecord("pending", by, {
+			id: randomUUID(),
+			text: payload.text as string,
+			placement: payload.placement === "user-prepend" ? "user-prepend" : "last-append",
+			...(payload.key ? { key: payload.key } : {}),
+			...(payload.raw ? { raw: true } : {}),
+			...(payload.toolCallId ? { toolCallId: payload.toolCallId } : {}),
+			...(payload.promptTimestamp !== undefined ? { promptTimestamp: payload.promptTimestamp } : {}),
+			...(payload.once ? { once: true } : {}),
+			...(payload.orTail ? { orTail: true } : {}),
+			...(payload.untilCompaction ? { untilCompaction: true } : {}),
+			...(payload.observations?.length ? { observations: payload.observations } : {}),
+			...(payload.notified?.length ? { notified: payload.notified } : {}),
+		});
+		pi.appendEntry(RECORD.pending, data);
+	};
+
+	/** The session's branch: the sticky states' starts it recorded. */
+	let branchOf: (() => EntryLike[]) | undefined;
+	/**
+	 * When each sticky state started, as the branch recorded it. An owner that
+	 * runs again (a resume, /reload, /tree) emits its state without a start, so
+	 * the renderer takes the branch's start for the same key and text: an epoch
+	 * that renders the conversation again (a model switch) then places the block
+	 * where the original requests did, and its first delivery stays told. A
+	 * removal records the run's end (null), so nothing carries past it.
+	 */
+	const stickyStart = (key: string): { since: number; hash: string } | undefined => {
+		const stored = branchOf ? (stateOnBranch(branchOf(), `${STICKY_START_PREFIX}${key}`) as { since?: unknown; hash?: unknown } | undefined) : undefined;
+		return typeof stored?.since === "number" && typeof stored.hash === "string" ? { since: stored.since, hash: stored.hash } : undefined;
+	};
 
 	pi.events.on(REMINDER_CHANNEL, (data) => {
-		const payload = data as ReminderPayload;
+		let payload = data as ReminderPayload | undefined;
 		if (!payload) return;
-		if (payload.remove && payload.key) {
-			reminderQueue.remove(payload.key);
-		} else if (typeof payload.text === "string") {
-			reminderQueue.enqueue(payload.text, {
-				scope: payload.scope,
-				key: payload.key,
-				placement: payload.placement,
-				order: payload.order,
-				suffix: payload.suffix,
-				raw: payload.raw,
-				since: payload.since,
-				once: payload.once,
-			});
+		const sticky = payload.placement === "sticky-append" && !payload.remove && typeof payload.text === "string";
+		const key = payload.key ?? payload.text ?? "";
+		const recorded = sticky ? stickyStart(key) : undefined;
+		if (sticky && payload.since === undefined && recorded?.hash === contentHash(payload.text)) payload = { ...payload, since: recorded.since };
+		// A removal ends the state's run: switched on again, even with the same
+		// text, it is a new state that rides the switching call's result, not the
+		// old run's start, whose first delivery the branch already told.
+		if (payload.remove && payload.key && branchOf && alive() && stickyStart(payload.key)) recordState(pi, `${STICKY_START_PREFIX}${payload.key}`, null);
+		const applied = live.apply(payload);
+		if (sticky && applied === "live" && branchOf && alive()) {
+			const entry = live.stickyEntries().find((state) => state.key === key);
+			const hash = entry ? contentHash(entry.text) : undefined;
+			if (entry && entry.since > 0 && (recorded?.since !== entry.since || recorded?.hash !== hash)) recordState(pi, `${STICKY_START_PREFIX}${key}`, { since: entry.since, hash });
 		}
+		if (applied !== "one-shot") return;
+		if (early) early.push(payload);
+		else if (alive()) persist(payload);
+	});
+	pi.on("session_start", (_event, ctx) => {
+		const sessionManager = ctx?.sessionManager;
+		branchOf = sessionManager ? () => sessionManager.getBranch() as EntryLike[] : undefined;
+		const queued = early ?? [];
+		early = undefined;
+		for (const payload of queued) persist(payload);
+	});
+	pi.events.on(LEDGER_PLAN_CHANNEL, (data) => {
+		plan = data as RequestPlan;
 	});
 
-	// A one-shot pending when a tool result is stored goes INTO that result: the
-	// model reads it right there, the session file keeps it, and no later request
-	// re-caches the message (a transient block would vanish on the next request
-	// and cost the result and everything after it). Runs before the hooks
-	// extension's PostToolUse in load order, so a hook that replaces the whole
-	// result would drop these appended blocks — the hooks extension re-attaches
-	// the trailing reminder run when it applies a replacement (review M3,
-	// applyPostToolUseOutcome / isAppendedReminderText).
+	// A tool's empty result is normalized before anything else reads it. Read's
+	// raw bytes stay for file-tracker's empty-file warning.
 	pi.on("tool_result", (event) => {
-		if (!reminderQueue.hasPendingOneShots) return;
-		const entries = reminderQueue.takeOneShots();
-		return { content: appendReminderBlocks(event.content, entries) };
+		const replacement = emptyToolResultContent(event.content, event.toolName);
+		if (!replacement) return;
+		return { content: replacement, ...(event.structuredContent !== undefined ? { structuredContent: event.structuredContent } : {}) };
 	});
 
-	pi.on("context", (event) => {
-		if (reminderQueue.size === 0) return;
-		// 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;
-		// 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);
+	/** The stack blocks the last `context` pass placed for the system message; the payload hook moves them. */
+	let moved: MovedBlock[] = [];
+	/** Whether the last `context` pass rendered an epoch: only then does the first user message carry the stack. */
+	let epochRequest = true;
+	/** The tool results' countdowns the last `context` pass lifted, by call id (lib/turn-budget-layout.ts). */
+	let countdowns = new Map<string, number>();
+
+	pi.on("context", (event, ctx) => {
+		const current = plan;
+		plan = undefined;
+		const layout = systemRoleLayout(ctx.model);
+		const epoch = current?.epoch ?? true;
+		const fold = current?.fold ?? foldBranch(ctx.sessionManager.getBranch() as EntryLike[]);
+
+		// Owners add nothing on an epoch (the live stack is rendered), so the told maps need no reset here.
+		const request: RenderRequest = { epoch, told: fold.told, modes: fold.modes, toldBlocks: fold.blocks, model: ctx.model, blocks: [] };
+		pi.events.emit(RENDER_CHANNEL, request);
+		const oneShots: OneShot[] = [
+			...fold.pending.filter((item) => !deliveredHere.has(item.id)).map(oneShotOf),
+			...request.blocks.map((block) => ({ text: block.text, placement: "last-append" as const, ...(block.facts ? { facts: block.facts } : {}) })),
+		];
+		const stack = live.stackEntries();
+		// A sticky state's first delivery is told, so a failed request's revokes and an epoch renders it again.
+		const toldBlocks = epoch ? new Map<string, string>() : fold.blocks;
+		const sticky = live.stickyEntries().map((entry) => {
+			const fact = stickyFact(entry);
+			return { ...entry, fact, delivered: toldBlocks.get(fact.key) === fact.hash };
+		});
+		const rendered = renderReminders(event.messages, { epoch, layout: layout !== undefined, stack, sticky, oneShots });
+		const stickyFacts = sticky.filter((entry) => !entry.delivered && rendered.stickyPlaced.includes(entry.key)).map((entry) => entry.fact);
+
+		const consumed = rendered.placed.flatMap((shot) => (shot.id ? [shot.id] : []));
+		// Each fact with the text that carries it: a repair that drops the text drops the fact.
+		const carried = [
+			...(epoch && rendered.stackPlaced ? stack.filter((entry) => layout !== undefined || !entry.systemRoleOnly).map((entry) => ({ text: entry.text, facts: entry.facts ?? [] })) : []),
+			...rendered.placed.map((shot) => ({ text: shot.text, facts: shot.facts ?? [] })),
+			...sticky.filter((entry) => stickyFacts.includes(entry.fact)).map((entry) => ({ text: entry.text, facts: [entry.fact] })),
+		].filter((block) => block.facts.length > 0);
+		if (current) {
+			current.consumed.push(...consumed);
+			current.carried.push(...carried);
+		} else {
+			for (const id of consumed) deliveredHere.add(id);
 		}
-		// 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);
-			if (anchor) reminderQueue.pin(anchor, "user-prepend");
+
+		moved = rendered.moved;
+		epochRequest = epoch;
+		// Each tool result's <total_tokens> countdown, 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.
+		countdowns = new Map();
+		const resolved = budgetMarkers() && ctx.model && wireShape(ctx.model.api) ? resolveCountdowns(rendered.messages, layout !== undefined) : undefined;
+		if (resolved) countdowns = resolved.left;
+		const out = resolved?.messages ?? rendered.messages;
+		const changed = out.length !== event.messages.length || out.some((message, i) => message !== event.messages[i]);
+		return changed ? { messages: out } : undefined;
+	});
+
+	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";
+		payload = withTurnBudgetMessages(payload, { shape, systemRole: layout !== undefined, role, left: countdowns, nudge, markers: budgetMarkers(), stackCarrier: epochRequest }) ?? payload;
+		if (payload !== event.payload && shape === "anthropic") {
+			const key = messagesKey(shape);
+			payload = { ...payload, [key]: reseatMessageMark(payload[key] as Array<{ role?: unknown; content?: unknown }>) };
 		}
-		const reminders = reminderQueue.drain(event.messages);
-		return { messages: injectReminders(event.messages, reminders) };
+		// The betas go on every request of a model that takes the layout: an
+		// earlier request's system messages are part of every later one.
+		if (layout === "anthropic" && firstParty) payload = withBetas(payload, nudge ? [MID_CONVERSATION_SYSTEM_BETA, CLEAR_AT_BETA] : [MID_CONVERSATION_SYSTEM_BETA]);
+		return payload === event.payload ? undefined : payload;
 	});
 }

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;