@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/provenance-refs.ts

@@ -0,0 +1,158 @@
+/**
+ * The provenance-ref guard (item a03ba7ab).
+ *
+ * Opaque 36-character UUIDs cross the model boundary by transcription, and
+ * transcription corrupts them — watched live on 2026-09-20 (session 340ca456):
+ * the server delivered `5733cc70-9ca8-4bb5-8261-…` and the model's writes came
+ * back carrying `5733cc70-9ca8-4f6d-9f10-…` — same 64-bit prefix, fabricated
+ * tail. The server refused correctly; the failure was invisible until it did.
+ *
+ * This module holds the one set the extension can know with certainty: the refs
+ * this process has actually been DEALT (delivery refs from validated ingress
+ * commands, work-claim refs observed in claim results). The guard refuses a
+ * write whose ref was never dealt here — locally, before the network, naming
+ * the current turn's refs and teaching omission, which is the safe default:
+ * the server works out who asked from the connection (its work on the item the
+ * write is about, its newest command, its only claim — DevSpec migrations 1161,
+ * 1216), and refuses rather than guesses when that is ambiguous.
+ *
+ * Deliberate scope: the rule is NEVER-DEALT, never "not currently valid".
+ * Whether a dealt ref is still inside the live turn is the server's call
+ * (651's live-turn check) — this guard does not duplicate it. A dealt-but-old
+ * ref passes here and the server decides; a fabricated one dies at the door.
+ *
+ * Never rewrite a ref: attribution is the point of the system.
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+interface DealtRef {
+	turnId: string | null;
+	seq: number;
+}
+
+interface RefStore {
+	delivery: Map<string, DealtRef>;
+	claim: Set<string>;
+	seq: number;
+}
+
+// jiti duplicates modules; Symbol.for(globalThis) keeps one store per process
+// (the established pattern from active-deliveries.ts).
+const STORE_KEY = Symbol.for("devspec.pi.provenance-refs.v1");
+const CAP = 512;
+
+function store(): RefStore {
+	const root = globalThis as typeof globalThis & { [STORE_KEY]?: RefStore };
+	if (!root[STORE_KEY]) root[STORE_KEY] = { delivery: new Map(), claim: new Set(), seq: 0 };
+	return root[STORE_KEY];
+}
+
+function cap(map: Map<string, DealtRef>): void {
+	while (map.size > CAP) {
+		const oldest = map.keys().next();
+		if (oldest.done) break;
+		map.delete(oldest.value);
+	}
+}
+
+function noteDeliveryRef(ref: unknown, turnId: string | null): void {
+	if (typeof ref !== "string" || !UUID.test(ref)) return;
+	const key = ref.trim().toLowerCase();
+	const s = store();
+	s.delivery.set(key, { turnId, seq: ++s.seq });
+	cap(store().delivery);
+}
+
+/** The parsed, intake-validated commands of an accepted delivery. Idempotent. */
+export function noteDeliveredCommandRefs(
+	commands: readonly { delivery?: { provenance_ref?: unknown; primary_provenance_ref?: unknown; turn_id?: unknown } }[],
+): void {
+	for (const command of commands) {
+		const delivery = command.delivery;
+		if (!delivery) continue;
+		const turnId = typeof delivery.turn_id === "string" ? delivery.turn_id : null;
+		noteDeliveryRef(delivery.provenance_ref, turnId);
+		noteDeliveryRef(delivery.primary_provenance_ref, turnId);
+	}
+}
+
+/** work_claim_ref values observed in successful claim results this process. */
+export function noteObservedClaimRef(value: unknown): void {
+	if (typeof value !== "string" || !UUID.test(value)) return;
+	const claims = store().claim;
+	claims.add(value.trim().toLowerCase());
+	while (claims.size > CAP) {
+		const oldest = claims.values().next();
+		if (oldest.done) break;
+		claims.delete(oldest.value);
+	}
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+/** Claim refs ride claim results (details.work_claim_ref or top level). */
+export function observeResultClaimRefs(result: unknown): void {
+	const root = record(result);
+	if (!root) return;
+	const details = record(root.details) ?? root;
+	noteObservedClaimRef(details.work_claim_ref);
+}
+
+/** Bond/connection resets clear the dealt set with the turn bindings (6f4136d8's lifecycle). */
+export function clearDealtRefs(): void {
+	store().delivery.clear();
+	store().claim.clear();
+}
+
+export type RefGuardVerdict = { ok: true } | { ok: false; message: string };
+
+function currentTurnRefs(): string[] {
+	const entries = [...store().delivery.entries()];
+	if (entries.length === 0) return [];
+	const latest = entries.reduce((a, b) => (b[1].seq > a[1].seq ? b : a));
+	const turn = latest[1].turnId;
+	const refs = entries.filter(([, v]) => v.turnId === turn).map(([k]) => k);
+	return refs.length > 0 ? refs : [latest[0]];
+}
+
+function refuse(kind: "provenance_ref" | "work_claim_ref", value: string): RefGuardVerdict {
+	if (kind === "provenance_ref") {
+		const known = currentTurnRefs();
+		const hint = known.length > 0
+			? `This session's current command refs are: ${known.join(", ")}. Unless you mean one of those exactly, omit the parameter: by default the server works out who asked from your connection.`
+			: "No command has been delivered to this process, so that value did not come from a delivery here. Omit the parameter: by default the server works out who asked from your connection.";
+		return {
+			ok: false,
+			message: `Unknown provenance_ref "${value}" — never delivered to this process (a mistyped ref fails closed; the server would reject it too). ${hint}`,
+		};
+	}
+	return {
+		ok: false,
+		message: `Unknown work_claim_ref "${value}" — no claim result this process has seen carries it. Copy the work_claim_ref from the claim_work_item result verbatim, or omit it and let the server work out who asked from your connection.`,
+	};
+}
+
+/**
+ * Check the model-supplied provenance refs on a tool call before it costs a
+ * server round-trip. Omission is always allowed — it is the default. Only a
+ * present, non-empty value is checked, and only against what this process has
+ * verifiably been dealt.
+ */
+export function guardWriteRefs(args: Record<string, unknown>): RefGuardVerdict {
+	const provenance = args.provenance_ref;
+	if (typeof provenance === "string" && provenance.trim()) {
+		const key = provenance.trim().toLowerCase();
+		if (!UUID.test(key) || !store().delivery.has(key)) return refuse("provenance_ref", provenance.trim());
+	}
+	const claim = args.work_claim_ref;
+	if (typeof claim === "string" && claim.trim()) {
+		const key = claim.trim().toLowerCase();
+		if (!UUID.test(key) || !store().claim.has(key)) return refuse("work_claim_ref", claim.trim());
+	}
+	return { ok: true };
+}

package/extensions/core/push-channel.ts

@@ -0,0 +1,281 @@
+/**
+ * DevSpec Pi — push channel client (SSE wake stream).
+ *
+ * Client for GET /api/mcp/connection-stream (devspecv2, item 0026da9f).
+ * The stream emits wake/ended/hello frames; the client fetches the packaged
+ * turn via poll_connection on wake (wake+fetch — packaging stays server-side
+ * in ONE place). Falls back to the held long-poll when the channel is
+ * unavailable (older server, proxy that buffers SSE, etc).
+ */
+
+import { pluginHeaders } from "./client-versions.ts";
+import { SYSTEM_NOTICE_CHANNEL_VERSION } from "./remote-payload.ts";
+
+export interface PushChannelHandlers {
+	/** A wake frame arrived — something moved; fetch now. */
+	onWake(): void;
+	/** The server tore the connection down (carries end_reason). */
+	onEnded(endReason: string | null): void;
+	/** The stream closed (cleanly or by error) — the pump decides what next. */
+	onClose(reason: string): void;
+}
+
+export interface PushChannelOptions {
+	/** The MCP endpoint URL (…/api/mcp); the stream lives under it. */
+	mcpUrl: string;
+	token: string;
+	connectionId: string;
+	/** Hidden exact-connection capability minted with this bond. */
+	connectionCapability?: string;
+	/** Main intake capability only; side polls never inherit this negotiation. */
+	systemNoticeVersion?: typeof SYSTEM_NOTICE_CHANNEL_VERSION;
+	/** Durable interaction events share this one stream's wake marker. */
+	interactionEventVersion?: 1;
+	questionDismissalEventVersion?: 1;
+	handlers: PushChannelHandlers;
+	/** Abort to close deliberately. */
+	signal: AbortSignal;
+}
+
+/** Parse an SSE frame block into {event, data}. Returns null for comments/keepalives. */
+export function parseSseFrame(block: string): { event: string; data: string } | null {
+	let event = "message";
+	const dataLines: string[] = [];
+	for (const line of block.split("\n")) {
+		if (line.startsWith(":")) return null; // comment / keepalive
+		if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) dataLines.push(line.slice(5).trim());
+	}
+	if (dataLines.length === 0) return null;
+	return { event, data: dataLines.join("\n") };
+}
+
+/**
+ * Reconnect backoff for unexpected drops (item 8b0c162b). A native host holds
+ * ONE stream; a proxy hiccup or brief network blip should NOT cost the rest of
+ * the bond's lifetime on the slow path. Returns the delay before the next
+ * reconnect attempt, or null when quick retries are exhausted and the caller
+ * should settle into the held long-poll fallback.
+ *
+ * `attempts` counts consecutive drops of SHORT-LIVED streams: a stream that
+ * stayed up past `healthyMs` proved the path works, so its drop restarts the
+ * backoff from zero instead of burning one of the few quick retries.
+ */
+export const PUSH_RECONNECT_BACKOFF_MS = [1_000, 4_000, 10_000] as const;
+export const PUSH_HEALTHY_MS = 30_000;
+
+/** Monotonic fence: callbacks/timers from a replaced stream cannot open another. */
+export class PushChannelGenerationFence {
+	private generation = 0;
+
+	begin(): number {
+		this.generation += 1;
+		return this.generation;
+	}
+
+	invalidate(): void {
+		this.generation += 1;
+	}
+
+	isCurrent(generation: number): boolean {
+		return generation === this.generation;
+	}
+}
+
+export type RuntimeRunKind = "owner" | "interaction" | "system_notice";
+
+export interface RuntimeOccupancyRevision {
+	revision: number;
+	kind: RuntimeRunKind;
+}
+
+/**
+ * True Pi runtime occupancy, independent from server-visible activity. System
+ * notices are activity-neutral but still occupy the model and must retain SSE
+ * wakes. A stale settle revision can never clear a newer run.
+ */
+export class RuntimeOccupancyFence {
+	private nextRevision = 1;
+	private current: RuntimeOccupancyRevision | null = null;
+
+	begin(kind: RuntimeRunKind): RuntimeOccupancyRevision {
+		// Every low-level Pi start receives a newer settle token, while retries and
+		// compaction retain the existing run kind. An older awaited settle can no
+		// longer finish after a newer start has occurred.
+		const current = {
+			revision: this.nextRevision++,
+			kind: this.current?.kind ?? kind,
+		};
+		this.current = current;
+		return { ...current };
+	}
+
+	promote(candidate: RuntimeOccupancyRevision | null, kind: RuntimeRunKind): RuntimeOccupancyRevision | null {
+		if (!this.isCurrent(candidate) || !this.current) return null;
+		this.current = { revision: this.nextRevision++, kind };
+		return { ...this.current };
+	}
+
+	capture(): RuntimeOccupancyRevision | null {
+		return this.current ? { ...this.current } : null;
+	}
+
+	isCurrent(candidate: RuntimeOccupancyRevision | null): boolean {
+		return Boolean(candidate && this.current
+			&& candidate.revision === this.current.revision
+			&& candidate.kind === this.current.kind);
+	}
+
+	finish(candidate: RuntimeOccupancyRevision | null): boolean {
+		if (!this.isCurrent(candidate)) return false;
+		this.current = null;
+		return true;
+	}
+
+	isBusy(): boolean {
+		return this.current !== null;
+	}
+}
+
+/**
+ * Monotonic wake gate for the one pump fetch loop. Resolving a waiter consumes
+ * that exact generation; a later/burst signal remains one pending generation.
+ */
+export class WakeGenerationGate {
+	private produced = 0;
+	private consumed = 0;
+	private waiter: { resolve: () => void; timer: ReturnType<typeof setTimeout> } | null = null;
+
+	signal(): void {
+		this.produced += 1;
+		const waiter = this.waiter;
+		if (!waiter) return;
+		this.waiter = null;
+		clearTimeout(waiter.timer);
+		this.consumed = this.produced;
+		waiter.resolve();
+	}
+
+	wait(safetyMs: number): Promise<void> {
+		if (this.produced > this.consumed) {
+			this.consumed = this.produced;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				if (this.waiter?.resolve === resolve) this.waiter = null;
+				resolve();
+			}, safetyMs);
+			if (typeof timer.unref === "function") timer.unref();
+			this.waiter = { resolve, timer };
+		});
+	}
+
+	cancel(): void {
+		const waiter = this.waiter;
+		this.waiter = null;
+		if (!waiter) return;
+		clearTimeout(waiter.timer);
+		waiter.resolve();
+	}
+
+	hasPending(): boolean {
+		return this.produced > this.consumed;
+	}
+}
+
+/** Coalesces wake markers consumed while Pi cannot negotiate idle-only lanes. */
+export class BusyWakeLatch {
+	private pending = false;
+
+	noteWake(busy: boolean): void {
+		if (busy) this.pending = true;
+	}
+
+	consumeAtIdle(idle: boolean): boolean {
+		if (!idle || !this.pending) return false;
+		this.pending = false;
+		return true;
+	}
+}
+
+export function nextPushReconnectDelayMs(
+	attempts: number,
+	openedAt: number | undefined,
+	now: number,
+	healthyMs: number = PUSH_HEALTHY_MS,
+): number | null {
+	const effective = openedAt !== undefined && now - openedAt > healthyMs ? 0 : attempts;
+	if (effective >= PUSH_RECONNECT_BACKOFF_MS.length) return null;
+	return PUSH_RECONNECT_BACKOFF_MS[effective];
+}
+
+/**
+ * Open and pump the SSE channel until it closes or the signal aborts.
+ * Resolves when the stream ends; rejects only on connect-level failure
+ * (non-2xx, network) so the caller can choose fallback BEFORE any frames
+ * flowed.
+ */
+export function pushChannelUrl(opts: Pick<PushChannelOptions, "mcpUrl" | "connectionId" | "systemNoticeVersion" | "interactionEventVersion" | "questionDismissalEventVersion">): string {
+	const query = new URLSearchParams({ connection_id: opts.connectionId });
+	if (opts.systemNoticeVersion === SYSTEM_NOTICE_CHANNEL_VERSION) query.set("system_notice_version", String(SYSTEM_NOTICE_CHANNEL_VERSION));
+	if (opts.interactionEventVersion === 1) query.set("interaction_event_version", "1");
+	if (opts.questionDismissalEventVersion === 1) {
+		if (opts.interactionEventVersion !== 1) throw new Error("Dismissal requires answer negotiation");
+		query.set("question_dismissal_event_version", "1");
+	}
+	return `${opts.mcpUrl.replace(/\/$/, "")}/connection-stream?${query.toString()}`;
+}
+
+export async function openPushChannel(opts: PushChannelOptions): Promise<void> {
+	const url = pushChannelUrl(opts);
+	const res = await fetch(url, {
+		method: "GET",
+		headers: {
+			authorization: `Bearer ${opts.token}`,
+			accept: "text/event-stream",
+			...pluginHeaders(),
+			...(opts.connectionCapability ? { "x-devspec-connection-capability": opts.connectionCapability } : {}),
+		},
+		signal: opts.signal,
+	});
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`push channel HTTP ${res.status}: ${body.slice(0, 200)}`);
+	}
+	if (!res.body) throw new Error("push channel: no response body");
+
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let sep: number;
+			while ((sep = buffer.indexOf("\n\n")) !== -1) {
+				const block = buffer.slice(0, sep);
+				buffer = buffer.slice(sep + 2);
+				const frame = parseSseFrame(block);
+				if (!frame) continue;
+				if (frame.event === "wake") {
+					opts.handlers.onWake();
+				} else if (frame.event === "ended") {
+					let reason: string | null = null;
+					try {
+						reason = (JSON.parse(frame.data) as { end_reason?: string | null }).end_reason ?? null;
+					} catch { /* keep null */ }
+					opts.handlers.onEnded(reason);
+				}
+				// hello frames need no action — the bond already knows its facts.
+			}
+		}
+		opts.handlers.onClose("stream closed");
+	} catch (err) {
+		if (opts.signal.aborted) return; // deliberate close — not an error
+		opts.handlers.onClose(err instanceof Error ? err.message : String(err));
+	}
+}

package/extensions/core/question-receipt-lifecycle.ts

@@ -0,0 +1,158 @@
+/**
+ * Runtime-mechanical lifecycle for a tool batch whose durable customer-visible
+ * output is owned by canonical directed-question transcript receipts.
+ *
+ * The server receipt owns only the otherwise-empty transcript/trail bubble. Pi
+ * still executes every tool and always completes the exact activity attempt.
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value != null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+/** Host-only receipt identity. It is control metadata and must never enter prose. */
+export function directedQuestionTranscriptReceiptId(result: unknown): string | null {
+	const outer = record(result);
+	const details = record(outer?.details) ?? outer;
+	const question = record(details?.question);
+	const id = question?.transcriptMessageId;
+	return typeof id === "string" && UUID.test(id) ? id : null;
+}
+
+export interface ReceiptToolResult {
+	success: boolean;
+	terminatingReceipt: boolean;
+}
+
+export function isPotentialDirectedQuestionCreate(
+	toolName: string,
+	args: unknown,
+): boolean {
+	return toolName === "manage_directed_question" && record(args)?.action === "create";
+}
+
+export function isReceiptOwningDirectedQuestionCreate(
+	toolName: string,
+	result: unknown,
+	isError: boolean,
+): boolean {
+	return toolName === "manage_directed_question" && !isError &&
+		(record(result)?.terminate === true) && directedQuestionTranscriptReceiptId(result) !== null;
+}
+
+/**
+ * One LLM tool batch at a time. A receipt may temporarily defer the 1s trail
+ * timer while sibling results are outstanding. Any non-receipt/failed sibling
+ * immediately resumes ordinary projection with the accumulated trail intact.
+ */
+export class TrailPostFence {
+	private pending = new Set<Promise<void>>();
+	private valid = true;
+
+	private adopt(observed: Promise<void>): void {
+		if (!this.valid || this.pending.has(observed)) return;
+		this.pending.add(observed);
+		void observed.then(() => this.pending.delete(observed));
+	}
+
+	track<T>(post: Promise<T>): Promise<T> {
+		// The observer handles rejection even when the caller intentionally fires
+		// and forgets. `drain` therefore never creates an unhandled rejection.
+		const observed = Promise.resolve(post).then(
+			() => undefined,
+			() => undefined,
+		);
+		this.adopt(observed);
+		return post;
+	}
+
+	async drain(): Promise<void> {
+		// Candidate marking stops future timer posts first. Looping also covers a
+		// projection synchronously tracked by the same turn just before the mark.
+		while (this.pending.size > 0) {
+			await Promise.all([...this.pending]);
+		}
+	}
+
+	invalidate(): void {
+		this.valid = false;
+	}
+
+	/**
+	 * Hand authority to a fresh fence without abandoning predecessor posts.
+	 * Directly adopting the normalized in-flight promises is the flattened form
+	 * of tracking `oldFence.drain()`: repeated rollovers remain O(in-flight), not
+	 * an ever-growing promise chain, and each settled promise removes itself.
+	 */
+	rollover(): TrailPostFence {
+		this.invalidate();
+		const replacement = new TrailPostFence();
+		for (const observed of this.pending) replacement.adopt(observed);
+		return replacement;
+	}
+
+	get size(): number {
+		return this.pending.size;
+	}
+}
+
+export class DirectedQuestionReceiptBatch {
+	private revision = 0;
+	private pending = new Set<string>();
+	private receiptCandidates = new Set<string>();
+	private nonReceiptStarted = false;
+	private resultCount = 0;
+	private receiptSeen = false;
+	private allResultsAreReceipts = true;
+	private substantiveAfterReceipt = false;
+
+	reset(revision: number): void {
+		this.revision = revision;
+		this.pending.clear();
+		this.receiptCandidates.clear();
+		this.nonReceiptStarted = false;
+		this.resultCount = 0;
+		this.receiptSeen = false;
+		this.allResultsAreReceipts = true;
+		this.substantiveAfterReceipt = false;
+	}
+
+	start(toolCallId: string, revision: number, potentialReceipt = false): void {
+		if (revision !== this.revision) this.reset(revision);
+		this.pending.add(toolCallId);
+		if (potentialReceipt) this.receiptCandidates.add(toolCallId);
+		else this.nonReceiptStarted = true;
+	}
+
+	finish(toolCallId: string, outcome: ReceiptToolResult, revision: number): void {
+		if (revision !== this.revision || !this.pending.has(toolCallId)) return;
+		this.pending.delete(toolCallId);
+		this.receiptCandidates.delete(toolCallId);
+		this.resultCount += 1;
+		this.receiptSeen ||= outcome.success && outcome.terminatingReceipt;
+		this.allResultsAreReceipts &&= outcome.success && outcome.terminatingReceipt;
+	}
+
+	noteAssistantText(text: string, revision: number): void {
+		if (revision !== this.revision || !this.receiptSeen) return;
+		if (text.trim().length > 0) this.substantiveAfterReceipt = true;
+	}
+
+	/** Stop the timer from opening a second bubble during a receipt-owned batch. */
+	deferTrail(revision: number): boolean {
+		if (revision !== this.revision || this.substantiveAfterReceipt) return false;
+		// Potential create is marked synchronously at tool_execution_start, before
+		// its awaited pre-invocation fence. No timer post may overtake takeover.
+		if (this.receiptCandidates.size > 0) return true;
+		return this.receiptSeen && this.allResultsAreReceipts && !this.nonReceiptStarted;
+	}
+
+	/** Suppress only the empty fallback after every sibling result is known. */
+	suppressEmptyFallback(revision: number): boolean {
+		return this.deferTrail(revision) && this.pending.size === 0 && this.resultCount > 0;
+	}
+}