one-code-extension 0.4.0 → 0.5.0

package/extensions/init/prompt.ts

@@ -1,40 +1,33 @@
 /**
- * The `/init` prompt — adapted from Claude Code's `/init`, kept provider-neutral
- * (One Code writes a CLAUDE.md that any Claude Code-compatible agent reads) and
- * self-contained (no dependency on CC-internal skills like `update-config`).
+ * The `/init` prompt: Claude Code's classic one, the prompt it sends by
+ * default, submitted verbatim as a user turn by extensions/init/index.ts.
  *
- * Submitted verbatim as a user turn by extensions/init/index.ts; the model does
- * the work with the normal tool set (subagent survey, ask_user_question, write).
+ * Three adaptations. The CLAUDE.md it writes is read by every Claude
+ * Code-compatible agent, One Code included, so the opening sentence and the
+ * file's header name AI coding agents rather than one product (the header is
+ * the one One Code's /init has always written). And the rules to fold in
+ * include an AGENTS.md: One Code reads a directory's AGENTS.md only when that
+ * directory has no CLAUDE.md, so once /init writes one, anything left in
+ * AGENTS.md alone would stop reaching the model.
  */
-export const INIT_PROMPT = `Analyze this codebase and set up a concise CLAUDE.md at the repository root, to be loaded into every future session working here. Keep it minimal — every line must earn its place: include only what an agent would get wrong or waste time rediscovering without it.
-
-## 1. Survey the codebase
-Launch an Explore subagent (or read directly if the repo is small) to gather:
-- Build, test, and lint commands — especially non-standard scripts, flags, or how to run a *single* test.
-- Languages, frameworks, package manager, and whether this is a monorepo/multi-module or single project.
-- High-level architecture that requires reading several files to grasp (the "big picture", not a file listing).
-- Non-obvious gotchas, required env vars, or workflow quirks.
-- Existing AI-tool config to fold in: an existing CLAUDE.md, AGENTS.md, .cursor/rules or .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules — and the important parts of README.md.
-
-## 2. Fill the gaps
-Use ask_user_question only for things the code cannot answer — branch/PR conventions, required setup, testing quirks, communication preferences. Skip anything already obvious from manifests or the README. Do not mark options as "recommended": this is how their team works, not best practices.
-
-## 3. Write CLAUDE.md
-Prefix the file with:
+export const INIT_PROMPT = `Please analyze this codebase and create a CLAUDE.md file, which will be given to future AI coding agents (Claude Code and compatible tools) to operate in this repository.
+
+What to add:
+1. Commands that will be commonly used, such as how to build, lint, and run tests. Include the necessary commands to develop in this codebase, such as how to run a single test.
+2. High-level code architecture and structure so that future instances can be productive more quickly. Focus on the "big picture" architecture that requires reading multiple files to understand.
+
+Usage notes:
+- If there's already a CLAUDE.md, suggest improvements to it.
+- When you make the initial CLAUDE.md, do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users", "Write unit tests for all new utilities", "Never include sensitive information (API keys, tokens) in code or commits".
+- Avoid listing every component or file structure that can be easily discovered.
+- Don't include generic development practices.
+- If there are Cursor rules (in .cursor/rules/ or .cursorrules), Copilot rules (in .github/copilot-instructions.md) or an AGENTS.md, make sure to include the important parts.
+- If there is a README.md, make sure to include the important parts.
+- Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
+- Be sure to prefix the file with the following text:
 
 \`\`\`
 # CLAUDE.md
 
 This file gives guidance to AI coding agents (Claude Code and compatible tools) working in this repository.
-\`\`\`
-
-Include: build/test/lint commands an agent can't guess; code-style rules that DIFFER from language defaults; testing instructions and quirks; repo etiquette (branch naming, PR/commit conventions); required env vars or setup; non-obvious gotchas and architectural decisions; the important parts of any existing AI-tool config.
-
-Exclude: file-by-file structure or component lists (discoverable by reading); standard language conventions; generic advice ("write clean code", "handle errors"); long references or API docs (link them with \`@path/to/file\` import syntax instead of inlining); anything that changes frequently (reference the source with \`@path\`).
-
-Be specific — "Use 2-space indentation in TypeScript" beats "format code properly." Do not repeat yourself and do not invent sections like "Common Development Tasks" — only include what you actually found.
-
-If a CLAUDE.md already exists: read it, propose concrete improvements as diffs, and explain each. Do NOT silently overwrite. For projects with distinct subdirectories (monorepos), mention that per-directory CLAUDE.md files are loaded automatically when working in those directories, and offer to create them.
-
-## 4. Recap
-Summarize which file(s) you wrote and the key points in each. Remind the user this is a starting point to review and tweak, and that they can run \`/init\` again anytime to re-scan.`;
+\`\`\``;

package/extensions/interrupted/index.ts

@@ -11,11 +11,13 @@
  * InterruptedByUser component. The paired turn-duration line suppresses itself
  * on the same signal, so an interrupted turn shows this note in place of the
  * "Cooked for …" line — CC's behaviour (its turn-duration render is gated on
- * `!aborted`).
+ * `!aborted`). A send now (ctrl+x ctrl+s, the send-now extension) aborts the
+ * turn too, but gets no note: the user has already said what to do instead.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { wasInterrupted } from "../lib/interrupt.ts";
+import { SEND_NOW_CHANNEL } from "../lib/send-now-channel.ts";
 import { linesComponent, safeThemePaint } from "../lib/tui-render.ts";
 import { INTERRUPTED_TEXT } from "./line.ts";
 
@@ -27,7 +29,17 @@ export default function interruptedExtension(pi: ExtensionAPI) {
 		return linesComponent(() => [paint("dim", INTERRUPTED_TEXT)]);
 	});
 
+	// Send now aborts the turn to deliver the queued messages: the user has
+	// already said what to do instead, so that abort gets no note.
+	let sendingNow = false;
+	pi.events.on(SEND_NOW_CHANNEL, () => {
+		sendingNow = true;
+	});
+
 	pi.on("agent_end", (event, ctx) => {
+		const skip = sendingNow;
+		sendingNow = false;
+		if (skip) return;
 		if (!ctx.hasUI) return;
 		if (!wasInterrupted(event.messages, ctx.signal?.aborted)) return;
 		pi.appendEntry(ENTRY_TYPE);

package/extensions/kept-thinking/index.ts

@@ -0,0 +1,27 @@
+/**
+ * kept-thinking extension — removes thinking from the turns a compaction keeps,
+ * on APIs that check a thinking block's signature against the conversation
+ * before it (`compaction/kept-thinking.ts` says why and which turns).
+ *
+ * The boundary comes from the session branch, not from the request's messages:
+ * system-reminder rewrites the compaction summary message into a plain user
+ * message, so a strip keyed on it found nothing (seen live on Opus 5.5: every
+ * request after the compaction was a 400). It is the first `context` hook in
+ * the package manifest, before every extension that captures the request's
+ * messages for a side call (skill, background, subagents, recap, btw,
+ * compaction), so each capture carries the stripped history the session sent.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { signsThinking, withoutKeptThinking } from "../compaction/kept-thinking.ts";
+import { latestCompaction } from "../lib/compaction-boundary.ts";
+
+export default function keptThinkingExtension(pi: ExtensionAPI) {
+	pi.on("context", (event, ctx) => {
+		const api = ctx.model?.api;
+		// Only a signing API pays for the branch walk.
+		if (!signsThinking(api)) return undefined;
+		const messages = withoutKeptThinking(event.messages, api, latestCompaction(ctx.sessionManager.getBranch())?.time);
+		return messages ? { messages } : undefined;
+	});
+}

package/extensions/lib/agent-cron.ts

@@ -0,0 +1,130 @@
+/**
+ * Cron jobs for subagents, Claude Code's way (findings §21): a subagent's
+ * `cron_create` stamps its task id on the job, `cron_list` shows it only its
+ * own jobs, `cron_delete` refuses another's, and a fire goes to that agent
+ * while it lives and is dropped once it has ended.
+ *
+ * Children never load the background extension, so the subagents extension
+ * gives each child proxy tools (`agentCronTools`) that reach the main
+ * session's store over the main session's bus: an `AgentCronRequest` on
+ * AGENT_CRON_CHANNEL, answered synchronously by the background extension. A
+ * fire for an agent's job goes the other way as an `AgentCronFire` on
+ * AGENT_CRON_FIRE_CHANNEL; the subagents extension sets `delivered` when the
+ * agent took it.
+ *
+ * Pure: no pi imports.
+ */
+
+import {
+	CRON_CREATE_DESCRIPTION,
+	CRON_CREATE_PARAMETERS,
+	CRON_DELETE_DESCRIPTION,
+	CRON_DELETE_PARAMETERS,
+	CRON_LIST_DESCRIPTION,
+	CRON_LIST_PARAMETERS,
+} from "../background/cron.ts";
+
+export const AGENT_CRON_CHANNEL = "one-code:agent-cron";
+export const AGENT_CRON_FIRE_CHANNEL = "one-code:agent-cron-fire";
+
+export type AgentCronRequest =
+	| { op: "create"; agentId: string; cwd: string; cron: string; prompt: string; recurring?: boolean; result?: AgentCronResult }
+	| { op: "list"; agentId: string; result?: AgentCronResult }
+	| { op: "delete"; agentId: string; id: string; result?: AgentCronResult };
+
+export interface AgentCronResult {
+	text: string;
+	isError?: boolean;
+	details?: Record<string, unknown>;
+}
+
+export interface AgentCronFire {
+	agentId: string;
+	jobId: string;
+	prompt: string;
+	/** Set by the subagents extension when a live agent received it. */
+	delivered?: boolean;
+}
+
+/**
+ * cron_create's refusal in an agent that runs to completion (a nested spawn,
+ * or any spawn in a one-shot run): a fire reaches only a background agent,
+ * and this one ends first.
+ */
+export const BLOCKING_RUN_REFUSAL =
+	"Nothing was scheduled: this agent runs until its task is done and then ends, so a job it schedules could never fire. Do the work now, or report back so the main session can schedule it.";
+
+/** Claude Code's refusal when an agent deletes a job it does not own. */
+export function formatNotOwner(id: string): string {
+	return `Cannot delete cron job '${id}': owned by another agent`;
+}
+
+interface Emitter {
+	emit(channel: string, data: unknown): unknown;
+}
+
+/**
+ * Whether `agentId` owns a pending job in the main session's store (its
+ * `cron_list` count). The subagents extension keeps such an agent resident,
+ * since a fire reaches only a live one.
+ */
+export function agentOwnsCronJobs(events: Emitter, agentId: string): boolean {
+	const request: AgentCronRequest = { op: "list", agentId };
+	events.emit(AGENT_CRON_CHANNEL, request);
+	return ((request.result?.details?.jobCount as number | undefined) ?? 0) > 0;
+}
+
+/** Where a child's cron tools live: only a `resident` (background) run can receive a fire. */
+export interface AgentCronOwner {
+	agentId: string;
+	cwd: string;
+	resident: boolean;
+}
+
+/**
+ * The three cron tools for a child session, bound to its owner and the MAIN
+ * session's bus. Same names, schemas and descriptions as the main session's
+ * (background/index.ts). A run that is not resident keeps all three, as in
+ * Claude Code, but its cron_create refuses.
+ */
+export function agentCronTools(events: Emitter, { agentId, cwd, resident }: AgentCronOwner) {
+	const toolResult = (result: AgentCronResult) => ({
+		content: [{ type: "text" as const, text: result.text }],
+		details: result.details ?? {},
+		...(result.isError ? { isError: true } : {}),
+	});
+	const ask = (request: AgentCronRequest) => {
+		events.emit(AGENT_CRON_CHANNEL, request);
+		return toolResult(request.result ?? { text: "The session's cron store is not loaded; nothing was scheduled.", isError: true });
+	};
+	return [
+		{
+			name: "cron_create",
+			label: "Cron Create",
+			description: CRON_CREATE_DESCRIPTION,
+			parameters: CRON_CREATE_PARAMETERS,
+			async execute(_id: string, params: { cron: string; prompt: string; recurring?: boolean; durable?: boolean }) {
+				if (!resident) return toolResult({ text: BLOCKING_RUN_REFUSAL, isError: true });
+				return ask({ op: "create", agentId, cwd, cron: params.cron, prompt: params.prompt, recurring: params.recurring });
+			},
+		},
+		{
+			name: "cron_list",
+			label: "Cron List",
+			description: CRON_LIST_DESCRIPTION,
+			parameters: CRON_LIST_PARAMETERS,
+			async execute() {
+				return ask({ op: "list", agentId });
+			},
+		},
+		{
+			name: "cron_delete",
+			label: "Cron Delete",
+			description: CRON_DELETE_DESCRIPTION,
+			parameters: CRON_DELETE_PARAMETERS,
+			async execute(_id: string, params: { id: string }) {
+				return ask({ op: "delete", agentId, id: params.id });
+			},
+		},
+	];
+}

package/extensions/lib/agent-loader.ts

@@ -31,6 +31,7 @@ import type { PermissionBridge } from "../permissions/subagent-gate.ts";
 import { withShortCacheRetention } from "./cache-retention.ts";
 import { hookGateFactory } from "./hook-gate.ts";
 import { permissionGateFactory } from "./permission-gate.ts";
+import { releaseSideCalls } from "./side-call-run.ts";
 import { worktreeGuardFactory } from "./worktree-isolation.ts";
 
 /** The last assistant message's text (the value an agent run returns). */
@@ -126,7 +127,8 @@ export async function buildAgentLoader(options: AgentLoaderOptions): Promise<Def
 			// Order is load-bearing, mirroring the main session's extension order:
 			// hooks first (a hook's updatedInput must be what every guard judges),
 			// then the worktree git-isolation guard, then the permission gate.
-			...(options.getHookBridge ? [hookGateFactory(options.getHookBridge, { agentTypeOf: options.agentTypeOf, neverGate: options.neverGate })] : []),
+			// Permission-autoallowed orchestration tools still run the user's hooks.
+			...(options.getHookBridge ? [hookGateFactory(options.getHookBridge, { agentTypeOf: options.agentTypeOf })] : []),
 			worktreeGuardFactory(options.cwd),
 			permissionGateFactory(options.cwd, os.homedir(), options.neverGate, options.getPermissionBridge),
 			...(options.extraFactories ?? []),
@@ -181,3 +183,15 @@ export async function openChildSession(options: OpenChildSessionOptions): Promis
 	await session.bindExtensions({ onError: options.onError });
 	return session;
 }
+
+/**
+ * Dispose a child opened by openChildSession. `dispose()` never emits
+ * `session_shutdown`, so the child's side-call keys (its web_fetch reader),
+ * which that event releases in a main session, are released here
+ * (lib/side-call-run.ts).
+ */
+export function disposeChildSession(session: AgentSession): void {
+	const sessionId = session.sessionManager.getSessionId();
+	session.dispose();
+	releaseSideCalls(sessionId);
+}

package/extensions/lib/agent-view.ts

@@ -0,0 +1,85 @@
+/**
+ * The agent view's shared half: while the user views an agent (the subagents
+ * panel's Enter-to-view), the editor targets that agent, as Claude Code
+ * 2.1.283's does (findings §40). A label sits on the editor's top border, the
+ * empty editor shows `Message @<label>…`, and what the user submits goes to
+ * the agent in Claude Code's mid-turn wrapper. The subagents extension owns
+ * the view and announces it over `AGENT_VIEW_CHANNEL`; the branding extension
+ * owns the editor and paints it (extensions share no module state).
+ */
+
+import { fitPainted, visibleWidth } from "./text-width.ts";
+import { cutPlainText } from "./tui-render.ts";
+
+/** `{ target }` while an agent is viewed, `{}` when the view returns to main. */
+export const AGENT_VIEW_CHANNEL = "one-code:agent-view";
+
+export interface AgentViewTarget {
+	/** The top-border label: `@<name>` for a fork, the run's description otherwise. */
+	badge: string;
+	/** The empty editor's placeholder: `Message @<name or agent type>…`. */
+	placeholder: string;
+}
+
+export interface AgentViewAnnouncement {
+	target?: AgentViewTarget;
+}
+
+/** The slice of a live run the target is built from. */
+export interface ViewedRun {
+	name: string;
+	agentType: string;
+	label: string;
+}
+
+/**
+ * The editor target for a viewed run, Claude Code's shapes: a fork shows
+ * `@what-word-is` on the border and `Message @what-word-is…`; a regular agent
+ * shows its description on the border and `Message @general-purpose…`.
+ */
+export function agentViewTarget(run: ViewedRun, fork: boolean): AgentViewTarget {
+	const handle = fork ? run.name : run.agentType;
+	return { badge: fork ? `@${run.name}` : run.label, placeholder: `Message @${handle}…` };
+}
+
+/**
+ * Claude Code's wrapper for a message the user types at an agent, idle or
+ * running (findings §40), verbatim.
+ */
+export function userMessageForAgent(text: string): string {
+	return `The user sent a new message while you were working:\n${text}\n\nThis is how Claude Code surfaces messages the user sends mid-turn — within the running turn, often alongside the next tool result, rather than as a separate conversation turn. Address the message above as you continue this turn.`;
+}
+
+const USER_MESSAGE_OPENER = "The user sent a new message while you were working:\n";
+const USER_MESSAGE_CLOSER = "\n\nThis is how Claude Code surfaces messages the user sends mid-turn";
+
+/** The user's own text inside `userMessageForAgent`'s wrapper, or undefined for any other prompt. */
+export function unwrapUserMessage(prompt: string): string | undefined {
+	if (!prompt.startsWith(USER_MESSAGE_OPENER)) return undefined;
+	const end = prompt.lastIndexOf(USER_MESSAGE_CLOSER);
+	return end < USER_MESSAGE_OPENER.length ? undefined : prompt.slice(USER_MESSAGE_OPENER.length, end);
+}
+
+/**
+ * Draw `badge` (already painted, padding included, `badgeWidth` columns) at the
+ * right end of the editor's top border, followed by one border glyph:
+ * `─── @name ─`. The rest of the border, and anything pi embeds at its left
+ * (the working status), keeps its paint. No-op when the border is too narrow.
+ */
+export function applyBorderBadge(lines: string[], badge: string, badgeWidth: number, borderGlyph: string): string[] {
+	const top = lines[0];
+	if (top === undefined) return lines;
+	const width = visibleWidth(top);
+	const tail = badgeWidth + 1;
+	if (width < tail + 4) return lines;
+	const head = fitPainted(top, width - tail).text;
+	const out = lines.slice();
+	out[0] = `${head}\x1b[0m${badge}${borderGlyph}`;
+	return out;
+}
+
+/** The label cut to fit a border of `width` columns, keeping room for the border itself. */
+export function fitBadge(label: string, width: number): string {
+	const room = Math.floor(width / 2) - 3;
+	return room <= 1 ? "" : cutPlainText(label, room);
+}

package/extensions/lib/anthropic-payload.ts

@@ -1,7 +1,8 @@
 /**
  * Recognising an Anthropic Messages request body inside a `before_provider_request`
  * payload (pure). Shared by context-management (clear_thinking), compaction
- * (its replayed request) and tool-search (deferred tool definitions).
+ * (its replayed request), tool-search (deferred tool definitions) and
+ * idle-compact (the cache lifetime).
  */
 
 /** Anthropic Messages API shape: `messages` + `max_tokens`, and not an OpenAI `input`. */
@@ -13,3 +14,83 @@ export function looksLikeAnthropicRequest(payload: unknown): boolean {
 	const model = typeof record.model === "string" ? record.model : "";
 	return model.includes("claude") || typeof record.max_tokens === "number";
 }
+
+/**
+ * The payload with `betas` added, each once, after the ones pi set. pi-ai 1.0
+ * sends `payload.betas` as the final `anthropic-beta` header (it wins over a
+ * configured header), so a beta goes here, never into the headers (findings
+ * §54). The payload is returned unchanged when nothing is missing.
+ */
+export function withBetas<T extends Record<string, unknown>>(payload: T, betas: readonly string[]): T {
+	const existing: unknown[] = Array.isArray(payload.betas) ? payload.betas : [];
+	const missing = [...new Set(betas)].filter((beta) => !existing.includes(beta));
+	if (missing.length === 0) return payload;
+	return { ...payload, betas: [...existing, ...missing] };
+}
+
+/** Anthropic's beta for a `role: "system"` message after the first one. */
+export const MID_CONVERSATION_SYSTEM_BETA = "mid-conversation-system-2026-04-07";
+/** Anthropic's beta for a system message's `clear_at`. */
+export const CLEAR_AT_BETA = "mid-conversation-system-clear-at-2026-08-21";
+/** Anthropic's beta for reference-form `tool_addition` blocks. */
+export const MID_CONVERSATION_TOOL_CHANGES_BETA = "mid-conversation-tool-changes-2026-07-01";
+
+type Message = { role?: unknown; content?: unknown };
+type Block = Record<string, unknown> & { cache_control?: unknown };
+
+/** pi's directive-only effort message, which cannot carry a cache mark. */
+export function isEmptySystemMessage(message: Message | undefined): boolean {
+	return message?.role === "system" && Array.isArray(message.content) && message.content.length === 0;
+}
+
+/** A system message with a `clear_at` nudge: a string body, and Anthropic refuses a cache mark on it. */
+function isClearAtMessage(message: Message): boolean {
+	return message?.role === "system" && "clear_at" in (message as object);
+}
+
+/**
+ * The messages with pi's conversation cache mark on the last block that can
+ * carry it. pi marks the last block of the last message it built; system
+ * messages added after it in `before_provider_request` (the context message,
+ * the per-turn budget, a tool addition) would otherwise sit outside the mark,
+ * so it moves onto the last one, as Claude Code marks its own. pi's empty
+ * effort messages and a `clear_at` nudge are skipped over. Unchanged when the
+ * mark already sits there or no added system message ends the request.
+ */
+export function reseatMessageMark<T extends Message>(messages: T[]): T[] {
+	let target = messages.length - 1;
+	while (target >= 0 && (isEmptySystemMessage(messages[target]) || isClearAtMessage(messages[target]))) target--;
+	const tail = messages[target];
+	if (tail?.role !== "system" || !Array.isArray(tail.content) || tail.content.length === 0) return messages;
+	const tailBlocks = tail.content as Block[];
+	if (tailBlocks[tailBlocks.length - 1].cache_control !== undefined) return messages;
+	let from = target - 1;
+	while (from >= 0 && messages[from]?.role === "system") from--;
+	const source = messages[from];
+	if (!source || !Array.isArray(source.content) || source.content.length === 0) return messages;
+	const sourceBlocks = source.content as Block[];
+	const { cache_control, ...unmarked } = sourceBlocks[sourceBlocks.length - 1];
+	if (cache_control === undefined) return messages;
+	const copy = [...messages];
+	copy[from] = { ...source, content: [...sourceBlocks.slice(0, -1), unmarked] };
+	copy[target] = { ...tail, content: [...tailBlocks.slice(0, -1), { ...tailBlocks[tailBlocks.length - 1], cache_control }] };
+	return copy;
+}
+
+/**
+ * Whether a request body caches with a one-hour TTL: a breakpoint on the
+ * system, the tools or a message carries `cache_control.ttl: "1h"` (pi's long
+ * retention on Anthropic, through pi's own compat gating, so the body is the
+ * ground truth). OpenAI bodies have no breakpoints and answer false.
+ */
+export function hasOneHourCache(payload: unknown): boolean {
+	if (!payload || typeof payload !== "object") return false;
+	const body = payload as { system?: unknown; tools?: unknown; messages?: unknown };
+	const list = (value: unknown): unknown[] => (Array.isArray(value) ? value : []);
+	const oneHour = (block: unknown) => (block as { cache_control?: { ttl?: unknown } } | null)?.cache_control?.ttl === "1h";
+	return (
+		list(body.system).some(oneHour) ||
+		list(body.tools).some(oneHour) ||
+		list(body.messages).some((message) => oneHour(message) || list((message as { content?: unknown } | null)?.content).some(oneHour))
+	);
+}