@zhushanwen/pi-goal 0.3.0 → 0.4.1

package/src/__tests__/service.test.ts

@@ -0,0 +1,317 @@
+/**
+ * service.ts 测试 — 用 fake ports（内存实现 ports.ts 接口）
+ *
+ * FR-7.2: service 层测试，不 import Pi SDK
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import { applyEvent, createGoal, finalizeGoal, persistAndUpdate, type ServicePorts } from "../service";
+import { createGoalSession } from "../session";
+
+// ── Fake Ports ───────────────────────────────────────
+
+function makeFakePorts(): ServicePorts & {
+	states: GoalRuntimeState[];
+	history: unknown[];
+} {
+	const states: GoalRuntimeState[] = [];
+	const history: unknown[] = [];
+	return {
+		states,
+		history,
+		persistence: {
+			appendState: (s) => {
+				states.push(s);
+			},
+			appendHistory: (e) => {
+				history.push(e);
+			},
+		},
+		ui: {
+			setWidget: () => {},
+			setStatus: () => {},
+			notify: () => {},
+			hasUI: true,
+			// ThemeLike 直接成员（widget 经 asTheme 取出，见 projection/widget.ts）
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		},
+		messaging: {
+			sendContextMessage: () => {},
+			sendUserMessage: () => {},
+		},
+		session: {
+			getEntries: () => [],
+			getContextUsage: () => null,
+			signal: undefined,
+		},
+	};
+}
+
+const makeState = (): GoalRuntimeState => createGoalState("test");
+
+// ── createGoal 测试 ──────────────────────────────────
+
+describe("createGoal — 唯一创建入口", () => {
+	it("成功创建：state 构造 + persist", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		const ok = createGoal(session, "my objective", {}, ports, false);
+		expect(ok).toBe(true);
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("my objective");
+		expect(ports.states.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it("已有 active goal → 拒绝创建（返回 false）", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		createGoal(session, "first", {}, ports, false);
+		const ok = createGoal(session, "second", {}, ports, false);
+		expect(ok).toBe(false);
+		expect(session.state!.objective).toBe("first"); // 保持原 goal
+	});
+
+	it("终态 goal → 允许创建（覆盖）", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		session.state = makeState();
+		session.state.status = "complete"; // 终态
+		const ok = createGoal(session, "new", {}, ports, false);
+		expect(ok).toBe(true);
+		expect(session.state.objective).toBe("new");
+	});
+});
+
+// ── finalizeGoal — history 写入矩阵 ──────────────────
+
+describe("finalizeGoal — history 写入矩阵", () => {
+	it("complete → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "complete", ports, { completedTasks: 1 });
+		expect(ports.history.length).toBe(1);
+		expect((ports.history[0] as { status: string }).status).toBe("complete");
+		expect(state.completedAtTurnIndex).toBe(state.currentTurnIndex);
+	});
+
+	it("cancelled → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "cancelled", ports, { completedTasks: 0 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("budget_limited → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "budget_limited", ports, { completedTasks: 2 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("time_limited → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "time_limited", ports, { completedTasks: 0 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("终态 goal 再 finalize → throw（查表非法转换）", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		state.status = "complete";
+		// transitionStatus 查表：终态不可转，调用方须先 isTerminalStatus 守卫
+		expect(() => finalizeGoal(state, "cancelled", ports, { completedTasks: 0 })).toThrow();
+		expect(state.status).toBe("complete");
+	});
+});
+
+// ── applyEvent — 简单事件（路径 B）────────────────────
+
+describe("applyEvent — 简单事件", () => {
+	it("message_end 累加 assistant token（FR-8.6）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: {
+				role: "assistant",
+				usage: { input: 100, output: 50, cacheRead: 20 },
+			},
+		}, makeFakePorts());
+		// accumulateTokens: max(100 - 20, 0) + 50 = 130
+		expect(session.state.tokensUsed).toBe(before + 130);
+	});
+
+	it("message_end 忽略非 assistant 消息", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: { role: "user", usage: { input: 100, output: 50 } },
+		}, makeFakePorts());
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("message_end 缺 usage → 不变", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", { message: { role: "assistant" } }, makeFakePorts());
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("回归#1: message_end 非 active（blocked）→ 不累加 token（FR-8.6 G-R2-001）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		session.state.status = "blocked"; // 非 active
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: {
+				role: "assistant",
+				usage: { input: 100, output: 50, cacheRead: 20 },
+			},
+		}, makeFakePorts());
+		// 回归修复：blocked 状态不累加 token（原 bug：缺 isActiveStatus 守卫）
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("turn_end → currentTurnIndex++ + updateWidget effect", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.currentTurnIndex;
+		const effects = applyEvent(session, "turn_end", {}, makeFakePorts());
+		expect(session.state.currentTurnIndex).toBe(before + 1);
+		expect(effects).toContainEqual({ kind: "updateWidget" });
+	});
+
+	it("agent_start → 无副作用（task 已移除）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const effects = applyEvent(session, "agent_start", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+
+	it("session.state=null → 返回空 effects", () => {
+		const session = createGoalSession();
+		const effects = applyEvent(session, "turn_end", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+
+	it("未知事件 → 返回空 effects（不报错）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const effects = applyEvent(session, "unknown_event", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+});
+
+// ── persistAndUpdate — #5 budget 终态检查（事件路径单一检查点，NFR F2）──
+
+describe("persistAndUpdate — #5 budget 终态检查（事件路径单一检查点）", () => {
+	it("active + token 超额（steering 已发）→ status 转 budget_limited + 写 history", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0, // 关闭时间累计，保证 tick 不额外累加
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000, // >= tokenBudget
+			budgetLimitSteeringSent: true, // token terminal 要求 steering 已发
+		};
+		const ports = makeFakePorts();
+		const stale = persistAndUpdate(session, ports);
+
+		expect(stale).toBe(false);
+		expect(session.state!.status).toBe("budget_limited");
+		expect(ports.history.length).toBe(1); // FR-8.7: 终态写 history
+		expect((ports.history[0] as { status: string }).status).toBe("budget_limited");
+	});
+
+	it("token 终态分支不重复 appendState（finalizeAndPersist 已含持久化）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000,
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+		// 仅 finalizeAndPersist 内部 1 次 appendState，不再走正常 appendState
+		expect(ports.states.length).toBe(1);
+	});
+
+	it("active + time 超额 → status 转 time_limited + 写 history", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { timeBudgetMinutes: 10 },
+			timeUsedSeconds: 600, // >= 10*60
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("time_limited");
+		expect(ports.history.length).toBe(1);
+		expect((ports.history[0] as { status: string }).status).toBe("time_limited");
+	});
+
+	it("非 active（blocked）→ 不触发 budget 检查，保持 blocked", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "blocked",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000, // 已超额，但 blocked 不检查
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("blocked"); // 未变
+		expect(ports.history.length).toBe(0); // blocked 不写 history
+		expect(ports.states.length).toBe(1); // 走正常 appendState 路径
+	});
+
+	it("active 但未超额 → 正常 persist（无终态、无 history）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 100, // 未超额
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("active"); // 未变
+		expect(ports.history.length).toBe(0);
+		expect(ports.states.length).toBe(1); // 正常 appendState
+	});
+
+	it("终态处理后 checkStale 触发 → 返回 true（status 已转终态）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000,
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		const stale = persistAndUpdate(session, ports, () => true);
+		expect(stale).toBe(true);
+		// finalizeAndPersist 已执行，status 已转终态
+		expect(session.state!.status).toBe("budget_limited");
+	});
+});

package/src/__tests__/session.test.ts

@@ -0,0 +1,220 @@
+/**
+ * session.ts 测试 — reconstructGoalState + isStaleContextError
+ *
+ * 覆盖：
+ * - MF-7: reconstructGoalState 3 条 FR（G-006 entry GC / G-015 强制激活 / G-024 throw→null）
+ * - MF-8: isStaleContextError 5 pattern 匹配（G-010）
+ *
+ * 用 fake SessionPort（内存 entries 数组）。
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import {
+	ENTRY_TYPE,
+	HISTORY_ENTRY_TYPE,
+	makeHistoryEntry,
+	serializeState,
+} from "../persistence";
+import type { SessionEntryLike, SessionPort } from "../ports";
+import {
+	createGoalSession,
+	isStaleContextError,
+	reconstructGoalState,
+	STALE_CONTEXT_PATTERNS,
+} from "../session";
+
+// ── Fake SessionPort ─────────────────────────────────
+
+function makeFakeSessionPort(entries: SessionEntryLike[]): SessionPort {
+	return {
+		// 模拟 Pi SDK filter-copy 语义：返回新数组，避免测试掩盖 splice GC 失效
+		getEntries: () => entries.slice(),
+		getContextUsage: () => null,
+		signal: undefined,
+	};
+}
+
+function makeGoalStateEntry(state: GoalRuntimeState): SessionEntryLike {
+	return { type: "custom", customType: ENTRY_TYPE, data: serializeState(state) };
+}
+
+function makeHistoryEntryWrapper(entry: unknown): SessionEntryLike {
+	return { type: "custom", customType: HISTORY_ENTRY_TYPE, data: entry };
+}
+
+// ── isStaleContextError（MF-8, FR-8.2 G-010）──────────
+
+describe("isStaleContextError (FR-8.2 G-010)", () => {
+	it("5 个 STALE_CONTEXT_PATTERNS 各匹配", () => {
+		for (const pattern of STALE_CONTEXT_PATTERNS) {
+			const err = new Error(`something ${pattern} happened`);
+			expect(isStaleContextError(err)).toBe(true);
+		}
+	});
+
+	it("大小写混合匹配", () => {
+		expect(isStaleContextError(new Error("Context CANCELED"))).toBe(true);
+		expect(isStaleContextError(new Error("ABORTED by user"))).toBe(true);
+	});
+
+	it("非 stale 错误 → false", () => {
+		expect(isStaleContextError(new Error("network timeout"))).toBe(false);
+		expect(isStaleContextError(new Error("permission denied"))).toBe(false);
+	});
+
+	it("字符串输入（非 Error）", () => {
+		expect(isStaleContextError("the context was aborted")).toBe(true);
+		expect(isStaleContextError("random error string")).toBe(false);
+	});
+
+	it("null/undefined 输入 → false（不抛错）", () => {
+		expect(isStaleContextError(null)).toBe(false);
+		expect(isStaleContextError(undefined)).toBe(false);
+	});
+});
+
+// ── reconstructGoalState（MF-7）──────────────────────
+
+describe("reconstructGoalState", () => {
+	it("无 goal-state entry → state=null", () => {
+		const session = createGoalSession();
+		const port = makeFakeSessionPort([]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("有 goal-state entry → 恢复 state", () => {
+		const session = createGoalSession();
+		const state = createGoalState("my objective");
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("my objective");
+	});
+
+	it("G-006: 多个 goal-state entry → 恢复最新（append-only，不 splice）", () => {
+		const session = createGoalSession();
+		const oldState = createGoalState("old");
+		const newState = createGoalState("new");
+		const entries: SessionEntryLike[] = [
+			makeGoalStateEntry(oldState),
+			makeGoalStateEntry(newState), // 最新（在后面）
+		];
+		const port = makeFakeSessionPort(entries);
+		reconstructGoalState(session, port);
+		// 恢复的是最新的
+		expect(session.state!.objective).toBe("new");
+		// append-only：旧 entry 不被删除（splice GC 在生产不生效）
+		const remaining = entries.filter((e) => e.customType === ENTRY_TYPE);
+		expect(remaining).toHaveLength(2);
+	});
+
+	it("G-006: goal-history 超出 20 条仍正确恢复 state（append-only，不 splice）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("active goal");
+		// 插入 25 个 history entry + 1 个 goal-state
+		const entries: SessionEntryLike[] = [];
+		for (let i = 0; i < 25; i++) {
+			entries.push(makeHistoryEntryWrapper({ goalId: `g-${i}`, timestamp: i }));
+		}
+		entries.push(makeGoalStateEntry(state));
+		const port = makeFakeSessionPort(entries);
+		reconstructGoalState(session, port);
+		// append-only：history 不被删除（显示侧截断，splice GC 在生产不生效）
+		const historyRemaining = entries.filter((e) => e.customType === HISTORY_ENTRY_TYPE);
+		expect(historyRemaining).toHaveLength(25);
+		// state 仍正确恢复
+		expect(session.state!.objective).toBe("active goal");
+	});
+
+	it("FR-3: blocked 非终态 → 保持 blocked（崩溃不抹除 agent 叫停状态）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("blocked goal");
+		state.status = "blocked";
+		state.timeStartedAt = 1000; // 旧值
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		// blocked 保持 blocked（不强制 active）
+		expect(session.state!.status).toBe("blocked");
+		// timeStartedAt 不重置（非 active 不重启计时）
+		expect(session.state!.timeStartedAt).toBe(1000);
+	});
+
+	it("FR-3: paused 非终态 → 保持 paused（崩溃不抹除用户叫停状态）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("paused goal");
+		state.status = "paused";
+		state.timeStartedAt = 2000;
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state!.status).toBe("paused");
+		expect(session.state!.timeStartedAt).toBe(2000);
+	});
+
+	it("FR-3: active → 保持 active + 重启计时（timeStartedAt = now）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("active goal");
+		state.timeStartedAt = 1000; // 旧值
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		const before = Date.now();
+		reconstructGoalState(session, port);
+		const after = Date.now();
+		expect(session.state!.status).toBe("active");
+		expect(session.state!.timeStartedAt).toBeGreaterThanOrEqual(before);
+		expect(session.state!.timeStartedAt).toBeLessThanOrEqual(after);
+	});
+
+	it("G-015: 终态保持终态（不强制激活）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("completed goal");
+		state.status = "complete";
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state!.status).toBe("complete");
+	});
+
+	it("G-024: deserialize throw（损坏 data）→ state=null", () => {
+		const session = createGoalSession();
+		// 缺少必填字段 → deserializeState throw
+		const brokenEntry: SessionEntryLike = {
+			type: "custom",
+			customType: ENTRY_TYPE,
+			data: { goalId: "x" }, // 缺大量必填字段
+		};
+		const port = makeFakeSessionPort([brokenEntry]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("data=undefined 的 entry → 跳过（state=null）", () => {
+		const session = createGoalSession();
+		const entry: SessionEntryLike = {
+			type: "custom",
+			customType: ENTRY_TYPE,
+			data: undefined,
+		};
+		const port = makeFakeSessionPort([entry]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("makeHistoryEntry + serializeState 往返一致性", () => {
+		// 验证辅助函数本身正确（makeHistoryEntry 用于 history entry 构造）
+		const state = createGoalState("roundtrip");
+		state.status = "complete";
+		const hist = makeHistoryEntry(state, 5);
+		expect(hist.goalId).toBe(state.goalId);
+		expect(hist.objective).toBe("roundtrip");
+		expect(hist.status).toBe("complete");
+		expect(hist.completedTasks).toBe(5);
+		expect(typeof hist.elapsedSeconds).toBe("number");
+		expect(typeof hist.timestamp).toBe("number");
+		// serializeState 返回深拷贝（修改返回值不影响原 state）
+		const serialized = serializeState(state);
+		expect(serialized.objective).toBe("roundtrip");
+		serialized.status = "cancelled";
+		expect(state.status).toBe("complete"); // 原状态未被修改
+	});
+});

package/src/__tests__/stale-checker.test.ts

@@ -0,0 +1,78 @@
+/**
+ * event-adapter 并发保护辅助函数测试（TC-3）
+ *
+ * 直接测试 makeStaleChecker / acquireProcessing / releaseProcessing 的快照语义，
+ * 非间接覆盖。重点：makeStaleChecker 在 state=null 时 snapshot=undefined，
+ * 后续任何新 goal 均视为 stale。
+ */
+import { describe, expect, it } from "vitest";
+
+import { acquireProcessing, makeStaleChecker, releaseProcessing } from "../adapters/event-handlers/shared";
+import { createGoalState } from "../engine/goal";
+import { createGoalSession } from "../session";
+
+describe("makeStaleChecker", () => {
+	it("snapshot 时 state=null → 后续新 goal 视为 stale", () => {
+		const session = createGoalSession();
+		// state 为 null 时 snapshot goalId = undefined
+		const checkStale = makeStaleChecker(session);
+		// 后续出现新 goal（goalId 有值）
+		session.state = createGoalState("new goal");
+		expect(checkStale()).toBe(true); // undefined !== "goal-xxx" → stale
+	});
+
+	it("snapshot 时有 goal → 同 goalId 返回 false（未 stale）", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("current");
+		const snapshotId = session.state.goalId;
+		const checkStale = makeStaleChecker(session);
+		// 后续 mutate 但 goalId 不变
+		session.state.currentTurnIndex = 99;
+		expect(checkStale()).toBe(false);
+		expect(session.state.goalId).toBe(snapshotId); // 确认 goalId 未变
+	});
+
+	it("snapshot 时有 goal → goalId 变更后视为 stale（被新 goal 覆盖）", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("old goal");
+		const checkStale = makeStaleChecker(session);
+		expect(checkStale()).toBe(false); // 初始未 stale
+		// 模拟新 goal 覆盖（createGoalState 生成新 goalId）
+		session.state = createGoalState("new goal overwrote");
+		expect(checkStale()).toBe(true); // goalId 变了 → stale
+	});
+
+	it("state 被清空（null）后 → 视为 stale", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("then cleared");
+		const checkStale = makeStaleChecker(session);
+		expect(checkStale()).toBe(false);
+		session.state = null; // clearGoalSession 清空
+		expect(checkStale()).toBe(true);
+	});
+});
+
+describe("acquireProcessing / releaseProcessing", () => {
+	it("首次 acquire → true 并设置 isProcessing", () => {
+		const session = createGoalSession();
+		expect(session.isProcessing).toBe(false);
+		expect(acquireProcessing(session)).toBe(true);
+		expect(session.isProcessing).toBe(true);
+	});
+
+	it("已占用时再 acquire → false（防重入）", () => {
+		const session = createGoalSession();
+		expect(acquireProcessing(session)).toBe(true); // 首次成功
+		expect(acquireProcessing(session)).toBe(false); // 重入拒绝
+		expect(acquireProcessing(session)).toBe(false); // 再入仍拒绝
+	});
+
+	it("release 后可再次 acquire", () => {
+		const session = createGoalSession();
+		acquireProcessing(session);
+		expect(session.isProcessing).toBe(true);
+		releaseProcessing(session);
+		expect(session.isProcessing).toBe(false);
+		expect(acquireProcessing(session)).toBe(true); // 释放后可重新获取
+	});
+});

package/src/__tests__/stubs/pi-sdk.ts

@@ -7,5 +7,10 @@ export function StringEnum<T extends readonly string[]>(values: T, _options?: Re
 	return values[0] as T[number];
 }
 
+// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）
+export class Text {
+	constructor(_content: unknown, _x: number, _y: number) {}
+}
+
 // Pi SDK types used in import chains — re-export as empty
 export {};