@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/runtime/mcp-auth-proxy.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * MCP AUTH PROXY — extracted from 20x `src/main/mcp-auth-proxy.ts`.
+ *
+ * WHY IT EXISTS, unchanged from the original: ACP, OpenCode and Claude Code all
+ * bake MCP server headers at SESSION start and none of them refresh those
+ * headers mid-session. A one-hour token therefore expires during a long agent
+ * run, and every MCP tool call after that point returns 401 with no recovery
+ * path — the session is alive, the model keeps trying, and every tool fails
+ * until a human notices. This proxy decouples token lifetime from session
+ * lifetime by fetching a fresh token PER REQUEST.
+ *
+ * AND IT MATTERS EVEN MORE ON A RUNNER. The agent is pointed at
+ * `127.0.0.1:<port>/<id>`, so the real gateway URL and the real token never
+ * appear in an MCP config file, in a backend's session state, or in anything
+ * the agent can read. The token is in this process's memory and nowhere else.
+ *
+ * WHAT CHANGED IN THE EXTRACTION
+ * - `enterpriseAuth.getJwt()` became the `TokenInjector` port, so the desktop
+ *   passes its enterprise JWT and a runner passes the session-scoped MCP token
+ *   from the lease.
+ * - `new Notification(...)` on a token failure became the `Notifier` port, a
+ *   no-op on a server.
+ * - Module-level singletons (`let server`, `let port`, three Maps and a
+ *   counter) became instance state. The original could only ever have ONE proxy
+ *   per process, which is correct for a desktop with one signed-in user and
+ *   wrong for a runner that may hold several sessions with DIFFERENT tokens.
+ *   Sharing one proxy across sessions there would let session A's agent reach
+ *   session B's targets by guessing a small integer id.
+ * - Ids are random, not `nextId++`. See `registerTarget`.
+ *
+ * ON "THE HARNESS MUST NEVER OPEN A LISTENING PORT": this binds 127.0.0.1 ONLY,
+ * exactly as the health check does. The property that rule protects is that
+ * nothing outside the host can initiate a connection to the harness, so a
+ * customer VM behind NAT needs no tunnel. A loopback socket is not reachable
+ * from the network and does not weaken it. Binding 0.0.0.0 here WOULD, and the
+ * test suite asserts the bind address.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpAuthProxy = void 0;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const node_crypto_1 = require("node:crypto");
+class McpAuthProxy {
+    options;
+    server = null;
+    port = null;
+    targets = new Map();
+    /** Reverse lookup, so re-registering the same URL does not leak ids. */
+    idsByUrl = new Map();
+    /** One notification per integration per process, not one per failed call. */
+    notifiedFailures = new Set();
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? console;
+    }
+    getPort() {
+        return this.port;
+    }
+    /**
+     * Register a real MCP URL and get back a loopback URL that injects a fresh
+     * token on every forwarded request. Returns null when the proxy is not running.
+     *
+     * IDS ARE RANDOM, where the 20x original used `String(nextId++)`. A
+     * monotonic counter is fine for a desktop with a single user, but on a runner
+     * holding several sessions it means session A can reach session B's targets by
+     * requesting `/1`, `/2`, `/3` — and the proxy would dutifully attach B's
+     * token. 16 random bytes makes that unguessable. It costs nothing.
+     */
+    registerTarget(targetUrl, label) {
+        if (!this.port) {
+            return null;
+        }
+        const existingId = this.idsByUrl.get(targetUrl);
+        if (existingId) {
+            if (label) {
+                const target = this.targets.get(existingId);
+                if (target) {
+                    target.label = label;
+                }
+            }
+            return `http://127.0.0.1:${this.port}/${existingId}`;
+        }
+        const id = (0, node_crypto_1.randomBytes)(16).toString('hex');
+        this.targets.set(id, { url: targetUrl, label: label || `target ${id}` });
+        this.idsByUrl.set(targetUrl, id);
+        return `http://127.0.0.1:${this.port}/${id}`;
+    }
+    unregisterTarget(proxyUrl) {
+        try {
+            const id = new URL(proxyUrl).pathname.split('/')[1];
+            const target = id ? this.targets.get(id) : undefined;
+            if (id && target) {
+                this.targets.delete(id);
+                this.idsByUrl.delete(target.url);
+            }
+        }
+        catch {
+            // A malformed URL means there is nothing to unregister.
+        }
+    }
+    start() {
+        if (this.server && this.port) {
+            return Promise.resolve(this.port);
+        }
+        return new Promise((resolvePort, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                void this.handleRequest(req, res);
+            });
+            this.server = server;
+            server.once('error', reject);
+            // LOOPBACK ONLY. Never 0.0.0.0, never a fixed port.
+            server.listen(0, '127.0.0.1', () => {
+                const address = server.address();
+                if (typeof address === 'object' && address) {
+                    this.port = address.port;
+                    resolvePort(address.port);
+                }
+                else {
+                    reject(new Error('MCP auth proxy could not determine its address'));
+                }
+            });
+        });
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        this.port = null;
+        this.targets.clear();
+        this.idsByUrl.clear();
+        this.notifiedFailures.clear();
+        if (!server) {
+            return;
+        }
+        await new Promise((resolveClose) => {
+            server.close(() => resolveClose());
+            // A live SSE response holds the server open; MCP streams are long-lived,
+            // so a shutdown that waited for them would hang for ever.
+            server.closeAllConnections?.();
+        });
+    }
+    async handleRequest(req, res) {
+        try {
+            const reqUrl = new URL(req.url || '/', 'http://localhost');
+            const pathParts = reqUrl.pathname.split('/').filter(Boolean);
+            const id = pathParts[0];
+            const target = id ? this.targets.get(id) : undefined;
+            if (!target) {
+                /*
+                 * A TERMINAL ROUTING FAILURE, WORDED SO NOTHING MISREADS IT.
+                 *
+                 * This id is not registered with THIS proxy instance, so the MCP server
+                 * is not routable for this session. It is NOT an auth challenge and NOT
+                 * an allowlist denial (that is the gateway's `server_not_allowed`, a 403
+                 * further upstream) — it is a registration/lifetime mismatch, and no
+                 * amount of retrying resolves an id this proxy never issued.
+                 *
+                 * THREE THINGS THIS RESPONSE GETS RIGHT, each a bug it replaces:
+                 *   1. A JSON body, not the bare text `Unknown proxy target`. OpenCode's
+                 *      MCP client treats a non-2xx during connect as a possible OAuth
+                 *      challenge and `JSON.parse`s the body; a plaintext body threw
+                 *      `SyntaxError: Unexpected identifier "Unknown"`, which is the
+                 *      "Invalid OAuth error response" a human then spent hours chasing.
+                 *      Valid JSON removes the parse crash. (The client STILL should not
+                 *      route a 404 into OAuth at all — that is an upstream defect,
+                 *      filed separately.)
+                 *   2. `terminal: true` and an explicit "do not retry", because the
+                 *      agent that hit this reasoned it was a transient connectivity
+                 *      problem and burned turns waiting. An unroutable target never
+                 *      becomes routable by waiting.
+                 *   3. A distinct `reason` so a filtered-out server and an unknown
+                 *      target are not indistinguishable at this layer.
+                 */
+                res.writeHead(404, {
+                    'Content-Type': 'application/json',
+                    'Cache-Control': 'no-store'
+                });
+                res.end(JSON.stringify({
+                    error: 'unknown_proxy_target',
+                    reason: 'unknown_proxy_target',
+                    terminal: true,
+                    retryable: false,
+                    message: 'MCP loopback proxy: no target is registered for this id, so ' +
+                        'this server is not routable for this session. This is a ' +
+                        'terminal routing failure (not authentication, not an allowlist ' +
+                        'denial) — do not retry.'
+                }));
+                return;
+            }
+            const targetUrl = new URL(target.url);
+            const subPath = pathParts.slice(1);
+            if (subPath.length > 0) {
+                targetUrl.pathname =
+                    targetUrl.pathname.replace(/\/$/, '') + '/' + subPath.join('/');
+            }
+            targetUrl.search = reqUrl.search;
+            let token;
+            try {
+                token = await this.options.tokens.getToken(target.url);
+            }
+            catch (error) {
+                this.reportTokenFailure(id, target.label, error);
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: `Failed to obtain auth token for "${target.label}"`
+                }));
+                return;
+            }
+            const forwardHeaders = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                const lower = key.toLowerCase();
+                // `host` is rewritten below. `connection` is hop-by-hop and must not be
+                // forwarded. `authorization` is DROPPED rather than passed through:
+                // whatever the agent put there is not the credential we intend to use,
+                // and forwarding it would let a backend's own stale header win.
+                if (lower === 'host' ||
+                    lower === 'connection' ||
+                    lower === 'authorization') {
+                    continue;
+                }
+                forwardHeaders[key] = value;
+            }
+            // A null token means "this endpoint needs no Authorization header",
+            // which is a different thing from a failure and must stay expressible.
+            if (token !== null) {
+                forwardHeaders['authorization'] = `Bearer ${token}`;
+            }
+            forwardHeaders['host'] = targetUrl.host;
+            const isHttps = targetUrl.protocol === 'https:';
+            const send = isHttps ? node_https_1.request : node_http_1.request;
+            const proxyReq = send(targetUrl.toString(), { method: req.method, headers: forwardHeaders }, (proxyRes) => {
+                const responseHeaders = { ...proxyRes.headers };
+                const contentType = String(proxyRes.headers['content-type'] || '');
+                const isSSE = contentType.includes('text/event-stream');
+                if (!isSSE) {
+                    // Node re-chunks the proxy→client leg itself. Kept for SSE so
+                    // events flush immediately instead of being buffered — a buffered
+                    // MCP stream looks exactly like a hung tool call.
+                    delete responseHeaders['transfer-encoding'];
+                }
+                res.writeHead(proxyRes.statusCode || 502, responseHeaders);
+                if (isSSE) {
+                    proxyRes.on('data', (chunk) => {
+                        res.write(chunk);
+                    });
+                    proxyRes.on('end', () => res.end());
+                    proxyRes.on('error', () => res.end());
+                }
+                else {
+                    proxyRes.pipe(res);
+                }
+            });
+            proxyReq.on('error', (error) => {
+                this.logger.error(`[McpAuthProxy] Upstream error for "${target.label}": ${error.message}`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Upstream error: ${error.message}` }));
+                }
+                else {
+                    res.end();
+                }
+            });
+            req.pipe(proxyReq);
+        }
+        catch (error) {
+            this.logger.error('[McpAuthProxy] Unexpected error:', error);
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('Internal proxy error');
+            }
+        }
+    }
+    /**
+     * One notification per TARGET per process — keyed on the target id, not on
+     * the human-readable label.
+     *
+     * Two different servers can be registered under the same label (a tenant with
+     * two Jira instances, say). Keyed on the label, the second one's auth failure
+     * would be silently swallowed for ever because the first had already "used
+     * up" the notification. The id is unique by construction.
+     */
+    reportTokenFailure(id, label, error) {
+        this.logger.error(`[McpAuthProxy] Failed to get a token for "${label}":`, error);
+        if (this.notifiedFailures.has(id)) {
+            return;
+        }
+        this.notifiedFailures.add(id);
+        try {
+            this.options.notifier?.notify({
+                title: 'MCP Auth Failed',
+                body: `Could not authenticate "${label}" — please sign in again.`
+            });
+        }
+        catch {
+            // A notifier must never be able to break a request path.
+        }
+    }
+}
+exports.McpAuthProxy = McpAuthProxy;

package/dist/runtime/permission-mode.d.ts

@@ -0,0 +1,116 @@
+/**
+ * THE PERMISSION-MODE MAPPING — defect G1's other half.
+ *
+ * THE PROBLEM. Two vocabularies meet here and they are not the same size.
+ *
+ *   The LEASE carries what the user actually chose in the agent editor, which
+ *   is Claude Code's four-valued vocabulary:
+ *       'default' | 'plan' | 'acceptEdits' | 'bypassPermissions'
+ *
+ *   The shared ADAPTER contract (`SessionConfig.permissionMode`) is two-valued:
+ *       'ask' | 'allow'
+ *   because it has to mean the same thing to Pi, Claude Code, Codex and
+ *   ACP, and only one of those four backends has a native notion of a plan mode.
+ *
+ * Until this module existed the lease value was simply DROPPED on the runner:
+ * `buildSessionConfig` never set `permissionMode`, so every session fell to the
+ * adapter default. That is defect G1 — a Permission control that is recorded,
+ * served, rendered, and enforced nowhere.
+ *
+ * THE RULE THE MAPPING OBEYS: **a mode may map to something STRICTER than the
+ * user asked for, never to something looser.** Everything that is not an
+ * explicit "stop asking me" maps to `'ask'`. `'allow'` is reachable from
+ * exactly one input, `bypassPermissions`, and from nothing else — including
+ * from an unrecognised value, which fails closed onto `'ask'`.
+ *
+ * ---------------------------------------------------------------------------
+ * THE TABLE, AND WHAT IS AND IS NOT FAITHFUL
+ * ---------------------------------------------------------------------------
+ *
+ *  lease mode           | permissionMode | sandboxMode        | faithful?
+ *  ---------------------|----------------|--------------------|-----------
+ *  'default'            | 'ask'          | 'workspace-write'  | YES
+ *  'plan'               | 'ask'          | 'read-only'        | partly
+ *  'acceptEdits'        | 'ask'          | 'workspace-write'  | partly
+ *  'bypassPermissions'  | 'allow'        | 'danger-full-access'| YES
+ *
+ * `sandboxMode` is NOT decoration. It is the existing second field on
+ * `SessionConfig` that carries the part of the user's intent `'ask' | 'allow'`
+ * cannot hold, and it is what makes the mapping lossless for the backends that
+ * read it.
+ *
+ * PER BACKEND, SAID PLAINLY — this is the "say so explicitly rather than
+ * quietly collapsing them" the brief asks for:
+ *
+ *   CLAUDE CODE — THREE OF FOUR. Its SDK natively takes all four values, so
+ *   `claudeCodePermissionMode()` below reconstructs `default`, `plan` and
+ *   `bypassPermissions` exactly. A user who picks `plan` gets Claude Code's
+ *   real plan mode.
+ *
+ *   `acceptEdits` IS THE EXCEPTION, AND IT IS LOST HERE RATHER THAN IN A
+ *   BACKEND. An earlier version of this comment claimed Claude Code was
+ *   lossless and "nothing is collapsed". THAT WAS WRONG, and the round-trip
+ *   test quietly omitted `acceptEdits` rather than failing — which is how a
+ *   false claim survives review. Corrected after it was caught.
+ *
+ *   The reason is structural, not an oversight: `acceptEdits` and `default`
+ *   both need `permissionMode: 'ask'` with a writable workspace, and the pair
+ *   (`'ask' | 'allow'`, three sandbox modes) has no third slot to tell them
+ *   apart. Distinguishing them would mean WIDENING the shared adapter contract,
+ *   which 20x also uses — a bigger change than this defect warrants, and one
+ *   the brief explicitly scoped out.
+ *
+ *   So `acceptEdits` resolves to `default` on EVERY backend: the user is asked
+ *   about edits they said they would accept. Interrupted more than they asked,
+ *   never less — the same safe direction as everything else in this table, and
+ *   the UI says so rather than implying a distinction that does not exist.
+ *
+ *   CODEX — PARTLY. It reads `sandboxMode` directly, so `plan` really is
+ *   read-only there, and its approval policy is `'never'` only for `'allow'`.
+ *
+ *   PI — COLLAPSED, AND THIS IS THE ONE THAT MATTERS, because Pi is
+ *   the only backend wired into the cloud runner today. Pi has no plan
+ *   mode and no accept-edits mode; it has a permission prompt or it has none.
+ *   So on Pi `plan` and `acceptEdits` are INDISTINGUISHABLE FROM
+ *   `default`: all three prompt for everything.
+ *
+ *   That collapse is deliberately in the SAFE direction. `acceptEdits` promises
+ *   "do not ask me about edits", and on Pi we ask anyway — the user is
+ *   interrupted more than they asked to be, never less. The alternative
+ *   (mapping `acceptEdits` to `'allow'`) would honour the label by granting
+ *   silent write access the user never asked for, which is the same class of
+ *   defect as G1 itself. The agent editor says this out loud rather than
+ *   letting the picker imply a distinction the runtime does not make.
+ */
+/** What the lease carries — the value stored on the agent definition. */
+export type LeasePermissionMode = 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+/** What the shared adapter contract accepts. */
+export type AdapterPermissionMode = 'ask' | 'allow';
+export type AdapterSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+export interface MappedPermission {
+    permissionMode: AdapterPermissionMode;
+    sandboxMode: AdapterSandboxMode;
+}
+/**
+ * THE ONLY PLACE the four-valued lease mode becomes the two-valued adapter
+ * mode. Deliberately total: an unknown value — a newer control plane, a hand-
+ * edited row — is not an error, it is `'ask'`, because the failure mode of
+ * guessing wrong in the other direction is an unattended agent with no prompt.
+ */
+export declare function mapPermissionMode(mode: LeasePermissionMode | string | null | undefined): MappedPermission;
+/**
+ * The inverse, for Claude Code only — it is the one backend whose own SDK takes
+ * the four-valued vocabulary, so the pair that `mapPermissionMode` produced can
+ * be turned back into exactly what the user chose.
+ *
+ * This is why the mapping is lossless there and lossy on Pi: the loss is
+ * in the BACKEND, not in the wire.
+ *
+ * Absent `permissionMode` means the caller never set one. That is the pre-G1
+ * state and it must NOT silently become `bypassPermissions` again, so it maps
+ * to `'default'` — Claude Code's own asking mode.
+ */
+export declare function claudeCodePermissionMode(config: {
+    permissionMode?: AdapterPermissionMode;
+    sandboxMode?: AdapterSandboxMode;
+}): LeasePermissionMode;

package/dist/runtime/permission-mode.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * THE PERMISSION-MODE MAPPING — defect G1's other half.
+ *
+ * THE PROBLEM. Two vocabularies meet here and they are not the same size.
+ *
+ *   The LEASE carries what the user actually chose in the agent editor, which
+ *   is Claude Code's four-valued vocabulary:
+ *       'default' | 'plan' | 'acceptEdits' | 'bypassPermissions'
+ *
+ *   The shared ADAPTER contract (`SessionConfig.permissionMode`) is two-valued:
+ *       'ask' | 'allow'
+ *   because it has to mean the same thing to Pi, Claude Code, Codex and
+ *   ACP, and only one of those four backends has a native notion of a plan mode.
+ *
+ * Until this module existed the lease value was simply DROPPED on the runner:
+ * `buildSessionConfig` never set `permissionMode`, so every session fell to the
+ * adapter default. That is defect G1 — a Permission control that is recorded,
+ * served, rendered, and enforced nowhere.
+ *
+ * THE RULE THE MAPPING OBEYS: **a mode may map to something STRICTER than the
+ * user asked for, never to something looser.** Everything that is not an
+ * explicit "stop asking me" maps to `'ask'`. `'allow'` is reachable from
+ * exactly one input, `bypassPermissions`, and from nothing else — including
+ * from an unrecognised value, which fails closed onto `'ask'`.
+ *
+ * ---------------------------------------------------------------------------
+ * THE TABLE, AND WHAT IS AND IS NOT FAITHFUL
+ * ---------------------------------------------------------------------------
+ *
+ *  lease mode           | permissionMode | sandboxMode        | faithful?
+ *  ---------------------|----------------|--------------------|-----------
+ *  'default'            | 'ask'          | 'workspace-write'  | YES
+ *  'plan'               | 'ask'          | 'read-only'        | partly
+ *  'acceptEdits'        | 'ask'          | 'workspace-write'  | partly
+ *  'bypassPermissions'  | 'allow'        | 'danger-full-access'| YES
+ *
+ * `sandboxMode` is NOT decoration. It is the existing second field on
+ * `SessionConfig` that carries the part of the user's intent `'ask' | 'allow'`
+ * cannot hold, and it is what makes the mapping lossless for the backends that
+ * read it.
+ *
+ * PER BACKEND, SAID PLAINLY — this is the "say so explicitly rather than
+ * quietly collapsing them" the brief asks for:
+ *
+ *   CLAUDE CODE — THREE OF FOUR. Its SDK natively takes all four values, so
+ *   `claudeCodePermissionMode()` below reconstructs `default`, `plan` and
+ *   `bypassPermissions` exactly. A user who picks `plan` gets Claude Code's
+ *   real plan mode.
+ *
+ *   `acceptEdits` IS THE EXCEPTION, AND IT IS LOST HERE RATHER THAN IN A
+ *   BACKEND. An earlier version of this comment claimed Claude Code was
+ *   lossless and "nothing is collapsed". THAT WAS WRONG, and the round-trip
+ *   test quietly omitted `acceptEdits` rather than failing — which is how a
+ *   false claim survives review. Corrected after it was caught.
+ *
+ *   The reason is structural, not an oversight: `acceptEdits` and `default`
+ *   both need `permissionMode: 'ask'` with a writable workspace, and the pair
+ *   (`'ask' | 'allow'`, three sandbox modes) has no third slot to tell them
+ *   apart. Distinguishing them would mean WIDENING the shared adapter contract,
+ *   which 20x also uses — a bigger change than this defect warrants, and one
+ *   the brief explicitly scoped out.
+ *
+ *   So `acceptEdits` resolves to `default` on EVERY backend: the user is asked
+ *   about edits they said they would accept. Interrupted more than they asked,
+ *   never less — the same safe direction as everything else in this table, and
+ *   the UI says so rather than implying a distinction that does not exist.
+ *
+ *   CODEX — PARTLY. It reads `sandboxMode` directly, so `plan` really is
+ *   read-only there, and its approval policy is `'never'` only for `'allow'`.
+ *
+ *   PI — COLLAPSED, AND THIS IS THE ONE THAT MATTERS, because Pi is
+ *   the only backend wired into the cloud runner today. Pi has no plan
+ *   mode and no accept-edits mode; it has a permission prompt or it has none.
+ *   So on Pi `plan` and `acceptEdits` are INDISTINGUISHABLE FROM
+ *   `default`: all three prompt for everything.
+ *
+ *   That collapse is deliberately in the SAFE direction. `acceptEdits` promises
+ *   "do not ask me about edits", and on Pi we ask anyway — the user is
+ *   interrupted more than they asked to be, never less. The alternative
+ *   (mapping `acceptEdits` to `'allow'`) would honour the label by granting
+ *   silent write access the user never asked for, which is the same class of
+ *   defect as G1 itself. The agent editor says this out loud rather than
+ *   letting the picker imply a distinction the runtime does not make.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapPermissionMode = mapPermissionMode;
+exports.claudeCodePermissionMode = claudeCodePermissionMode;
+/**
+ * THE ONLY PLACE the four-valued lease mode becomes the two-valued adapter
+ * mode. Deliberately total: an unknown value — a newer control plane, a hand-
+ * edited row — is not an error, it is `'ask'`, because the failure mode of
+ * guessing wrong in the other direction is an unattended agent with no prompt.
+ */
+function mapPermissionMode(mode) {
+    switch (mode) {
+        case 'bypassPermissions':
+            return {
+                permissionMode: 'allow',
+                sandboxMode: 'danger-full-access'
+            };
+        case 'plan':
+            return { permissionMode: 'ask', sandboxMode: 'read-only' };
+        case 'acceptEdits':
+            return { permissionMode: 'ask', sandboxMode: 'workspace-write' };
+        case 'default':
+            return { permissionMode: 'ask', sandboxMode: 'workspace-write' };
+        default:
+            // Unrecognised, absent, null. Ask. See the rule above.
+            return { permissionMode: 'ask', sandboxMode: 'workspace-write' };
+    }
+}
+/**
+ * The inverse, for Claude Code only — it is the one backend whose own SDK takes
+ * the four-valued vocabulary, so the pair that `mapPermissionMode` produced can
+ * be turned back into exactly what the user chose.
+ *
+ * This is why the mapping is lossless there and lossy on Pi: the loss is
+ * in the BACKEND, not in the wire.
+ *
+ * Absent `permissionMode` means the caller never set one. That is the pre-G1
+ * state and it must NOT silently become `bypassPermissions` again, so it maps
+ * to `'default'` — Claude Code's own asking mode.
+ */
+function claudeCodePermissionMode(config) {
+    if (config.permissionMode === 'allow') {
+        return 'bypassPermissions';
+    }
+    if (config.sandboxMode === 'read-only') {
+        return 'plan';
+    }
+    if (config.sandboxMode === 'workspace-write') {
+        /*
+         * `acceptEdits` AND `default` SHARE THIS PAIR, so this direction cannot
+         * tell them apart — which means `acceptEdits` is UNREACHABLE from here and
+         * no backend ever receives it. That is a real, deliberate loss, described
+         * in the header and surfaced to the user in the agent editor; it is not a
+         * gap someone forgot to close.
+         *
+         * `default` is the stricter of the two, so it is the right answer when the
+         * pair is ambiguous.
+         */
+        return 'default';
+    }
+    return 'default';
+}

package/dist/runtime/projection.d.ts

@@ -0,0 +1,71 @@
+/**
+ * THE PROJECTION — adapter message parts in, transcript parts out.
+ *
+ * Ported from the single chokepoint in 20x `agent-manager.ts`
+ * (`persistTranscriptEvent`, :5269) through which every piece of live streaming
+ * output passes on its way to the durable log. Keeping it a chokepoint is the
+ * whole reason the 20x transcript is reliable, and it is reproduced here for the
+ * same reason: one function decides what a transcript part IS, so a new backend
+ * cannot invent a second answer.
+ *
+ * THREE FILTERS, IN ORDER, each of which exists because of a real defect:
+ *
+ * 1. NO ID, NO PART. The upsert is keyed on (sessionId, partId); a part with no
+ *    id has no identity, so a second delta for it would insert a duplicate
+ *    instead of updating the first.
+ *
+ * 2. THE EPHEMERAL THREE ARE DROPPED. 'step-start', 'step-finish' and
+ *    'system-status' are UI-only frame markers. Persisting them would put
+ *    thousands of meaningless rows in every transcript and stream each one to
+ *    every reader. Their actual information — duration, token counts — belongs
+ *    in `TurnMetadata`, which is what closes defect G7.
+ *
+ *    The check goes through the SHARED predicate `isEphemeralPartType`, which
+ *    trims and lowercases. A backend emitting ' Step-Start ' must not slip past
+ *    a case-sensitive comparison and corrupt the projection permanently.
+ *
+ * 3. AN EMPTY PART IS DROPPED. The opening frame of a text part that never
+ *    received a delta is a stream artefact, and storing it puts a blank bubble
+ *    in the UI for ever. A part with a payload and no content is KEPT — a tool
+ *    call with arguments and no textual body is perfectly ordinary.
+ */
+import { StoredPartInput } from '../ports';
+import { TranscriptPartInput } from '../types';
+/**
+ * The adapter-side part shape.
+ *
+ * Structurally typed against `MessagePart` from the adapter interface rather
+ * than imported from it. The projection must accept a part from ANY backend,
+ * including one added later that this package has never seen, so it depends on
+ * the fields it reads and on nothing else.
+ */
+export interface ProjectableMessagePart {
+    id?: string;
+    role?: string;
+    type?: string;
+    text?: string;
+    content?: string;
+    partType?: string;
+    tool?: unknown;
+    questions?: unknown;
+    todos?: unknown;
+    taskProgress?: unknown;
+    /** Unix ms when the event was ORIGINALLY received. Preserved through replay. */
+    receivedAt?: number;
+}
+/**
+ * Project a batch of adapter parts into transcript parts.
+ *
+ * Returns only the parts worth storing. An empty result is an ordinary outcome
+ * — a poll that saw nothing but step markers — and is NOT an error.
+ */
+export declare function projectParts(raw: ReadonlyArray<ProjectableMessagePart | null | undefined>): StoredPartInput[];
+/**
+ * Convert a stored part into the wire shape for `POST /ingest`.
+ *
+ * `seq` and `rev` are dropped: they are SERVER-ALLOCATED, and a runner that
+ * could send them could fabricate an ordering or replay an old rev over a newer
+ * one. The contract's `TranscriptPartInput` has no field for either, so this is
+ * enforced by the type rather than by a convention someone must remember.
+ */
+export declare function toIngestPart(part: StoredPartInput): TranscriptPartInput;