@junghanacs/entwurf 0.12.10 → 0.13.0

package/scripts/check-shell-quote.ts

@@ -5,9 +5,10 @@
  * SSH command strings with `JSON.stringify`, which is NOT a shell-safe escape.
  * Backticks and `$(...)` inside a user prompt got executed by the remote shell
  * before pi ever saw them. The fix introduced `shellQuote()` (POSIX `'...'`
- * with `'\''` escape) in two places:
- *   - pi-extensions/lib/entwurf-core.ts (the one remaining site; the entwurf.ts /
+ * with `'\''` escape) in:
+ *   - pi-extensions/lib/entwurf-core.ts (the one remaining core site; the entwurf.ts /
  *     entwurf-async.ts siblings this once cross-checked were removed in 0.12)
+ *   - pi-extensions/lib/acp/backend-adapter.ts (cortex CORTEX_ACP_COMMAND override arg quoting)
  *
  * This script enforces two invariants:
  *   1. `shellQuote()` source matches the reference implementation byte-for-byte.
@@ -15,7 +16,6 @@
  *      payload classes that caused the original incident — backtick command
  *      substitution, `$(...)` command substitution, `$VAR` expansion, embedded
  *      single quotes, whitespace, empty string, non-ASCII text.
- *
  * No process spawn, no SSH, no API. Pure-string verification — safe in `pnpm
  * check` chain.
  */
@@ -38,7 +38,7 @@ const REFERENCE_BODY = `function shellQuote(value: string): string {
 \treturn \`'\${value.replace(/'/g, \`'\\\\''\`)}\`;
 }`;
 
-const SOURCE_SITES = ["pi-extensions/lib/entwurf-core.ts"] as const;
+const SOURCE_SITES = ["pi-extensions/lib/entwurf-core.ts", "pi-extensions/lib/acp/backend-adapter.ts"] as const;
 
 // Match the function block from `function shellQuote` up to the closing brace.
 // Tab indentation is required (matches the rest of the repo).

package/scripts/fixtures/probe-cli-shim

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// §11-7-c B-name-snapshot producer — the launcher the SDK actually execs.
+//
+// EXTENSIONLESS ON PURPOSE, and that is a contract, not a style choice. The SDK
+// picks its launch branch off a pure suffix test: a path ending in one of
+// SDK_SCRIPT_SUFFIXES (.js/.mjs/.tsx/.ts/.jsx) is run as `node|bun <path>`, and
+// anything else is spawned DIRECTLY. The probe asserts the native branch instead
+// of reproducing the interpreter choice (probe-cli-target.ts), so the instrument
+// itself has to sit on that branch too — hence no extension, a shebang, and the
+// executable bit tracked in git. Renaming this file to *.js would silently move
+// the shim onto the other launch branch.
+//
+// It stays two lines because an extensionless file is outside `tsc --noEmit` and
+// outside biome: every behaviour worth typechecking, linting and mutating lives
+// in ../lib/probe-cli-shim.ts, which check-probe-cli-shim drives as a real
+// process. Node >=24 (package.json engines) with "type": "module" resolves this
+// file as ESM and strips types from the imported .ts SSOT.
+import { runProbeCliShim } from "../lib/probe-cli-shim.ts";
+
+runProbeCliShim();

package/scripts/fixtures/probe-mcp-server.ts

@@ -1,4 +1,5 @@
-// Tiny stdio MCP server used ONLY by smoke-acp-mcp-live (S2g LIVE 1).
+// Tiny stdio MCP server used by smoke-acp-mcp-live (S2g LIVE 1) and by the
+// §11-7 ordering probe (smoke-acp-ordering-probe-live).
 //
 // It exposes ONE tool — `probe_nonce` — that returns a per-run secret nonce
 // supplied via the PROBE_NONCE env var. The smoke registers this server in a
@@ -9,25 +10,180 @@
 // is broken (the pre-S2g hardcoded `mcpServers:[]`), the tool never exists and
 // the nonce cannot appear.
 //
+// §11-7 ordering-probe mode — active ONLY when PROBE_MCP_EVENT_LOG is set
+// (smoke-acp-mcp-live never sets it, so its behavior is unchanged):
+//   - PROBE_MCP_STARTUP_DELAY_MS delays the transport connect — the controlled
+//     input the probe injects instead of trying to observe a window that has no
+//     observable signal on this server's ACP surface;
+//   - the tool takes a REQUIRED `probeRunId` argument, the cross-layer join key
+//     (§11-7: the ACP toolCallId and the MCP JSON-RPC id share no namespace, so
+//     correlation must ride an argument we control);
+//   - every wire step appends to the shared NDJSON event log, including THE
+//     wire-availability marker `tools_list_response_forwarded`, emitted only
+//     after the ENTIRE tools/list response frame was write()-n to downstream
+//     stdio AND the write callback fired. The SDK's own send() resolves on
+//     buffered-write/drain — NOT the write callback — which is exactly the
+//     false-green §11-7 forbids, so probe mode swaps in a callback-forwarding
+//     transport instead of trusting send().
+//
 // Lives under the repo's scripts/fixtures/ so its `@modelcontextprotocol/sdk`
 // import resolves against the repo node_modules even though the server is spawned
 // (by the claude ACP child) with an arbitrary scratch cwd. Deliberately minimal:
-// no identity / env coupling beyond PROBE_NONCE, so a failure isolates to "did
-// the operator mcpServers reach newSession" — not to entwurf-bridge wiring.
+// no identity / env coupling beyond the PROBE_* vars, so a failure isolates to
+// "did the operator mcpServers reach newSession" — not to entwurf-bridge wiring.
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
+import { z } from "zod";
+import {
+	appendProbeEvent,
+	PROBE_EXPECTED_TOOL as EXPECTED_TOOL,
+	PROBE_ENV,
+	PROBE_EVENTS,
+	type ProbeEventName,
+} from "../lib/probe-event-log.ts";
+
+const eventLog = process.env[PROBE_ENV.eventLog];
+const probeMode = typeof eventLog === "string" && eventLog.length > 0;
+const runId = process.env[PROBE_ENV.runId] ?? "unknown-run";
+const startupDelayMs = Math.max(0, Number(process.env[PROBE_ENV.startupDelayMs] ?? "0") || 0);
+
+function emit(event: ProbeEventName, payload: Record<string, unknown> = {}): void {
+	if (probeMode && eventLog) appendProbeEvent(eventLog, runId, event, payload);
+}
+
+// ---------------------------------------------------------------------------
+// §11-7 instrumented transport — write-callback semantics + wire markers.
+// ---------------------------------------------------------------------------
+
+type JsonRpcMessage = {
+	id?: string | number;
+	method?: string;
+	params?: { name?: string; arguments?: Record<string, unknown> };
+	result?: { tools?: Array<{ name?: string }> };
+};
+
+class InstrumentedStdioServerTransport extends StdioServerTransport {
+	// JSON-RPC request id → method, so a response frame can be attributed to the
+	// request that caused it (the response itself carries no method).
+	private readonly pendingMethods = new Map<string | number, string>();
+
+	constructor() {
+		super();
+		// The SDK protocol layer assigns `transport.onmessage = handler` after
+		// connect; the base class reads `this.onmessage`. Intercept the assignment
+		// so every inbound frame is stamped BEFORE the handler runs — receipt
+		// markers, not handler-return markers. Installed via defineProperty because
+		// the base declares `onmessage` as a plain property (TS2611 forbids a
+		// static accessor override) yet never assigns it in its constructor, so an
+		// instance accessor here wins cleanly.
+		let raw: ((message: unknown, extra?: unknown) => void) | undefined;
+		const stampInbound = (msg: JsonRpcMessage) => this.stampInbound(msg);
+		Object.defineProperty(this, "onmessage", {
+			get(): ((message: unknown, extra?: unknown) => void) | undefined {
+				if (!raw) return undefined;
+				return (message: unknown, extra?: unknown) => {
+					stampInbound(message as JsonRpcMessage);
+					raw?.(message, extra);
+				};
+			},
+			set(handler: ((message: unknown, extra?: unknown) => void) | undefined) {
+				raw = handler;
+			},
+		});
+	}
+
+	private stampInbound(msg: JsonRpcMessage): void {
+		if (typeof msg?.method !== "string") return;
+		if (msg.id !== undefined) this.pendingMethods.set(msg.id, msg.method);
+		if (msg.method === "initialize") {
+			emit(PROBE_EVENTS.fixtureInitializeReceived, { jsonrpcId: msg.id });
+		} else if (msg.method === "tools/list") {
+			emit(PROBE_EVENTS.fixtureToolsListReceived, { jsonrpcId: msg.id });
+		} else if (msg.method === "tools/call") {
+			emit(PROBE_EVENTS.fixtureToolsCallReceived, {
+				jsonrpcId: msg.id,
+				tool: msg.params?.name,
+				probeRunId: msg.params?.arguments?.probeRunId,
+			});
+		}
+	}
+
+	// Write with the CALLBACK, not the buffered-return the SDK send() settles
+	// for: the callback fires when the frame reached the OS pipe, which is the
+	// §11-7 definition of "forwarded". Markers are emitted inside the callback
+	// so they can never precede the hand-off they claim — and ONLY on a
+	// SUCCESSFUL callback: an errored write (EPIPE, closed stream) must reject,
+	// never stamp, or the marker would claim a hand-off that did not happen.
+	override send(message: unknown): Promise<void> {
+		const json = serializeMessage(message as never);
+		return new Promise((resolve, reject) => {
+			(this as unknown as { _stdout: NodeJS.WriteStream })._stdout.write(json, (err?: Error | null) => {
+				if (err) {
+					reject(err);
+					return;
+				}
+				this.stampOutbound(message as JsonRpcMessage);
+				resolve();
+			});
+		});
+	}
+
+	private stampOutbound(msg: JsonRpcMessage): void {
+		if (msg?.id === undefined || typeof msg.method === "string") return;
+		const requestMethod = this.pendingMethods.get(msg.id);
+		if (requestMethod === undefined) return;
+		this.pendingMethods.delete(msg.id);
+		if (requestMethod === "tools/list") {
+			const toolNames = (msg.result?.tools ?? []).map((t) => t?.name).filter((n): n is string => !!n);
+			if (toolNames.includes(EXPECTED_TOOL)) {
+				emit(PROBE_EVENTS.toolsListResponseForwarded, { jsonrpcId: msg.id, tools: toolNames });
+			}
+		} else if (requestMethod === "tools/call") {
+			emit(PROBE_EVENTS.fixtureToolsCallReplied, { jsonrpcId: msg.id });
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Server — one tool in both modes; probe mode adds the REQUIRED join key.
+// ---------------------------------------------------------------------------
+
+emit(PROBE_EVENTS.fixtureProcessStart, { startupDelayMs });
 
 const server = new McpServer({ name: "probe", version: "0.0.1" });
 
-server.tool(
-	"probe_nonce",
-	"Return this session's secret probe nonce. Call this when asked for the probe nonce.",
-	{},
-	async () => ({
-		content: [{ type: "text", text: `PROBE_NONCE=${process.env.PROBE_NONCE ?? "MISSING"}` }],
-	}),
-);
+if (probeMode) {
+	server.tool(
+		EXPECTED_TOOL,
+		"Return this session's secret probe nonce. Call this when asked for the probe nonce, " +
+			"passing the exact probeRunId given in the prompt.",
+		{ probeRunId: z.string().describe("The exact probeRunId string given in the prompt.") },
+		async () => ({
+			content: [{ type: "text", text: `PROBE_NONCE=${process.env[PROBE_ENV.nonce] ?? "MISSING"}` }],
+		}),
+	);
+} else {
+	server.tool(
+		EXPECTED_TOOL,
+		"Return this session's secret probe nonce. Call this when asked for the probe nonce.",
+		{},
+		async () => ({
+			content: [{ type: "text", text: `PROBE_NONCE=${process.env[PROBE_ENV.nonce] ?? "MISSING"}` }],
+		}),
+	);
+}
+
+// The injected startup delay sits BEFORE the transport exists at all — the
+// probe's controlled input models a slow-to-serve MCP server, so nothing may be
+// readable on the wire until the delay elapses.
+if (startupDelayMs > 0) {
+	emit(PROBE_EVENTS.fixtureDelayStart, { delayMs: startupDelayMs });
+	await new Promise((resolve) => setTimeout(resolve, startupDelayMs));
+	emit(PROBE_EVENTS.fixtureDelayEnd, { delayMs: startupDelayMs });
+}
 
-const transport = new StdioServerTransport();
+const transport = probeMode ? new InstrumentedStdioServerTransport() : new StdioServerTransport();
 await server.connect(transport);
+emit(PROBE_EVENTS.fixtureTransportConnected, {});

package/scripts/lib/probe-acp-turn.ts

@@ -0,0 +1,207 @@
+// §11-7 ordering probe — the ACP-side turn driver (probe-dedicated raw client).
+//
+// §11-7 names two client seams and requires picking one explicitly. This lane
+// picks the RAW CLIENT (not the stdio wire proxy), so it carries §11-7's bound:
+// it is NOT the production path and must be gated as issuing the SAME calls,
+// arguments, and order as the backend's real sequence (backend.ts runNewTurn) —
+// otherwise the probe measures a lookalike. check-probe-ordering is that gate;
+// it drives this exact function over a recording fake connection.
+//
+// Production values arrive through the `adapter` / `enrichMcpServers` seams —
+// the LIVE runner tsc-emits pi-extensions and injects the REAL claudeAdapter +
+// enrichMcpServersWithEnvelope (backend-adapter.ts carries `.js` value imports,
+// so it is not strip-types-loadable from here; the emit-then-import pattern is
+// the house one, see check-acp-session-reuse). This module therefore holds ONLY
+// the orchestration backend.ts owns: phase order, arg assembly, timeouts, and
+// phase-attributed failure — each pinned against backend.ts source by the gate
+// so production drift turns the gate red instead of silently unbinding the probe.
+//
+// Every phase start/end is stamped into the shared NDJSON log — including
+// set-model, because §11-7 measured that dropping it misreads an enforceModel
+// stall as C or D.
+
+import { PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
+import type { AcpConnectionLike } from "../../pi-extensions/lib/acp/acp-client.ts";
+import type { ResolvedAcpConfig } from "../../pi-extensions/lib/acp/config.ts";
+import { PROBE_EVENTS, type ProbeEventName } from "./probe-event-log.ts";
+
+export interface ProbePhaseTimeouts {
+	initializeMs: number;
+	newSessionMs: number;
+	setModelMs: number;
+	promptMs: number;
+}
+
+// Phase timeouts — MUST equal backend.ts's INITIALIZE/NEW_SESSION/SET_MODEL/
+// PROMPT_TIMEOUT_MS (check-probe-ordering pins them against the source). §11-7:
+// a D verdict is only readable against these boundaries, so the probe may not
+// invent its own.
+export const PROBE_PHASE_TIMEOUTS: ProbePhaseTimeouts = {
+	initializeMs: 30_000,
+	newSessionMs: 30_000,
+	setModelMs: 30_000,
+	promptMs: 600_000,
+};
+
+/** The two adapter methods the turn drives — satisfied by the REAL claudeAdapter
+ *  (emitted) in the LIVE runner and by recording stubs in the gate. */
+export interface ProbeAdapterSeam {
+	buildSessionMeta(
+		params: { modelId: string; nativeModelId: string; config: ResolvedAcpConfig },
+		carrier: string | null,
+	): Record<string, unknown> | undefined;
+	enforceModel(params: {
+		connection: AcpConnectionLike;
+		acpSessionId: string;
+		modelId: string;
+		nativeModelId: string;
+	}): Promise<void>;
+}
+
+/** Production's enrichMcpServersWithEnvelope shape (config.ts). */
+export type ProbeMcpEnricher = (
+	servers: ResolvedAcpConfig["mcpServers"],
+	envelope: { modelId?: string; piSessionId?: string },
+) => ResolvedAcpConfig["mcpServers"];
+
+/** The turn phases in production order. `initialize` failures are P0/I0 input
+ *  (run-invalidating), the rest map to phase-qualified D readings. */
+export type ProbeTurnPhase = "initialize" | "newSession" | "enforceModel" | "prompt";
+
+/** A phase-attributed turn failure — the classifier needs WHICH wire step died,
+ *  never just that the turn died. */
+export class ProbePhaseError extends Error {
+	readonly phase: ProbeTurnPhase;
+	readonly timedOut: boolean;
+
+	constructor(phase: ProbeTurnPhase, cause: Error, timedOut: boolean) {
+		super(`${phase}: ${cause.message}`);
+		this.phase = phase;
+		this.timedOut = timedOut;
+		this.cause = cause;
+	}
+}
+
+class PhaseTimeoutError extends Error {}
+
+// Same guard shape as backend.ts withTimeout / smoke-acp-raw-turn-live: always
+// clear the timer so a passing turn cannot pin the event loop on a stale timer.
+function withPhaseTimeout<T>(label: string, p: Promise<T>, ms: number): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new PhaseTimeoutError(`${label} timed out after ${ms}ms`)), ms);
+	});
+	return Promise.race([p, timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+export interface ProbeTurnParams {
+	cwd: string;
+	modelId: string;
+	nativeModelId: string;
+	config: ResolvedAcpConfig;
+	/** Production carrier (adapter.loadCarrier result) — folded into `_meta` by
+	 *  buildSessionMeta so the probe's newSession matches production shape. */
+	carrier: string | null;
+	promptText: string;
+	adapter: ProbeAdapterSeam;
+	enrichMcpServers: ProbeMcpEnricher;
+	log: (event: ProbeEventName, payload?: Record<string, unknown>) => void;
+	timeouts?: ProbePhaseTimeouts;
+}
+
+export interface ProbeTurnResult {
+	acpSessionId: string;
+	stopReason: string | undefined;
+}
+
+async function runPhase<T>(
+	phase: ProbeTurnPhase,
+	startEvent: ProbeEventName,
+	endEvent: ProbeEventName,
+	log: ProbeTurnParams["log"],
+	ms: number,
+	body: () => Promise<T>,
+): Promise<T> {
+	log(startEvent, { timeoutMs: ms });
+	try {
+		const result = await withPhaseTimeout(phase, body(), ms);
+		log(endEvent, { ok: true });
+		return result;
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		const timedOut = error instanceof PhaseTimeoutError;
+		log(endEvent, { ok: false, timedOut, error: error.message });
+		throw new ProbePhaseError(phase, error, timedOut);
+	}
+}
+
+/**
+ * Drive ONE production-shaped turn over an already-connected ACP connection:
+ *
+ *   initialize → newSession → enforceModel(setSessionConfigOption) → prompt
+ *
+ * The connection seam is `AcpConnectionLike` — the same seam backend.ts drives —
+ * so the sameness gate runs this function over a recording fake with zero
+ * launch/IO coupling.
+ */
+export async function driveProbeTurn(connection: AcpConnectionLike, params: ProbeTurnParams): Promise<ProbeTurnResult> {
+	const t = params.timeouts ?? PROBE_PHASE_TIMEOUTS;
+	const log = params.log;
+
+	await runPhase("initialize", PROBE_EVENTS.initializeStart, PROBE_EVENTS.initializeEnd, log, t.initializeMs, () =>
+		connection.initialize({
+			protocolVersion: PROTOCOL_VERSION,
+			clientCapabilities: {},
+			clientInfo: { name: "entwurf", version: "s2d" },
+		}),
+	);
+
+	// _meta + wire servers exactly as backend.ts assembles them (S2g/§9-4): the
+	// injected production buildSessionMeta (omitted key when undefined) + the
+	// injected production envelope enrichment over the resolved config.
+	const sessionMeta = params.adapter.buildSessionMeta(
+		{ modelId: params.modelId, nativeModelId: params.nativeModelId, config: params.config },
+		params.carrier,
+	);
+	const wireMcpServers = params.enrichMcpServers(params.config.mcpServers, {
+		modelId: params.modelId,
+		piSessionId: process.env.PI_SESSION_ID?.trim() || undefined,
+	});
+	const newSessionArgs =
+		sessionMeta === undefined
+			? { cwd: params.cwd, mcpServers: wireMcpServers }
+			: { cwd: params.cwd, mcpServers: wireMcpServers, _meta: sessionMeta };
+
+	const created = await runPhase(
+		"newSession",
+		PROBE_EVENTS.newSessionStart,
+		PROBE_EVENTS.newSessionEnd,
+		log,
+		t.newSessionMs,
+		() => connection.newSession(newSessionArgs),
+	);
+	const acpSessionId = created?.sessionId;
+	if (!acpSessionId) {
+		throw new ProbePhaseError("newSession", new Error("newSession returned no sessionId"), false);
+	}
+
+	await runPhase("enforceModel", PROBE_EVENTS.setModelStart, PROBE_EVENTS.setModelEnd, log, t.setModelMs, () =>
+		params.adapter.enforceModel({
+			connection,
+			acpSessionId,
+			modelId: params.modelId,
+			nativeModelId: params.nativeModelId,
+		}),
+	);
+
+	const promptResult = await runPhase("prompt", PROBE_EVENTS.promptStart, PROBE_EVENTS.promptEnd, log, t.promptMs, () =>
+		connection.prompt({
+			sessionId: acpSessionId,
+			prompt: [{ type: "text", text: params.promptText }],
+		}),
+	);
+
+	return { acpSessionId, stopReason: promptResult?.stopReason };
+}