@vanillagreen/pi-claude-bridge 1.9.0 → 3.2.2

package/src/auth-presence.ts

@@ -6,10 +6,12 @@
 // "not-used"` as "configured" and the provider would look connected while every
 // request fails at spawn time.
 //
-// This module answers two pure questions used to gate registration:
-//   1. hasClaudeCredentials() — are real credentials present RIGHT NOW?
-//   2. decideRegistration()   — given credential presence + the primary-instance
-//      / stream-guard tokens, should we register / unregister / do nothing?
+// This module answers one pure question: hasClaudeCredentials() — are real
+// credentials present RIGHT NOW? Since 2.0 it feeds the native provider's
+// auth check/resolve (native-provider.ts) and the pre-spawn fail-fast, rather
+// than gating register/unregister transitions (the 1.x decideRegistration
+// state machine is gone — registration is unconditional and pi hides
+// unconfigured providers' models itself).
 //
 // SECURITY: this module only ever checks for the EXISTENCE of credentials — a
 // file's presence, an env var being non-empty, a settings key being a non-empty
@@ -110,49 +112,3 @@ export function hasClaudeCredentials(
 	return false;
 }
 
-/**
- * Snapshot of the inputs to a registration decision.
- *
- * The bridge keeps two process-global tokens (Symbol.for): a PRIMARY-instance
- * token, claimed unconditionally by the first-loaded module instance, and the
- * stream-guard token holding the registered instance's streamSimple. ONLY the
- * primary instance may ever register/unregister or claim the stream guard — this
- * prevents a subagent module reload (a fresh, non-primary instance) from
- * stealing ownership and registering ITS streamSimple, which would split-brain
- * the shared session/ctx and break tool-result delivery.
- */
-export interface RegistrationState {
-	/** Does the machine have Claude credentials right now? */
-	credentialed: boolean;
-	/** Is THIS module instance the primary (first-loaded) instance? */
-	isPrimary: boolean;
-	/** Has this instance already registered (owns the stream guard)? */
-	registered: boolean;
-}
-
-export type RegistrationDecision = "register" | "unregister" | "noop";
-
-/**
- * Pure decision for extension load, every session_start re-check, and the
- * pre-spawn fail-fast path.
- *
- * Rules:
- *   - Not the primary instance                    → NOOP (never touch registration).
- *   - Primary + credentialed + not registered     → REGISTER (claim guard + register).
- *   - Primary + credentialed + already registered → NOOP.
- *   - Primary + uncredentialed                    → UNREGISTER (defensive).
- *
- * The uncredentialed primary always returns UNREGISTER rather than NOOP:
- * pi.unregisterProvider is idempotent ("Has no effect if the provider was never
- * registered"), and a defensive call is the ONLY way to retract a registration
- * that survived a /reload — the ModelRegistry's registeredProviders is a
- * process-lifetime Map and module reload does NOT clear it. (At extension-load
- * time this defensive unregister only filters the pending-registration queue and
- * cannot mutate the persistent registry; the authoritative retraction happens on
- * the post-load session_start re-check — see applyProviderRegistration.)
- */
-export function decideRegistration(state: RegistrationState): RegistrationDecision {
-	if (!state.isPrimary) return "noop";
-	if (state.credentialed) return state.registered ? "noop" : "register";
-	return "unregister";
-}

package/src/bridge-commands.ts

@@ -0,0 +1,86 @@
+// The /pi-claude command surface: settings/status UI and the deterministic
+// connector-inventory report. Extracted from index.ts (pure move).
+
+import { type Model } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { accountSessionScope, resolveClaudeAccountRouter } from "./account-router.js";
+import { loadConfig } from "./config.js";
+import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory.js";
+import { connectorCredentialEnv, readCredentialFile } from "./connector-runtime.js";
+
+const COMMANDS_REGISTERED_KEY = Symbol.for("claude-bridge:commandsRegistered");
+
+function commandCwd(ctx: unknown): string {
+	const value = (ctx as { cwd?: unknown })?.cwd;
+	return typeof value === "string" && value.length > 0 ? value : process.cwd();
+}
+
+async function tryOpenExtensionManagerSettings(ctx: { ui: ExtensionUIContext }): Promise<boolean> {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const openQuickSettings = host[Symbol.for("vstack.pi.extension-manager.open-quick-settings")];
+	if (typeof openQuickSettings !== "function") return false;
+	try {
+		await (openQuickSettings as (ctx: unknown, hint?: string) => Promise<void>)(ctx, "@vanillagreen/pi-claude-bridge");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function showBridgeStatus(ctx: { ui: ExtensionUIContext; cwd?: string }): void {
+	const config = loadConfig(commandCwd(ctx));
+	ctx.ui.notify([
+		`Pi Claude: ${config.enabled === false ? "disabled" : "enabled"}`,
+		"Claude account billing settings (including Extra Usage) are managed in Claude.",
+	].join("\n"), "info");
+}
+
+// Deterministic connector enumeration for the host app (vstack#838). Reports the
+// failure reason rather than an empty list, so "no connectors" and "could not
+// check" stay distinguishable.
+async function reportConnectorInventory(ctx: {
+	ui: ExtensionUIContext;
+	model?: Model<any>;
+	sessionManager?: { getSessionId?: () => string };
+}): Promise<void> {
+	// With a router active, enumerate the CURRENT route's account rather than
+	// whatever the process env points at.
+	const account = ctx.model
+		? resolveClaudeAccountRouter()?.current(ctx.model.id, ctx.sessionManager?.getSessionId?.())
+		: undefined;
+	const credentials = resolveClaudeOAuth(readCredentialFile, connectorCredentialEnv(account ? accountSessionScope(account).claudeConfigDir : undefined));
+	if (!credentials) {
+		ctx.ui.notify("Pi Claude: no Claude OAuth credentials found — cannot enumerate connectors.", "error");
+		return;
+	}
+	const inventory = await listAccountConnectors({ credentials });
+	if (!inventory.ok) {
+		ctx.ui.notify(`Pi Claude: connector enumeration failed — ${inventory.reason}`, "error");
+		return;
+	}
+	if (inventory.connectors.length === 0) {
+		ctx.ui.notify("Pi Claude: this account has no connectors installed.", "info");
+		return;
+	}
+	const names = inventory.connectors.map((c) => c.name).join(", ");
+	ctx.ui.notify(`Pi Claude: ${inventory.connectors.length} connector(s) installed — ${names}`, "info");
+}
+
+export function registerBridgeCommands(pi: ExtensionAPI): void {
+	const guard = pi as unknown as Record<PropertyKey, unknown>;
+	if (guard[COMMANDS_REGISTERED_KEY]) return;
+	guard[COMMANDS_REGISTERED_KEY] = true;
+
+	pi.registerCommand("pi-claude", {
+		description: "Open Pi Claude settings/status",
+		handler: async (args: string, ctx) => {
+			if (args.trim()) ctx.ui.notify("Unknown /pi-claude argument.", "warning");
+			if (await tryOpenExtensionManagerSettings(ctx)) return;
+			showBridgeStatus(ctx);
+		},
+	});
+	pi.registerCommand("pi-claude:connectors", {
+		description: "List the Claude account's installed claude.ai connectors",
+		handler: async (_args: string, ctx) => reportConnectorInventory(ctx),
+	});
+}

package/src/bridge-state.ts

@@ -1,12 +1,35 @@
 import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { debug, diagDump, diagLogPath } from "./debug.js";
+import { debug, diagDump, diagGuidance } from "./debug.js";
 import { type QueryContext } from "./query-state.js";
+import { currentRequestLaneId } from "./request-lane.js";
 import { summarizeMissingToolNames, type MissingToolResult } from "./tool-pairing-audit.js";
 
 export interface SessionState {
 	sessionId: string;
 	cursor: number;
 	cwd: string;
+	// Claude Code session files and resume IDs are credential-profile scoped.
+	// Missing values mean the legacy/default Claude profile (process env rules).
+	// `claudeConfigDir` is the RESOLVED dir (see claudeDirForProfile) and is
+	// in-memory only — persistence strips it and keeps just the opaque profile
+	// id, re-deriving the dir through the router on restore.
+	accountProfileId?: string;
+	claudeConfigDir?: string;
+	// Identity anchor of the pi conversation this record belongs to, encoded
+	// component-wise as `u:<12hex>` or `u:<12hex>|a:<12hex>` (see
+	// conversationFingerprint in session-persistence.ts): a short sha256 of the
+	// FIRST user message's normalized text, plus — once the conversation has
+	// one — of the FIRST assistant message's normalized text. Pi histories
+	// never rewrite those opening messages — compact/tree-nav mutations set
+	// needsRebuild instead — so a component mismatch marks a FOREIGN
+	// conversation (a subagent-shaped query arriving while the parent is idle,
+	// vstack#1001) that must run as a clean one-shot without touching this
+	// record. The user component must always match; the assistant component is
+	// compared only when BOTH sides carry one, so a record stamped on turn 1
+	// (no assistant yet) still matches its own grown conversation and upgrades
+	// to the two-component form on the next REUSE. Absent on records restored
+	// from pre-3.1.1 markers → identity unknown, pre-fingerprint behavior.
+	conversationFingerprint?: string;
 	// Force the next syncSharedSession call down the REBUILD path. Set when
 	// pi has mutated its messages array out from under us (compact, tree
 	// navigation) or after an abort left the JSONL in an indeterminate state.
@@ -23,16 +46,101 @@ export interface SessionState {
 	forceRotate?: boolean;
 }
 
-// Shared mutable bridge state. Lives in its own module so the extracted
-// modules and index.ts observe the SAME state: ESM live bindings let every
-// importer READ these `let` bindings live, but only this module may assign
-// them — cross-module writes must go through the setters below.
-export let sharedSession: SessionState | null = null;
+// Claude session state is scoped to Pi's provider `sessionId`. Parent and child
+// agents can load separate copies of the extension module while sharing the
+// primary provider closure, so the lane registry must live on globalThis rather
+// than in one module instance. The versioned symbol prevents an incompatible
+// future store shape from being mistaken for this one.
+interface SharedSessionLaneStoreV1 {
+	defaultSession: SessionState | null;
+	sessions: Map<string, SessionState | null>;
+}
+
+const SHARED_SESSION_LANES_SYMBOL = Symbol.for("vstack.pi.claude-bridge.shared-session-lanes.v1");
+
+function sharedSessionLaneStore(): SharedSessionLaneStoreV1 {
+	const host = globalThis as Record<symbol, unknown>;
+	let store = host[SHARED_SESSION_LANES_SYMBOL] as SharedSessionLaneStoreV1 | undefined;
+	if (!store) {
+		store = { defaultSession: null, sessions: new Map() };
+		host[SHARED_SESSION_LANES_SYMBOL] = store;
+	}
+	return store;
+}
+
 export let extensionApi: ExtensionAPI | undefined;
 export let piUI: ExtensionUIContext | undefined;
 
+export function getSharedSession(): SessionState | null {
+	const store = sharedSessionLaneStore();
+	const sessionId = currentRequestLaneId();
+	return sessionId === undefined
+		? store.defaultSession
+		: (store.sessions.get(sessionId) ?? null);
+}
+
 export function setSharedSession(next: SessionState | null): void {
-	sharedSession = next;
+	const store = sharedSessionLaneStore();
+	const sessionId = currentRequestLaneId();
+	if (sessionId === undefined) store.defaultSession = next;
+	else store.sessions.set(sessionId, next);
+}
+
+export function deleteSharedSessionLane(sessionId: string | undefined): void {
+	const store = sharedSessionLaneStore();
+	if (sessionId === undefined) store.defaultSession = null;
+	else store.sessions.delete(sessionId);
+}
+
+export function clearSharedSessionLanes(): void {
+	const store = sharedSessionLaneStore();
+	store.sessions.clear();
+	store.defaultSession = null;
+}
+
+// The lane each pi session started in, keyed by its SessionManager. An in-memory
+// session (`pi --no-session`) forks by mutating the SAME SessionManager's id
+// before session_shutdown fires, so the live id there names the fork rather than
+// the session being torn down, and the fallback to it would prune a live
+// sibling. Keyed per manager (not one slot) so overlapping parent/child
+// session_start events keep their own entries, and on globalThis like the
+// registry above because session_start and session_shutdown can reach different
+// module instances (`/reload` mid-session, a child agent's own copy) and both
+// must see the same entry.
+const STARTED_LANES_SYMBOL = Symbol.for("vstack.pi.claude-bridge.started-lanes.v1");
+
+function startedLaneStore(): WeakMap<object, string> {
+	const host = globalThis as Record<symbol, unknown>;
+	let store = host[STARTED_LANES_SYMBOL] as WeakMap<object, string> | undefined;
+	if (!store) {
+		store = new WeakMap<object, string>();
+		host[STARTED_LANES_SYMBOL] = store;
+	}
+	return store;
+}
+
+export function recordStartedLane(sessionManager: object, sessionId: string): void {
+	startedLaneStore().set(sessionManager, sessionId);
+}
+
+/** The lane recorded at this manager's session_start, removed as it is read —
+ *  one shutdown per start. Undefined when no start was recorded (the caller
+ *  falls back to the manager's live id). */
+export function takeStartedLane(sessionManager: object): string | undefined {
+	const store = startedLaneStore();
+	const sessionId = store.get(sessionManager);
+	store.delete(sessionManager);
+	return sessionId;
+}
+
+/** Force the next syncSharedSession down the REBUILD path (no-op without a
+ *  session). `forceRotate` additionally rotates the session UUID — set it when
+ *  a concurrent CC writer may still be flushing (abort, idle kill); see the
+ *  field docs on SessionState. */
+export function markSessionForRebuild(opts: { forceRotate?: boolean } = {}): void {
+	const sharedSession = getSharedSession();
+	if (!sharedSession) return;
+	setSharedSession({ ...sharedSession, needsRebuild: true, ...(opts.forceRotate ? { forceRotate: true } : {}) });
 }
 
 export function setExtensionApi(next: ExtensionAPI | undefined): void {
@@ -56,6 +164,33 @@ export function safeToolCallSummary(calls: Array<{ id: string; toolName: string;
 	return calls.map((call) => ({ id: call.id, toolName: call.toolName, argKeys: argKeys(call.arguments) }));
 }
 
+export const INTEGRITY_CUSTOM_TYPE = "claude-bridge-integrity";
+
+/**
+ * Persist a bridge integrity event into the pi session transcript.
+ *
+ * The diag log and a piUI toast both die with the machine or the render cycle:
+ * the 2026-07-28 post-mortem found `Error: Claude bridge: …` messages that were
+ * SHOWN but existed nowhere in the pi session file, making analysis from the
+ * session alone impossible. A `CustomEntry` closes that gap the same way the
+ * connector-call audit does — persisted, never part of built context, never
+ * dispatchable by pi's agent loop. Payloads must stay compact metadata (ids,
+ * counts, tool names), never tool output.
+ *
+ * Never throws; returns whether the entry was appended (false outside a pi
+ * session — tests, embedded hosts without extensionApi).
+ */
+export function appendIntegrityEntry(label: string, data: Record<string, unknown>): boolean {
+	try {
+		if (!extensionApi) return false;
+		extensionApi.appendEntry(INTEGRITY_CUSTOM_TYPE, { label, at: new Date().toISOString(), ...data });
+		return true;
+	} catch (error) {
+		debug("appendIntegrityEntry failed:", error);
+		return false;
+	}
+}
+
 function compactToolNameSummary(names: Array<{ name: string; count: number }>, limit = 12): string[] {
 	const shown = names.slice(0, limit).map(({ name, count }) => count > 1 ? `${name}×${count}` : name);
 	if (names.length > limit) shown.push(`+${names.length - limit} more`);
@@ -75,10 +210,15 @@ export function reportSyntheticToolResultRepair(missing: MissingToolResult[], co
 			missing: missing.slice(0, 50),
 			...context,
 		});
+		appendIntegrityEntry("repair_tool_pairing_synthetic_results", {
+			count: missing.length,
+			toolNames,
+			sampledToolCallIds: sampledToolCallIds.slice(0, 12),
+		});
 		safeNotify(
-			`Claude bridge: ${missing.length} missing tool result(s) repaired with "[no tool result recorded]"` +
+			`Claude bridge: ${missing.length} missing tool result(s) repaired with an explicit error placeholder` +
 			`${toolNameSummary.length ? ` for ${toolNameSummary.join(", ")}` : ""}. ` +
-			`Real tool output was lost before Claude session import; see ${diagLogPath()}.`,
+			`Real tool output was lost before Claude session import; ${diagGuidance()}.`,
 			"error",
 		);
 	} catch (error) {
@@ -86,7 +226,12 @@ export function reportSyntheticToolResultRepair(missing: MissingToolResult[], co
 	}
 }
 
-export function reportToolResultMismatch(queryCtx: QueryContext, reason: string, cwd: string | undefined, opts: { forceRotate?: boolean } = {}): boolean {
+export function reportToolResultMismatch(
+	queryCtx: QueryContext,
+	reason: string,
+	cwd: string | undefined,
+	opts: { expectedInterruption?: boolean; forceRotate?: boolean } = {},
+): boolean {
 	try {
 		if (queryCtx.reportedToolResultMismatch) return false;
 		const progress = queryCtx.toolResultProgress();
@@ -95,15 +240,33 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 			: progress.waitingCount > 0 || progress.queuedCount > 0 || progress.unmatchedResultCount > 0;
 		if (!hasMismatch) return false;
 		queryCtx.reportedToolResultMismatch = true;
-		if (sharedSession) {
-			sharedSession = { ...sharedSession, needsRebuild: true, ...(opts.forceRotate ? { forceRotate: true } : {}) };
+		// The single choke point every mismatch path funnels through (abort,
+		// unmatched result, stream-idle, teardown). A context with no claim on
+		// the shared record (reentrant subagent or foreign one-shot, vstack#1001)
+		// still gets the full diagnostics below, but its unresolved tool state is
+		// its own — marking the PARENT's record needsRebuild/forceRotate here
+		// would flush the parent's prompt cache for a query that never touched
+		// its session.
+		if (!queryCtx.detachedFromSharedSession) markSessionForRebuild(opts);
+		// A user abort interrupting in-flight tool calls is expected teardown, not
+		// an integrity fault: mark the rebuild but skip the diag dump and toast.
+		if (opts.expectedInterruption) {
+			debug(
+				`tool result delivery interrupted as expected during ${reason}; ` +
+				`delivered=${progress.deliveredCount}/${progress.expectedCount} ` +
+				`resolved=${progress.resolvedCount}/${progress.expectedCount} ` +
+				`waiting=${progress.waitingCount} queued=${progress.queuedCount}`,
+			);
+			return true;
 		}
 		const toolNameSummary = compactToolNameSummary(progress.toolNames);
+		const sharedSession = getSharedSession();
 		diagDump("tool_result_delivery_mismatch", {
 			reason,
 			cwd,
 			progress,
 			activeQueryExists: queryCtx.activeQuery !== null,
+			detachedFromSharedSession: queryCtx.detachedFromSharedSession,
 			sharedSession: sharedSession ? {
 				sessionId: sharedSession.sessionId.slice(0, 8),
 				cursor: sharedSession.cursor,
@@ -111,12 +274,24 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 				forceRotate: sharedSession.forceRotate === true,
 			} : null,
 		});
+		appendIntegrityEntry("tool_result_delivery_mismatch", {
+			reason,
+			toolNames: progress.toolNames,
+			expectedCount: progress.expectedCount,
+			deliveredCount: progress.deliveredCount,
+			resolvedCount: progress.resolvedCount,
+			waitingIds: progress.waitingIds,
+			queuedIds: progress.queuedIds,
+			unmatchedResultIds: progress.unmatchedResultIds,
+		});
 		safeNotify(
 			`Claude bridge: tool result delivery interrupted during ${reason}; ` +
 			`delivered ${progress.deliveredCount}/${progress.expectedCount}, resolved ${progress.resolvedCount}/${progress.expectedCount}, ` +
 			`waiting=${progress.waitingCount}, queued=${progress.queuedCount}, unmatched=${progress.unmatchedResultCount}` +
 			`${toolNameSummary.length ? `, tools=${toolNameSummary.join(", ")}` : ""}. ` +
-			`Claude session will rebuild before the next turn; see ${diagLogPath()}.`,
+			(queryCtx.detachedFromSharedSession
+				? `Detached one-shot query — shared Claude session record left untouched; ${diagGuidance()}.`
+				: `Claude session will rebuild before the next turn; ${diagGuidance()}.`),
 			"error",
 		);
 		return true;
@@ -128,9 +303,19 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 
 export function __testSetBridgeIntegrityState(state: { ui?: Pick<ExtensionUIContext, "notify"> | null; sharedSession?: SessionState | null }): void {
 	if ("ui" in state) piUI = state.ui as ExtensionUIContext | undefined;
-	if ("sharedSession" in state) sharedSession = state.sharedSession ?? null;
+	if ("sharedSession" in state) {
+		if (currentRequestLaneId() !== undefined) setSharedSession(state.sharedSession ?? null);
+		else {
+			clearSharedSessionLanes();
+			sharedSessionLaneStore().defaultSession = state.sharedSession ?? null;
+		}
+	}
 }
 
 export function __testGetBridgeIntegrityState(): { sharedSession: SessionState | null } {
-	return { sharedSession };
+	return { sharedSession: getSharedSession() };
+}
+
+export function __testSharedSessionLaneCount(): number {
+	return sharedSessionLaneStore().sessions.size;
 }