@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/owner-inject.ts

@@ -0,0 +1,148 @@
+/**
+ * Owner-command inject hygiene (items aa98098f, 09d4993e).
+ *
+ * Rebond starts a new pump with no cursor. The first poll is catch-up
+ * (already-answered history). If that lap is an empty wake, `synced`
+ * must not flip — the next cursor-less poll is still catch-up.
+ *
+ * Only PRE-ATTACH commands on that lap are history. A live owner
+ * command created at/after this bond attached must still be delivered
+ * even when it rides the cursor-less window (live miss: Ali 2026-08-13,
+ * “can you pick up from here?” swallowed on Rapid Quokka’s first sync).
+ *
+ * send("now") while the runtime is busy prints
+ * "already processing" and is fire-and-forget — we cannot catch it.
+ * Never choose `now` unless idle at send time.
+ */
+
+import type { OwnerCommand } from "./remote-payload.ts";
+import { sendModeFor, type OwnerDeliveryMode, type OwnerSendMode } from "./preempt.ts";
+
+type OwnerCommandIdentity = Pick<OwnerCommand, "id"> & Partial<Pick<OwnerCommand, "text" | "createdAt" | "userName">>;
+
+export type BundleReservation = "reserved" | "seen" | "conflict";
+
+export class SeenOwnerCommands {
+	private readonly ids = new Set<string>();
+	private readonly inFlight = new Set<string>();
+
+	private addSeen(id: string): void {
+		// Stable ids are never evicted during this pump generation: cursor state is
+		// primary, but replay defense must not become time/volume dependent.
+		this.ids.add(id);
+	}
+
+	remember(commands: readonly OwnerCommandIdentity[]): void {
+		for (const cmd of commands) this.addSeen(cmd.id);
+	}
+
+	/** Reserve all ids in one canonical turn or none of them. */
+	reserveBundle(commands: readonly OwnerCommandIdentity[]): BundleReservation {
+		if (commands.length === 0) return "conflict";
+		const ids = commands.map((command) => command.id);
+		const seenCount = ids.filter((id) => this.ids.has(id)).length;
+		if (seenCount === ids.length) return "seen";
+		if (seenCount > 0 || ids.some((id) => this.inFlight.has(id))) return "conflict";
+		for (const id of ids) this.inFlight.add(id);
+		return "reserved";
+	}
+
+	commitBundle(commands: readonly OwnerCommandIdentity[]): void {
+		for (const command of commands) {
+			this.inFlight.delete(command.id);
+			this.addSeen(command.id);
+		}
+	}
+
+	releaseBundle(commands: readonly OwnerCommandIdentity[]): void {
+		for (const command of commands) this.inFlight.delete(command.id);
+	}
+
+	/** Reserve unseen commands without committing replay state yet. */
+	takeUnseen<T extends OwnerCommandIdentity>(commands: readonly T[]): T[] {
+		const out: T[] = [];
+		for (const cmd of commands) {
+			if (this.ids.has(cmd.id) || this.inFlight.has(cmd.id)) continue;
+			this.inFlight.add(cmd.id);
+			out.push(cmd);
+		}
+		return out;
+	}
+
+	/** Commit only after hidden context + hydrated command were accepted by Pi. */
+	commit(command: Pick<OwnerCommandIdentity, "id">): void {
+		this.inFlight.delete(command.id);
+		this.addSeen(command.id);
+	}
+
+	/** Release a failure so the unchanged canonical cursor can retry it. */
+	release(command: Pick<OwnerCommandIdentity, "id">): void {
+		this.inFlight.delete(command.id);
+	}
+
+	has(id: string): boolean {
+		return this.ids.has(id);
+	}
+
+	isInFlight(id: string): boolean {
+		return this.inFlight.has(id);
+	}
+
+	get size(): number {
+		return this.ids.size;
+	}
+}
+
+export function parseTimestampMs(value: unknown): number | null {
+	if (typeof value !== "string" || !value.trim()) return null;
+	const ms = Date.parse(value);
+	return Number.isNaN(ms) ? null : ms;
+}
+
+/** Prefer the server attach stamp; otherwise the moment the pump started. */
+export function resolveAttachedAtMs(value: unknown, fallbackMs: number): number {
+	return parseTimestampMs(value) ?? fallbackMs;
+}
+
+/**
+ * Split the cursor-less catch-up window into already-answered history
+ * (created before this bond attached) and live first-touch commands.
+ * Missing/unparseable created_at is live — dropping an instruction is worse
+ * than a possible replay.
+ */
+export function splitCatchUpCommands<T extends OwnerCommandIdentity>(
+	commands: readonly T[],
+	attachedAtMs: number,
+): { historical: T[]; live: T[] } {
+	const historical: T[] = [];
+	const live: T[] = [];
+	for (const cmd of commands) {
+		const createdMs = parseTimestampMs(cmd.createdAt);
+		if (createdMs !== null && createdMs < attachedAtMs) historical.push(cmd);
+		else live.push(cmd);
+	}
+	return { historical, live };
+}
+
+/**
+ * First poll after rebond: adopt cursors, remember historical ids.
+ * An empty wake (no cursor, no commands) is not a completed sync — the
+ * next cursor-less poll is still the catch-up window.
+ */
+export function shouldCompleteSync(pkg: {
+	cursor?: string;
+	ownerCommands: readonly OwnerCommand[];
+}): boolean {
+	return Boolean(pkg.cursor) || pkg.ownerCommands.length > 0;
+}
+
+/** Never `now` unless the runtime is idle right now. */
+export function sendModeAtSendTime(
+	mode: OwnerDeliveryMode,
+	idleNow: boolean,
+	settled = false,
+): OwnerSendMode {
+	if (mode === "immediate" && !idleNow) return "steer";
+	if (mode === "preempt") return sendModeFor(mode, settled && idleNow);
+	return sendModeFor(mode, settled);
+}

package/extensions/core/post-session-receipt.ts

@@ -0,0 +1,70 @@
+import { unwrapMcpResult } from "./result.ts";
+
+export type PostSessionReceipt =
+	| { status: "stored" | "idempotently_stored"; messageId: string }
+	| { status: "skipped" | "rejected" | "malformed" };
+
+export interface ExpectedPostReceipt {
+	connectionId: string;
+	sessionId?: string | null;
+	phase: string;
+	turnKind?: string;
+	/** Source-aware delivery must not accept a different row's legacy receipt. */
+	assistantSourceId?: string;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown> : null;
+}
+
+/** Accept deployed text-JSON and structured MCP envelopes, never transport success alone. */
+export function parsePostSessionReceipt(raw: unknown, expected: ExpectedPostReceipt): PostSessionReceipt {
+	const { details, isError } = unwrapMcpResult(raw);
+	if (isError) return { status: "rejected" };
+	const data = record(details);
+	if (!data) return { status: "malformed" };
+	const receipt = record(data.delivery);
+	if (receipt?.status === "rejected") return { status: "rejected" };
+	if (data.skipped === true || data.noop === true || receipt?.status === "skipped") return { status: "skipped" };
+	if (data.error !== undefined) return { status: "rejected" };
+	const expectedSessionId = expected.sessionId ?? null;
+	if ((data.session_id ?? null) !== expectedSessionId || data.phase !== expected.phase ||
+		data.connection_id !== expected.connectionId ||
+		(expected.turnKind !== undefined && data.turn_kind !== expected.turnKind) ||
+		typeof data.message_id !== "string" || !data.message_id.trim()) return { status: "malformed" };
+	if (expected.assistantSourceId !== undefined &&
+		(data.assistant_source_id !== expected.assistantSourceId || !receipt)) return { status: "malformed" };
+	if (data.delivery !== undefined) {
+		if (!receipt || (receipt.status !== "stored" && receipt.status !== "idempotently_stored") ||
+			receipt.message_id !== data.message_id) return { status: "malformed" };
+		return { status: receipt.status, messageId: data.message_id };
+	}
+	// Legacy answer (including local_prompt) and trail successes all include the
+	// persisted row id, session, connection and phase. Bare noop is NOT idempotence.
+	return { status: "stored", messageId: data.message_id };
+}
+
+/** A cumulative snapshot stays dirty until acknowledged. Failure stops automatic
+ * replay for this segment: stale authority and ambiguous response loss are not retry permission. */
+export class TrailDeliveryState {
+	private revision = 0;
+	private acknowledged = 0;
+	private pending: number | null = null;
+	private failed = false;
+
+	markDirty(): void { this.revision += 1; }
+	get dirty(): boolean { return this.revision !== this.acknowledged; }
+	get blocked(): boolean { return this.failed || this.pending !== null; }
+	begin(): number | null {
+		if (!this.dirty || this.blocked) return null;
+		this.pending = this.revision;
+		return this.pending;
+	}
+	finish(snapshot: number, stored: boolean): void {
+		if (this.pending !== snapshot) return;
+		this.pending = null;
+		if (stored) this.acknowledged = snapshot;
+		else this.failed = true;
+	}
+}

package/extensions/core/preempt.ts

@@ -0,0 +1,100 @@
+/**
+ * Owner-instruction preemption policy (item f5bbc8f8).
+ *
+ * Arrival of an owner command mid-turn is a LIFECYCLE event, not content
+ * authorship: abort the running turn (pause, never undo), then deliver the
+ * owner message. Ambient/room noise never reaches this function — the pump
+ * only calls it for ownerCommands.
+ *
+ * Pure so the three modes are unit-testable without a live pi session.
+ */
+
+export type OwnerDeliveryMode = "immediate" | "queue" | "preempt";
+
+/** How sendUserMessage must be called for that mode. */
+export type OwnerSendMode = "now" | "steer" | "followUp";
+
+export function decideOwnerDelivery(input: {
+	idle: boolean;
+	preemptEnabled: boolean;
+	hasOwnerCommand: boolean;
+}): OwnerDeliveryMode {
+	if (!input.hasOwnerCommand) return "immediate";
+	if (input.idle) return "immediate";
+	if (input.preemptEnabled) return "preempt";
+	return "queue";
+}
+
+/** How a directed-question answer should meet a running Pi turn (item 4221d08e). */
+export type InteractionDeliveryMode = "apply" | "preempt" | "defer";
+
+export function decideInteractionDelivery(input: {
+	idle: boolean;
+	preemptEnabled: boolean;
+	hasEvent: boolean;
+}): InteractionDeliveryMode {
+	if (!input.hasEvent) return "defer";
+	if (input.idle) return "apply";
+	if (input.preemptEnabled) return "preempt";
+	return "defer";
+}
+
+/**
+ * After abort(), isStreaming stays true until the aborted run settles
+ * (cooperative AbortSignal). A bare send during that window throws
+ * "already processing" (live miss 1). Steering into the SAME run then
+ * produces a terminal answer that agent_settled never posts — settle
+ * nulls turn state first (live miss 2, Ali 2026-08-13: interrupt worked,
+ * reply stayed in the terminal).
+ *
+ * Wait for idle, then send as a fresh turn (`now`). If the wait times
+ * out, fall back to steer so the message is not dropped.
+ */
+export function sendModeFor(mode: OwnerDeliveryMode, settled = false): OwnerSendMode {
+	if (mode === "preempt") return settled ? "now" : "steer";
+	if (mode === "queue") return "followUp";
+	return "now";
+}
+
+export async function waitUntil(
+	check: () => boolean,
+	opts: {
+		timeoutMs: number;
+		intervalMs: number;
+		now?: () => number;
+		sleep?: (ms: number) => Promise<void>;
+	},
+): Promise<boolean> {
+	const now = opts.now ?? Date.now;
+	const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const deadline = now() + opts.timeoutMs;
+	while (!check()) {
+		if (now() >= deadline) return false;
+		await sleep(opts.intervalMs);
+	}
+	return true;
+}
+
+/**
+ * Stranded-busy recovery (item 3f07f97b). pi_abort() is cooperative: when the
+ * aborted run never settles, the settle wait times out while the model is
+ * already idle and nothing holds occupancy — yet active.busy stays true, so
+ * every later lap defers the same interaction event ("awaiting idle") and the
+ * event-only lane starves all command delivery (live wedge 2026-09-18, 73
+ * minutes). Clearing is safe exactly when nothing is running: a genuinely
+ * settling run keeps either ctx or occupancy busy. Deliberately not gated on
+ * background tasks: a stale pending entry must not preserve the wedge, and the
+ * applied event starts a run that reasserts busy within one lap.
+ */
+export function shouldClearStrandedBusyAfterAbort(input: {
+	settled: boolean;
+	ctxIdle: boolean;
+	occupancyBusy: boolean;
+	pumpBusy: boolean;
+}): boolean {
+	return !input.settled && input.ctxIdle && !input.occupancyBusy && input.pumpBusy;
+}
+
+/** Tail note so the model judges stop-vs-continue. Not an instruction to invent work. */
+export const PREEMPT_TAIL =
+	"[This interrupted a running turn. Answer this first. Then continue the prior work if that is appropriate — a short ack is enough to stop; do not throw the previous context away.]";

package/extensions/core/project-choice.ts

@@ -0,0 +1,145 @@
+/** Conversation-owned project intent, separate from committable folder defaults. */
+export const PROJECT_CHOICE_ENTRY = "devspec-project-choice-v1";
+export interface ProjectCandidate {
+	id: string;
+	name: string;
+	organization?: { id: string; name: string };
+}
+export interface ProjectChoice {
+	version: 1;
+	endpoint: string;
+	project: ProjectCandidate;
+	source: string;
+}
+export interface ProjectChoiceRequired {
+	version: 1;
+	status: "choice_required";
+	reason: string;
+	candidates: ProjectCandidate[];
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const object = (value: unknown): Record<string, unknown> | null =>
+	value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+
+export function readProjectCandidate(value: unknown): ProjectCandidate | null {
+	const row = object(value);
+	if (!row || typeof row.id !== "string" || !UUID.test(row.id) || typeof row.name !== "string") return null;
+	const org = object(row.organization);
+	return { id: row.id, name: row.name, ...(org && typeof org.id === "string" && UUID.test(org.id) && typeof org.name === "string"
+		? { organization: { id: org.id, name: org.name } } : {}) };
+}
+
+/** Read structured MCP data or its JSON text equivalent, never English error prose. */
+export function projectResultData(raw: unknown): Record<string, unknown> | null {
+	const row = object(raw);
+	if (!row) return null;
+	if (object(row.structuredContent)) return object(row.structuredContent);
+	if (Array.isArray(row.content)) for (const block of row.content) {
+		const text = object(block);
+		if (text?.type !== "text" || typeof text.text !== "string") continue;
+		try { const parsed = object(JSON.parse(text.text)); if (parsed) return parsed; } catch { /* legacy plain message */ }
+	}
+	return null;
+}
+export function readProjectChoiceRequired(raw: unknown): ProjectChoiceRequired | null {
+	const data = projectResultData(raw);
+	const selection = object(data?.project_selection);
+	if (data?.code !== "project_choice_required" || selection?.version !== 1 || selection.status !== "choice_required" || !Array.isArray(selection.candidates)) return null;
+	const candidates = selection.candidates.map(readProjectCandidate);
+	if (candidates.some(p => !p || !p.organization)) return null;
+	return { version: 1, status: "choice_required", reason: String(selection.reason ?? "project_required"), candidates: candidates as ProjectCandidate[] };
+}
+export function projectFromRegistration(data: Record<string, unknown>, endpoint: string, fallback?: ProjectCandidate): ProjectChoice | null {
+	const selection = object(data.project_selection);
+	const project = selection?.version === 1 && selection.status === "resolved" ? readProjectCandidate(selection.project) : null;
+	const id = typeof data.project_id === "string" && UUID.test(data.project_id) ? data.project_id : null;
+	if (!id || (project && project.id !== id)) return null;
+	return { version: 1, endpoint, project: project ?? (fallback?.id === id ? fallback : { id, name: id }), source: typeof selection?.source === "string" ? selection.source : "conversation" };
+}
+
+interface ChoiceStore { localId: string | null; choice: ProjectChoice | null; launchConsumed: boolean; error: string | null }
+const KEY = "__devspecPiConversationProject";
+function store(): ChoiceStore {
+	const global = globalThis as unknown as Record<string, ChoiceStore | undefined>;
+	return global[KEY] ??= { localId: null, choice: null, launchConsumed: false, error: null };
+}
+export function getProjectChoice(localId?: string): ProjectChoice | null {
+	return localId && store().localId !== localId ? null : store().choice;
+}
+export function consumeProjectLaunchFlag(): boolean {
+	const first = !store().launchConsumed;
+	store().launchConsumed = true;
+	return first;
+}
+export function setProjectChoice(localId: string, choice: ProjectChoice | null): void {
+	store().localId = localId; store().choice = choice; store().error = null;
+}
+export function blockProjectChoice(localId: string, error: string): void {
+	store().localId = localId; store().error = error;
+}
+export function restoreProjectChoice(entries: readonly unknown[], localId: string, endpoint: string): ProjectChoice | null {
+	let restored: ProjectChoice | null = null;
+	for (const entry of entries) {
+		const row = object(entry);
+		if (row?.type !== "custom" || row.customType !== PROJECT_CHOICE_ENTRY) continue;
+		const data = object(row.data);
+		const project = readProjectCandidate(data?.project);
+		if (data?.version === 1 && data.endpoint === endpoint && project && typeof data.source === "string") {
+			restored = { version: 1, endpoint, project, source: data.source };
+		}
+	}
+	setProjectChoice(localId, restored);
+	return restored;
+}
+export function hasConversationProjectScope(): boolean { return Boolean(store().choice || store().error); }
+export function conversationScope(args: Record<string, unknown>, endpoint: string): Record<string, unknown> {
+	if (store().error && !args.project_id) throw new Error(store().error!);
+	const choice = getProjectChoice();
+	// Discovery is still account-wide; explicit/entity identifiers are validated server-side.
+	return choice?.endpoint === endpoint && !args.project_id ? { ...args, project_id: choice.project.id } : args;
+}
+const terminalText = (text: string) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+export function projectLabel(project: ProjectCandidate): string {
+	return `${terminalText(project.name)} — ${terminalText(project.organization?.name ?? "organisation unavailable")}`;
+}
+/** IDs are exceptional disambiguators, not decoration on every choice. */
+export function projectChoiceLabels(projects: readonly ProjectCandidate[]): string[] {
+	const labels = projects.map(projectLabel);
+	return labels.map((label, index) => labels.filter(value => value === label).length > 1
+		? `${label} · ${projects[index]!.id}` : label);
+}
+export function projectDetails(choice: ProjectChoice): string {
+	const sources: Record<string, string> = {
+		git_remote: "Repository match", folder_pin: "Folder default", conversation: "Saved conversation choice",
+		explicit: "Chosen for this conversation", connection: "Existing connection", single_project: "Only accessible project", entity: "Selected record",
+	};
+	return `Project: ${terminalText(choice.project.name)}\nOrganisation: ${terminalText(choice.project.organization?.name ?? "Not reported")}\nProject ID: ${choice.project.id}\nSelected by: ${sources[choice.source] ?? "Not reported"}`;
+}
+export function matchingProjects(projects: readonly ProjectCandidate[], selector: string): ProjectCandidate[] {
+	const value = selector.trim().toLowerCase();
+	const ids = projects.filter(p => p.id.toLowerCase() === value);
+	return ids.length ? ids : projects.filter(p => p.name.toLowerCase() === value);
+}
+
+/** Extract only our flag, leaving the existing room parser's vocabulary untouched. */
+export function projectRemoteArgs(input: string): { selector?: string; remaining: string; error?: string } {
+	const tokens: string[] = [];
+	let current = "", quote = "", inToken = false;
+	for (const char of input.trim()) {
+		if (quote) { if (char === quote) quote = ""; else current += char; inToken = true; }
+		else if (char === '"' || char === "'") { quote = char; inToken = true; }
+		else if (/\s/.test(char)) { if (inToken) { tokens.push(current); current = ""; inToken = false; } }
+		else { current += char; inToken = true; }
+	}
+	if (quote) return { remaining: "", error: "Close the quoted project name before connecting." };
+	if (inToken) tokens.push(current);
+	let selector: string | undefined;
+	const remaining: string[] = [];
+	for (let i = 0; i < tokens.length; i++) {
+		if (tokens[i] === "--project" || tokens[i] === "--devspec-project") {
+			if (selector !== undefined || !tokens[i + 1]?.trim() || tokens[i + 1]!.startsWith("--")) return { remaining: "", error: "Pass one project name or ID after --project." };
+			selector = tokens[++i];
+		} else remaining.push(tokens[i]!);
+	}
+	return { selector, remaining: remaining.join(" ") };
+}