@aeondave/pi-persona 1.15.2

package/src/persona/spine.ts

@@ -0,0 +1,221 @@
+/**
+ * The spine — the shared behavioral layer injected between Pi's base prompt and the
+ * persona body (docs/SPINE.md). This module owns SOURCE resolution only: which files, if
+ * any, supply the layer. Composition lives in `persona.ts` (supervisor turns) and in
+ * the engines (delegated legs).
+ *
+ * Two texts, not one: the supervisor gets `spine.md`, a delegated leg gets `spine.worker.md`.
+ * They are different prompts doing different jobs — the supervisor text tells its reader to
+ * confirm irreversible actions with the user, and a leg runs headless (`pi -p --no-session`)
+ * with no user to confirm with, so that rule would make it stall or hand the question back as
+ * its deliverable. Two SELECTORS for the same reason: whether each text helps is a separate
+ * question, and the A/B in docs/SPINE.md needs the arms that turn one on without the other.
+ *
+ * Pure over an injected reader, mirroring `resolveConfig`'s injected env, so the whole
+ * precedence table is unit-testable without touching a disk.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Size ceiling for a spine file. The layer is prepended to EVERY supervisor turn AND every
+ *  delegated leg, so a mistyped path aimed at a log, a binary, or a big JSON would silently
+ *  inflate every request — multiplied by the fanout width. 64 KiB is orders of magnitude past
+ *  any hand-written behavioral layer (the bundled ones are ~2 KiB) and well short of a file
+ *  worth paying for on every turn. Past it we degrade like every other bad input: a warning
+ *  and no spine. */
+export const MAX_SPINE_BYTES = 64 * 1024;
+
+/** The outcome of one read attempt. The three cases are kept apart because they send a user to
+ *  three different places: permissions, content, and the size of the file they pointed at. */
+export type SpineRead = { kind: "ok"; text: string } | { kind: "missing" } | { kind: "oversize"; bytes: number };
+
+/** Reads a file, or reports why it yielded nothing usable. */
+export type SpineReader = (path: string) => SpineRead;
+
+export interface SpineSources {
+	/** `config.spine` — the SUPERVISOR selector: `""` (off), `"on"`, or an explicit path. */
+	selector: string;
+	/** `config.spineLegs` — the same grammar for the delegated legs. A separate selector because
+	 *  the two texts are separable decisions and the A/B in docs/SPINE.md has to isolate them;
+	 *  `config` has already applied the "follows `selector` unless set" default, so by the time
+	 *  it arrives here it is just another selector. */
+	workerSelector: string;
+	/** `<persona data dir>/spine.md` — the user's own copy, which shadows the bundled one. */
+	userPath: string;
+	/** The `prompts/spine.md` shipped with the package. */
+	bundledPath: string;
+	/** `<persona data dir>/spine.worker.md` — the user's own copy of the delegated-leg text. */
+	workerUserPath: string;
+	/** The `prompts/spine.worker.md` shipped with the package. */
+	workerBundledPath: string;
+	/** Read-only upgrade compatibility: skip a user candidate already identified as the exact
+	 * pristine v1.8.0 prompt and fall through to the current bundle. Explicit selectors do not use
+	 * candidate lists, so they remain literal even when they name the same file. */
+	skipUserPath?: boolean;
+	skipWorkerUserPath?: boolean;
+	read: SpineReader;
+}
+
+export interface ResolvedSpine {
+	/** The supervisor layer text, trimmed. Absent ⇒ no spine on supervisor turns. */
+	text?: string;
+	/** Which file supplied it (diagnostics / `/doctor`). */
+	source?: string;
+	/** The delegated-leg layer text, trimmed. Absent ⇒ legs run without one; they are never
+	 *  given the supervisor text as a stand-in (see the module header). */
+	worker?: string;
+	workerSource?: string;
+	/** Degradation notice: a spine was asked for and something did not supply one. The
+	 *  session continues without it — a missing prompt file is never a hard failure. */
+	warning?: string;
+}
+
+/** The bundled supervisor spine that ships with the package. Derived from THIS module's own
+ *  URL, so it resolves identically from a checkout and from an installed `node_modules/pi-persona`
+ *  (where `files: ["prompts", …]` puts `prompts/` next to `src/`). */
+export function bundledSpinePath(moduleUrl: string = import.meta.url): string {
+	return bundledPromptPath("spine.md", moduleUrl);
+}
+
+/** The bundled worker variant — the text a delegated leg gets. */
+export function bundledWorkerSpinePath(moduleUrl: string = import.meta.url): string {
+	return bundledPromptPath("spine.worker.md", moduleUrl);
+}
+
+function bundledPromptPath(file: string, moduleUrl: string): string {
+	return resolve(dirname(fileURLToPath(moduleUrl)), "..", "..", "prompts", file);
+}
+
+/** The two filesystem calls the production reader makes, behind a seam. It exists so the ORDER
+ *  can be witnessed: reading first and measuring the resulting string refuses exactly the same
+ *  files, so the refusal on its own proves nothing about what was loaded to reach it. */
+export interface SpineFs {
+	/** Byte size of the file at `path`; throws if it isn't there or can't be stat'd. */
+	size: (path: string) => number;
+	/** The file's UTF-8 contents. */
+	text: (path: string) => string;
+}
+
+const NODE_FS: SpineFs = { size: (path) => statSync(path).size, text: (path) => readFileSync(path, "utf8") };
+
+/** The production reader: a missing/unreadable file is "no content", and an oversize one is
+ *  refused on its `stat` so its bytes never enter the process at all. `fs` is defaulted — no
+ *  caller passes it — so this stays a plain {@link SpineReader} to everything downstream. */
+export function readSpineFile(path: string, fs: SpineFs = NODE_FS): SpineRead {
+	try {
+		const bytes = fs.size(path);
+		if (bytes > MAX_SPINE_BYTES) return { kind: "oversize", bytes };
+		return { kind: "ok", text: fs.text(path) };
+	} catch {
+		return { kind: "missing" };
+	}
+}
+
+/** One of the two roles the layer is resolved for, reduced to what the resolution actually needs. */
+interface SpineRole {
+	selector: string;
+	/** `on` candidates in precedence order — the user's own copy shadows the bundled default,
+	 *  the precedence every other pi-persona resource follows. */
+	candidates: string[];
+	/** The file name to say out loud when neither candidate is there. */
+	file: string;
+	/** What is lost when this role ends up without a layer — the two roles lose different things. */
+	consequence: string;
+}
+
+interface ResolvedRole {
+	/** The text and the file it came from, together — a role either has both or has neither. */
+	found?: { text: string; source: string };
+	/** Every candidate that WAS there and still could not be used, plus a note when the role is
+	 *  left with nothing at all. Collected rather than thrown: no prompt file is a hard failure. */
+	problems: string[];
+}
+
+/** Resolve which files supply the spine. See the table in docs/SPINE.md. */
+export function resolveSpine(sources: SpineSources): ResolvedSpine {
+	const { selector, workerSelector, userPath, bundledPath, workerUserPath, workerBundledPath, read } = sources;
+	const supervisor = resolveRole(
+		{ selector, candidates: sources.skipUserPath ? [bundledPath] : [userPath, bundledPath], file: "spine.md", consequence: "continuing without one" },
+		read,
+	);
+	// The default wiring points BOTH roles at the same explicit path (the legs follow the
+	// supervisor selector unless set), and that is one decision: resolving it twice would stat and
+	// slurp the file twice and answer one mistyped path with two warnings. `on` is not shared —
+	// there the two roles name different files by design.
+	const legs =
+		workerSelector === selector && selector !== "" && selector !== "on"
+			? supervisor
+			: resolveRole(
+					{
+						selector: workerSelector,
+						candidates: sources.skipWorkerUserPath ? [workerBundledPath] : [workerUserPath, workerBundledPath],
+						file: "spine.worker.md",
+						consequence: "delegated legs continue without one",
+					},
+					read,
+				);
+
+	const out: ResolvedSpine = {};
+	if (supervisor.found) {
+		out.text = supervisor.found.text;
+		out.source = supervisor.found.source;
+	}
+	if (legs.found) {
+		out.worker = legs.found.text;
+		out.workerSource = legs.found.source;
+	}
+	const problems = legs === supervisor ? supervisor.problems : [...supervisor.problems, ...legs.problems];
+	if (problems.length > 0) out.warning = `spine: ${problems.join("; ")}`;
+	return out;
+}
+
+/** Resolve one role's source. Off reads nothing at all, so the disabled path cannot even fail. */
+function resolveRole(role: SpineRole, read: SpineReader): ResolvedRole {
+	const { selector, candidates, file, consequence } = role;
+	if (selector === "") return { problems: [] };
+	if (selector === "on") {
+		const { found, problems } = firstUsable(read, candidates);
+		if (found) return { found, problems };
+		problems.push(`no ${file} found (looked in ${candidates.join(" and ")}) — ${consequence}`);
+		return { problems };
+	}
+	// An explicit path is a deliberate choice: it never falls back to another file, because
+	// silently running a DIFFERENT behavioral layer than the one asked for is worse than none.
+	const explicit = read(selector);
+	const usable = usableText(explicit);
+	if (!usable) return { problems: [`${unusableReason(selector, explicit)} — ${consequence}`] };
+	return { found: { text: usable, source: selector }, problems: [] };
+}
+
+/** The first candidate that yields usable text, plus a note for every candidate that WAS there
+ *  and still could not be used — an empty or oversize file the user meant to be read is worth
+ *  saying out loud, whereas a candidate that simply isn't there is the normal case. */
+function firstUsable(read: SpineReader, candidates: string[]): { found?: { text: string; source: string }; problems: string[] } {
+	const problems: string[] = [];
+	for (const path of candidates) {
+		const attempt = read(path);
+		if (attempt.kind === "missing") continue;
+		const text = usableText(attempt);
+		if (text) return { found: { text, source: path }, problems };
+		problems.push(`${unusableReason(path, attempt)} — skipped`);
+	}
+	return { problems };
+}
+
+/** An empty (or whitespace-only) file has nothing to inject — treat it as absent. */
+function usableText(attempt: SpineRead): string | undefined {
+	if (attempt.kind !== "ok") return undefined;
+	const text = attempt.text.trim();
+	return text ? text : undefined;
+}
+
+/** Why a candidate yielded nothing — stated without a consequence, so each caller can attach
+ *  its own ("continuing without one" for the single explicit file, "skipped" for a candidate
+ *  the search moves past). */
+function unusableReason(path: string, attempt: SpineRead): string {
+	if (attempt.kind === "missing") return `cannot read ${path}`;
+	if (attempt.kind === "oversize") return `${path} is ${attempt.bytes} bytes, over the ${MAX_SPINE_BYTES}-byte limit`;
+	return `${path} is empty`;
+}

package/src/persona/state.ts

@@ -0,0 +1,28 @@
+/**
+ * Persona persistence — remember the last explicitly-selected persona and restore
+ * it on the next start. Mirrors pi-subagents-persona: the state file lives in the
+ * global persona folder (`<agentDir>/persona/state.json`); session-start restore
+ * only READS it, only user gestures (f8 / /persona) write it. Best-effort: any
+ * I/O failure is swallowed (persistence must never break a session).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function readLastPersona(stateFile: string): string | undefined {
+	try {
+		const data = JSON.parse(fs.readFileSync(stateFile, "utf-8")) as { lastPersona?: unknown };
+		return typeof data.lastPersona === "string" && data.lastPersona ? data.lastPersona : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function writeLastPersona(stateFile: string, name: string | undefined): void {
+	try {
+		fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+		fs.writeFileSync(stateFile, `${JSON.stringify({ lastPersona: name ?? null }, null, 2)}\n`);
+	} catch {
+		/* best-effort */
+	}
+}

package/src/telemetry/contract.ts

@@ -0,0 +1,244 @@
+/** Vendor-neutral telemetry wire contract with a common lifecycle vocabulary. */
+export const TELEMETRY_VERSION = 2 as const;
+export const TELEMETRY_EVENT_NAME = "pi:telemetry" as const;
+export const LEGACY_TELEMETRY_EVENT_NAME = "pi-persona:telemetry" as const;
+export const LEGACY_TELEMETRY_VERSION = 1 as const;
+export const TELEMETRY_PRODUCER_ID = "pi-persona" as const;
+export const TELEMETRY_PRODUCER_VERSION = "1.15.2" as const;
+
+export type InstanceStatus = "active" | "idle" | "stopped" | "stale" | (string & {});
+export type AgentKind = "subagent" | "delegate" | "council" | "flow" | "phase" | (string & {});
+export type AgentStatus = "queued" | "running" | "waiting" | "done" | "failed" | "stopped" | (string & {});
+export type MessageChannel = "intercom" | "exocom" | (string & {});
+export type MessageStatus = "queued" | "delivered" | "replied" | "rejected" | "failed" | (string & {});
+
+export interface InstanceDescriptor {
+	displayName: string;
+	status: InstanceStatus;
+	/** Optional producer metadata. The common lifecycle does not require a persona or model. */
+	persona?: string;
+	model?: string;
+	pid?: number;
+	contextPercent?: number;
+	/** pi-persona adapter capability; other producers omit it. */
+	exocomEnabled?: boolean;
+	color?: string;
+}
+
+export interface AgentDescriptor {
+	id: string;
+	label: string;
+	kind: AgentKind;
+	status: AgentStatus;
+	parentId?: string;
+	agent?: string;
+	persona?: string;
+	model?: string;
+}
+
+export interface ToolDescriptor {
+	callId: string;
+	agentId: string;
+	name: string;
+	status: "running" | "done" | "failed" | (string & {});
+	durationMs?: number;
+}
+
+export interface MessageDescriptor {
+	id: string;
+	channel: MessageChannel;
+	from: string;
+	to: string;
+	kind: string;
+	status: MessageStatus;
+	expectsReply: boolean;
+	size: number;
+	replyTo?: string;
+}
+
+export interface PeerDescriptor {
+	sessionId: string;
+	displayName: string;
+	persona: string;
+	model: string;
+	contextPercent: number;
+	status: "online" | "idle";
+	color?: string;
+	sent: number;
+	received: number;
+}
+
+export type KnownTelemetryEventType =
+	| "instance.started" | "instance.updated" | "instance.heartbeat" | "instance.stopped"
+	| "agent.added" | "agent.updated" | "agent.removed" | "agent.cleared"
+	| "tool.started" | "tool.finished"
+	| "message.sent" | "message.received" | "message.replied" | "peers.snapshot";
+/** Namespaced values from other producers are valid v2 events. */
+export type TelemetryEventType = KnownTelemetryEventType | (string & {});
+
+export interface TelemetryPayloadByType {
+	"instance.started": InstanceDescriptor;
+	"instance.updated": Partial<InstanceDescriptor>;
+	"instance.heartbeat": Partial<InstanceDescriptor>;
+	"instance.stopped": { reason: string };
+	"agent.added": AgentDescriptor;
+	"agent.updated": { id: string; patch: Partial<AgentDescriptor> };
+	"agent.removed": { id: string; status?: AgentStatus };
+	"agent.cleared": Record<string, never>;
+	"tool.started": ToolDescriptor;
+	"tool.finished": ToolDescriptor;
+	"message.sent": MessageDescriptor;
+	"message.received": MessageDescriptor;
+	"message.replied": MessageDescriptor;
+	"peers.snapshot": { peers: PeerDescriptor[] };
+}
+
+export type TelemetryPayload<T extends TelemetryEventType> = T extends keyof TelemetryPayloadByType ? TelemetryPayloadByType[T] : Record<string, unknown>;
+
+export interface GenericTelemetryEvent {
+	version: typeof TELEMETRY_VERSION;
+	producerId: string;
+	producerVersion: string;
+	id: string;
+	seq: number;
+	ts: number;
+	sessionId: string;
+	workspaceId: string;
+	type: string;
+	payload: Record<string, unknown>;
+}
+
+export type KnownTelemetryEvent = { [K in KnownTelemetryEventType]: { version: typeof TELEMETRY_VERSION; producerId: string; producerVersion: string; id: string; seq: number; ts: number; sessionId: string; workspaceId: string; type: K; payload: TelemetryPayloadByType[K] } }[KnownTelemetryEventType];
+export type TelemetryEvent<T extends TelemetryEventType = TelemetryEventType> = T extends KnownTelemetryEventType
+	? { version: typeof TELEMETRY_VERSION; producerId: string; producerVersion: string; id: string; seq: number; ts: number; sessionId: string; workspaceId: string; type: T; payload: TelemetryPayload<T> }
+	: GenericTelemetryEvent;
+
+const KNOWN_TYPES = new Set<KnownTelemetryEventType>([
+	"instance.started", "instance.updated", "instance.heartbeat", "instance.stopped",
+	"agent.added", "agent.updated", "agent.removed", "agent.cleared",
+	"tool.started", "tool.finished", "message.sent", "message.received", "message.replied", "peers.snapshot",
+]);
+const SAFE_ID = /^[A-Za-z0-9._:@/-]+$/;
+const TYPE_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+const WORKSPACE_ID = /^[a-f0-9]{24}$/;
+const SENSITIVE_KEY = /(?:task|prompt|args?|command|path|query|url|cwd|output|detail|content|message|secret|token|password|authorization|headers?|api.?key|credential|private.?key)/i;
+
+/** Drop raw prompts, arguments, activity, output and credential-shaped fields at the sink boundary. */
+export function sanitizeTelemetryPayload(value: unknown, depth = 0): unknown {
+	if (depth > 8) return "[depth bounded]";
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) return value;
+	if (Array.isArray(value)) return value.slice(0, 256).map((item) => sanitizeTelemetryPayload(item, depth + 1));
+	if (!value || typeof value !== "object") return undefined;
+	const out: Record<string, unknown> = {};
+	for (const [key, item] of Object.entries(value).slice(0, 256)) {
+		if (SENSITIVE_KEY.test(key) || item === undefined) continue;
+		const safe = sanitizeTelemetryPayload(item, depth + 1);
+		if (safe !== undefined) out[key] = safe;
+	}
+	return out;
+}
+
+const KNOWN_FIELDS: Record<string, readonly string[]> = {
+	"instance.started": ["displayName", "persona", "model", "status", "pid", "contextPercent", "exocomEnabled", "color"],
+	"instance.updated": ["displayName", "persona", "model", "status", "pid", "contextPercent", "exocomEnabled", "color"],
+	"instance.heartbeat": ["displayName", "persona", "model", "status", "pid", "contextPercent", "exocomEnabled", "color"],
+	"instance.stopped": ["reason"], "agent.added": ["id", "label", "kind", "status", "parentId", "agent", "persona", "model"],
+	"agent.updated": ["id", "patch"], "agent.removed": ["id", "status"], "agent.cleared": [],
+	"tool.started": ["callId", "agentId", "name", "status"], "tool.finished": ["callId", "agentId", "name", "status", "durationMs"],
+	"message.sent": ["id", "channel", "from", "to", "kind", "status", "expectsReply", "size", "replyTo"],
+	"message.received": ["id", "channel", "from", "to", "kind", "status", "expectsReply", "size", "replyTo"],
+	"message.replied": ["id", "channel", "from", "to", "kind", "status", "expectsReply", "size", "replyTo"],
+	"peers.snapshot": ["peers"],
+};
+
+/** Producer-side projection is deliberately closed: future producers must publish a reviewed event schema. */
+export function projectTelemetryPayload(type: string, value: unknown): Record<string, unknown> {
+	const safe = sanitizeTelemetryPayload(value);
+	if (!safe || typeof safe !== "object" || Array.isArray(safe)) return {};
+	const fields = KNOWN_FIELDS[type];
+	if (!fields) return {};
+	const projected = Object.fromEntries(fields.filter((field) => field in safe).map((field) => [field, (safe as Record<string, unknown>)[field]]));
+	if (type === "agent.updated" && projected.patch && typeof projected.patch === "object" && !Array.isArray(projected.patch)) {
+		const allowed = ["label", "kind", "status", "parentId", "agent", "persona", "model"];
+		projected.patch = Object.fromEntries(allowed.filter((field) => field in (projected.patch as Record<string, unknown>)).map((field) => [field, (projected.patch as Record<string, unknown>)[field]]));
+	}
+	return projected;
+}
+
+export function isKnownTelemetryEvent(event: TelemetryEvent): event is KnownTelemetryEvent {
+	return KNOWN_TYPES.has(event.type as KnownTelemetryEventType);
+}
+
+function objectPayload(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function stringField(payload: Record<string, unknown>, key: string, required = true): boolean {
+	if (payload[key] === undefined) return !required;
+	return typeof payload[key] === "string" && (required ? (payload[key] as string).length > 0 : true) && (payload[key] as string).length <= 1_024;
+}
+function numberField(payload: Record<string, unknown>, key: string, opts: { integer?: boolean; min?: number; max?: number } = {}): boolean {
+	if (payload[key] === undefined) return true;
+	if (typeof payload[key] !== "number" || !Number.isFinite(payload[key])) return false;
+	if (opts.integer && !Number.isSafeInteger(payload[key])) return false;
+	return (opts.min === undefined || payload[key] >= opts.min) && (opts.max === undefined || payload[key] <= opts.max);
+}
+/** A start event may name its in-flight state with the producer's own word — `terminalTool` in the
+ *  consumer classifies by denylist and the descriptor type is open — but it may not claim to be over. */
+const TERMINAL_TOOL_STATUS = ["done", "failed"];
+function validKnownPayload(type: string, payload: Record<string, unknown>): boolean {
+	if (type === "instance.updated" || type === "instance.heartbeat") return Object.keys(payload).every((key) => ["displayName", "persona", "model", "status", "exocomEnabled", "color", "pid", "contextPercent"].includes(key)) && ["displayName", "status"].every((key) => payload[key] === undefined || stringField(payload, key)) && ["persona", "model", "color"].every((key) => payload[key] === undefined || stringField(payload, key, false)) && (payload.exocomEnabled === undefined || typeof payload.exocomEnabled === "boolean") && numberField(payload, "pid", { integer: true, min: 0 }) && numberField(payload, "contextPercent", { min: 0, max: 100 });
+	if (type === "agent.cleared") return true;
+	if (type === "instance.started") return stringField(payload, "displayName") && stringField(payload, "status") && ["persona", "model", "color"].every((key) => payload[key] === undefined || stringField(payload, key, false)) && numberField(payload, "pid", { integer: true, min: 0 }) && numberField(payload, "contextPercent", { min: 0, max: 100 }) && (payload.exocomEnabled === undefined || typeof payload.exocomEnabled === "boolean");
+	if (type === "instance.stopped") return stringField(payload, "reason");
+	if (type === "agent.added") return stringField(payload, "id") && stringField(payload, "label") && stringField(payload, "kind") && stringField(payload, "status") && ["parentId", "agent", "persona", "model"].every((key) => payload[key] === undefined || stringField(payload, key, false));
+	if (type === "agent.updated") {
+		const patch = objectPayload(payload.patch);
+		return stringField(payload, "id") && patch !== undefined && Object.entries(patch).every(([key, value]) => ["label", "kind", "status", "parentId", "agent", "persona", "model"].includes(key) ? typeof value === "string" : false);
+	}
+	if (type === "agent.removed") return stringField(payload, "id") && (payload.status === undefined || ["done", "failed", "stopped"].includes(payload.status as string));
+	if (type === "tool.started") return stringField(payload, "callId") && stringField(payload, "agentId") && stringField(payload, "name") && stringField(payload, "status") && !TERMINAL_TOOL_STATUS.includes(payload.status as string);
+	if (type === "tool.finished") return stringField(payload, "callId") && stringField(payload, "agentId") && stringField(payload, "name") && ["done", "failed"].includes(payload.status as string) && numberField(payload, "durationMs", { min: 0 });
+	if (type === "message.sent" || type === "message.received" || type === "message.replied") return stringField(payload, "id") && stringField(payload, "channel") && stringField(payload, "from") && stringField(payload, "to") && stringField(payload, "kind") && stringField(payload, "status") && typeof payload.expectsReply === "boolean" && numberField(payload, "size", { integer: true, min: 0 }) && (payload.replyTo === undefined || stringField(payload, "replyTo"));
+	if (type === "peers.snapshot") return Array.isArray(payload.peers) && payload.peers.every((peer) => { const p = objectPayload(peer); return p !== undefined && stringField(p, "sessionId") && stringField(p, "displayName") && stringField(p, "persona", false) && stringField(p, "model", false) && numberField(p, "contextPercent", { min: 0, max: 100 }) && typeof p.status === "string" && numberField(p, "sent", { integer: true, min: 0 }) && numberField(p, "received", { integer: true, min: 0 }); });
+	return true;
+}
+function containsNonFinite(value: unknown): boolean {
+	if (typeof value === "number") return !Number.isFinite(value);
+	if (Array.isArray(value)) return value.some(containsNonFinite);
+	if (value && typeof value === "object") return Object.values(value).some(containsNonFinite);
+	return false;
+}
+
+function validIdentity(value: unknown, max: number): value is string {
+	return typeof value === "string" && value.length > 0 && value.length <= max && SAFE_ID.test(value);
+}
+
+export function parseTelemetryEvent(value: unknown): TelemetryEvent | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const e = value as Record<string, unknown>;
+	const legacy = e.version === LEGACY_TELEMETRY_VERSION;
+	if (!legacy && e.version !== TELEMETRY_VERSION) return undefined;
+	if (!validIdentity(e.id, 256) || !Number.isSafeInteger(e.seq) || (e.seq as number) < 1) return undefined;
+	if (typeof e.ts !== "number" || !Number.isFinite(e.ts) || e.ts < 0) return undefined;
+	if (!validIdentity(e.sessionId, 128) || typeof e.workspaceId !== "string" || !WORKSPACE_ID.test(e.workspaceId)) return undefined;
+	if (typeof e.type !== "string" || e.type.length === 0 || e.type.length > 160 || !TYPE_NAME.test(e.type) || !e.payload || typeof e.payload !== "object" || Array.isArray(e.payload)) return undefined;
+	if (legacy && !KNOWN_TYPES.has(e.type as KnownTelemetryEventType)) return undefined;
+	const producerId = legacy ? TELEMETRY_PRODUCER_ID : e.producerId;
+	const producerVersion = legacy ? "legacy-v1" : e.producerVersion;
+	if (!validIdentity(producerId, 96) || !validIdentity(producerVersion, 64)) return undefined;
+	if (KNOWN_TYPES.has(e.type as KnownTelemetryEventType) && containsNonFinite(e.payload)) return undefined;
+	const payload = KNOWN_TYPES.has(e.type as KnownTelemetryEventType) ? projectTelemetryPayload(e.type, e.payload) : {};
+	if (KNOWN_TYPES.has(e.type as KnownTelemetryEventType) && !validKnownPayload(e.type, payload)) return undefined;
+	return {
+		version: TELEMETRY_VERSION,
+		producerId,
+		producerVersion,
+		id: e.id,
+		seq: e.seq,
+		ts: e.ts,
+		sessionId: e.sessionId,
+		workspaceId: e.workspaceId,
+		type: e.type,
+		payload,
+	} as TelemetryEvent;
+}

package/src/telemetry/paths.ts

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+
+/** Stable workspace scope shared by every telemetry producer, independent of plugin storage. */
+export function telemetryWorkspaceId(cwd: string): string {
+	const resolved = resolve(cwd);
+	const canonical = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	return createHash("sha256").update(canonical).digest("hex").slice(0, 24);
+}
+
+/** Opaque filename component; the original session id remains only inside validated envelopes. */
+export function telemetrySessionFileKey(sessionId: string): string {
+	return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+}