@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/routes/git.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Git routes: the fleet-level remote + GitHub device-flow auth, plus the
+ * per-project working-tree status / diff / commit surface (#258). Push is a
+ * separate explicit action from a project commit.
+ */
+import type { FastifyInstance } from "fastify";
+import type { RouteCtx } from "../route-context.js";
+export declare function registerGitRoutes(app: FastifyInstance, ctx: RouteCtx): void;
+/**
+ * The workspace-scoped git surface: registered once per workspace mount (root
+ * and per project) — see `workspace-mount.ts`. Paths are relative to the mount.
+ */
+export declare function registerGitWorkspaceRoutes(app: FastifyInstance, ctx: RouteCtx): void;

package/packages/server/dist/routes/git.js

@@ -0,0 +1,236 @@
+import { sendProjectError } from "../route-errors.js";
+export function registerGitRoutes(app, ctx) {
+    const { git, githubAuth } = ctx;
+    // --- git (backing store): fleet-level remote + connection state --------
+    app.get("/api/git", {
+        schema: {
+            tags: ["Git"],
+            summary: "Get fleet-level git remote and GitHub connection state",
+            description: "Returns the configured backing-store remote details merged with a `github` object describing the current GitHub device-flow connection status.",
+            response: {
+                200: {
+                    description: "Object containing the remote configuration fields plus a nested `github` object with connection state.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async () => {
+        const [remote, github] = await Promise.all([git.remote(), githubAuth.status()]);
+        return { ...remote, github };
+    });
+    // Push the working tree to origin (the NAS bare repo / configured remote).
+    app.post("/api/git/push", {
+        schema: {
+            tags: ["Git"],
+            summary: "Push the working tree to origin",
+            description: "Pushes the projects working tree to the configured remote (the NAS bare repo / origin). Returns an object describing the push result.",
+            response: {
+                200: {
+                    description: "Object describing the outcome of the push operation.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async () => {
+        return git.push();
+    });
+    // GitHub device-flow auth: begin → poll → disconnect.
+    app.post("/api/git/github/connect", {
+        schema: {
+            tags: ["Git"],
+            summary: "Begin GitHub device-flow authentication",
+            description: "Starts the GitHub device-flow authorization and returns the device/user codes and verification URL. Responds with 400 (`{ error }`) if the flow cannot be started.",
+            response: {
+                200: {
+                    description: "Object with the GitHub device-flow details (e.g. device code, user code, verification URI).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                400: {
+                    description: "Error object `{ error }` when the device flow cannot be started.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (_req, reply) => {
+        try {
+            return await githubAuth.startDeviceFlow();
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err.message });
+        }
+    });
+    app.post("/api/git/github/poll", {
+        schema: {
+            tags: ["Git"],
+            summary: "Poll GitHub device-flow authentication",
+            description: "Polls GitHub for completion of a previously-started device flow using the supplied `deviceCode`. Returns the current auth status; responds with 400 (`{ error }`) if `deviceCode` is missing.",
+            body: {
+                // Documentation-only (no validation/coercion): accept any/empty body.
+                type: ["object", "null"],
+                additionalProperties: true,
+                properties: {
+                    deviceCode: { description: "The device code returned by the connect step." },
+                },
+            },
+            response: {
+                200: {
+                    description: "Object describing the current device-flow poll result / auth status.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                400: {
+                    description: "Error object `{ error }` when `deviceCode` is missing.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        const code = req.body?.deviceCode;
+        if (!code)
+            return reply.code(400).send({ error: "deviceCode required" });
+        return githubAuth.pollDeviceFlow(code);
+    });
+    app.post("/api/git/github/disconnect", {
+        schema: {
+            tags: ["Git"],
+            summary: "Disconnect the GitHub connection",
+            description: "Clears the stored GitHub credentials / connection. Returns `{ ok: true }` on success.",
+            response: {
+                200: {
+                    description: "Object `{ ok: true }` confirming the disconnect.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async () => {
+        await githubAuth.disconnect();
+        return { ok: true };
+    });
+}
+/**
+ * The workspace-scoped git surface: registered once per workspace mount (root
+ * and per project) — see `workspace-mount.ts`. Paths are relative to the mount.
+ */
+export function registerGitWorkspaceRoutes(app, ctx) {
+    const { git, projects } = ctx;
+    // --- git (backing-store capability, phase 1: read surface) -------------
+    // Uncommitted changes confined to this project's subtree. Returns
+    // `{ repo: false }` when the projects dir isn't a git working tree, so the
+    // UI hides the git affordance entirely. Never throws on git errors.
+    app.get("/git/status", {
+        schema: {
+            tags: ["Git"],
+            summary: "Get a project's git working-tree status",
+            description: "Returns the uncommitted changes confined to this project's subtree. Returns `{ repo: false }` when the projects dir isn't a git working tree. Never throws on git errors.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            response: {
+                200: {
+                    description: "Object describing the project's working-tree status, or `{ repo: false }` when not a git working tree.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            return await git.projectStatus(project.dir);
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Unified diff for the project's tracked changes (working tree vs HEAD), or a
+    // single file via ?file=. Untracked files are reported by /git/status instead.
+    app.get("/git/diff", {
+        schema: {
+            tags: ["Git"],
+            summary: "Get a project's unified diff",
+            description: "Returns the raw unified diff (text/plain) for the project's tracked changes (working tree vs HEAD), or for a single file via `?file=`. Untracked files are reported by /git/status instead.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            querystring: {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    file: {
+                        type: "string",
+                        description: "Optional project-relative path to diff a single file.",
+                    },
+                },
+            },
+            produces: ["text/plain"],
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            const diff = await git.projectDiff(project.dir, req.query.file);
+            reply.header("content-type", "text/plain; charset=utf-8");
+            return diff;
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Commit this project's pending changes (phase 2). `committed: false` when
+    // there was nothing to commit. Push is a separate explicit action (/api/git/push).
+    app.post("/git/commit", {
+        schema: {
+            tags: ["Git"],
+            summary: "Commit a project's pending changes",
+            description: "Commits the project's pending changes. Optional `files` (project-relative) commits only those changes; omitted commits the whole subtree. Returns an object where `committed: false` indicates there was nothing to commit. Push is a separate explicit action (/api/git/push).",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "The project slug." },
+                },
+                required: ["slug"],
+            },
+            body: {
+                // Documentation-only (no validation/coercion): accept any/empty body.
+                type: ["object", "null"],
+                additionalProperties: true,
+                properties: {
+                    message: { description: "Optional commit message; defaults to `Update <project name>`." },
+                    files: { description: "Optional project-relative paths (array) to commit only those changes." },
+                },
+            },
+            response: {
+                200: {
+                    description: "Object describing the commit result; `committed: false` when there was nothing to commit.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            const message = req.body?.message?.trim() || `Update ${project.name}`;
+            // Optional `files` (project-relative) commits only those changes (#258);
+            // omitted ⇒ commit the whole subtree (legacy behavior).
+            const files = Array.isArray(req.body?.files) ? req.body?.files : undefined;
+            return await git.commitProject(project.dir, message, files);
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+}

package/packages/server/dist/routes/mcp.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The `/mcp` Management API endpoint (issue #312).
+ *
+ * M1 shipped the gate (authentication, principal resolution, fail-closed
+ * behaviour); M2 mounts the streamable-HTTP MCP transport behind it and the RFC
+ * 9728 discovery document beside it.
+ *
+ * ── The response matrix ────────────────────────────────────────────────────
+ *   404  — no `managementApi.clients` (or no `publicUrl`). The endpoint DOES
+ *          NOT EXIST until an operator deliberately turns it on. This is the
+ *          backstop for the deploy-ordering hazard: exempting `/mcp` at an edge
+ *          proxy removes the only other gate in front of it.
+ *   401  — credential missing or bad. Always `401` + `WWW-Authenticate`, NEVER
+ *          a 302 to a login page: an MCP client cannot follow a redirect, and
+ *          OAuth discovery reads this exact challenge.
+ *   403  — authenticated but out of scope (`insufficient_scope`), or plaintext
+ *          from a non-loopback client. `X-Forwarded-Proto: https` lifts that
+ *          refusal only when the immediate peer is a trusted proxy (#474) —
+ *          a client cannot vouch for its own transport.
+ *   405  — GET/DELETE. In stateless mode the transport answers a GET with an SSE
+ *          stream that never emits anything, so a client would hang forever on a
+ *          socket with no headers.
+ *
+ * Authentication runs in `onRequest` — BEFORE body parsing — so a malformed or
+ * oversized body can never preempt the auth decision.
+ */
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import type { RouteCtx } from "../route-context.js";
+import type { ManagementPrincipal } from "../management-policy.js";
+import type { ManagementApiConfig } from "../management-config.js";
+/** The URL path the management surface is mounted at. */
+export declare const MCP_PATH = "/mcp";
+declare module "fastify" {
+    interface FastifyRequest {
+        /**
+         * The authenticated Management API caller, set by the `/mcp` guard. Absent
+         * on every other route — this is NOT the browser user (`req.user`), which is
+         * a separate, independent identity (see management-auth.ts).
+         */
+        managementPrincipal?: ManagementPrincipal;
+    }
+}
+/** How a request earned (or failed to earn) its "secure" verdict. */
+export interface TransportSecurity {
+    secure: boolean;
+    /**
+     * `tls` — real TLS at this process; `forwarded` — a TRUSTED proxy said https;
+     * `loopback` — the client is on this host; `spoofable` — a forwarded https
+     * claim we refused because the peer is not a trusted proxy; `plaintext` —
+     * no claim at all.
+     */
+    via: "tls" | "forwarded" | "loopback" | "spoofable" | "plaintext";
+    /** The immediate peer's socket address, for the log line and the 403 body. */
+    peer: string;
+    /**
+     * True when the verdict rests on a forwarded header believed under the
+     * DEFAULT trust list rather than an operator-named proxy — worth telling the
+     * operator once, since only an explicit list makes this a control (#474).
+     */
+    assumedProxy: boolean;
+}
+/**
+ * Whether the request reached us over a secure channel.
+ *
+ * Three ways to be secure: real TLS at this process, a TLS-terminating proxy
+ * that set `X-Forwarded-Proto: https`, or a loopback client (nothing left the
+ * host, so there is no wire to sniff). Everything else is plaintext over a real
+ * network, where a bearer token would be readable in transit — refused,
+ * mirroring the spirit of the bind-safety guard (#435).
+ *
+ * The forwarded case is the one #474 tightened: the header is believed only
+ * when the IMMEDIATE PEER — the socket address, which no client can set — is a
+ * trusted proxy. See trusted-proxy.ts for the trust list and its default.
+ *
+ * Note what this deliberately does NOT use: Fastify's `trustProxy`. In the
+ * version pinned here (4.28) enabling it makes `req.protocol` return
+ * `x-forwarded-proto` whenever the header is PRESENT, without consulting the
+ * trust function at all — the trust check applies to `req.ip`/`req.ips` only.
+ * Building this guard on `req.protocol` would therefore reproduce the exact bug
+ * it is meant to close, so the peer check is done here, explicitly.
+ */
+export declare function evaluateTransportSecurity(req: FastifyRequest, cfg: ManagementApiConfig): TransportSecurity;
+export declare function registerMcpRoutes(app: FastifyInstance, ctx: RouteCtx): void;

package/packages/server/dist/routes/mcp.js

@@ -0,0 +1,250 @@
+import { Readable } from "node:stream";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { authenticateManagementRequest, challengeHeader, isManagementApiEnabled, resourceMetadataUrl, } from "../management-auth.js";
+import { buildProtectedResourceMetadata, PROTECTED_RESOURCE_METADATA_PREFIX, MCP_RESOURCE_PATH, } from "../management-metadata.js";
+import { buildManagementOps, enforceManagementPolicy } from "../management-ops.js";
+import { selfMcpServerDefForOps } from "../ws-self-mcp.js";
+import { buildManagementMcpServer } from "../management-mcp-server.js";
+import { HUMAN_ROOT } from "../run-provenance.js";
+import { defaultTrustedProxies, isLoopbackAddress, isTrustedProxy } from "../trusted-proxy.js";
+/** The URL path the management surface is mounted at. */
+export const MCP_PATH = MCP_RESOURCE_PATH;
+/**
+ * Whether the request reached us over a secure channel.
+ *
+ * Three ways to be secure: real TLS at this process, a TLS-terminating proxy
+ * that set `X-Forwarded-Proto: https`, or a loopback client (nothing left the
+ * host, so there is no wire to sniff). Everything else is plaintext over a real
+ * network, where a bearer token would be readable in transit — refused,
+ * mirroring the spirit of the bind-safety guard (#435).
+ *
+ * The forwarded case is the one #474 tightened: the header is believed only
+ * when the IMMEDIATE PEER — the socket address, which no client can set — is a
+ * trusted proxy. See trusted-proxy.ts for the trust list and its default.
+ *
+ * Note what this deliberately does NOT use: Fastify's `trustProxy`. In the
+ * version pinned here (4.28) enabling it makes `req.protocol` return
+ * `x-forwarded-proto` whenever the header is PRESENT, without consulting the
+ * trust function at all — the trust check applies to `req.ip`/`req.ips` only.
+ * Building this guard on `req.protocol` would therefore reproduce the exact bug
+ * it is meant to close, so the peer check is done here, explicitly.
+ */
+export function evaluateTransportSecurity(req, cfg) {
+    const peer = req.socket.remoteAddress ?? "";
+    const base = { peer, assumedProxy: false };
+    // `req.socket.encrypted` rather than `req.protocol`: with trustProxy off they
+    // agree, and this cannot be influenced by a header even if that changes.
+    if (req.socket.encrypted) {
+        return { ...base, secure: true, via: "tls" };
+    }
+    const fwd = req.headers["x-forwarded-proto"];
+    const proto = (Array.isArray(fwd) ? fwd[0] : fwd)?.split(",")[0]?.trim().toLowerCase();
+    const trusted = cfg.trustedProxies ?? defaultTrustedProxies();
+    if (proto === "https") {
+        if (isTrustedProxy(peer, trusted)) {
+            return {
+                ...base,
+                secure: true,
+                via: "forwarded",
+                assumedProxy: !trusted.explicit,
+            };
+        }
+        // A loopback client that spoofs the header is still secure — by being on
+        // loopback, not by asking. Fall through so it gets the honest reason.
+        if (!isLoopbackAddress(peer))
+            return { ...base, secure: false, via: "spoofable" };
+    }
+    if (isLoopbackAddress(peer))
+        return { ...base, secure: true, via: "loopback" };
+    return { ...base, secure: false, via: "plaintext" };
+}
+export function registerMcpRoutes(app, ctx) {
+    const { cfg, managementOpsContext } = ctx;
+    // ── Discovery (unauthenticated by design) ────────────────────────────────
+    // A client fetches this BEFORE it holds any credential, so gating it would
+    // make discovery impossible. The document names the authorization server and
+    // supported scopes — never a secret.
+    //
+    // Served at BOTH the path-inserted URL (what clients actually request for a
+    // resource with a path) and the bare root (harmless, and other clients may
+    // use it). Still 404s when the surface is off, so a disabled instance doesn't
+    // advertise a management API.
+    const metadataHandler = async (_req, reply) => {
+        if (!isManagementApiEnabled(cfg.managementApi)) {
+            return reply.code(404).send({ error: "not found" });
+        }
+        const doc = buildProtectedResourceMetadata(cfg.managementApi);
+        if (!doc)
+            return reply.code(404).send({ error: "not found" });
+        return reply
+            .header("access-control-allow-origin", "*")
+            .header("cache-control", "public, max-age=300")
+            .type("application/json; charset=utf-8")
+            .send(doc);
+    };
+    for (const url of [
+        `${PROTECTED_RESOURCE_METADATA_PREFIX}${MCP_RESOURCE_PATH}`,
+        PROTECTED_RESOURCE_METADATA_PREFIX,
+    ]) {
+        app.get(url, { schema: { hide: true } }, metadataHandler);
+    }
+    // ── The gate ─────────────────────────────────────────────────────────────
+    // Peers we have already warned about (see the assumedProxy branch below).
+    // Per-app, and capped, so a hostile spread of source addresses can't grow it.
+    const warnedPeers = new Set();
+    const guard = async (req, reply) => {
+        if (!isManagementApiEnabled(cfg.managementApi)) {
+            return reply.code(404).send({ error: "not found" });
+        }
+        const transport = evaluateTransportSecurity(req, cfg.managementApi);
+        if (!transport.secure) {
+            req.log.warn({ url: req.url, peer: transport.peer, via: transport.via }, transport.via === "spoofable"
+                ? "management API: refusing a plaintext request whose X-Forwarded-Proto: https came from a peer that is not a trusted proxy (#474)"
+                : "management API: refusing a plaintext non-loopback request (a bearer token would be readable in transit)");
+            return reply.code(403).send({
+                error: "https required",
+                code: "insecure_transport",
+                message: transport.via === "spoofable"
+                    ? `The management API refuses plaintext requests from non-loopback clients. ` +
+                        `X-Forwarded-Proto: https was ignored because the peer (${transport.peer}) is not a ` +
+                        `trusted proxy — a client cannot vouch for its own transport. If that address IS ` +
+                        `your TLS-terminating proxy, list it in managementApi.trustedProxies (or ` +
+                        `PADDOCK_MANAGEMENT_TRUSTED_PROXIES); otherwise terminate TLS in front of Paddock, ` +
+                        `or connect over loopback.`
+                    : `The management API refuses plaintext requests from non-loopback clients ` +
+                        `(peer: ${transport.peer || "unknown"}). Terminate TLS in front of Paddock (and ` +
+                        `forward X-Forwarded-Proto from a trusted proxy), or connect over loopback.`,
+            });
+        }
+        // Believed a forwarded scheme from a peer that only matched the DEFAULT
+        // trust list. It is probably the operator's proxy — but nothing proves it,
+        // and if it is not, the token in this request just crossed a network in
+        // clear. Say so once per peer rather than on every request.
+        if (transport.assumedProxy && !warnedPeers.has(transport.peer)) {
+            if (warnedPeers.size < 32)
+                warnedPeers.add(transport.peer);
+            req.log.warn({ peer: transport.peer }, `management API: believing X-Forwarded-Proto: https from ${transport.peer}, which matched ` +
+                `the DEFAULT trusted-proxy list (loopback + private address space) rather than a proxy ` +
+                `you named. If that peer is not your TLS terminator, bearer tokens are reaching this ` +
+                `instance in plaintext. Set managementApi.trustedProxies to make this a control (#474).`);
+        }
+        const result = authenticateManagementRequest(req.headers.authorization, cfg.managementApi);
+        if (!result.ok) {
+            // Log the failure and the caller, never the presented credential.
+            req.log.warn({ url: req.url, failure: result.failure, ip: req.socket.remoteAddress }, "management API: authentication failed");
+            return reply
+                .code(401)
+                .header("WWW-Authenticate", challengeHeader(result.failure, resourceMetadataUrl(cfg.managementApi)))
+                .send({ error: "unauthorized", code: "auth_required" });
+        }
+        req.managementPrincipal = result.principal;
+    };
+    // ── GET / DELETE → 405 ───────────────────────────────────────────────────
+    // Stateless transport: a GET would open an SSE stream that never emits, so the
+    // client waits forever on a header-less socket. Refuse explicitly instead.
+    app.route({
+        method: ["GET", "DELETE"],
+        url: MCP_PATH,
+        schema: { hide: true },
+        onRequest: guard,
+        handler: async (_req, reply) => reply
+            .code(405)
+            .header("allow", "POST")
+            .send({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed. Use POST for the MCP endpoint.",
+            },
+            id: null,
+        }),
+    });
+    // ── POST → the MCP transport ─────────────────────────────────────────────
+    app.route({
+        method: ["POST"],
+        url: MCP_PATH,
+        // Kept out of the OpenAPI document (#466): this is a JSON-RPC MCP endpoint,
+        // not a REST resource, and a body schema here would become an active
+        // request validator over MCP payloads.
+        schema: { hide: true },
+        onRequest: guard,
+        handler: async (req, reply) => {
+            const principal = req.managementPrincipal;
+            if (!principal)
+                return reply.code(401).send({ error: "unauthorized" });
+            if (!managementOpsContext) {
+                // Wiring error rather than a client error — the surface is configured
+                // but the server didn't hand the route its ops context.
+                req.log.error("management API: ops context unavailable; /mcp cannot serve requests");
+                return reply.code(503).send({ error: "unavailable", code: "ops_unavailable" });
+            }
+            // Ops are built PER REQUEST, bound to this principal, then policed. An
+            // external caller has no "current chat", so it addresses everything
+            // explicitly and its spawns are rooted like a human's.
+            const ops = buildManagementOps(managementOpsContext, {
+                currentProjectSlug: "",
+                currentSessionId: () => null,
+                parentProvenance: HUMAN_ROOT,
+                // All three capability gates are opened here and NARROWED by scope
+                // immediately below. That is the right split for an external caller:
+                // these per-project/per-instance gates exist to bound what a KEEPER may
+                // reach, whereas an external client is bounded by its credential. So a
+                // client gets `create_project` only by naming it in `allow` — the
+                // read-only default excludes it, as it does every other mutation.
+                includeWrite: true,
+                includeTriggers: true,
+                includeProjects: true,
+                spawnDepthCap: principal.scope.maxSpawnDepth,
+            });
+            const policed = enforceManagementPolicy(ops, principal);
+            const def = selfMcpServerDefForOps(policed, principal);
+            const server = buildManagementMcpServer(def, principal);
+            // Stateless: a fresh server+transport per request. No session store, no
+            // cross-request state, restart-safe — and a principal's tool visibility
+            // can never leak into another caller's session.
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await server.connect(transport);
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (v === undefined)
+                    continue;
+                for (const one of Array.isArray(v) ? v : [v])
+                    headers.append(k, String(one));
+            }
+            const base = cfg.managementApi.publicUrl ?? "http://localhost";
+            const response = await transport.handleRequest(new Request(new URL(req.url, base), { method: "POST", headers }), {
+                // MANDATORY: Fastify has already drained the socket, so without this
+                // the transport calls .json() on an empty body and reports
+                // "Parse error: Invalid JSON" for perfectly valid input.
+                parsedBody: req.body,
+            });
+            // Flush response headers BEFORE the body. Node buffers writeHead() until
+            // the first body byte, so a slow tool call (every turn-spawning op is one)
+            // would stall the response headers for its whole duration — measured at
+            // 3011ms vs 28ms — which reads as a hang to a proxy with a header timeout.
+            // `forEach` rather than `entries()`: the server tsconfig's lib doesn't
+            // include the DOM iterable declarations, so `Headers` has no iterator here.
+            const outHeaders = {};
+            response.headers.forEach((value, key) => {
+                outHeaders[key] = value;
+            });
+            reply.raw.writeHead(response.status, outHeaders);
+            reply.raw.flushHeaders();
+            if (!response.body) {
+                reply.raw.end();
+                void server.close();
+                return reply.hijack();
+            }
+            const body = Readable.fromWeb(response.body);
+            body.pipe(reply.raw);
+            reply.raw.on("close", () => {
+                body.destroy();
+                void server.close();
+            });
+            // Hijack tells Fastify we own the socket — the SDK has already written it.
+            return reply.hijack();
+        },
+    });
+}

package/packages/server/dist/routes/meta.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Instance/identity/metadata routes + the attachment byte surface: voice
+ * transcription, `/api/me`, health, `/api/models`, `/api/fleet`,
+ * instance-wide settings (issue #385), the inbound composer
+ * upload (#328), and the range-serving `/api/chat-files/:id` endpoint (#112/#126).
+ */
+import type { FastifyInstance } from "fastify";
+import { type RouteCtx } from "../route-context.js";
+export declare function registerMetaRoutes(app: FastifyInstance, ctx: RouteCtx): void;
+/**
+ * The workspace-scoped slice of this file: registered once per workspace mount
+ * (root and per project) — see `workspace-mount.ts`. Paths are relative to the
+ * mount.
+ */
+export declare function registerMetaWorkspaceRoutes(app: FastifyInstance, ctx: RouteCtx): void;