@asterxsk/kiln 0.1.0

package/agent/extensions/todo/tool/types.ts

@@ -0,0 +1,206 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Tool / command identity — verbatim string boundaries.
+// Tool name "todo" is the persistence key for branch replay (filtering
+// `toolResult.toolName === "todo"`) AND the permissions entry at
+// `templates/pi-permissions.jsonc:26`. DO NOT rename.
+// ---------------------------------------------------------------------------
+
+export const TOOL_NAME = "todo";
+export const TOOL_LABEL = "Todo";
+export const COMMAND_NAME = "todos";
+
+// ---------------------------------------------------------------------------
+// User-facing strings (kept stable for /todos UX parity).
+// ---------------------------------------------------------------------------
+
+export const ERR_REQUIRES_INTERACTIVE = "/todos requires interactive mode";
+export const MSG_NO_TODOS = "No todos yet. Ask the agent to add some!";
+
+// ---------------------------------------------------------------------------
+// Public domain types
+// ---------------------------------------------------------------------------
+
+export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+
+export type TaskAction = "create" | "update" | "list" | "get" | "delete" | "clear" | "batch";
+
+/**
+ * A single operation within a batch call. Mirrors TaskMutationParams minus
+ * the `items` field (batches cannot be nested).
+ */
+export interface BatchItem {
+	action: Exclude<TaskAction, "batch" | "list" | "get">;
+	subject?: string;
+	description?: string;
+	activeForm?: string;
+	status?: TaskStatus;
+	blockedBy?: number[];
+	addBlockedBy?: number[];
+	removeBlockedBy?: number[];
+	owner?: string;
+	metadata?: Record<string, unknown>;
+	id?: number;
+	subjects?: string[];
+	ids?: number[];
+	/** Labels to assign to created tasks (index-aligned with subjects, create only) */
+	as?: string[];
+	/** Reference labels from earlier batch items instead of numeric ids */
+	refs?: string[];
+}
+
+export interface Task {
+	id: number;
+	subject: string;
+	description?: string;
+	activeForm?: string;
+	status: TaskStatus;
+	blockedBy?: number[];
+	owner?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Persistence + replay snapshot. Every successful `todo` tool call returns this
+ * shape under `details`; `state/replay.ts` reads the latest one from the branch
+ * to reconstruct module state. Field order and field names are pinned by
+ * cross-version replay compatibility.
+ */
+export interface TaskDetails {
+	action: TaskAction;
+	params: Record<string, unknown>;
+	tasks: Task[];
+	nextId: number;
+	error?: string;
+}
+
+/**
+ * Open-shape input bag the reducer accepts. Stays an interface so the index
+ * signature (`[key: string]: unknown`) lets the runtime pass through TypeBox
+ * `Static<typeof TodoParamsSchema>` without `as` casts.
+ */
+export interface TaskMutationParams {
+	[key: string]: unknown;
+	subject?: string;
+	description?: string;
+	activeForm?: string;
+	status?: TaskStatus;
+	blockedBy?: number[];
+	addBlockedBy?: number[];
+	removeBlockedBy?: number[];
+	owner?: string;
+	metadata?: Record<string, unknown>;
+	id?: number;
+	includeDeleted?: boolean;
+	/** Batch mode: list of sub-operations to apply atomically in order. */
+	items?: BatchItem[];
+	/** Batch create: task subjects for multiple creates in one call. */
+	subjects?: string[];
+	/** Batch update/get/delete: task ids for operating on multiple tasks in one call. */
+	ids?: number[];
+}
+
+// ---------------------------------------------------------------------------
+// TypeBox parameter schema — every `description` doubles as LLM-facing prompt
+// copy. Field order and wording are pinned by registration tests and the
+// pre-refactor schema at `packages/rpiv-todo/todo.ts:512-573`.
+// ---------------------------------------------------------------------------
+
+const BatchItemSchema = Type.Object({
+	action: StringEnum(["create", "update", "delete", "clear"] as const, {
+		description: "create | update | delete | clear",
+	}),
+	subject: Type.Optional(Type.String({ description: "Subject (required for create)" })),
+	description: Type.Optional(Type.String({ description: "Long-form task description" })),
+	activeForm: Type.Optional(Type.String({ description: "In-progress spinner label" })),
+	status: Type.Optional(
+		StringEnum(["pending", "in_progress", "completed", "deleted"] as const, {
+			description: "Target status",
+		}),
+	),
+	blockedBy: Type.Optional(Type.Array(Type.Number(), { description: "blockedBy ids (create only)" })),
+	addBlockedBy: Type.Optional(Type.Array(Type.Number(), { description: "Add to blockedBy" })),
+	removeBlockedBy: Type.Optional(Type.Array(Type.Number(), { description: "Remove from blockedBy" })),
+	owner: Type.Optional(Type.String({ description: "Owner" })),
+	metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata" })),
+	id: Type.Optional(Type.Number({ description: "Task id (required for update/delete)" })),
+	subjects: Type.Optional(Type.Array(Type.String(), { description: "Batch-create subjects" })),
+	ids: Type.Optional(Type.Array(Type.Number(), { description: "Batch task ids" })),
+	as: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Labels for new task ids (e.g. ['$t1'])",
+		}),
+	),
+	refs: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Reference earlier item labels (e.g. ['$t1'])",
+		}),
+	),
+});
+
+export const TodoParamsSchema = Type.Object({
+	action: StringEnum(["create", "update", "list", "get", "delete", "clear", "batch"] as const),
+	subject: Type.Optional(Type.String({ description: "Task subject line (required for create)" })),
+	description: Type.Optional(Type.String({ description: "Long-form task description" })),
+	activeForm: Type.Optional(
+		Type.String({
+			description: "Present-continuous label while in_progress (e.g. 'writing tests')",
+		}),
+	),
+	status: Type.Optional(
+		StringEnum(["pending", "in_progress", "completed", "deleted"] as const, {
+			description: "Target status (update) or list filter (list)",
+		}),
+	),
+	blockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Initial blockedBy ids (create only)",
+		}),
+	),
+	addBlockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Task ids to add to blockedBy (update only, additive merge)",
+		}),
+	),
+	removeBlockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Task ids to remove from blockedBy (update only, additive merge)",
+		}),
+	),
+	owner: Type.Optional(Type.String({ description: "Agent/owner assigned to this task" })),
+	metadata: Type.Optional(
+		Type.Record(Type.String(), Type.Unknown(), {
+			description: "Arbitrary metadata; pass null value for a key to delete that key on update",
+		}),
+	),
+	id: Type.Optional(
+		Type.Number({
+			description: "Task id (required for update, get, delete)",
+		}),
+	),
+	subjects: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Batch-create subjects (multiple creates in one call).",
+		}),
+	),
+	ids: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Batch update/get/delete: task ids for operating on multiple tasks in one call.",
+		}),
+	),
+	includeDeleted: Type.Optional(
+		Type.Boolean({
+			description: "If true, list action returns deleted (tombstoned) tasks as well. Default: false.",
+		}),
+	),
+	items: Type.Optional(
+		Type.Array(BatchItemSchema, {
+			description:
+				"Batch mode only: ordered create/update/delete/clear sub-ops. Use 'as'/'refs' to label and cross-reference new ids.",
+		}),
+	),
+});
+
+export type TodoParams = Static<typeof TodoParamsSchema>;

package/agent/extensions/todo/view/format.ts

@@ -0,0 +1,177 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { formatStatusLabel } from "../state/i18n-bridge.js";
+import { selectTaskSubjectById } from "../state/selectors.js";
+import type { TaskState } from "../state/state.js";
+import type { Task, TaskAction, TaskDetails, TaskMutationParams, TaskStatus } from "../tool/types.js";
+
+// Re-export so legacy import paths (todo.ts, tests) continue to resolve;
+// the canonical definition lives in the i18n bridge.
+export { formatStatusLabel };
+
+// ---------------------------------------------------------------------------
+// Status presentation tables — the single source of truth for glyph/color.
+// ---------------------------------------------------------------------------
+
+export const STATUS_GLYPH: Record<TaskStatus, string> = {
+	pending: "○",
+	in_progress: "◐",
+	completed: "●",
+	deleted: "⊘",
+};
+
+/**
+ * Color palette for the renderResult status echo. `deleted` uses `muted` so a
+ * successful delete is visually distinct from the error branch (which uses
+ * `error` + `✗`). Mirrors pre-refactor `todo.ts:444-450`.
+ */
+export const STATUS_COLOR: Record<TaskStatus, "dim" | "warning" | "success" | "muted"> = {
+	pending: "dim",
+	in_progress: "warning",
+	completed: "success",
+	deleted: "muted",
+};
+
+/**
+ * Per-action prefix glyph for renderCall. `+` create, `→` update, `×` delete,
+ * `›` get, `☰` list, `∅` clear. Pre-refactor `todo.ts:457-464`.
+ */
+export const ACTION_GLYPH: Record<TaskAction, string> = {
+	create: "+",
+	update: "→",
+	delete: "×",
+	get: "›",
+	list: "☰",
+	clear: "∅",
+};
+
+/**
+ * Glyph for the persistent overlay's per-task row. Differs from `STATUS_GLYPH`
+ * for `completed` (`✓` vs `●`) and `deleted` (`✗` vs `⊘`) because the
+ * overlay caller never renders a `deleted` row but uses `✗` in its
+ * error-toned palette. Mirrors pre-refactor `todo-overlay.ts:23-33`.
+ */
+export function overlayStatusGlyph(status: TaskStatus, theme: Theme): string {
+	switch (status) {
+		case "pending":
+			return "○";
+		case "in_progress":
+			return "●";
+		case "completed":
+			return theme.fg("success", "✓");
+		case "deleted":
+			return theme.fg("error", "✗");
+	}
+}
+
+/**
+ * Format a single task for the overlay (with theme + glyph + dep suffix).
+ * Used by `TodoOverlay.formatTaskLine` post-refactor; behavior is unchanged.
+ */
+export function formatOverlayTaskLine(t: Task, theme: Theme, showId: boolean, prefix: string): string {
+	const glyph = overlayStatusGlyph(t.status, theme);
+	const greyPrefix = theme.fg("dim", prefix);
+
+	if (t.status === "completed") {
+		return greyPrefix + glyph + ` ${theme.fg("dim", theme.strikethrough(t.subject))}`;
+	}
+
+	let line = greyPrefix + glyph + ` ${t.subject}`;
+	if (t.status === "in_progress" && t.activeForm) {
+		line += ` (${t.activeForm})`;
+	}
+	if (t.blockedBy && t.blockedBy.length > 0) {
+		line += ` ${theme.fg("dim", `⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}`)}`;
+	}
+	return line;
+}
+
+/**
+ * Format a single task line for the `/todos` slash command (no glyph color,
+ * indented bullet prefix). Pre-refactor `todo.ts:670-674`.
+ */
+export function formatCommandTaskLine(t: Task, glyph: string): string {
+	const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+	const block = t.blockedBy?.length ? `    ⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}` : "";
+	return `  ${glyph} #${t.id} ${t.subject}${form}${block}`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool render hooks — wrapped so `todo.ts` becomes a thin call-site.
+// ---------------------------------------------------------------------------
+
+/**
+ * `renderCall` body. Receives the parsed args, the theme, and the live
+ * `TaskState` (resolved by the caller via `getState()`). Returns a `Text`
+ * node identical to pre-refactor `todo.ts:507-525`.
+ */
+export function renderTodoCall(
+	args: TaskMutationParams & { action: TaskAction },
+	theme: Theme,
+	state: TaskState,
+): Text {
+	const glyph = ACTION_GLYPH[args.action] ?? args.action;
+	let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", glyph);
+
+	if (args.action === "create" && args.subjects?.length) {
+		text += ` ${theme.fg("dim", `+${args.subjects.length} tasks`)}`;
+	} else if (args.action === "create" && args.subject) {
+		text += ` ${theme.fg("dim", args.subject)}`;
+	} else if (
+		(args.action === "update" || args.action === "get" || args.action === "delete") &&
+		args.ids?.length
+	) {
+		const idsStr = args.ids.map((id) => `#${id}`).join(",");
+		text += ` ${theme.fg("accent", idsStr)}`;
+	} else if (
+		(args.action === "update" || args.action === "get" || args.action === "delete") &&
+		args.id !== undefined
+	) {
+		const subject = selectTaskSubjectById(state, args.id);
+		text += ` ${theme.fg("accent", subject ?? `#${args.id}`)}`;
+	} else if (args.action === "list" && args.status) {
+		text += ` ${theme.fg("muted", formatStatusLabel(args.status))}`;
+	}
+	return new Text(text, 0, 0);
+}
+
+/**
+ * `renderResult` body. Inspects `details` to pick the per-action status echo
+ * (only `create`/`update`/`delete` advertise a status; `list`/`get`/`clear`
+ * fall back to plain `✓`). Identical visual output to pre-refactor
+ * `todo.ts:533-565`.
+ */
+export function renderTodoResult(result: { details?: unknown }, theme: Theme): Text {
+	const details = result.details as TaskDetails | undefined;
+	let status: TaskStatus | undefined;
+	if (details) {
+		const params = details.params as TaskMutationParams;
+		switch (details.action) {
+			case "create":
+				status = details.tasks[details.tasks.length - 1]?.status;
+				break;
+			case "update":
+				if (params.ids?.length) {
+					status = params.status ?? details.tasks[details.tasks.length - 1]?.status;
+				} else {
+					status = params.status ?? details.tasks.find((t) => t.id === params.id)?.status;
+				}
+				break;
+			case "delete":
+				if (params.ids?.length) {
+					status = "deleted";
+				} else {
+					status = details.tasks.find((t) => t.id === params.id)?.status;
+				}
+				break;
+			case "list":
+			case "get":
+			case "clear":
+				break;
+		}
+	}
+	if (status) {
+		return new Text(theme.fg(STATUS_COLOR[status], `${STATUS_GLYPH[status]} ${formatStatusLabel(status)}`), 0, 0);
+	}
+	return new Text(theme.fg("success", "✓"), 0, 0);
+}

package/agent/extensions/trim-context/README.md

@@ -0,0 +1,54 @@
+# trim-context — crush/amp/lsp style context manager for pi
+
+Aggressive context savings so pi behaves like `opencode` / `crush` / `amp`.
+
+## What it does
+
+| Layer | Hook | Behavior |
+|---|---|---|
+| **Caching** | `process.env.PI_CACHE_RETENTION=long` + `before_provider_request` | Forces 1h Anthropic / 24h OpenAI cache. Adds `cache_control: {type:"ephemeral", ttl:"1h"}` to system + last user block if pi's built-in misses. |
+| **Output compression** | `tool_result` | Truncates any tool result >30KB or >400 lines to 30KB/400 lines (head 75% + tail 25%). Full output saved to `tmpdir/pi-trim-*/full-output.txt` and path is inlined. |
+| **Trim context** | `context` (before each LLM call) | Keeps last `KEEP_RECENT_TURNS=6` turns verbatim. Older turns: strip `thinking` blocks, compress `toolResult` to 800 chars / 30 lines, bash tail to 20 lines, dedupe superseded `read` results, and if still >80k tokens, hard-prune oldest toolResults. |
+
+This matches crush's `trimContext` and amp's `context pruning` — pi's default keeps 20k recent tokens until 184k/200k, this keeps ~6 turns fully and aggressively compresses the rest.
+
+## Config
+
+Edit `index.ts` `CONFIG` block:
+
+```ts
+KEEP_RECENT_TURNS: 6
+IMMEDIATE_MAX_BYTES: 30*1024
+IMMEDIATE_MAX_LINES: 400
+OLD_MAX_CHARS: 800
+OLD_MAX_LINES: 30
+SOFT_TOKEN_LIMIT: 80_000
+DEDUPE_READS: true
+STRIP_OLD_THINKING: true
+```
+
+`settings.json` also tuned:
+```json
+"compaction": { "keepRecentTokens": 12000, "reserveTokens": 24000 }
+```
+(compacts earlier than pi default 20k/16k)
+
+## Commands
+
+- `/trimContext` — stats + config
+- `/trim-context` — alias
+
+Footer shows `cache:long keep:6t` while active.
+
+## Verify
+
+```bash
+pi --no-session -p "test"   # should not throw
+# in interactive pi:
+# /trimContext  -> shows ~0 compressed initially, grows as you work
+```
+
+## How it saves vs vanilla pi
+
+Vanilla pi: 5x reads of 10KB files = 50KB paid every turn until compaction at 184k.
+With trim-context: same 5 reads = only last read kept fully, older 4 compressed to 1 line each + immediate truncation to 30KB. Typical saving: 60-80% input tokens on long sessions.