@junghanacs/entwurf 0.12.10 → 0.13.1

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -1,9 +1,10 @@
 // ACP backend adapter rail — the PRODUCT seam by which a curated model id selects
-// which ACP backend (claude / future backend / …) drives a turn. See docs/acp-backend-rail.md §9.
+// which ACP backend (claude / future backend / …) drives a turn. See the adapter contract in
+// docs/acp-backend-rail.md.
 //
 // This seam is DISTINCT from `AcpTurnDeps` (backend.ts), which is the test/runtime
-// seam (fake spawn/connection/clock for the gates). The two are kept apart on
-// purpose (GPT-agreed §9-2): merging them would make a fake-deps fixture look like
+// seam (fake spawn/connection/clock for the gates). Merging them would make a
+// fake-deps fixture look like
 // a fake backend and force the adapter to carry clock/sessionDir/createConnection.
 // The wiring is `defaultDeps(adapter)` — the turn loop in backend.ts stays
 // backend-invariant; only these per-backend functions change with `adapter`.
@@ -19,15 +20,32 @@
 
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import type { AcpConnectionLike } from "./acp-client.js";
-import type { ResolvedAcpConfig } from "./config.js";
+import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
 import { loadEngraving } from "./engraving.js";
-import { curatedClaudeModels, SUPPORTED_ANTHROPIC_MODEL_IDS } from "./models.js";
-import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay } from "./overlay.js";
+import {
+	CORTEX_MODEL_PREFIX,
+	curatedClaudeModels,
+	curatedCortexModels,
+	SUPPORTED_ANTHROPIC_MODEL_IDS,
+	SUPPORTED_CORTEX_MODEL_IDS,
+} from "./models.js";
+import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay, ensureCortexDualHomeOverlay } from "./overlay.js";
 import { buildClaudeSessionMeta } from "./tool-surface.js";
 
+// POSIX-safe single-quote wrapper for shell arg interpolation. Byte-for-byte
+// identical to the reference in entwurf-core.ts; PARITY-PINNED by
+// scripts/check-shell-quote.ts (SOURCE_SITES). Used only by the cortex override
+// path below, where operator-configured connection/model tokens are appended to
+// an operator `bash -lc` string — quoting keeps a connection name with shell
+// metacharacters from being reinterpreted by the shell.
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
 // ---------------------------------------------------------------------------
 // Shared shapes
 // ---------------------------------------------------------------------------
@@ -64,13 +82,19 @@ export interface AcpCarrierParams {
 
 /** ensureOverlay input — cwd + (native) model id + the resolved config. A backend
  *  whose overlay/env depends on its OWN settings reads them off `config.adapterSettings`
- *  here; backend.ts never inspects config. Same shape as AcpLaunchParams (overlay and
- *  launch are distinct phases, so they keep distinct names). */
+ *  here; backend.ts never inspects config. Same shape as AcpLaunchParams plus the
+ *  session key (overlay and launch are distinct phases, so they keep distinct names). */
 export interface AcpOverlayParams {
 	cwd: string;
 	modelId: string;
 	nativeModelId: string;
 	config: ResolvedAcpConfig;
+	/** The AUTHORITATIVE per-session key backend.ts already computed
+	 *  (resolveSessionKey: opts.sessionId → PI_SESSION_ID → cwd). A session-scoped
+	 *  overlay MUST scope on this value, never on an ambient re-derivation — the
+	 *  re-derived form drops `opts.sessionId`, so two sessions in one process/cwd
+	 *  would alias one overlay (GPT review 2026-07-29, cortex P0-1). */
+	sessionKey: string;
 }
 
 /** buildSessionMeta input — mirrors the newSession `_meta` inputs. */
@@ -194,7 +218,7 @@ function resolveClaudeLaunch(): AcpLaunchSpec {
 export const claudeAdapter: AcpBackendAdapter = {
 	backend: "claude",
 
-	// Claude owns its UNPREFIXED curated ids only (GPT-agreed §9-1). The native id
+	// Claude owns its UNPREFIXED curated ids only (rail “Adapter contract”). The native id
 	// equals the curated id — claude carries no curation prefix to strip.
 	routeModel(modelId) {
 		return SUPPORTED_CLAUDE_IDS.has(modelId) ? { nativeModelId: modelId } : undefined;
@@ -270,14 +294,166 @@ export const claudeAdapter: AcpBackendAdapter = {
 // ---------------------------------------------------------------------------
 
 /** Registered adapters. Order carries NO routing authority — routeModel decides.
- *  Step A: claude only. A second backend appends here with its reserved prefix
- *  (e.g. `<backend>-*`), and the fail-fast below proves no two adapters claim one id. */
-const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter];
+ *  claude (unprefixed ids) + cortex (the `cortex-` prefix). A further backend
+ *  appends here with its own reserved prefix; the fail-fast below proves no two
+ *  adapters claim one id. */
+// ---------------------------------------------------------------------------
+// cortex adapter — Snowflake Cortex Code, the first non-claude backend on the
+// rail (docs/acp-backend-rail.md, “Shipped adapters”). It adds ZERO to the common layer:
+// everything cortex-specific lives here + models.ts + overlay.ts + the gates.
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_CORTEX_IDS: ReadonlySet<string> = new Set(SUPPORTED_CORTEX_MODEL_IDS);
+
+/** Cortex's OWN settings: a Snowflake connection name, or null. Opaque to
+ *  config.ts / backend.ts — only cortexAdapter reads it (casting back). */
+export interface CortexAdapterSettings {
+	cortexConnection: string | null;
+}
+
+/** The env var an operator sets to pin a Snowflake connection per-shell without
+ *  editing settings.json. Wins over `entwurfProvider.cortexConnection`. The
+ *  ENTWURF_ACP_* convention (PR #40's legacy PI_SHELL_ACP* cortex-connection var renamed). */
+export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
+
+export const cortexAdapter: AcpBackendAdapter = {
+	backend: "cortex",
+
+	// Cortex owns the reserved `cortex-` prefix (rail “Adapter contract”). routeModel strips it to the
+	// native id: `cortex-auto` → "auto", `cortex-claude-sonnet-5` → "claude-sonnet-5".
+	routeModel(modelId) {
+		if (!SUPPORTED_CORTEX_IDS.has(modelId)) return undefined;
+		return { nativeModelId: modelId.slice(CORTEX_MODEL_PREFIX.length) };
+	},
+
+	curatedModels() {
+		return curatedCortexModels();
+	},
+
+	// Cortex's ONLY own setting is the connection name. env override wins over
+	// settings (per-shell pin); empty/whitespace → null (Cortex falls back to its
+	// own default connection). A non-string settings value fails loud.
+	resolveAdapterSettings({ mergedBlock, projectBlock, globalPath, projectPath }): CortexAdapterSettings {
+		const raw = mergedBlock.cortexConnection;
+		if (raw !== undefined && typeof raw !== "string") {
+			const offending = projectBlock.cortexConnection !== undefined ? projectPath : globalPath;
+			throw new Error(`${offending}: invalid entwurfProvider settings: cortexConnection must be a string`);
+		}
+		const envConn = process.env[CORTEX_CONNECTION_ENV]?.trim();
+		const settingsConn = raw?.trim();
+		const cortexConnection = envConn || settingsConn || null;
+		return { cortexConnection };
+	},
+
+	// `cortex acp serve` resolved from PATH (the CLI itself IS the ACP server — no
+	// `*-acp` npm package, unlike claude). `-c <conn>` appended when a connection
+	// is pinned. NO `-m`: the model is enforced per-turn via
+	// session/set_config_option (enforceModel below, CP0-M measured GO) and a
+	// launch pin would be a SECOND model authority that drifts from it.
+	// CORTEX_ACP_COMMAND override runs via `bash -lc` with the selection flags
+	// appended so the bridge's choice wins (later yargs args override earlier ones).
+	resolveLaunch({ config }) {
+		const settings = config.adapterSettings as CortexAdapterSettings | undefined;
+		const connection = settings?.cortexConnection?.trim() || undefined;
+		const selectionArgs: string[] = [];
+		if (connection) selectionArgs.push("-c", connection);
+		const override = process.env.CORTEX_ACP_COMMAND?.trim();
+		if (override) {
+			const command = selectionArgs.length > 0 ? `${override} ${selectionArgs.map(shellQuote).join(" ")}` : override;
+			return { command: "bash", args: ["-lc", command] };
+		}
+		return { command: "cortex", args: ["acp", "serve", ...selectionArgs] };
+	},
+
+	// The overlay location is SESSION-SCOPED (never static), so the spawn env
+	// rides ensureOverlay(...).envOverrides; there is no static launch env. The
+	// v1.1.8-era CORTEX_DISABLE_AUTO_APPLY_PROFILES knob was retired with the
+	// dual-HOME redesign: profiles now live inside the overlay-owned isolated
+	// home (empty by construction), and the knob is unmeasured on v1.1.52.
+	launchEnvDefaults() {
+		return {};
+	},
+
+	// Dual-HOME containment (CP0 D2/D3/D9/D10 — see the overlay module header):
+	// refuse an ambient CORTEX_HOME outright, then materialize the session-scoped
+	// isolated HOME with auth symlinks, `autoUpdate:false`, and the mcp.json
+	// projection of the envelope-enriched explicit servers (cortex ignores the
+	// wire mcpServers param, so this file IS how tools reach a cortex session).
+	ensureOverlay({ modelId, config, sessionKey }) {
+		// D3 — presence refusal, empty string included: upstream's resolver treats
+		// a set-but-empty CORTEX_HOME differently from unset, and one ambient value
+		// would silently bypass SNOWFLAKE_HOME (the probe's CLAUDE_CODE_EXECUTABLE
+		// precondition is the same family). Refuse the ambiguity; never pick a side.
+		if ("CORTEX_HOME" in process.env) {
+			throw new Error(
+				"entwurf: CORTEX_HOME is present in the environment (empty string included) — it overrides " +
+					"SNOWFLAKE_HOME inside cortex and would bypass the dual-HOME overlay entirely (CP0 D3). " +
+					"Unset it to run a cortex ACP turn.",
+			);
+		}
+		// The scope authority is the AUTHORITATIVE params.sessionKey backend.ts
+		// computed — never an ambient re-derivation, which would drop opts.sessionId
+		// and alias two same-process/cwd sessions onto one overlay (P0-1). The
+		// envelope below still reads PI_SESSION_ID: that is the identity CARRIER for
+		// the bridge child (the same source the turn loop's wire enrichment uses),
+		// a different axis from overlay-dir scoping.
+		const piSessionId = process.env.PI_SESSION_ID?.trim() || undefined;
+		const enriched = enrichMcpServersWithEnvelope(config.mcpServers, { modelId, piSessionId });
+		const overlay = ensureCortexDualHomeOverlay({
+			scopeKey: sessionKey,
+			mcpServers: enriched,
+			realHome: homedir(),
+		});
+		return { envOverrides: { HOME: overlay.home, SNOWFLAKE_HOME: overlay.snowflakeHome } };
+	},
+
+	// System-prompt-carrier-less (ACP rail “Cortex Code audit”): Cortex ACP exposes no
+	// `_meta.systemPrompt` and has no developer_instructions / GEMINI_SYSTEM_MD
+	// equivalent. (It does READ `_meta` — a caller-session-id seam, measured but
+	// unexplored and deliberately not part of this contract.) loadCarrier returns
+	// null WITHOUT calling loadEngraving, so the cortex turn never touches the
+	// shipped-engraving / appendSystemPrompt signature; buildSessionMeta returns
+	// undefined so backend.ts omits the `_meta` key entirely. The operator
+	// engraving instead rides the first-user augment (augment.ts).
+	loadCarrier() {
+		return null;
+	},
+
+	buildSessionMeta() {
+		return undefined;
+	},
+
+	// Per-turn enforcement via session/set_config_option — the SAME wire call the
+	// claude adapter makes, measured live against cortex v1.1.52 (CP0-M): the
+	// option id is "model", accepted values are the NATIVE ids (`auto`,
+	// `claude-sonnet-5`, `openai-gpt-5.4`, …), and a value cortex no longer
+	// serves fails loud BEFORE the prompt (`Unsupported model: …`). PR #40's
+	// launch-time `-m` pin was retired for this: set-model is the single model
+	// authority (resolveLaunch never passes `-m`), and "auto" is set explicitly
+	// rather than treated as an unspoken default.
+	async enforceModel({ connection, acpSessionId, nativeModelId, modelId }) {
+		const setConfig = connection.setSessionConfigOption;
+		if (typeof setConfig !== "function") {
+			throw new Error(`setSessionConfigOption unsupported — cannot enforce model ${modelId}`);
+		}
+		await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
+	},
+
+	// A connection change must invalidate a reused session (rail: Adapter contract). Flat,
+	// sorted-stable primitive map; reads ONLY the opaque adapterSettings. `backend`
+	// + `nativeModelId` are added by backend.ts.
+	configSignatureFields(adapterSettings) {
+		const settings = adapterSettings as CortexAdapterSettings | undefined;
+		return { cortexConnection: settings?.cortexConnection ?? null };
+	},
+};
+
+const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];
 
 /**
  * Resolve the backend adapter that owns `modelId`.
  *
- * GPT-agreed §9-1 fail-fast contract:
+ * Routing fail-fast contract (rail “Adapter contract”):
  *  - 0 matches  → throw (unknown model — no silent default).
  *  - 2+ matches → throw (prefix collision — a startup-visible registry bug).
  *
@@ -301,7 +477,7 @@ export function resolveAcpBackendAdapter(modelId: string): { adapter: AcpBackend
 }
 
 /** Every curated model row across all registered adapters — for provider registration.
- *  GPT-agreed §9-6 registration-time fail-fast: every curated id must route to EXACTLY
+ *  Registration-time fail-fast (rail “Adapter contract”): every curated id must route to EXACTLY
  *  one adapter and no id may be duplicated across adapters. Catching it here means a
  *  prefix-collision / duplicate surfaces at provider registration, not mid-turn. */
 export function allCuratedModels(): AcpModelRow[] {