@andares/pi-toolkits 0.9.6 → 0.9.7

package/src/features/ask/scratch-tool.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for the `scratchpad` tool: it must stay inactive until ask mode turns
+ * it on, keep every operation inside the session store, and teach the
+ * "notes, not deliverables" rule through its own declaration.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ASK_SCRATCH_TOOL } from "./constants.js";
+import { createScratchStore, type ScratchStore } from "./scratch.js";
+import { registerScratchTool } from "./scratch-tool.js";
+
+interface ToolDefinition {
+	name: string;
+	defaultActive?: boolean;
+	description: string;
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+	parameters: unknown;
+	execute(
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: undefined,
+		onUpdate: undefined,
+		ctx: unknown,
+	): Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>;
+}
+
+function harness() {
+	let definition: ToolDefinition | undefined;
+	let current: ScratchStore | undefined;
+	const pi = {
+		registerTool(candidate: ToolDefinition) {
+			definition = candidate;
+		},
+	} as unknown as ExtensionAPI;
+	registerScratchTool(pi, () => current);
+	const registered = definition;
+	if (!registered) throw new Error("scratch tool was not registered");
+
+	const call = (params: Record<string, unknown>) =>
+		registered.execute("call-1", params, undefined, undefined, {});
+
+	return {
+		definition: registered,
+		use: (store: ScratchStore | undefined) => {
+			current = store;
+		},
+		call,
+	};
+}
+
+function store(): ScratchStore {
+	return createScratchStore({
+		baseDir: mkdtempSync(join(tmpdir(), "pi-ask-tool-")),
+		sessionId: "session-1",
+	});
+}
+
+describe("scratchpad tool declaration", () => {
+	it("is inactive until ask mode activates it", () => {
+		const h = harness();
+		expect(h.definition.name).toBe(ASK_SCRATCH_TOOL);
+		expect(h.definition.defaultActive).toBe(false);
+	});
+
+	it("carries the mode-scoped guidelines that keep notes out of the deliverable", () => {
+		const h = harness();
+		const guidelines = (h.definition.promptGuidelines ?? []).join("\n");
+		expect(guidelines).toContain("ask mode");
+		expect(guidelines).toContain("not deliverables");
+		expect(h.definition.description).toContain("NOT deliverables");
+		expect(h.definition.description).toContain("absolute paths");
+	});
+});
+
+describe("scratchpad operations", () => {
+	it("writes and reads a note back", async () => {
+		const h = harness();
+		const s = await store();
+		h.use(s);
+
+		const written = await h.call({
+			op: "write",
+			name: "plan.md",
+			content: "1. read\n2. answer\n",
+		});
+		expect(written.isError).toBeUndefined();
+		expect(written.content[0]?.text).toContain("Wrote plan.md");
+		expect(written.content[0]?.text).toContain("2 lines");
+
+		const read = await h.call({ op: "read", name: "plan.md" });
+		expect(read.content[0]?.text).toBe("1. read\n2. answer\n");
+	});
+
+	it("appends and lists", async () => {
+		const h = harness();
+		h.use(await store());
+		await h.call({ op: "write", name: "plan.md", content: "a" });
+		const appended = await h.call({ op: "append", name: "plan.md", content: "b" });
+		expect(appended.content[0]?.text).toContain("Appended to plan.md");
+		const listed = await h.call({ op: "list" });
+		expect(listed.content[0]?.text).toContain("plan.md");
+	});
+
+	it("deletes, and reading afterwards explains the miss", async () => {
+		const h = harness();
+		h.use(await store());
+		await h.call({ op: "write", name: "plan.md", content: "x" });
+		const deleted = await h.call({ op: "delete", name: "plan.md" });
+		expect(deleted.content[0]?.text).toContain("Deleted plan.md");
+
+		const read = await h.call({ op: "read", name: "plan.md" });
+		expect(read.isError).toBe(true);
+		expect(read.content[0]?.text).toContain("no scratch note");
+	});
+});
+
+describe("scratchpad failures", () => {
+	it("rejects an absolute name without touching the disk", async () => {
+		const h = harness();
+		h.use(await store());
+		const result = await h.call({
+			op: "write",
+			name: "/etc/passwd",
+			content: "x",
+		});
+		expect(result.isError).toBe(true);
+		expect(result.content[0]?.text).toContain("not a relative name");
+	});
+
+	it("reports the size cap", async () => {
+		const h = harness();
+		h.use(await store());
+		const result = await h.call({
+			op: "write",
+			name: "big.md",
+			content: "x".repeat(256 * 1024 + 1),
+		});
+		expect(result.isError).toBe(true);
+		expect(result.content[0]?.text).toContain("capped at");
+	});
+
+	it("asks for a name when the op needs one", async () => {
+		const h = harness();
+		h.use(await store());
+		const result = await h.call({ op: "read" });
+		expect(result.isError).toBe(true);
+		expect(result.content[0]?.text).toContain("needs a note name");
+	});
+
+	it("refuses to write when the mode has no scratch space", async () => {
+		const h = harness();
+		h.use(undefined);
+		const result = await h.call({ op: "list" });
+		expect(result.isError).toBe(true);
+		expect(result.content[0]?.text).toContain("not available");
+	});
+});

package/src/features/ask/scratch-tool.ts

@@ -0,0 +1,195 @@
+/**
+ * ask feature — the `scratchpad` tool.
+ *
+ * The tool the model writes planning notes with while ask mode is on. It is
+ * registered once with `defaultActive: false` and activated by `/ask`, so the
+ * tool declaration is part of the request only in that mode — the mode-scoped
+ * surface is the cheapest place to keep the rules: `promptGuidelines` rides in
+ * the system prompt only while the tool is active, and the declaration itself
+ * tells the model that the only writable place is throwaway.
+ *
+ * Deliberately *not* a path-taking tool: `name` is a relative note name and the
+ * store validates it, so the model never juggles absolute paths and the host
+ * never has to parse one. Nothing written here can reach the project.
+ */
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ASK_SCRATCH_TOOL } from "./constants.js";
+import type { ScratchStore } from "./scratch.js";
+import { SCRATCH_MAX_BYTES } from "./scratch.js";
+
+const SCRATCH_PARAMS = Type.Object({
+	op: Type.Union(
+		[
+			Type.Literal("write"),
+			Type.Literal("append"),
+			Type.Literal("read"),
+			Type.Literal("list"),
+			Type.Literal("delete"),
+		],
+		{
+			description:
+				"write replaces a note, append adds to it, read returns it, list shows the notes that exist, delete removes one.",
+		},
+	),
+	name: Type.Optional(
+		Type.String({
+			description:
+				'Relative note name, for example "plan.md" or "notes/api.md". Required for every op except list. Absolute paths are rejected.',
+		}),
+	),
+	content: Type.Optional(
+		Type.String({
+			description: 'Full note text for op "write", the added text for op "append".',
+		}),
+	),
+});
+
+const SCRATCH_DESCRIPTION = `Throwaway scratch notes for this consult session.
+
+Ask mode is read-only for the project, so this is the one place to keep
+intermediate planning output that would clutter the reply: an outline, a
+checklist, a comparison table, draft analysis. Notes live in a temp directory
+that is separate from the repository and cleaned up by the system later.
+
+These notes are NOT deliverables and NOT changes: nothing written here shows up
+in the project, and the operator never asked for it. If the answer requires
+changing a real file, describe the change and tell the operator to exit ask mode
+with /ask instead of writing the change here.
+
+Ops: write (create or replace), append, read, list, delete. Names are relative
+("plan.md", "notes/api.md"); absolute paths are rejected. Each note is capped at
+${Math.floor(SCRATCH_MAX_BYTES / 1024)} KiB.`;
+
+const SCRATCH_GUIDELINES = [
+	"While in ask mode, use `scratchpad` for intermediate notes (outlines, checklists, draft analysis) instead of pasting them into the reply; it writes only to a throwaway temp directory, never to the project.",
+	"Scratch notes are not deliverables: when the answer needs a real file change, describe the change and tell the operator to exit ask mode with /ask.",
+];
+
+/** Bytes as `1.2 KiB` / `320 B`, for tool results. */
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+
+/** Model-facing text of an operation on a note. */
+function describe(
+	op: "write" | "append" | "delete",
+	name: string,
+	bytes: number,
+	lines: number,
+): string {
+	if (op === "delete") return `Deleted ${name} from the scratch directory.`;
+	const size = formatBytes(bytes);
+	if (op === "append") {
+		return `Appended to ${name} (now ${size}). Scratch notes are not part of the project.`;
+	}
+	return `Wrote ${name} (${size}, ${lines} line${lines === 1 ? "" : "s"}). Scratch notes are not part of the project.`;
+}
+
+/** Result details of a `scratchpad` call (shown by renderers, not the model). */
+export interface ScratchDetails {
+	readonly op: string;
+	readonly name?: string;
+	readonly bytes?: number;
+}
+
+/**
+ * Register the tool. `store` is read on every call: ask mode sets it on entry
+ * and clears it on exit, so an unexpected call after exit fails with an
+ * explanation instead of writing anywhere.
+ */
+export function registerScratchTool(
+	pi: ExtensionAPI,
+	store: () => ScratchStore | undefined,
+): void {
+	pi.registerTool<typeof SCRATCH_PARAMS, ScratchDetails>({
+		name: ASK_SCRATCH_TOOL,
+		label: "Scratch note",
+		description: SCRATCH_DESCRIPTION,
+		promptSnippet:
+			"Write throwaway planning notes to a temp scratch directory (ask mode only)",
+		promptGuidelines: SCRATCH_GUIDELINES,
+		parameters: SCRATCH_PARAMS,
+		defaultActive: false,
+		async execute(_toolCallId, params) {
+			const scratch = store();
+			if (!scratch) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "The scratch directory is not available in this session, so nothing can be written. Answer with the information you can gather from reading.",
+						},
+					],
+					details: { op: params.op },
+					isError: true,
+				};
+			}
+
+			const name = params.name?.trim();
+			try {
+				switch (params.op) {
+					case "list": {
+						const files = await scratch.list();
+						const text =
+							files.length === 0
+								? "The scratch directory is empty."
+								: [
+										`Scratch notes (${files.length}):`,
+										...files.map((file) => `- ${file.name} — ${formatBytes(file.bytes)}`),
+									].join("\n");
+						return { content: [{ type: "text" as const, text }], details: { op: params.op } };
+					}
+					case "read": {
+						if (name === undefined) throw new Error('op "read" needs a note name.');
+						const text = await scratch.read(name);
+						return {
+							content: [{ type: "text" as const, text }],
+							details: { op: params.op, name, bytes: Buffer.byteLength(text, "utf8") },
+						};
+					}
+					case "delete": {
+						if (name === undefined) throw new Error('op "delete" needs a note name.');
+						await scratch.remove(name);
+						return {
+							content: [
+								{ type: "text" as const, text: describe("delete", name, 0, 0) },
+							],
+							details: { op: params.op, name },
+						};
+					}
+					case "write":
+					case "append": {
+						if (name === undefined) throw new Error(`op "${params.op}" needs a note name.`);
+						const content = params.content ?? "";
+						const result =
+							params.op === "write"
+								? await scratch.write(name, content)
+								: await scratch.append(name, content);
+						return {
+							content: [
+								{
+									type: "text" as const,
+									text: describe(params.op, result.name, result.bytes, result.lines),
+								},
+							],
+							details: { op: params.op, name, bytes: result.bytes },
+						};
+					}
+					default: {
+						const unknown: never = params.op;
+						throw new Error(`Unknown scratchpad op: ${String(unknown)}`);
+					}
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `scratchpad: ${message}` }],
+					details: { op: params.op, name },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/src/features/ask/scratch.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for the ask scratch store: name validation, containment, size caps,
+ * symlink refusal, listing, and the cleanup/availability contract.
+ */
+import {
+	mkdirSync,
+	mkdtempSync,
+	symlinkSync,
+	utimesSync,
+	writeFileSync,
+} from "node:fs";
+import { readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+	createScratchStore,
+	nameError,
+	SCRATCH_MAX_BYTES,
+	sweepScratchDirs,
+} from "./scratch.js";
+
+function tempBase(): string {
+	return mkdtempSync(join(tmpdir(), "pi-ask-scratch-"));
+}
+
+function store(base: string, sessionId = "session-1") {
+	return createScratchStore({ baseDir: base, sessionId });
+}
+
+describe("nameError", () => {
+	it.each(["plan.md", "notes/api.md", "a", "A_1-2.txt", "topic.v2.json"])(
+		"accepts %s",
+		(name) => {
+			expect(nameError(name)).toBeUndefined();
+		},
+	);
+
+	it.each([
+		[""],
+		["   "],
+		["/etc/passwd"],
+		["../x"],
+		["notes/../../x"],
+		["notes//api.md"],
+		["C:\\x"],
+		["a\\b"],
+		["a/b/c"],
+		[".hidden"],
+		["notes/"],
+		["with space"],
+		["semi;colon"],
+	])("rejects %s", (name) => {
+		expect(nameError(name)).toBeDefined();
+	});
+});
+
+describe("createScratchStore", () => {
+	it("keeps sessions in separate directories under one base", async () => {
+		const base = tempBase();
+		const a = await store(base, "a");
+		const b = await store(base, "b");
+		expect(a.root).not.toBe(b.root);
+		await a.write("plan.md", "one");
+		expect(await b.list()).toEqual([]);
+	});
+
+	it("hashes a session id that is not directory-safe", async () => {
+		const base = tempBase();
+		const s = await store(base, "../../etc");
+		expect(s.root.startsWith(base)).toBe(true);
+		expect(s.root).not.toContain("..");
+	});
+
+	it("writes, reads, appends and reports sizes", async () => {
+		const s = await store(tempBase());
+		const written = await s.write("plan.md", "one\ntwo\n");
+		expect(written.bytes).toBe(8);
+		expect(written.lines).toBe(2);
+		expect(await s.read("plan.md")).toBe("one\ntwo\n");
+
+		await s.append("plan.md", "three");
+		expect(await s.read("plan.md")).toBe("one\ntwo\nthree");
+	});
+
+	it("nests one level", async () => {
+		const s = await store(tempBase());
+		await s.write("notes/api.md", "x");
+		expect(await s.list()).toEqual([{ name: "notes/api.md", bytes: 1 }]);
+	});
+
+	it("lists notes sorted, skipping directories and dotfiles", async () => {
+		const s = await store(tempBase());
+		await s.write("b.md", "22");
+		await s.write("a.md", "1");
+		await s.write("notes/c.md", "333");
+		writeFileSync(join(s.root, ".hidden"), "x");
+		expect((await s.list()).map((file) => file.name)).toEqual([
+			"a.md",
+			"b.md",
+			"notes/c.md",
+		]);
+	});
+
+	it("deletes a note, and deleting a missing note is not an error", async () => {
+		const s = await store(tempBase());
+		await s.write("plan.md", "x");
+		await s.remove("plan.md");
+		expect(await s.list()).toEqual([]);
+		await expect(s.remove("plan.md")).resolves.toBeUndefined();
+	});
+
+	it("explains a missing note instead of throwing an fs error", async () => {
+		const s = await store(tempBase());
+		await expect(s.read("nope.md")).rejects.toThrow(
+			'There is no scratch note named "nope.md"',
+		);
+	});
+
+	it("caps a single note at SCRATCH_MAX_BYTES", async () => {
+		const s = await store(tempBase());
+		const tooBig = "x".repeat(SCRATCH_MAX_BYTES + 1);
+		await expect(s.write("big.md", tooBig)).rejects.toThrow("capped at");
+		await s.write("ok.md", "x".repeat(10));
+		await expect(
+			s.append("ok.md", "x".repeat(SCRATCH_MAX_BYTES)),
+		).rejects.toThrow("capped at");
+	});
+
+	it("refuses to write through a symlink that already sits in the root", async () => {
+		const base = tempBase();
+		const s = await store(base);
+		const outside = mkdtempSync(join(tmpdir(), "pi-ask-outside-"));
+		try {
+			symlinkSync(outside, join(s.root, "link"), "dir");
+		} catch {
+			// Unprivileged Windows cannot create symlinks; nothing to assert there.
+			return;
+		}
+		await expect(s.write("link/x.md", "escape")).rejects.toThrow(
+			"symbolic link",
+		);
+	});
+
+	it("refuses when the base directory is not a directory", async () => {
+		const base = tempBase();
+		const file = join(base, "not-a-dir");
+		writeFileSync(file, "x");
+		expect(() => createScratchStore({ baseDir: file, sessionId: "s" })).toThrow();
+	});
+});
+
+describe("sweepScratchDirs", () => {
+	it("removes directories older than the cap and keeps fresh ones", async () => {
+		const base = tempBase();
+		const oldDir = join(base, "old");
+		const freshDir = join(base, "fresh");
+		mkdirSync(oldDir);
+		mkdirSync(freshDir);
+		const old = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);
+		utimesSync(oldDir, old, old);
+
+		const removed = sweepScratchDirs(base, 7 * 24 * 60 * 60 * 1000);
+
+		expect(removed).toEqual(["old"]);
+		expect(readdirSync(base)).toEqual(["fresh"]);
+	});
+
+	it("is silent when the base does not exist", async () => {
+		expect(sweepScratchDirs(join(tempBase(), "missing"), 1)).toEqual([]);
+	});
+});