@junghanacs/entwurf 0.12.5 → 0.12.7

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/config.js

@@ -0,0 +1,436 @@
+// ACP plugin — operator provider-config loader (S2g).
+//
+// THE BASELINE FIX. Before S2g, backend.ts hardcoded `mcpServers:[]`,
+// `settingSources:[]`, `tools:DEFAULT_CLAUDE_TOOLS`, `skillPlugins:[]` — so an
+// operator who wrote `entwurfProvider.mcpServers` / `skillPlugins` into their
+// `.pi/settings.json` (the very surface `./run.sh install` wires up) saw the ACP
+// model boot with 4 tools and no MCP/skills. This module reads that operator
+// config and hands it to the backend so the documented passthrough actually
+// reaches `newSession`.
+//
+// Claude-only scope (NEXT §스코프). Ported from the v0.11.0 behavior oracle
+// (index.ts `loadProviderSettings`/`readSettingsFile` + acp-bridge.ts
+// `normalizeMcpServers`/`enrichMcpServersWithEnvelope`) — structure new, behavior
+// preserved. Codex/Gemini fields (codexDisabledFeatures, …) are out of scope and
+// deliberately NOT carried.
+//
+// PURITY / SIGNATURE contract (NEXT oracle C / 핀1 / GPT `…2f9325` boost):
+//   - `normalizeMcpServers` is pure: a SORTED, validated server list + a sha256
+//     `hash` of its canonical JSON. The HASH (not the name list) is what feeds
+//     `bridgeConfigSignature`, so a change to a server's command/args/env/url/
+//     headers — not just its name — invalidates a reused session.
+//   - `enrichMcpServersWithEnvelope` injects the per-session PI_SESSION_ID /
+//     PI_AGENT_ID into the entwurf-bridge stdio entry. It runs AFTER the hash is
+//     taken (runtime wiring, not config), so a new session id alone never forces
+//     a rebuild.
+//
+// FAIL-LOUD (GPT `…2f9325`): a config the bridge cannot honor must error before
+// the session spawns, never silently degrade (the "warnings make agents flail"
+// anti-pattern):
+//   - bad mcpServers entry           → McpServerConfigError (names the server)
+//   - bad skillPlugins path/manifest → settingsConfigError
+//   - appendSystemPrompt: true       → unsupported (rich context = first-user
+//                                      augment; tiny carrier = engraving)
+//   - strictMcpConfig: false         → unsupported (Hard Rule #4: no ambient MCP)
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+// Defaults are mirrored as local constants (NOT imported from tool-surface.ts):
+// the strip-types gate loads this file by its `.ts` source and cannot resolve a
+// cross-sibling VALUE import. check-acp-config + check-acp-tool-surface keep the
+// two in lockstep behaviorally; a drift would diverge the resolved default
+// surface from the declared one.
+const DEFAULT_TOOLS = ["Read", "Bash", "Edit", "Write"];
+const DEFAULT_PERMISSION_ALLOW = ["Read(*)", "Bash(*)", "Edit(*)", "Write(*)", "mcp__*"];
+const DEFAULT_DISALLOWED_TOOLS = [
+    "AskUserQuestion",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "EnterPlanMode",
+    "EnterWorktree",
+    "ExitPlanMode",
+    "ExitWorktree",
+    "Monitor",
+    "NotebookEdit",
+    "PushNotification",
+    "RemoteTrigger",
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskOutput",
+    "TaskStop",
+    "TaskUpdate",
+    "WebFetch",
+    "WebSearch",
+];
+const GLOBAL_SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+/** Thrown when one or more `mcpServers` entries are structurally invalid. */
+export class McpServerConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid entwurfProvider.mcpServers:\n${issues.map((i) => `  - ${i.server}: ${i.reason}`).join("\n")}`);
+        this.name = "McpServerConfigError";
+        this.issues = issues;
+    }
+}
+/** A settings-file validation error (non-mcpServers fields). */
+export function settingsConfigError(filePath, message) {
+    return new Error(`${filePath}: invalid entwurfProvider settings: ${message}`);
+}
+// ---------------------------------------------------------------------------
+// mcpServers normalization (pure)
+// ---------------------------------------------------------------------------
+function validateKvEntries(server, field, input, issues) {
+    if (input === undefined)
+        return [];
+    const entries = [];
+    if (Array.isArray(input)) {
+        for (let i = 0; i < input.length; i++) {
+            const kv = input[i];
+            if (!kv || typeof kv !== "object" || Array.isArray(kv)) {
+                issues.push({ server, reason: `"${field}[${i}]" must be an object` });
+                return undefined;
+            }
+            const pair = kv;
+            if (typeof pair.name !== "string" || typeof pair.value !== "string") {
+                issues.push({ server, reason: `"${field}[${i}]" must have string "name" and "value"` });
+                return undefined;
+            }
+            entries.push({ name: pair.name, value: pair.value });
+        }
+    }
+    else if (typeof input === "object") {
+        for (const [name, value] of Object.entries(input)) {
+            if (typeof value !== "string") {
+                issues.push({ server, reason: `"${field}.${name}" must be a string` });
+                return undefined;
+            }
+            entries.push({ name, value });
+        }
+    }
+    else {
+        issues.push({ server, reason: `"${field}" must be an object or array of {name,value}` });
+        return undefined;
+    }
+    // Sort by name so a caller-side ordering difference never drifts the hash.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return entries;
+}
+function normalizeMcpServerEntry(name, raw, issues) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        issues.push({ server: name, reason: "server entry must be an object" });
+        return undefined;
+    }
+    const obj = raw;
+    const declaredType = obj.type;
+    let type;
+    if (declaredType === undefined) {
+        type = "stdio";
+    }
+    else if (declaredType === "stdio" || declaredType === "http" || declaredType === "sse") {
+        type = declaredType;
+    }
+    else {
+        issues.push({
+            server: name,
+            reason: `unsupported "type" ${JSON.stringify(declaredType)} (expected "stdio" | "http" | "sse")`,
+        });
+        return undefined;
+    }
+    if (type === "http" || type === "sse") {
+        const url = obj.url;
+        if (typeof url !== "string" || url.length === 0) {
+            issues.push({ server: name, reason: `${type} server requires non-empty "url"` });
+            return undefined;
+        }
+        const headers = validateKvEntries(name, "headers", obj.headers, issues);
+        if (headers === undefined)
+            return undefined;
+        return { type, name, url, headers };
+    }
+    const command = obj.command;
+    if (typeof command !== "string" || command.length === 0) {
+        issues.push({ server: name, reason: `stdio server requires non-empty "command"` });
+        return undefined;
+    }
+    let args = [];
+    if (obj.args !== undefined) {
+        if (!Array.isArray(obj.args)) {
+            issues.push({ server: name, reason: `"args" must be a string array` });
+            return undefined;
+        }
+        for (let i = 0; i < obj.args.length; i++) {
+            if (typeof obj.args[i] !== "string") {
+                issues.push({ server: name, reason: `"args[${i}]" must be a string` });
+                return undefined;
+            }
+        }
+        args = obj.args;
+    }
+    const env = validateKvEntries(name, "env", obj.env, issues);
+    if (env === undefined)
+        return undefined;
+    return { name, command, args, env };
+}
+/**
+ * Normalize an `mcpServers` map into a SORTED, validated server list plus a
+ * sha256 hash of its canonical JSON. Pure. Throws McpServerConfigError listing
+ * every bad entry (so a typo names the offending server, not just "invalid").
+ */
+export function normalizeMcpServers(input) {
+    if (input === undefined || input === null) {
+        return { servers: [], hash: createHash("sha256").update("[]").digest("hex") };
+    }
+    if (typeof input !== "object" || Array.isArray(input)) {
+        throw new McpServerConfigError([
+            {
+                server: "<root>",
+                reason: `mcpServers must be an object (got ${Array.isArray(input) ? "array" : typeof input})`,
+            },
+        ]);
+    }
+    const issues = [];
+    const servers = [];
+    for (const name of Object.keys(input).sort()) {
+        const entry = normalizeMcpServerEntry(name, input[name], issues);
+        if (entry)
+            servers.push(entry);
+    }
+    if (issues.length > 0)
+        throw new McpServerConfigError(issues);
+    const canonical = JSON.stringify(servers);
+    return { servers, hash: createHash("sha256").update(canonical).digest("hex") };
+}
+/**
+ * Inject the per-session entwurf envelope (PI_SESSION_ID + PI_AGENT_ID) into the
+ * `entwurf-bridge` stdio MCP entry so the bridge's MCP child can resolve the
+ * caller identity (entwurf_self / entwurf_v2). Runs AFTER the config hash is
+ * taken — this is runtime wiring, not config, so a new session id alone must not
+ * invalidate a reused session. http/sse have no env carrier; other stdio servers
+ * are left untouched. Pre-existing PI_SESSION_ID/PI_AGENT_ID env are filtered so
+ * the bridge-supplied values always win (mid-session model switch surfaces the
+ * new PI_AGENT_ID at the next spawn).
+ */
+export function enrichMcpServersWithEnvelope(servers, envelope) {
+    const piAgentId = envelope.modelId ? `entwurf/${envelope.modelId}` : undefined;
+    const piSessionId = envelope.piSessionId;
+    if (!piSessionId && !piAgentId)
+        return [...servers];
+    return servers.map((s) => {
+        if ("type" in s && (s.type === "http" || s.type === "sse"))
+            return s;
+        if (s.name !== "entwurf-bridge")
+            return s;
+        const stdio = s;
+        const baseEnv = stdio.env.filter((e) => e.name !== "PI_SESSION_ID" && e.name !== "PI_AGENT_ID");
+        const extras = [];
+        if (piSessionId)
+            extras.push({ name: "PI_SESSION_ID", value: piSessionId });
+        if (piAgentId)
+            extras.push({ name: "PI_AGENT_ID", value: piAgentId });
+        return { ...stdio, env: [...baseEnv, ...extras] };
+    });
+}
+// ---------------------------------------------------------------------------
+// settings file parse + validate
+// ---------------------------------------------------------------------------
+function assertOptionalBoolean(settings, key, filePath) {
+    const value = settings[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw settingsConfigError(filePath, `${key} must be a boolean`);
+    return value;
+}
+function parseStringArray(settings, key, filePath) {
+    const value = settings[key];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+        throw settingsConfigError(filePath, `${key} must be an array of strings`);
+    }
+    return value;
+}
+/**
+ * Validate `skillPlugins` paths: each must be an absolute path to an existing
+ * directory containing `.claude-plugin/plugin.json`. The Claude Agent SDK
+ * silently drops anything else at spawn time — leaving the operator's skill
+ * invisible with no failure signal — so we fail fast here instead (oracle G).
+ */
+export function validateSkillPluginPaths(paths, filePath) {
+    for (let index = 0; index < paths.length; index++) {
+        const pluginPath = paths[index];
+        const label = `skillPlugins[${index}]`;
+        if (!isAbsolute(pluginPath)) {
+            throw settingsConfigError(filePath, `${label} must be an absolute path (got ${JSON.stringify(pluginPath)})`);
+        }
+        let isDir = false;
+        try {
+            isDir = statSync(pluginPath).isDirectory();
+        }
+        catch {
+            throw settingsConfigError(filePath, `${label} does not exist: ${pluginPath}`);
+        }
+        if (!isDir)
+            throw settingsConfigError(filePath, `${label} must point at a directory: ${pluginPath}`);
+        const manifestPath = join(pluginPath, ".claude-plugin", "plugin.json");
+        if (!existsSync(manifestPath)) {
+            throw settingsConfigError(filePath, `${label} is missing .claude-plugin/plugin.json — expected ${manifestPath}. ` +
+                `See README §Custom Skills for the minimum plugin shape.`);
+        }
+    }
+}
+/**
+ * Read + validate the `entwurfProvider` block of one settings file. Returns BOTH
+ * the typed (common) `settings` and the `raw` untyped block — the raw block feeds
+ * `adapter.resolveAdapterSettings` so a backend can read its OWN keys (which the
+ * typed ProviderSettings deliberately drops). Missing file or absent block → empty
+ * both. Malformed JSON / wrong shapes throw a settingsConfigError naming the file.
+ */
+export function readProviderSettingsFile(filePath) {
+    if (!existsSync(filePath))
+        return { settings: {}, raw: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw settingsConfigError(filePath, `malformed JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw settingsConfigError(filePath, "settings file root must be an object");
+    }
+    const block = parsed.entwurfProvider;
+    if (block === undefined)
+        return { settings: {}, raw: {} };
+    if (!block || typeof block !== "object" || Array.isArray(block)) {
+        throw settingsConfigError(filePath, "entwurfProvider must be an object");
+    }
+    const settings = block;
+    // `backend` is the operator's DECLARED backend — a diagnostic guard, NOT the
+    // routing authority (the curated model-id prefix is; see backend-adapter.ts).
+    // config.ts validates only that it is a string and does NOT whitelist values:
+    // the adapter registry owns the set of valid backends, so a new backend never
+    // needs a config.ts edit. The semantic cross-check (declared backend must match
+    // the adapter the model id routes to) lives at the routing site in backend.ts —
+    // keeping config a pure syntactic parser and the model id the SINGLE routing
+    // authority (no duplicate authority).
+    const backendRaw = settings.backend;
+    if (backendRaw !== undefined && typeof backendRaw !== "string") {
+        throw settingsConfigError(filePath, "backend must be a string");
+    }
+    const settingSourcesRaw = settings.settingSources;
+    let settingSources;
+    if (settingSourcesRaw !== undefined) {
+        if (!Array.isArray(settingSourcesRaw))
+            throw settingsConfigError(filePath, "settingSources must be an array");
+        if (!settingSourcesRaw.every((v) => v === "user" || v === "project" || v === "local")) {
+            throw settingsConfigError(filePath, "settingSources entries must be one of: user, project, local");
+        }
+        settingSources = settingSourcesRaw;
+    }
+    const mcpServersRaw = settings.mcpServers;
+    let mcpServers;
+    if (mcpServersRaw !== undefined) {
+        if (!mcpServersRaw || typeof mcpServersRaw !== "object" || Array.isArray(mcpServersRaw)) {
+            throw settingsConfigError(filePath, "mcpServers must be an object");
+        }
+        mcpServers = mcpServersRaw;
+    }
+    const skillPlugins = parseStringArray(settings, "skillPlugins", filePath);
+    if (skillPlugins)
+        validateSkillPluginPaths(skillPlugins, filePath);
+    return {
+        settings: {
+            backend: backendRaw?.trim() || undefined,
+            appendSystemPrompt: assertOptionalBoolean(settings, "appendSystemPrompt", filePath),
+            settingSources,
+            strictMcpConfig: assertOptionalBoolean(settings, "strictMcpConfig", filePath),
+            showToolNotifications: assertOptionalBoolean(settings, "showToolNotifications", filePath),
+            mcpServers,
+            tools: parseStringArray(settings, "tools", filePath),
+            skillPlugins,
+            permissionAllow: parseStringArray(settings, "permissionAllow", filePath),
+            disallowedTools: parseStringArray(settings, "disallowedTools", filePath),
+        },
+        raw: settings,
+    };
+}
+/**
+ * Resolve the effective Claude provider config from global + project settings.
+ *
+ * Merge: project overrides global, but ONLY for keys the project actually sets
+ * (an absent key must not nuke the global value). `mcpServers` is a special
+ * shallow MERGE — `{...global, ...project}` — so a project adds/overrides
+ * individual servers without dropping the global set.
+ *
+ * Fail-loud: `appendSystemPrompt: true` and `strictMcpConfig: false` are
+ * unsupported on this lane (see file header).
+ */
+export function resolveProviderConfig(params) {
+    const globalPath = params.globalSettingsPath ?? GLOBAL_SETTINGS_PATH;
+    const projectPath = params.projectSettingsPath ?? join(params.cwd, ".pi", "settings.json");
+    const { settings: globalSettings, raw: globalRaw } = readProviderSettingsFile(globalPath);
+    const { settings: projectSettings, raw: projectRaw } = readProviderSettingsFile(projectPath);
+    // Project overrides global only for keys it actually defines (undefined =
+    // "unset", which JS spread would otherwise treat as an override).
+    const projectDefined = Object.fromEntries(Object.entries(projectSettings).filter(([, v]) => v !== undefined));
+    const merged = { ...globalSettings, ...projectDefined };
+    if (merged.appendSystemPrompt === true) {
+        throw settingsConfigError(projectSettings.appendSystemPrompt !== undefined ? projectPath : globalPath, "appendSystemPrompt: true is unsupported on acp-on-v2 — rich context rides the first-user augment and the " +
+            "tiny system-prompt carrier is the engraving (ENTWURF_ACP_ENGRAVING_PATH). Remove the key.");
+    }
+    const strictMcpConfig = merged.strictMcpConfig ?? true;
+    if (strictMcpConfig === false) {
+        throw settingsConfigError(projectSettings.strictMcpConfig !== undefined ? projectPath : globalPath, "strictMcpConfig: false is unsupported on acp-on-v2 — ambient MCP inheritance (~/.mcp.json, project .mcp.json, " +
+            "~/.claude settings) is disallowed (Hard Rule #4). Declare every server explicitly under mcpServers.");
+    }
+    const settingSources = merged.settingSources ?? [];
+    const showToolNotifications = merged.showToolNotifications ?? true;
+    const skillPlugins = merged.skillPlugins ?? [];
+    const baseTools = merged.tools ?? [...DEFAULT_TOOLS];
+    const baseAllow = merged.permissionAllow ?? [...DEFAULT_PERMISSION_ALLOW];
+    // When skillPlugins is non-empty the SDK's skill-listing emitter is gated on
+    // `tools.some(name === "Skill")` — without it the listing returns empty and
+    // skills never reach the system prompt, even though the plugin loaded them.
+    // Auto-allow `Skill(*)` too so the listing surface is not denied at the
+    // permission layer (oracle G, verified against claude-agent-sdk 0.2.114/119).
+    const tools = skillPlugins.length > 0 && !baseTools.includes("Skill") ? [...baseTools, "Skill"] : baseTools;
+    const permissionAllow = skillPlugins.length > 0 && !baseAllow.includes("Skill(*)") ? [...baseAllow, "Skill(*)"] : baseAllow;
+    const disallowedTools = merged.disallowedTools ?? [...DEFAULT_DISALLOWED_TOOLS];
+    // mcpServers: shallow per-name merge across global + project, then normalize.
+    const mergedMcpServersRaw = {
+        ...(globalSettings.mcpServers ?? {}),
+        ...(projectSettings.mcpServers ?? {}),
+    };
+    const { servers: mcpServers, hash: mcpServersHash } = normalizeMcpServers(mergedMcpServersRaw);
+    // Backend-OWNED settings seam: the routed adapter parses its own keys off the RAW
+    // blocks (project-over-global merge). The result is opaque to config.ts and backend.ts
+    // — only the adapter's own methods read it. claude returns undefined (no own settings).
+    const adapterSettings = params.adapter.resolveAdapterSettings({
+        globalBlock: globalRaw,
+        projectBlock: projectRaw,
+        mergedBlock: { ...globalRaw, ...projectRaw },
+        globalPath,
+        projectPath,
+    });
+    return {
+        backend: merged.backend,
+        settingSources,
+        strictMcpConfig,
+        showToolNotifications,
+        mcpServers,
+        mcpServersHash,
+        tools,
+        skillPlugins,
+        permissionAllow,
+        disallowedTools,
+        adapterSettings,
+    };
+}
+/** The MCP server names exposed to a session (for engraving + augment). */
+export function mcpServerNames(config) {
+    return config.mcpServers.map((s) => s.name);
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/context.js

@@ -0,0 +1,157 @@
+// ACP plugin — pi Context → ACP prompt conversion (S2c).
+//
+// S2c is spawn-per-turn: every streamSimple call spawns a fresh ACP session, so
+// the backend has NO memory of prior turns. Sending only the last user message
+// would silently drop multi-turn history — that is context loss, not a thin
+// substrate. So this flattens the whole pi conversation into ONE text transcript
+// and sends it as a single ACP user prompt block.
+//
+// S2c/S2d boundary (GPT S2c Q2): this is CONVERSATION TRANSCRIPT PASSTHROUGH, not
+// rich-carrier identity injection. Deliberately EXCLUDED here (all S2d):
+//   - `context.systemPrompt` — never read into the prompt or `_meta.systemPrompt`
+//     (the billing carrier stays absent — NEXT §S2-scout 핀1);
+//   - `~/AGENTS.md` / cwd AGENTS / bridge identity narrative;
+//   - first-user-message augment + project-context de-dup;
+//   - `context.tools` — the ACP child tool surface is the S2b
+//     `_meta.claudeCode.options` SSOT, never re-sent here.
+// Structured tool replay is also excluded: tool calls/results render as plain
+// transcript text, never as ACP tool invocations (the child runs its own tools).
+// MUST equal event-mapper.ts `LIFECYCLE_NOTICE_SIGNATURE` (the SSOT/producer).
+// It is mirrored, not imported: the strip-types deterministic gates load these
+// lib files by their `.ts` source and cannot resolve a cross-sibling VALUE
+// import (`./event-mapper.js`) — the lib modules share TYPES only. The mirror is
+// kept honest behaviorally by check-acp-session-reuse (a drift would leave the
+// `[acp: …]` notices in the captured ACP prompt and fail the gate).
+const LIFECYCLE_NOTICE_SIGNATURE = "entwurf:lifecycle-notice-v1";
+function textFromUserOrToolContent(content) {
+    if (typeof content === "string")
+        return content;
+    // Render text verbatim; images are NOT dropped silently — they leave a text
+    // marker so the transcript honestly records an attachment the text-only S2c
+    // transcript cannot carry (real ACP image passthrough is a later lane).
+    return content
+        .map((c) => {
+        if (c.type === "text")
+            return c.text;
+        if (c.type === "image")
+            return `[image omitted: ${c.mimeType ?? "unknown"}]`;
+        return "";
+    })
+        .filter((s) => s !== "")
+        .join("\n");
+}
+function textFromAssistantContent(content) {
+    // Assistant text only — thinking is omitted and tool calls are not replayed
+    // (the ACP child executes its own tools; replaying structured calls would be
+    // a lie). Tool RESULTS still appear via their own toolResult message below.
+    return (content
+        .filter((c) => c.type === "text")
+        // Drop S2f lifecycle progress notices (`[acp: …]`): display-only, stamped
+        // with LIFECYCLE_NOTICE_SIGNATURE. Replaying them into a `new` rebuild's
+        // full transcript would inject bridge-internal chatter into the ACP prompt.
+        .filter((c) => c.textSignature !== LIFECYCLE_NOTICE_SIGNATURE)
+        .map((c) => c.text)
+        .join(""));
+}
+/** Render one pi message as a transcript line, or undefined to skip it. */
+function renderMessage(message) {
+    switch (message.role) {
+        case "user": {
+            const text = textFromUserOrToolContent(message.content).trim();
+            return text ? `User: ${text}` : undefined;
+        }
+        case "assistant": {
+            const text = textFromAssistantContent(message.content).trim();
+            return text ? `Assistant: ${text}` : undefined;
+        }
+        case "toolResult": {
+            const text = textFromUserOrToolContent(message.content).trim();
+            const tag = message.isError ? "Tool error" : "Tool result";
+            return text ? `${tag} (${message.toolName}): ${text}` : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Flatten a pi Context into a single transcript string. Excludes
+ * `context.systemPrompt` and `context.tools` by construction.
+ */
+export function contextTranscript(context) {
+    const lines = [];
+    for (const message of context.messages) {
+        const line = renderMessage(message);
+        if (line)
+            lines.push(line);
+    }
+    return lines.join("\n\n");
+}
+/**
+ * Convert a pi Context into the ACP `prompt` array (a single text block holding
+ * the flattened transcript). Empty history yields an empty array — the caller
+ * decides whether that is a hard error.
+ */
+export function contextToAcpPrompt(context) {
+    const transcript = contextTranscript(context);
+    if (!transcript)
+        return [];
+    return [{ type: "text", text: transcript }];
+}
+/**
+ * The latest user turn only — the first user message AFTER the last assistant
+ * message. Ported from 0.11.0 `index.ts:732 extractPromptBlocks`: taking the
+ * FIRST user of the trailing group (not `reverse().find()`) skips the
+ * SessionStart hook user-message (`device=…, time_kst=…`) that pi appends AFTER
+ * the real prompt. Images leave a text marker (S2c decision — real ACP image
+ * passthrough is a later lane), never raw data.
+ *
+ * This is the prompt scope for a session that ALREADY holds the prior turns
+ * (reuse/resume/load): re-sending the whole transcript there would duplicate
+ * history the backend already remembers.
+ */
+export function latestUserDelta(context) {
+    let lastAssistantIdx = -1;
+    for (let i = context.messages.length - 1; i >= 0; i--) {
+        if (context.messages[i].role === "assistant") {
+            lastAssistantIdx = i;
+            break;
+        }
+    }
+    const latestUser = context.messages.slice(lastAssistantIdx + 1).find((m) => m.role === "user");
+    if (!latestUser)
+        return [];
+    // The delta IS the user's actual prompt — preserve its body verbatim (0.11.0
+    // extractPromptBlocks sent it near-raw). Only the EMPTINESS test trims, so a
+    // whitespace-only turn yields no block.
+    const raw = textFromUserOrToolContent(latestUser.content);
+    return raw.trim() ? [{ type: "text", text: raw }] : [];
+}
+/**
+ * Build the ACP prompt array for a turn, scoping it by bootstrapPath (핀4):
+ *   - `"new"` (incompatible rebuild included): a fresh ACP session holds NO
+ *     history, so the whole transcript is the only history carrier (same as the
+ *     S2c spawn-per-turn path). Delta-only here would lose history on
+ *     rebuild/compaction/edited-history.
+ *   - `"reuse" | "resume" | "load"`: the stateful ACP session already holds the
+ *     prior turns, so send only the latest user delta — the whole transcript
+ *     would duplicate remembered history.
+ *
+ * The delta-only SAFETY for resume/load is owned by the caller's
+ * `contextMessageSignatures` prefix-compat gate (mismatch → fall back to
+ * `"new"` + full transcript); this pure function only splits the scope.
+ */
+export function buildAcpPrompt(context, bootstrapPath) {
+    switch (bootstrapPath) {
+        case "new":
+            return contextToAcpPrompt(context);
+        case "reuse":
+        case "resume":
+        case "load":
+            return latestUserDelta(context);
+        default:
+            // Fail-loud (핀4): a bad/unknown bootstrapPath must CRASH, never fall
+            // through to delta-only. A silent delta on a path that should carry the
+            // full transcript loses history — fail-OPEN toward the dangerous side.
+            throw new Error(`buildAcpPrompt: unknown bootstrapPath ${JSON.stringify(bootstrapPath)}`);
+    }
+}