pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/src/context-gateway/index.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+	CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE,
+	loadContextGatewayConfig,
+} from "./config.js";
+import { ContextGatewayTelemetry } from "./telemetry.js";
+import type {
+	ContextGatewayEffectiveMode,
+	ContextGatewayMode,
+	ContextGatewayResolvedConfig,
+	ContextGatewayRuntimeState,
+} from "./types.js";
+
+export interface RegisterContextGatewayOptions {
+	loadConfig?: () => ContextGatewayResolvedConfig;
+	telemetry?: ContextGatewayTelemetry;
+}
+
+export interface RegisteredContextGateway extends ContextGatewayRuntimeState {
+	setRuntimeMode(mode: ContextGatewayMode): { ok: boolean; message: string };
+}
+
+function formatStatus(runtime: RegisteredContextGateway): string {
+	const telemetry = runtime.telemetry.snapshot();
+	return [
+		`Context Gateway requested=${runtime.requestedMode}, effective=${runtime.effectiveMode}.`,
+		`Observed results=${telemetry.results}, errors=${telemetry.errors}, upstreamTruncated=${telemetry.upstreamTruncatedResults}, overBudget=${telemetry.overBudgetResults}, unbound results=${telemetry.unboundResults}.`,
+		`Repeat candidates=${telemetry.repeatCandidateCount}, retrieval calls=${telemetry.retrievalCalls}.`,
+		`Native policy results=${telemetry.nativePolicy.results}, refusals=${telemetry.nativePolicy.refusals}, full overrides=${telemetry.nativePolicy.fullOverrides}.`,
+		`Observed contentBytes=${telemetry.contentBytes}, textBytes=${telemetry.textBytes}, detailsBytes=${telemetry.detailsBytes}, potentialBytesOverBudget=${telemetry.potentialBytesOverBudget}.`,
+	].join("\n");
+}
+
+function formatDoctor(runtime: RegisteredContextGateway): string {
+	const lines = [
+		`Context Gateway doctor: requested=${runtime.requestedMode}, effective=${runtime.effectiveMode}.`,
+		"Capture: read=limited; bash=limited+temp-output; repo_*=suite-adapter-not-wired; ast_grep=suite-adapter-not-wired.",
+		"External paths: MCP=current Pix adapter unsupported; direct parent browser capture=unsupported.",
+		"Storage: disabled; no durable archive, index, quota reservation, or retrieval tools are active.",
+	];
+	if (runtime.requestedMode === "enforce") {
+		lines.push("BLOCKED: enforce is unavailable in P01; effective mode is off.");
+	}
+	for (const issue of runtime.config.issues) lines.push(`Config issue: ${issue}`);
+	return lines.join("\n");
+}
+
+function notify(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error" = "info"): void {
+	ctx.ui.notify(message, type);
+}
+
+export function registerContextGateway(
+	pi: ExtensionAPI,
+	options: RegisterContextGatewayOptions = {},
+): RegisteredContextGateway {
+	const config = (options.loadConfig ?? (() => loadContextGatewayConfig()))();
+	const telemetry = options.telemetry ?? new ContextGatewayTelemetry();
+	let requestedMode = config.mode;
+	let effectiveMode: ContextGatewayEffectiveMode = requestedMode === "enforce" ? "off" : requestedMode;
+	const inFlightToolCalls = new Set<string>();
+
+	const resetRuntimeTelemetry = (): void => {
+		inFlightToolCalls.clear();
+		telemetry.reset();
+	};
+
+	const runtime: RegisteredContextGateway = {
+		get requestedMode() { return requestedMode; },
+		get effectiveMode() { return effectiveMode; },
+		config,
+		telemetry,
+		setRuntimeMode(mode) {
+			if (mode === "enforce") {
+				return { ok: false, message: CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE };
+			}
+			if (mode !== effectiveMode && inFlightToolCalls.size > 0) {
+				return {
+					ok: false,
+					message: `Context Gateway mode change requires a safe boundary; ${inFlightToolCalls.size} tool call(s) are still in flight.`,
+				};
+			}
+			requestedMode = mode;
+			effectiveMode = mode;
+			telemetry.clearTransientBindings();
+			return { ok: true, message: `Context Gateway runtime mode set to ${mode}; config was not changed.` };
+		},
+	};
+
+	pi.on("tool_call", async (event) => {
+		if (typeof event.toolCallId === "string") inFlightToolCalls.add(event.toolCallId);
+		if (effectiveMode === "observe") telemetry.recordToolCall(event);
+		return undefined;
+	});
+
+	pi.on("tool_result", async (event) => {
+		try {
+			if (effectiveMode === "observe") telemetry.recordToolResult(event, config.budgets.maxResultBytes);
+		} finally {
+			if (typeof event.toolCallId === "string") inFlightToolCalls.delete(event.toolCallId);
+		}
+		return undefined;
+	});
+
+	pi.on("session_start", async () => {
+		resetRuntimeTelemetry();
+		return undefined;
+	});
+
+	pi.on("session_tree", async () => {
+		resetRuntimeTelemetry();
+		return undefined;
+	});
+
+	pi.on("session_shutdown", async () => {
+		resetRuntimeTelemetry();
+		return undefined;
+	});
+
+	pi.registerCommand("context-gateway", {
+		description: "Show Context Gateway status/doctor output or change the runtime-only off/observe mode.",
+		handler: async (rawArgs, ctx) => {
+			const args = rawArgs.trim().split(/\s+/).filter(Boolean);
+			const action = (args[0] ?? "status").toLowerCase();
+			if (action === "status") {
+				notify(ctx, formatStatus(runtime));
+				return;
+			}
+			if (action === "doctor") {
+				notify(ctx, formatDoctor(runtime), runtime.requestedMode === "enforce" ? "warning" : "info");
+				return;
+			}
+			if (action === "mode") {
+				const mode = args[1]?.toLowerCase() as ContextGatewayMode | undefined;
+				if (mode !== "off" && mode !== "observe" && mode !== "enforce") {
+					notify(ctx, "Usage: /context-gateway mode off|observe|enforce", "error");
+					return;
+				}
+				const result = runtime.setRuntimeMode(mode);
+				notify(ctx, result.message, result.ok ? "info" : "error");
+				return;
+			}
+			notify(ctx, "Usage: /context-gateway status|doctor|mode off|observe|enforce", "error");
+		},
+	});
+
+	return runtime;
+}
+
+export default function contextGatewayExtension(pi: ExtensionAPI): void {
+	registerContextGateway(pi);
+}
+
+export { accountContextGatewayParts } from "./accounting.js";
+export { loadContextGatewayConfig } from "./config.js";
+export { normalizeRedundantTruncationMetadata } from "./metadata-normalization.js";
+export { STORELESS_CAPABILITIES, storelessCapability } from "./storeless-capabilities.js";
+export { parseTestBuildOutput, planProspectiveTestOutputDelivery } from "./test-output-parser.js";
+export { ContextGatewayTelemetry, classifyContextGatewayTool, classifyRoleParts, observeToolResult } from "./telemetry.js";
+export type * from "./types.js";

package/external/pi-tools-suite/src/context-gateway/metadata-normalization.ts

@@ -0,0 +1,88 @@
+export interface TruncationMetadataNormalization {
+	details: unknown;
+	changed: boolean;
+	removedBytes: number;
+}
+
+type ToolResultLike = {
+	toolName?: unknown;
+	content?: unknown;
+	details?: unknown;
+};
+
+const KNOWN_TRUNCATION_TOOLS = new Set([
+	"read",
+	"bash",
+	"shell",
+	"shell_command",
+	"ast_grep",
+]);
+
+// This allowlist is an applicability/compatibility guard, not a provenance or
+// authorization boundary. `tool_result` exposes a tool name but not a trusted
+// owner identity, so a replacement extension can reuse one of these names. The
+// transform is therefore deliberately limited to removing an exact duplicate
+// of delivered text and preserves every other details field; callers must not
+// infer built-in-tool capabilities, trust, lifetime, or access rights from the
+// name/shape match alone.
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function deliveredText(content: unknown): string | undefined {
+	if (!Array.isArray(content)) return undefined;
+	const parts: string[] = [];
+	for (const raw of content) {
+		if (!isRecord(raw)) continue;
+		if (raw.type === "text" && typeof raw.text === "string") parts.push(raw.text);
+	}
+	return parts.length > 0 ? parts.join("") : undefined;
+}
+
+type SdkTruncationShape = Record<string, unknown> & {
+	content: string;
+	truncated: true;
+	truncatedBy: "lines" | "bytes";
+};
+
+function hasSdkTruncationShape(value: Record<string, unknown>): value is SdkTruncationShape {
+	if (value.truncated !== true || typeof value.content !== "string" || value.content.length === 0) return false;
+	if (value.truncatedBy !== "lines" && value.truncatedBy !== "bytes") return false;
+	for (const key of ["totalLines", "totalBytes", "outputLines", "outputBytes", "maxLines", "maxBytes"] as const) {
+		const item = value[key];
+		if (typeof item !== "number" || !Number.isFinite(item) || item < 0) return false;
+	}
+	if (typeof value.lastLinePartial !== "boolean" || typeof value.firstLineExceedsLimit !== "boolean") return false;
+	return true;
+}
+
+/**
+ * Remove only the known redundant truncation payload copied into tool-result
+ * metadata when that payload is also the prefix of the delivered text.
+ *
+ * This intentionally does not normalize arbitrary `details.truncation.content`
+ * fields: custom tools may use a similarly named field for unrelated data.
+ */
+export function normalizeRedundantTruncationMetadata(event: ToolResultLike): TruncationMetadataNormalization {
+	const toolName = typeof event.toolName === "string" ? event.toolName.trim().toLowerCase() : "";
+	if (!KNOWN_TRUNCATION_TOOLS.has(toolName)) return { details: event.details, changed: false, removedBytes: 0 };
+	if (!isRecord(event.details)) return { details: event.details, changed: false, removedBytes: 0 };
+	const truncation = event.details.truncation;
+	if (!isRecord(truncation) || !hasSdkTruncationShape(truncation)) {
+		return { details: event.details, changed: false, removedBytes: 0 };
+	}
+
+	const text = deliveredText(event.content);
+	if (text === undefined || !text.startsWith(truncation.content)) {
+		return { details: event.details, changed: false, removedBytes: 0 };
+	}
+
+	const normalizedTruncation: Record<string, unknown> = { ...truncation };
+	delete normalizedTruncation.content;
+	return {
+		details: { ...event.details, truncation: normalizedTruncation },
+		changed: true,
+		removedBytes: new TextEncoder().encode(truncation.content).byteLength,
+	};
+}

package/external/pi-tools-suite/src/context-gateway/storeless-capabilities.ts

@@ -0,0 +1,89 @@
+export type StorelessCapabilityStatus = "supported" | "limited" | "unsupported";
+export type StorelessCapabilityStrategy = "native-passthrough" | "metadata-only" | "pure-parser-candidate" | "none";
+
+export interface StorelessCapabilityEntry {
+	surface:
+		| "test-build"
+		| "mutation-lsp"
+		| "web-document"
+		| "structured-json"
+		| "subagent-result"
+		| "visual"
+		| "browser-direct"
+		| "mcp-direct";
+	status: StorelessCapabilityStatus;
+	strategy: StorelessCapabilityStrategy;
+	lifetime: "current-result" | "producer-managed" | "visual-message" | "none";
+	reason: string;
+}
+
+/**
+ * Storeless capability claims proven or deliberately limited by P01-R.
+ *
+ * This table is documentation/doctor-ready metadata only. It does not register
+ * adapters, readers, grants, fetchers, parsers, or filesystem capabilities.
+ */
+export const STORELESS_CAPABILITIES: readonly StorelessCapabilityEntry[] = Object.freeze([
+	{
+		surface: "test-build",
+		status: "limited",
+		strategy: "pure-parser-candidate",
+		lifetime: "current-result",
+		reason: "Bun/TAP/bounded TypeScript parsing is observe-only; production delivery remains passthrough without a recovery/lifetime contract.",
+	},
+	{
+		surface: "mutation-lsp",
+		status: "supported",
+		strategy: "native-passthrough",
+		lifetime: "current-result",
+		reason: "Execution outcome, actual changedFiles and appended diagnostics stay in the native tool result; Context Gateway adds no diff or mutation retry.",
+	},
+	{
+		surface: "web-document",
+		status: "limited",
+		strategy: "native-passthrough",
+		lifetime: "current-result",
+		reason: "Existing web tools own fetch, URL/provider metadata and truncation. Storeless Gateway does not refetch, archive, or claim stable pagination of omitted content.",
+	},
+	{
+		surface: "structured-json",
+		status: "limited",
+		strategy: "native-passthrough",
+		lifetime: "current-result",
+		reason: "No generic JSON field-selection adapter is enabled. JSON text/numbers pass through exactly as delivered by the producer.",
+	},
+	{
+		surface: "subagent-result",
+		status: "limited",
+		strategy: "native-passthrough",
+		lifetime: "producer-managed",
+		reason: "The producer already returns a compact result and artifact paths. P01-R neither reads internal history nor grants/extends artifact lifetime by path.",
+	},
+	{
+		surface: "visual",
+		status: "supported",
+		strategy: "native-passthrough",
+		lifetime: "visual-message",
+		reason: "Image parts remain image parts; storeless text accounting/cleanup does not replace them with textual summaries.",
+	},
+	{
+		surface: "browser-direct",
+		status: "unsupported",
+		strategy: "none",
+		lifetime: "none",
+		reason: "Current browser QA executes in a child Pi process without the parent extension result boundary; no direct DOM/network/console Gateway adapter is claimed.",
+	},
+	{
+		surface: "mcp-direct",
+		status: "unsupported",
+		strategy: "none",
+		lifetime: "none",
+		reason: "No supported direct MCP execution/result boundary was proven in P00 for the current Pix adapter.",
+	},
+]);
+
+export function storelessCapability(surface: StorelessCapabilityEntry["surface"]): StorelessCapabilityEntry {
+	const entry = STORELESS_CAPABILITIES.find((candidate) => candidate.surface === surface);
+	if (!entry) throw new Error(`Unknown storeless capability surface: ${surface}`);
+	return entry;
+}