@fyeeme/pi-goal 1.0.0

package/test/runtime.test.ts

@@ -0,0 +1,471 @@
+/**
+ * pi-goal — runtime tests.
+ *
+ * Scenarios ported from oh-my-pi `test/goals/goal-runtime.test.ts`
+ * (bun:test → vitest; the harness shape is carried over). Together they pin
+ * the budget-accounting semantics that must never drift: cache writes count,
+ * cache reads do not; wall-clock accounting advances in whole persisted
+ * seconds; budget-limit steering fires once per goal id; interrupts pause;
+ * resume auto-pauses.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	GoalRuntime,
+	type GoalRuntimeHost,
+	goalTokenDelta,
+	renderGoalPrompt,
+	renderTrustedObjective,
+} from "../src/runtime.ts";
+import type { Goal, GoalModeState, GoalRuntimeEvent, GoalTokenUsage } from "../src/state.ts";
+import { escapeXmlText } from "../src/template.ts";
+
+function createUsage(overrides: Partial<GoalTokenUsage> = {}): GoalTokenUsage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		...overrides,
+	};
+}
+
+function createGoal(overrides: Partial<Goal> = {}): Goal {
+	return {
+		id: "goal-1",
+		objective: "Ship <fast> & safely",
+		status: "active",
+		tokenBudget: undefined,
+		tokensUsed: 0,
+		timeUsedSeconds: 0,
+		createdAt: 0,
+		updatedAt: 0,
+		...overrides,
+	};
+}
+
+function cloneGoal(goal: Goal): Goal {
+	return { ...goal };
+}
+
+function cloneState(state: GoalModeState | undefined): GoalModeState | undefined {
+	return state ? { ...state, goal: cloneGoal(state.goal) } : undefined;
+}
+
+function cloneEvent(event: GoalRuntimeEvent): GoalRuntimeEvent {
+	if (event.type === "goal_updated") {
+		return {
+			...event,
+			goal: event.goal ? cloneGoal(event.goal) : null,
+			state: cloneState(event.state),
+		};
+	}
+	return { ...event };
+}
+
+function createHarness(initial: { state?: GoalModeState; usage?: GoalTokenUsage; now?: number } = {}) {
+	let state = cloneState(initial.state);
+	let usage = createUsage(initial.usage);
+	let now = initial.now ?? 0;
+	const events: GoalRuntimeEvent[] = [];
+	const persists: Array<{ mode: "goal" | "goal_paused" | "none"; state?: GoalModeState }> = [];
+	const hiddenMessages: Array<{ customType: string; content: string; deliverAs?: "steer" | "followUp" | "nextTurn" }> =
+		[];
+	const host: GoalRuntimeHost = {
+		getState: () => cloneState(state),
+		setState: (next) => {
+			state = cloneState(next);
+		},
+		getCurrentUsage: () => createUsage(usage),
+		emit: async (event) => {
+			events.push(cloneEvent(event));
+		},
+		persist: (mode, persistedState) => {
+			persists.push({ mode, state: cloneState(persistedState) });
+		},
+		sendHiddenMessage: async (message) => {
+			hiddenMessages.push({ ...message });
+		},
+		now: () => now,
+	};
+	return {
+		runtime: new GoalRuntime(host),
+		getState: () => cloneState(state),
+		setState: (next: GoalModeState | undefined) => {
+			state = cloneState(next);
+		},
+		setUsage: (next: Partial<GoalTokenUsage>) => {
+			usage = createUsage(next);
+		},
+		advance: (ms: number) => {
+			now += ms;
+		},
+		events,
+		persists,
+		hiddenMessages,
+	};
+}
+
+describe("goal runtime", () => {
+	it("counts cache writes but ignores cache reads in token deltas", () => {
+		expect(
+			goalTokenDelta(
+				createUsage({ input: 13, output: 6, cacheRead: 999, cacheWrite: 8 }),
+				createUsage({ input: 10, output: 4, cacheRead: 1, cacheWrite: 5 }),
+			),
+		).toBe(8);
+	});
+
+	it("clamps token deltas at zero across usage resets", () => {
+		expect(
+			goalTokenDelta(
+				createUsage({ input: 10, output: 5, cacheRead: 0, cacheWrite: 2 }),
+				createUsage({ input: 100, output: 50, cacheRead: 500, cacheWrite: 20 }),
+			),
+		).toBe(0);
+	});
+
+	it("advances wall-clock accounting only by persisted whole seconds", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.advance(2_500);
+		harness.setUsage(createUsage({ input: 1 }));
+		await harness.runtime.flushUsage("suppressed");
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(2);
+		expect(harness.runtime.snapshot.wallClock.lastAccountedAt).toBe(2_000);
+		expect(harness.persists).toHaveLength(1);
+
+		harness.advance(400);
+		await harness.runtime.flushUsage("suppressed");
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(2);
+		expect(harness.runtime.snapshot.wallClock.lastAccountedAt).toBe(2_000);
+		expect(harness.persists).toHaveLength(1);
+
+		harness.advance(700);
+		harness.setUsage(createUsage({ input: 2 }));
+		await harness.runtime.flushUsage("suppressed");
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(3);
+		expect(harness.runtime.snapshot.wallClock.lastAccountedAt).toBe(3_000);
+		expect(harness.persists).toHaveLength(2);
+	});
+
+	it("does not persist snapshots on wall-clock-only flushes", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.advance(2_500);
+		// Flush wall-clock time without any token usage changes.
+		await harness.runtime.flushUsage("suppressed");
+		// The in-memory state should still be updated.
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(2);
+		// But it should not write/persist to the session log.
+		expect(harness.persists).toHaveLength(0);
+	});
+
+	it("persists wall-clock-only usage before internal compaction or session-switch aborts", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.advance(2_500);
+		await harness.runtime.onTaskAborted({ reason: "internal" });
+
+		expect(harness.getState()?.enabled).toBe(true);
+		expect(harness.getState()?.goal.status).toBe("active");
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(2);
+		expect(harness.persists).toHaveLength(1);
+		expect(harness.persists[0]).toMatchObject({
+			mode: "goal",
+			state: { goal: { timeUsedSeconds: 2 } },
+		});
+	});
+
+	it("resets wall-clock baseline when preserving an active goal after a no-goal switch", async () => {
+		const goal = createGoal();
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal },
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.setState(undefined);
+		harness.advance(10_000);
+		harness.setState({ enabled: true, mode: "active", goal });
+
+		const resumed = await harness.runtime.onThreadResumed({ preserveActiveGoal: true });
+		harness.advance(1_000);
+		await harness.runtime.flushUsage("suppressed");
+
+		expect(resumed?.goal.status).toBe("active");
+		expect(harness.getState()?.goal.timeUsedSeconds).toBe(1);
+		expect(harness.runtime.snapshot.wallClock.lastAccountedAt).toBe(11_000);
+	});
+
+	it("steers only once until a budget mutation resets the cycle", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ tokenBudget: 10, tokensUsed: 8 }),
+			},
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.setUsage({ input: 2 });
+		await harness.runtime.flushUsage("allowed");
+		expect(harness.getState()?.goal.status).toBe("budget-limited");
+		expect(harness.hiddenMessages).toHaveLength(1);
+		expect(harness.hiddenMessages[0]).toMatchObject({
+			customType: "goal-budget-limit",
+			deliverAs: "steer",
+		});
+
+		harness.setUsage({ input: 5 });
+		await harness.runtime.flushUsage("allowed");
+		expect(harness.hiddenMessages).toHaveLength(1);
+
+		await harness.runtime.onBudgetMutated(20);
+		expect(harness.getState()?.enabled).toBe(true);
+		expect(harness.getState()?.goal.status).toBe("active");
+		expect(harness.getState()?.goal.tokenBudget).toBe(20);
+		expect(harness.hiddenMessages).toHaveLength(1);
+
+		harness.setUsage({ input: 15 });
+		await harness.runtime.flushUsage("allowed");
+		expect(harness.getState()?.goal.status).toBe("budget-limited");
+		expect(harness.hiddenMessages).toHaveLength(2);
+	});
+
+	it("pauses an active goal when an interruption aborts the task", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.advance(1_000);
+		harness.setUsage({ output: 4 });
+		await harness.runtime.onTaskAborted({ reason: "interrupted" });
+
+		const state = harness.getState();
+		expect(state?.enabled).toBe(false);
+		expect(state?.goal.status).toBe("paused");
+		expect(state?.goal.tokensUsed).toBe(4);
+		expect(state?.goal.timeUsedSeconds).toBe(1);
+		expect(harness.persists.at(-1)?.mode).toBe("goal_paused");
+	});
+
+	it("auto-pauses active goals when a thread resumes", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		const resumed = await harness.runtime.onThreadResumed();
+		expect(resumed?.enabled).toBe(false);
+		expect(resumed?.goal.status).toBe("paused");
+		expect(harness.getState()?.enabled).toBe(false);
+		expect(harness.getState()?.goal.status).toBe("paused");
+		expect(harness.persists.at(-1)?.mode).toBe("goal_paused");
+	});
+
+	it("preserves an active goal during internal session-switch reconciliation", async () => {
+		const harness = createHarness({
+			state: { enabled: true, mode: "active", goal: createGoal() },
+		});
+
+		const resumed = await harness.runtime.onThreadResumed({ preserveActiveGoal: true });
+
+		expect(resumed?.enabled).toBe(true);
+		expect(resumed?.goal.status).toBe("active");
+		expect(harness.getState()?.enabled).toBe(true);
+		expect(harness.getState()?.goal.status).toBe("active");
+		expect(harness.persists).toHaveLength(0);
+	});
+
+	it("escapes XML in goal helpers and rendered prompts", () => {
+		const objective = "Fix <root>&keep>safe";
+		const goal = createGoal({ objective });
+		const prompt = renderGoalPrompt("active", goal);
+
+		expect(renderTrustedObjective(objective)).toBe("<objective>\nFix &lt;root&gt;&amp;keep&gt;safe\n</objective>");
+		expect(prompt).toContain("Fix &lt;root&gt;&amp;keep&gt;safe");
+		expect(prompt).not.toContain(objective);
+	});
+
+	it("escapeXmlText escapes the XML-significant characters", () => {
+		expect(escapeXmlText("a & b < c > d")).toBe("a &amp; b &lt; c &gt; d");
+	});
+
+	it("onBudgetMutated downward to below current usage flips active to budget-limited and steers", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ tokenBudget: 100, tokensUsed: 30, status: "active" }),
+			},
+		});
+
+		const next = await harness.runtime.onBudgetMutated(20);
+
+		expect(next?.goal.status).toBe("budget-limited");
+		expect(next?.goal.tokenBudget).toBe(20);
+		expect(next?.goal.tokensUsed).toBe(30);
+		expect(harness.hiddenMessages).toHaveLength(1);
+		expect(harness.hiddenMessages[0]?.customType).toBe("goal-budget-limit");
+	});
+
+	it("completeGoalFromTool clears enabled and flips status to complete with mode exiting", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ tokenBudget: 100, tokensUsed: 42, timeUsedSeconds: 7 }),
+			},
+		});
+
+		const completed = await harness.runtime.completeGoalFromTool();
+
+		expect(completed.status).toBe("complete");
+		const state = harness.getState();
+		expect(state?.enabled).toBe(false);
+		expect(state?.mode).toBe("exiting");
+		expect(state?.reason).toBe("completed");
+		expect(state?.goal.status).toBe("complete");
+	});
+
+	it("recordImpossibleReport bumps the dispute counter and persists", async () => {
+		const harness = createHarness({ state: { enabled: true, mode: "active", goal: createGoal() } });
+
+		const first = await harness.runtime.recordImpossibleReport();
+		expect(first.impossibleReports).toBe(1);
+		const second = await harness.runtime.recordImpossibleReport();
+		expect(second.impossibleReports).toBe(2);
+		expect(harness.getState()?.goal.impossibleReports).toBe(2);
+	});
+
+	it("recordImpossibleReport requires an accounting-active goal", async () => {
+		const harness = createHarness({
+			state: { enabled: false, mode: "active", goal: createGoal({ status: "paused" }) },
+		});
+		await expect(harness.runtime.recordImpossibleReport()).rejects.toThrow(
+			"cannot report impossibility because no active goal exists",
+		);
+	});
+
+	it("pauseGoal carries an explicit reason (impossible outcomes)", async () => {
+		const harness = createHarness({ state: { enabled: true, mode: "active", goal: createGoal() } });
+
+		const paused = await harness.runtime.pauseGoal({ reason: "impossible-confirmed" });
+
+		expect(paused?.enabled).toBe(false);
+		expect(paused?.goal.status).toBe("paused");
+		expect(paused?.reason).toBe("impossible-confirmed");
+		expect(harness.getState()?.reason).toBe("impossible-confirmed");
+	});
+
+	it("dropGoal emits goal_updated with the dropped goal and clears persisted state", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ id: "g-99", objective: "Ship soon" }),
+			},
+		});
+
+		const dropped = await harness.runtime.dropGoal();
+
+		expect(dropped?.status).toBe("dropped");
+		expect(dropped?.id).toBe("g-99");
+		expect(harness.getState()).toBeUndefined();
+		const lastEvent = harness.events.at(-1);
+		if (lastEvent?.type !== "goal_updated") {
+			throw new Error("expected goal_updated event after dropGoal");
+		}
+		expect(lastEvent.goal?.status).toBe("dropped");
+		expect(lastEvent.state?.enabled).toBe(false);
+	});
+
+	it("rejects op=create on the runtime when a non-dropped goal already exists", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ objective: "Existing" }),
+			},
+		});
+
+		await expect(harness.runtime.createGoal({ objective: "Second" })).rejects.toThrow(
+			"cannot create a new goal because this session already has a goal",
+		);
+	});
+
+	it("replaces an active goal with a fresh active goal", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: true,
+				mode: "active",
+				goal: createGoal({ objective: "Existing", tokenBudget: 100 }),
+			},
+		});
+
+		harness.runtime.onTurnStart("turn-1", createUsage());
+		harness.advance(1_000);
+		harness.setUsage({ input: 12 });
+
+		const next = await harness.runtime.replaceGoal({ objective: "Second", tokenBudget: 25 });
+
+		expect(next.enabled).toBe(true);
+		expect(next.goal.objective).toBe("Second");
+		expect(next.goal.status).toBe("active");
+		expect(next.goal.tokenBudget).toBe(25);
+		expect(next.goal.tokensUsed).toBe(0);
+		expect(next.goal.timeUsedSeconds).toBe(0);
+		expect(next.goal.id).not.toBe("goal-1");
+		expect(harness.persists.at(-1)?.state?.goal.objective).toBe("Second");
+	});
+
+	it("allows creating a new goal after the previous one is complete", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: false,
+				mode: "exiting",
+				reason: "completed",
+				goal: createGoal({ status: "complete" }),
+			},
+		});
+
+		const next = await harness.runtime.createGoal({ objective: "Phase 4" });
+		expect(next.goal.objective).toBe("Phase 4");
+		expect(next.goal.status).toBe("active");
+		expect(next.enabled).toBe(true);
+	});
+
+	it("completeGoalFromTool succeeds for a paused goal (enabled=false)", async () => {
+		const harness = createHarness({
+			state: {
+				enabled: false,
+				mode: "active",
+				goal: createGoal({ status: "paused", tokensUsed: 30, timeUsedSeconds: 5 }),
+			},
+		});
+
+		const completed = await harness.runtime.completeGoalFromTool();
+		expect(completed.status).toBe("complete");
+		const state = harness.getState();
+		expect(state?.enabled).toBe(false);
+		expect(state?.mode).toBe("exiting");
+		expect(state?.goal.status).toBe("complete");
+	});
+
+	it("goal ids are unique (randomUUID replaced omp Snowflake)", async () => {
+		const harness = createHarness();
+		const first = await harness.runtime.createGoal({ objective: "One" });
+		harness.setState(undefined);
+		const second = await harness.runtime.createGoal({ objective: "Two" });
+		expect(first.goal.id).not.toBe(second.goal.id);
+	});
+});

package/test/template.test.ts

@@ -0,0 +1,89 @@
+/**
+ * pi-goal — template renderer tests.
+ *
+ * The renderer replaces omp `prompt.render` for the goal prompt templates; it
+ * must support exactly the constructs those templates use and nothing more.
+ */
+
+import { describe, expect, it } from "vitest";
+import { escapeXmlText, renderTemplate } from "../src/template.ts";
+
+describe("renderTemplate", () => {
+	it("interpolates variables", () => {
+		expect(renderTemplate("Hello {{name}}, {{count}}!", { name: "world", count: "3" })).toBe("Hello world, 3!");
+	});
+
+	it("renders unknown variables as empty strings", () => {
+		expect(renderTemplate("a{{missing}}b", {})).toBe("ab");
+	});
+
+	it("supports if with a truthy condition", () => {
+		expect(renderTemplate("A{{#if flag}}yes{{/if}}B", { flag: "x" })).toBe("AyesB");
+	});
+
+	it("supports if with a falsy condition", () => {
+		expect(renderTemplate("A{{#if flag}}yes{{/if}}B", { flag: "" })).toBe("AB");
+		expect(renderTemplate("A{{#if flag}}yes{{/if}}B", {})).toBe("AB");
+	});
+
+	it("supports else branches", () => {
+		const template = "{{#if todoContext}}[{{todoContext}}]{{/if}}";
+		expect(renderTemplate(template, { todoContext: "T" })).toBe("[T]");
+		expect(renderTemplate(template, {})).toBe("");
+	});
+
+	it("renders the goal-mode-context template shape (if with newline body)", () => {
+		const template = "{{goalContext}}\n{{#if todoContext}}\n{{todoContext}}\n{{/if}}";
+		// omp prompt.render emits the same blank line between the two blocks.
+		expect(renderTemplate(template, { goalContext: "G", todoContext: "T" })).toBe("G\n\nT\n");
+		expect(renderTemplate(template, { goalContext: "G" })).toBe("G\n");
+	});
+
+	it("iterates each with item field shadowing", () => {
+		const template = "{{#each phases}}- {{name}}:\n{{#each tasks}}  - [{{status}}] {{content}}\n{{/each}}{{/each}}";
+		const out = renderTemplate(template, {
+			phases: [
+				{
+					name: "P1",
+					tasks: [
+						{ status: "done", content: "a" },
+						{ status: "open", content: "b" },
+					],
+				},
+				{ name: "P2", tasks: [{ status: "open", content: "c" }] },
+			],
+		});
+		expect(out).toBe("- P1:\n  - [done] a\n  - [open] b\n- P2:\n  - [open] c\n");
+	});
+
+	it("renders {{#if initial}}...{{else}}...{{/if}} like the guided-goal template", () => {
+		const template =
+			"{{#if initial}}\n<rough-goal>\n{{initial}}\n</rough-goal>\n{{else}}\nNo objective stated.\n{{/if}}";
+		expect(renderTemplate(template, { initial: "build a birdhouse" })).toBe(
+			"\n<rough-goal>\nbuild a birdhouse\n</rough-goal>\n",
+		);
+		expect(renderTemplate(template, {})).toBe("\nNo objective stated.\n");
+	});
+
+	it("skips each over non-array values", () => {
+		expect(renderTemplate("a{{#each items}}x{{/each}}b", { items: "nope" })).toBe("ab");
+		expect(renderTemplate("a{{#each items}}x{{/each}}b", {})).toBe("ab");
+	});
+
+	it("throws on unclosed blocks and stray closers", () => {
+		expect(() => renderTemplate("{{#if flag}}oops", { flag: 1 })).toThrow();
+		expect(() => renderTemplate("{{/if}}", {})).toThrow();
+	});
+
+	it("caches parses (same template rendered twice)", () => {
+		const template = "{{#if x}}y{{/if}}";
+		expect(renderTemplate(template, { x: 1 })).toBe("y");
+		expect(renderTemplate(template, {})).toBe("");
+	});
+});
+
+describe("escapeXmlText", () => {
+	it("escapes the XML-significant trio and leaves quotes verbatim (omp semantics)", () => {
+		expect(escapeXmlText(`&<>'"`)).toBe("&amp;&lt;&gt;'\"");
+	});
+});