pi-firecode 0.8.0

package/tools/index.ts

@@ -0,0 +1,183 @@
+/**
+ * 接管默认 4 工具（read/bash/edit/write）的展示：单行摘要 + 耗时/大小列 + 连续行轨道。
+ *
+ * 只包装默认激活的工具：原版 pi 的 registerTool 是注册即激活（会话构建与 reload
+ * 固定 includeAllExtensionTools），给 grep/find/ls 挂渲染包装会把它们在所有会话
+ * 强制打开——渲染接管不得改变工具集，因此那三个用宿主默认渲染。
+ */
+import {
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { installGroupPatch, uninstallGroupPatch } from "./grouping.js";
+import { ToolLine, makeResultRenderer } from "./line.js";
+import { commandParts, diffMeta, pathValue } from "./parts.js";
+import { clearDurations, executeTimed } from "./timing.js";
+
+const LABEL = { read: "读取", bash: "操作", edit: "修改", write: "写入" } as const;
+
+type ToolArgs = {
+	path?: string;
+	file_path?: string;
+	offset?: number;
+	limit?: number;
+};
+
+type ToolMap = {
+	read: ReturnType<typeof createReadTool>;
+	bash: ReturnType<typeof createBashTool>;
+	edit: ReturnType<typeof createEditTool>;
+	write: ReturnType<typeof createWriteTool>;
+};
+
+const cache = new Map<string, ToolMap>();
+
+function createTools(cwd: string): ToolMap {
+	return {
+		read: createReadTool(cwd),
+		bash: createBashTool(cwd),
+		edit: createEditTool(cwd),
+		write: createWriteTool(cwd),
+	};
+}
+
+/** 工具实例按 cwd 复用：同一会话内 cwd 不变，切目录也不必重建全部工具。 */
+function tools(cwd: string): ToolMap {
+	let value = cache.get(cwd);
+	if (!value) {
+		value = createTools(cwd);
+		cache.set(cwd, value);
+	}
+	return value;
+}
+
+const argPath = (args: ToolArgs): string => args?.file_path ?? args?.path ?? "";
+
+/** read 的 offset/limit → `:12-40`、`:12+`。 */
+function rangeSuffix(args: ToolArgs): string {
+	if (args.offset === undefined && args.limit === undefined) return "";
+	const start = args.offset ?? 1;
+	if (args.limit === undefined) return `:${start}+`;
+	return `:${start}-${start + args.limit - 1}`;
+}
+
+function lineCount(text: string): number {
+	if (text === "") return 0;
+	const lines = text.split("\n").length;
+	return text.endsWith("\n") ? lines - 1 : lines;
+}
+
+function invoke<T extends (...args: never[]) => unknown>(
+	execute: T,
+	args: unknown[],
+): ReturnType<T> {
+	return Reflect.apply(execute, undefined, args) as ReturnType<T>;
+}
+
+export function registerToolRendering(pi: ExtensionAPI): void {
+	const initial = tools(process.cwd());
+	const decorated = new Set<string>(Object.keys(LABEL));
+
+	pi.on("session_start", async (_event, ctx) => {
+		clearDurations();
+		for (const tool of pi.getAllTools()) {
+			decorated.add(tool.name);
+		}
+		installGroupPatch(ctx.ui, decorated);
+	});
+	pi.on("session_shutdown", async () => {
+		clearDurations();
+		uninstallGroupPatch();
+	});
+
+	pi.registerTool({
+		...initial.read,
+		label: LABEL.read,
+		renderShell: "self",
+		execute: (id, params, signal, update, ctx) =>
+			executeTimed(id, () => invoke(tools(ctx.cwd).read.execute, [id, params, signal, update, ctx])),
+		renderCall: (args, theme, ctx) =>
+			new ToolLine({
+				label: LABEL.read,
+				value: pathValue(argPath(args), ctx.cwd, rangeSuffix(args)),
+				clip: "start",
+				theme,
+				ctx,
+			}),
+		renderResult: makeResultRenderer(true),
+	});
+
+	pi.registerTool({
+		...initial.bash,
+		label: LABEL.bash,
+		renderShell: "self",
+		execute: (id, params, signal, update, ctx) =>
+			executeTimed(id, () => invoke(tools(ctx.cwd).bash.execute, [id, params, signal, update, ctx])),
+		renderCall: (args, theme, ctx) =>
+			new ToolLine({
+				label: LABEL.bash,
+				value: commandParts(args.command),
+				clip: "end",
+				theme,
+				ctx,
+			}),
+		renderResult: makeResultRenderer(true),
+	});
+
+	const editResult = makeResultRenderer(false);
+	pi.registerTool({
+		...initial.edit,
+		label: LABEL.edit,
+		renderShell: "self",
+		execute: (id, params, signal, update, ctx) =>
+			executeTimed(id, () => invoke(tools(ctx.cwd).edit.execute, [id, params, signal, update, ctx])),
+		renderCall: (args, theme, ctx) =>
+			new ToolLine({
+				label: LABEL.edit,
+				value: pathValue(argPath(args), ctx.cwd),
+				clip: "start",
+				theme,
+				ctx,
+			}),
+		renderResult(result, options, theme, ctx) {
+			const details = result.details as { diff?: unknown } | undefined;
+			const diff = !ctx.isError && typeof details?.diff === "string" ? details.diff : undefined;
+			ctx.state.meta = diff ? diffMeta(diff) : undefined;
+			return editResult(result, options, theme, ctx);
+		},
+	});
+
+	pi.registerTool({
+		...initial.write,
+		label: LABEL.write,
+		renderShell: "self",
+		execute: (id, params, signal, update, ctx) =>
+			executeTimed(id, () => invoke(tools(ctx.cwd).write.execute, [id, params, signal, update, ctx])),
+		renderCall: (args, theme, ctx) =>
+			new ToolLine({
+				label: LABEL.write,
+				value: pathValue(argPath(args), ctx.cwd),
+				clip: "start",
+				meta: [{ text: ` +${lineCount(args.content ?? "")}`, color: "toolDiffAdded" }],
+				theme,
+				ctx,
+			}),
+		renderResult: makeResultRenderer(false),
+	});
+
+	pi.registerCommand("tool-status", {
+		description: "显示当前已加载/启用工具",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(
+				`active: ${pi.getActiveTools().join(", ")}\nall: ${pi
+					.getAllTools()
+					.map((tool) => tool.name)
+					.join(", ")}`,
+				"info",
+			);
+		},
+	});
+}

package/tools/line.ts

@@ -0,0 +1,194 @@
+/** 单条工具行的渲染：状态字形 + 标签 + 主体 + 右侧耗时/大小，展开时附完整结果。 */
+import { stripVTControlCharacters } from "node:util";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { type ClipSide, clip, oneLine } from "../format.js";
+import {
+	type Part,
+	clipParts,
+	durationPart,
+	paint,
+	partsWidth,
+	sizePart,
+} from "./parts.js";
+import { takeDuration } from "./timing.js";
+
+export const RAIL = "▏ ";
+/** 右侧列与主体之间至少留出的空隙，不够就先丢弃右侧列 */
+const RIGHT_GAP = 2;
+const MIN_VALUE_WIDTH = 8;
+/** 有错误摘要时，主体最多占可用宽度的比例 */
+const ERROR_VALUE_RATIO = 0.4;
+
+const STATUS = {
+	run: { glyph: "●", color: "accent", bg: "toolPendingBg" },
+	ok: { glyph: "✓", color: "success", bg: "toolSuccessBg" },
+	err: { glyph: "✗", color: "error", bg: "toolErrorBg" },
+} as const;
+
+/** renderCall / renderResult 之间共享的行状态。 */
+export type RowState = {
+	/** 结果字符数（read/bash），驱动右对齐大小列 */
+	chars?: number;
+	durationMs?: number;
+	/** 结果产生的动态后缀（edit 的 ±diff） */
+	meta?: Part[];
+	/** 失败时的一行摘要 */
+	errorText?: string;
+};
+
+export type RenderContext = {
+	state: RowState;
+	cwd: string;
+	toolCallId: string;
+	isPartial: boolean;
+	isError: boolean;
+	expanded: boolean;
+};
+
+type ResultContent = { type: string; text?: string };
+export type ToolResult = { content?: ResultContent[]; details?: unknown };
+
+export type ToolLineOptions = {
+	label: string;
+	value: Part[];
+	/** 溢出时从哪端截断：路径保尾部，命令保头部 */
+	clip: ClipSide;
+	/** 紧跟 value 的左侧后缀（edit ±diff、write +N） */
+	meta?: Part[];
+	theme: Theme;
+	ctx: RenderContext;
+};
+
+function sanitizeDisplayText(text: string): string {
+	let output = "";
+	for (const char of stripVTControlCharacters(text)) {
+		const code = char.codePointAt(0);
+		if (code === undefined || code === 0x0d) continue;
+		if (code === 0x09 || code === 0x0a) output += char;
+		else if (code > 0x1f && (code < 0xfff9 || code > 0xfffb)) output += char;
+	}
+	return output;
+}
+
+function resultText(result: ToolResult): { displayText: string; chars: number } {
+	const blocks: string[] = [];
+	let chars = 0;
+	for (const item of result.content ?? []) {
+		if (item.type !== "text" || typeof item.text !== "string") continue;
+		blocks.push(sanitizeDisplayText(item.text));
+		chars += item.text.length;
+	}
+	return { displayText: blocks.join("\n"), chars };
+}
+
+/** 右侧列之间用 " · " 分隔。 */
+function rightContentWidth(parts: Part[]): number {
+	return partsWidth(parts) + Math.max(0, parts.length - 1) * 3;
+}
+
+const EMPTY_RESULT: Component = { render: () => [], invalidate() {} };
+
+class ExpandedResult implements Component {
+	constructor(
+		private readonly text: string,
+		private readonly theme: Theme,
+	) {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const lines = wrapTextWithAnsi(this.text, Math.max(1, width));
+		return ["", ...lines.map((line) => this.theme.fg("toolOutput", line))];
+	}
+}
+
+export function paintBgLine(line: string, width: number, bgFn?: (text: string) => string): string {
+	const visLen = visibleWidth(line);
+	const padNeeded = Math.max(0, width - visLen);
+	const padded = line + " ".repeat(padNeeded);
+	return bgFn ? bgFn(padded) : padded;
+}
+
+export class ToolLine implements Component {
+	constructor(private readonly options: ToolLineOptions) {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const { theme, ctx } = this.options;
+		const state = ctx.state;
+		const status = ctx.isError ? STATUS.err : ctx.isPartial ? STATUS.run : STATUS.ok;
+		const safeWidth = Math.max(1, width - 2);
+		const head: Part[] = [
+			{ text: RAIL, color: "dim" },
+			{ text: `${status.glyph} `, color: status.color, bold: true },
+			{
+				text: `${this.options.label} `,
+				color: ctx.isError ? "error" : "toolTitle",
+				bold: true,
+			},
+		];
+		const headWidth = partsWidth(head);
+		const bgFn = typeof theme.bg === "function" ? (text: string) => theme.bg(status.bg, text) : undefined;
+		if (safeWidth <= headWidth) {
+			const clipped = paint(theme, clipParts(head, safeWidth, "end"));
+			return [paintBgLine(clipped, width, bgFn)];
+		}
+
+		const meta = [...(this.options.meta ?? []), ...(state.meta ?? [])];
+		const right = [durationPart(state.durationMs), sizePart(state.chars)].filter(
+			(part): part is Part => !!part,
+		);
+		while (
+			right.length &&
+			safeWidth - headWidth - rightContentWidth(right) - RIGHT_GAP < MIN_VALUE_WIDTH
+		)
+			right.pop();
+		const rightVisible = rightContentWidth(right);
+		const freeWidth = safeWidth - headWidth - (right.length ? rightVisible + RIGHT_GAP : 0);
+		const errorText = ctx.isError && !ctx.expanded ? oneLine(state.errorText ?? "") : "";
+		let value = [...this.options.value, ...meta];
+		if (ctx.isError) value = value.map((part) => ({ ...part, color: "error" as const }));
+
+		let errorPart: Part | undefined;
+		if (errorText) {
+			value = clipParts(value, Math.max(1, Math.floor(freeWidth * ERROR_VALUE_RATIO)), this.options.clip);
+			const errorWidth = freeWidth - partsWidth(value) - 3;
+			if (errorWidth >= 1)
+				errorPart = { text: ` · ${clip(errorText, errorWidth, "end")}`, color: "error" };
+		} else {
+			value = clipParts(value, freeWidth, this.options.clip);
+		}
+
+		const body = [...head, ...value, ...(errorPart ? [errorPart] : [])];
+		let line = paint(theme, body);
+		if (right.length) {
+			const pad = Math.max(RIGHT_GAP, safeWidth - partsWidth(body) - rightVisible);
+			line +=
+				" ".repeat(pad) +
+				right.map((part) => paint(theme, [part])).join(theme.fg("dim", " · "));
+		}
+		return [paintBgLine(line, width, bgFn)];
+	}
+}
+
+/** 折叠时只回写行状态；展开时输出完整结果。 */
+export function makeResultRenderer(sized: boolean) {
+	return (
+		result: ToolResult,
+		options: { expanded: boolean },
+		theme: Theme,
+		context: RenderContext,
+	): Component => {
+		const state = context.state;
+		const { displayText, chars } = resultText(result);
+		if (sized) state.chars = chars;
+		const durationMs = takeDuration(context.toolCallId);
+		if (durationMs !== undefined) state.durationMs = durationMs;
+		state.errorText = context.isError ? displayText : "";
+		return options.expanded && displayText !== ""
+			? new ExpandedResult(displayText, theme)
+			: EMPTY_RESULT;
+	};
+}

package/tools/parts.ts

@@ -0,0 +1,143 @@
+/** 工具行的着色片段：路径、命令、大小、耗时、diff 统计。 */
+import { homedir } from "node:os";
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { type ClipSide, clip, formatDuration, oneLine } from "../format.js";
+import { sizeColor } from "../theme.js";
+
+/** pi 公共出口未导出 ThemeBg：从 Theme.bg 的参数派生，避免依赖内部路径。 */
+type ThemeBg = Parameters<Theme["bg"]>[0];
+
+const HOME = homedir();
+const ELLIPSIS = "…";
+/** 结果小于此字符数不显示大小列（噪音阈值） */
+const SIZE_MIN_CHARS = 100;
+/** 快过此耗时不值得占一列 */
+const DURATION_MIN_MS = 1_000;
+
+/** 一段带颜色的文本片段；不给 color 则用终端默认前景色。 */
+export type Part = { text: string; color?: ThemeColor; bg?: ThemeBg; bold?: boolean };
+
+export function partsWidth(parts: Part[]): number {
+	return parts.reduce((total, part) => total + visibleWidth(part.text), 0);
+}
+
+export function paint(theme: Theme, parts: Part[]): string {
+	return parts
+		.map((part) => {
+			let text = part.bold ? theme.bold(part.text) : part.text;
+			if (part.color && typeof theme.fg === "function") text = theme.fg(part.color, text);
+			if (part.bg && typeof theme.bg === "function") text = theme.bg(part.bg, text);
+			return text;
+		})
+		.join("");
+}
+
+/** 按方向截断片段序列：start 保留尾部片段（basename 优先），end 保留头部。 */
+export function clipParts(parts: Part[], width: number, from: ClipSide): Part[] {
+	if (partsWidth(parts) <= width) return parts;
+	const ordered = from === "start" ? [...parts].reverse() : parts;
+	const kept: Part[] = [];
+	let used = 0;
+	for (const part of ordered) {
+		const partWidth = visibleWidth(part.text);
+		if (used + partWidth <= width) {
+			kept.push(part);
+			used += partWidth;
+			continue;
+		}
+		const room = width - used;
+		if (room >= 1) kept.push({ ...part, text: clip(part.text, room, from) });
+		break;
+	}
+	return from === "start" ? kept.reverse() : kept;
+}
+
+/** 路径显示：cwd 内 → ./，家目录 → ~，目录前缀暗色、basename 亮色。 */
+export function pathValue(path: string, cwd: string, suffix = ""): Part[] {
+	let display = path || ELLIPSIS;
+	if (cwd && display.startsWith(`${cwd}/`)) display = `./${display.slice(cwd.length + 1)}`;
+	else if (HOME && display.startsWith(HOME)) display = `~${display.slice(HOME.length)}`;
+	const cut = display.lastIndexOf("/") + 1;
+	const parts: Part[] = [];
+	if (cut > 0) parts.push({ text: display.slice(0, cut), color: "muted" });
+	parts.push({ text: display.slice(cut), color: "accent" });
+	if (suffix) parts.push({ text: suffix, color: "muted" });
+	return parts;
+}
+
+const CONNECTOR = /^(&&|\|\||\||;|↵)$/;
+const REDIRECT = /^\d*(>>?|<)/;
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+function appendPart(parts: Part[], text: string, color?: ThemeColor): void {
+	const last = parts[parts.length - 1];
+	if (last && last.color === color) last.text += text;
+	else parts.push({ text, color });
+}
+
+/** 命令分层着色：命令词 accent，参数默认色，管道/重定向/连接符/环境赋值暗色。 */
+export function commandParts(command: string): Part[] {
+	const display = oneLine((command || "").replace(/\r?\n/g, " ↵ ")).replaceAll(HOME, "~");
+	if (!display) return [{ text: "$ ", color: "muted" }, { text: ELLIPSIS, color: "accent" }];
+	const parts: Part[] = [{ text: "$ ", color: "muted" }];
+	let expectCommand = true;
+	for (const token of display.split(" ")) {
+		let color: ThemeColor | undefined;
+		if (CONNECTOR.test(token)) {
+			color = "muted";
+			expectCommand = true;
+		} else if (REDIRECT.test(token)) {
+			color = "muted";
+		} else if (expectCommand && ENV_ASSIGN.test(token)) {
+			color = "muted";
+		} else if (expectCommand) {
+			color = "accent";
+			expectCommand = false;
+		}
+		if (token.endsWith(";")) expectCommand = true;
+		appendPart(parts, `${token} `, color);
+	}
+	const last = parts[parts.length - 1];
+	last.text = last.text.trimEnd();
+	return parts;
+}
+
+export function sizePart(chars: number | undefined): Part | undefined {
+	if (chars === undefined || chars < SIZE_MIN_CHARS) return undefined;
+	return { text: `${(chars / 1000).toFixed(1)}k`, color: sizeColor(chars) };
+}
+
+export function durationPart(durationMs: number | undefined): Part | undefined {
+	if (durationMs === undefined || durationMs < DURATION_MIN_MS) return undefined;
+	return { text: formatDuration(durationMs), color: "dim" };
+}
+
+export function diffMeta(diff: string): Part[] {
+	let added = 0;
+	let removed = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("+")) added++;
+		else if (line.startsWith("-")) removed++;
+	}
+	const parts: Part[] = [];
+	if (added) parts.push({ text: ` +${added}`, color: "toolDiffAdded" });
+	if (removed) parts.push({ text: ` -${removed}`, color: "toolDiffRemoved" });
+	return parts;
+}
+
+export function genericArgsParts(args: unknown): Part[] {
+	if (!args || typeof args !== "object") {
+		return [{ text: String(args ?? ""), color: "accent" }];
+	}
+	const entries = Object.entries(args as Record<string, unknown>);
+	if (entries.length === 0) return [];
+	const preferredKey = ["prompt", "task", "query", "path", "command", "name", "message", "url"]
+		.find((k) => k in (args as object));
+	const [key, value] = preferredKey
+		? [preferredKey, (args as Record<string, unknown>)[preferredKey]]
+		: entries[0];
+	const valStr = typeof value === "string" ? value : JSON.stringify(value);
+	const text = oneLine(valStr.length > 60 ? `${valStr.slice(0, 57)}…` : valStr);
+	return [{ text: `${key}: `, color: "muted" }, { text, color: "accent" }];
+}

package/tools/timing.ts

@@ -0,0 +1,22 @@
+/** 工具真实执行耗时：execute 侧写入，渲染侧按 toolCallId 取走。 */
+const durations = new Map<string, number>();
+
+export async function executeTimed<T>(id: string, execute: () => Promise<T>): Promise<T> {
+	const startedAt = performance.now();
+	try {
+		return await execute();
+	} finally {
+		durations.set(id, performance.now() - startedAt);
+	}
+}
+
+/** 取一次即释放，避免长会话里堆积。 */
+export function takeDuration(id: string): number | undefined {
+	const duration = durations.get(id);
+	if (duration !== undefined) durations.delete(id);
+	return duration;
+}
+
+export function clearDurations(): void {
+	durations.clear();
+}

package/watcher/card.ts

@@ -0,0 +1,85 @@
+/**
+ * 观察员建议的展示：单通道单一样式，随投递消息一起渲染。
+ * 渲染器永不抛异常；校验失败降级纯文本。
+ */
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+
+import { clip, oneLine } from "../format.js";
+import { RAIL, paintBgLine } from "../tools/line.js";
+
+export const WATCHER_MESSAGE_TYPE = "firecode-watcher-note";
+
+/** 继承 OMP 的 weigh don't blindly obey：投递给模型的正文自带权衡包装。 */
+const WEIGH_NOTICE = "这是观察员供你权衡的第二意见，不是指令：与你掌握的上下文冲突时按你的判断继续。";
+const LABEL = "👓 观察员";
+
+export function adviceMessage(card: WatcherCard): string {
+	return `<firecode_watcher>\n${adviceHeadline(card)}\n${card.note}\n${WEIGH_NOTICE}\n</firecode_watcher>`;
+}
+
+export interface WatcherCard {
+	note: string;
+	turnIndex: number;
+}
+
+export function adviceHeadline(card: WatcherCard): string {
+	return `${LABEL}（${timeMark(card.turnIndex)}）`;
+}
+
+/** 建议自带时点标记：投递时主会话可能已经走远，读的人要知道它看的是哪一刻。 */
+export function timeMark(turnIndex: number): string {
+	return `基于第 ${turnIndex} 回合前的观察`;
+}
+
+export function registerWatcherCardRenderer(pi: ExtensionAPI): void {
+	pi.registerMessageRenderer<WatcherCard>(WATCHER_MESSAGE_TYPE, (message, options, theme) =>
+		isValidCard(message.details)
+			? new AdviceLine(message.details, options.expanded, theme)
+			: new Text(String(message.content), 0, 0));
+}
+
+class AdviceLine implements Component {
+	private readonly fallback: Component;
+
+	constructor(
+		private readonly card: WatcherCard,
+		private readonly expanded: boolean,
+		private readonly theme: Theme,
+	) {
+		this.fallback = new Text(`${adviceHeadline(card)} ${card.note}`, 0, 0);
+	}
+
+	render(width: number): string[] {
+		const columns = Math.max(1, width);
+		try {
+			const bgFn = typeof this.theme.bg === "function"
+				? (text: string) => this.theme.bg("toolPendingBg", text)
+				: undefined;
+			if (this.expanded) {
+				const headline = this.theme.fg("warning", clip(oneLine(adviceHeadline(this.card)), columns));
+				const body = new Text(this.theme.fg("dim", `  ${this.card.note}\n  （供权衡，勿盲从）`), 0, 0);
+				return [paintBgLine(headline, columns, bgFn), ...body.render(columns)];
+			}
+			// 收起与工具行同构：单行 + 背景条；时点标记只在展开态显示。
+			const firstLine = oneLine(this.card.note.split(/\r?\n/u, 1)[0] ?? "");
+			const line = clip(
+				`${this.theme.fg("dim", RAIL)}${this.theme.fg("warning", LABEL)}${this.theme.fg("dim", ` — ${firstLine}`)}`,
+				columns,
+			);
+			return [paintBgLine(line, columns, bgFn)];
+		} catch {
+			return this.fallback.render(columns);
+		}
+	}
+
+	invalidate(): void {
+		this.fallback.invalidate?.();
+	}
+}
+
+function isValidCard(value: unknown): value is WatcherCard {
+	if (!value || typeof value !== "object") return false;
+	const card = value as Record<string, unknown>;
+	return typeof card.note === "string" && typeof card.turnIndex === "number";
+}