@jxsuite/server 4.2.2 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "4.2.2",
+  "version": "4.4.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,7 @@
     "./packages": "./src/packages.ts",
     "./project-server": "./src/project-server.ts",
     "./oauth-loopback": "./src/oauth-loopback.ts",
+    "./net-guard": "./src/net-guard.ts",
     "./live-preview": "./src/live-preview.ts",
     "./site-preview": "./src/site-preview.ts",
     "./refactor": "./src/refactor/index.ts",
@@ -40,23 +41,25 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
+    "@jxsuite/ai": "^0.39.0",
     "@jxsuite/catalog": "^0.1.0",
-    "@jxsuite/collab": "^0.9.0",
-    "@jxsuite/compiler": "^4.0.1",
-    "@jxsuite/create": "^1.3.11",
-    "@jxsuite/import": "^0.40.3",
-    "@jxsuite/protocol": "^2.3.1",
-    "@jxsuite/runtime": "^4.0.1",
-    "@jxsuite/schema": "^2.2.0",
-    "@jxsuite/site": "^2.0.1",
-    "@jxsuite/starters": "^1.8.1",
+    "@jxsuite/collab": "^0.10.0",
+    "@jxsuite/compiler": "^4.0.2",
+    "@jxsuite/create": "^1.3.12",
+    "@jxsuite/import": "^0.40.4",
+    "@jxsuite/protocol": "^2.5.0",
+    "@jxsuite/runtime": "^4.0.2",
+    "@jxsuite/schema": "^2.3.0",
+    "@jxsuite/site": "^2.0.2",
+    "@jxsuite/starters": "^1.8.2",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.6",
+    "oxfmt": "^0.70.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.6.0",
-    "@jxsuite/connector": "^0.6.0",
-    "@jxsuite/parser": "^1.8.1"
+    "@jxsuite/auth": "^0.6.1",
+    "@jxsuite/connector": "^0.6.1",
+    "@jxsuite/parser": "^1.8.2"
   }
 }

package/src/ai-api.ts

@@ -1,54 +1,65 @@
 /**
  * Ai-api.js — AI proxy endpoints for Jx Studio
  *
- * Handles /__studio/ai/chat (SSE streaming proxy to OpenAI) and /__studio/ai/models.
- * The server acts as a thin proxy: validates the request shape, forwards to OpenAI,
- * normalizes the SSE stream into StreamEvent-compatible format, and pipes back.
+ * Handles /__studio/ai/chat (SSE streaming proxy to OpenAI) and /__studio/ai/models. The server
+ * acts as a thin proxy: validates the request shape, forwards to OpenAI, normalizes the SSE stream
+ * into StreamEvent-compatible format, and pipes back.
+ *
+ * The wire half of that (reading the body, the upstream request, the stream normalizer, the SSE
+ * framing, the problem responses) is `@jxsuite/ai/gateway`, which every backend serving these
+ * routes can share. What stays here is this server's POLICY, which no other host shares:
  *
  * API key flow:
- *   1. Request header X-Api-Key or Authorization: Bearer <key>
- *   2. Fallback: OPENAI_API_KEY env var — attached ONLY to the env/default base URL, never to a
- *      caller-supplied X-Api-Base-URL (prevents exfiltrating the server key to a chosen endpoint)
- *   3. If neither → 401 with error message
+ *
+ * 1. Request header X-Api-Key or Authorization: Bearer <key>
+ * 2. Fallback: OPENAI_API_KEY env var — attached ONLY to the env/default base URL, never to a
+ *    caller-supplied X-Api-Base-URL (prevents exfiltrating the server key to a chosen endpoint)
+ * 3. If neither → 401 with error message
  *
  * Base URL flow:
- *   1. Request header X-Api-Base-URL — allowed only alongside a header API key
- *   2. Fallback: OPENAI_BASE_URL env var
- *   3. Default: https://api.openai.com/v1
- *   A base URL resolving to a cloud metadata / link-local host is refused (SSRF defense).
+ *
+ * 1. Request header X-Api-Base-URL — allowed only alongside a header API key
+ * 2. Fallback: OPENAI_BASE_URL env var
+ * 3. Default: https://api.openai.com/v1
+ *
+ * A base URL resolving to a cloud metadata / link-local host is refused (SSRF defense).
+ *
+ * Prompt-cache affinity: a request carrying a valid X-Jx-Ai-Session header (the client's
+ * conversation id) is forwarded with `sessionAffinity` set to a hash of it, scoped to this server
+ * ("local"). The gateway sends that hash only to an upstream that routes on it (OpenAI, Workers
+ * AI); the raw id never leaves this process. An absent or malformed header just means no hint: the
+ * request is still served.
+ *
+ * The model catalogue for /models is this server's too: its defaults, and how it reads the
+ * upstream's own listing.
  *
  * @license MIT
  */
-import { problem, problemTypeForStatus } from "./problem.ts";
+import {
+  AI_SESSION_HEADER,
+  affinityKey,
+  createChatHandler,
+  extractUpstreamErrorMessage,
+  isAiSessionId,
+  modelsResponse,
+  problemResponse,
+} from "@jxsuite/ai/gateway";
+import type { GatewayRefusal, Upstream } from "@jxsuite/ai/gateway";
 import { problemDetails } from "@jxsuite/protocol";
+import { problemTypeForStatus } from "./problem.ts";
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 
 const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 
-/** A tool-call fragment inside an OpenAI streaming `delta`. */
-interface ToolCallDelta {
-  index: number;
-  id?: string;
-  type?: string;
-  function?: { name?: string; arguments?: string };
-}
+/** The model a chat request that names none is forwarded with. */
+const DEFAULT_MODEL = "gpt-4o";
 
-/** A single OpenAI chat-completions streaming chunk (the JSON after `data: `). */
-interface OpenAIStreamChunk {
-  choices?: {
-    index?: number;
-    delta?: {
-      content?: string;
-      /** Thinking models' chain-of-thought: DeepSeek/Volcengine spell it this way… */
-      reasoning_content?: string;
-      /** …and OpenRouter this way. Both carry the same thing. */
-      reasoning?: string;
-      tool_calls?: ToolCallDelta[];
-    };
-    finish_reason?: string | null;
-  }[];
-}
+/**
+ * This server's namespace for affinity keys. Every dev/desktop server shares it: their keys never
+ * meet a hosted backend's, because that one hashes under its own scope.
+ */
+const AFFINITY_SCOPE = "local";
 
 /** A model entry from the upstream `/models` listing. */
 interface ModelEntry {
@@ -144,347 +155,57 @@ function getConfig(req: Request): AiConfig {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-/** Write an SSE event to the response stream. */
-function writeSSE(controller: ReadableStreamDefaultController, event: unknown): void {
-  const data = JSON.stringify(event);
-  controller.enqueue(new TextEncoder().encode(`data: ${data}\n\n`));
-}
-
 /**
- * Extract a human-readable message from an upstream error body, falling back to the raw body (or
- * `fallback` when the body is empty).
+ * A refusal at a status this file chose.
  *
- * OpenAI-compatible providers return `{ error: "..." }` or `{ error: { message: "..." } }`.
- * Cloudflare's own REST API — what a BYOK base URL pointed at Workers AI actually returns — uses a
- * different envelope, `{ success: false, errors: [{ code, message }] }`, with no top-level `error`
- * key at all. Without this branch that shape parses as valid JSON with nothing matched, and the
- * caller was left showing the whole raw body (e.g. the full `{"success":false,"errors":[...]}`
- * blob) instead of the human sentence inside it.
+ * The status picks the type rather than the other way round, because this file's refusals were
+ * always written as statuses (`reject.status`), and the response carries the TYPE's status, exactly
+ * as `problem()` answers.
  */
-function extractUpstreamErrorMessage(rawBody: string, fallback: string): string {
-  if (!rawBody) {
-    return fallback;
-  }
-  try {
-    const { error, errors } = JSON.parse(rawBody) as {
-      error?: string | { message?: string };
-      errors?: { code?: number; message?: string }[];
-    };
-    if (typeof error === "string") {
-      return error;
-    }
-    if (error) {
-      const { message } = error;
-      if (message) {
-        return message;
-      }
-    }
-    const [first] = errors ?? [];
-    if (first) {
-      const { message } = first;
-      if (message) {
-        return message;
-      }
-    }
-  } catch {
-    /* Not JSON — use the raw body. */
-  }
-  return rawBody;
+function refuse(status: number, message: string): GatewayRefusal {
+  const problem = problemDetails(problemTypeForStatus(status), message);
+  return { problem, status: problem.status };
 }
 
 /**
- * Write a failure response for the non-streaming endpoints.
- *
- * The status is chosen by the caller here rather than by the type, because this file's callers
- * forward an upstream provider's status — which is information, and collapsing it to the type's own
- * would throw it away.
+ * This server's upstream for a request, or its refusal: the key-provenance and SSRF rules above,
+ * applied per request (the environment is read each time, so a key set later is honoured). A valid
+ * session header adds the hashed affinity key; an invalid one is ignored rather than refused.
  */
-function jsonError(status: number, message: string): Response {
-  return problem(problemTypeForStatus(status), message);
-}
-
-// ─── /__studio/ai/chat — SSE streaming proxy ───────────────────────────────
-
-/** Handle POST /__studio/ai/chat — proxy chat completions to OpenAI via SSE. */
-export async function handleChat(req: Request): Promise<Response> {
-  const { apiKey, baseUrl, missingKey, reject } = getConfig(req);
+async function resolveUpstream(req: Request): Promise<Upstream | GatewayRefusal> {
+  const { apiKey, baseUrl, reject } = getConfig(req);
   if (reject) {
-    return jsonError(reject.status, reject.message);
+    return refuse(reject.status, reject.message);
   }
-  if (missingKey) {
-    return jsonError(
+  if (!apiKey) {
+    return refuse(
       401,
       "No API key configured. Set OPENAI_API_KEY env var or send X-Api-Key header.",
     );
   }
-
-  // Parse request body
-  let body: {
-    messages?: unknown[];
-    tools?: unknown[];
-    systemPrompt?: string;
-    model?: string;
+  const upstream: Upstream = {
+    apiKey,
+    baseUrl,
+    defaultModel: DEFAULT_MODEL,
+    family: "openai-compat",
+    managed: false,
   };
-  try {
-    body = (await req.json()) as {
-      messages?: unknown[];
-      tools?: unknown[];
-      systemPrompt?: string;
-      model?: string;
-    };
-  } catch {
-    return jsonError(400, "Invalid JSON body");
+  const sessionId = req.headers.get(AI_SESSION_HEADER);
+  if (isAiSessionId(sessionId)) {
+    return { ...upstream, sessionAffinity: await affinityKey(AFFINITY_SCOPE, sessionId) };
   }
+  return upstream;
+}
 
-  const { messages = [], tools = [], systemPrompt = "", model = "gpt-4o" } = body;
-
-  if (!Array.isArray(messages)) {
-    return jsonError(400, "messages must be an array");
-  }
-
-  // Build OpenAI request
-  const openaiBody: {
-    model: string;
-    messages: unknown[];
-    stream: boolean;
-    stream_options: { include_usage: boolean };
-    tools?: unknown[];
-    tool_choice?: string;
-    parallel_tool_calls?: boolean;
-  } = {
-    model,
-    messages: [{ role: "system", content: systemPrompt }, ...messages],
-    stream: true,
-    stream_options: { include_usage: true },
-  };
-
-  if (tools && tools.length > 0) {
-    openaiBody.tools = tools;
-    openaiBody.tool_choice = "auto";
-    openaiBody.parallel_tool_calls = true;
-  }
-
-  const upstreamUrl = `${baseUrl}/chat/completions`;
-
-  // Create the SSE stream
-  const stream = new ReadableStream({
-    async start(controller) {
-      let response;
-      try {
-        response = await fetch(upstreamUrl, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${apiKey}`,
-          },
-          body: JSON.stringify(openaiBody),
-          signal: req.signal,
-        });
-      } catch (error) {
-        if ((error as Error).name === "AbortError") {
-          writeSSE(controller, { type: "done", stopReason: "cancelled" });
-        } else {
-          const message = `Network error: ${(error as Error).message}`;
-          writeSSE(controller, {
-            message,
-            /*
-             * The frame carries a problem rather than being one: the response began with a 200
-             * long before this failed, so nothing can change the status now. `message` stays for
-             * the readers that already show it (server.md §4.3).
-             */
-            problem: problemDetails("upstreamFailure", message),
-            type: "error",
-          });
-        }
-        controller.close();
-        return;
-      }
-
-      if (!response.ok) {
-        let errorBody = "";
-        try {
-          errorBody = await response.text();
-        } catch {
-          /* Ignore */
-        }
-        const cleanMessage = extractUpstreamErrorMessage(errorBody, response.statusText);
-        writeSSE(controller, {
-          code: String(response.status),
-          message: cleanMessage,
-          // The upstream's own status is preserved in `code`; the problem names the KIND.
-          problem: problemDetails(problemTypeForStatus(response.status), cleanMessage),
-          type: "error",
-        });
-        controller.close();
-        return;
-      }
-
-      const reader = response.body?.getReader();
-      if (!reader) {
-        writeSSE(controller, {
-          message: "No response body from upstream",
-          problem: problemDetails("upstreamFailure", "No response body from upstream"),
-          type: "error",
-        });
-        controller.close();
-        return;
-      }
-
-      const decoder = new TextDecoder();
-      let buffer = "";
+// ─── /__studio/ai/chat — SSE streaming proxy ───────────────────────────────
 
-      const pendingToolCalls = new Map<number, { id: string; name: string; args: string }>();
+const chatHandler = createChatHandler<{ readonly signal: AbortSignal }>({
+  resolveUpstream: (request) => resolveUpstream(request),
+});
 
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) {
-            break;
-          }
-
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop() || "";
-
-          for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed || !trimmed.startsWith("data: ")) {
-              continue;
-            }
-
-            const dataStr = trimmed.slice(6);
-            if (dataStr === "[DONE]") {
-              // Emit pending tool call ends
-              for (const [, tc] of pendingToolCalls) {
-                writeSSE(controller, { type: "tool_call_end", id: tc.id });
-              }
-              pendingToolCalls.clear();
-              writeSSE(controller, { type: "done", stopReason: "stop" });
-              controller.close();
-              return;
-            }
-
-            let parsed: OpenAIStreamChunk;
-            try {
-              parsed = JSON.parse(dataStr) as OpenAIStreamChunk;
-            } catch {
-              continue;
-            }
-
-            const choice = parsed.choices?.[0];
-            if (!choice) {
-              continue;
-            }
-
-            const { delta } = choice;
-            if (!delta) {
-              continue;
-            }
-
-            // Text content
-            if (delta.content) {
-              writeSSE(controller, { type: "delta", content: delta.content });
-            }
-
-            /* Chain-of-thought, under either of the two names providers give it. Forwarded rather
-               than dropped: DeepSeek's thinking mode requires every prior turn's reasoning back on
-               any request carrying `tools`, so a proxy that swallows these frames makes the NEXT
-               round a 400 the client cannot repair. */
-            const reasoning = delta.reasoning_content ?? delta.reasoning;
-            if (typeof reasoning === "string" && reasoning) {
-              writeSSE(controller, { type: "reasoning", content: reasoning });
-            }
-
-            // Tool calls
-            if (delta.tool_calls) {
-              for (const tc of delta.tool_calls) {
-                if (tc.id) {
-                  // First appearance
-                  const entry = {
-                    id: tc.id,
-                    name: tc.function?.name || "",
-                    args: tc.function?.arguments || "",
-                  };
-                  pendingToolCalls.set(tc.index, entry);
-
-                  writeSSE(controller, { type: "tool_call_start", id: tc.id, name: entry.name });
-
-                  if (entry.args) {
-                    writeSSE(controller, { type: "tool_call_delta", id: tc.id, args: entry.args });
-                  }
-                } else if (tc.function?.arguments) {
-                  // Subsequent fragment
-                  const existing = pendingToolCalls.get(tc.index);
-                  if (existing) {
-                    existing.args += tc.function.arguments;
-                    writeSSE(controller, {
-                      type: "tool_call_delta",
-                      id: existing.id,
-                      args: tc.function.arguments,
-                    });
-                  }
-                }
-              }
-            }
-
-            // Finish reason
-            if (choice.finish_reason === "tool_calls") {
-              for (const [, tc] of pendingToolCalls) {
-                writeSSE(controller, { type: "tool_call_end", id: tc.id });
-              }
-              pendingToolCalls.clear();
-              writeSSE(controller, { type: "done", stopReason: "tool_calls" });
-              controller.close();
-              return;
-            }
-
-            if (choice.finish_reason === "stop" || choice.finish_reason === "length") {
-              for (const [, tc] of pendingToolCalls) {
-                writeSSE(controller, { type: "tool_call_end", id: tc.id });
-              }
-              pendingToolCalls.clear();
-              writeSSE(controller, {
-                type: "done",
-                stopReason: choice.finish_reason === "length" ? "length" : "stop",
-              });
-              controller.close();
-              return;
-            }
-          }
-        }
-
-        // Stream ended without explicit finish_reason
-        for (const [, tc] of pendingToolCalls) {
-          writeSSE(controller, { type: "tool_call_end", id: tc.id });
-        }
-        pendingToolCalls.clear();
-        writeSSE(controller, { type: "done", stopReason: "stop" });
-        controller.close();
-      } catch (error) {
-        void reader.cancel();
-        if ((error as Error).name === "AbortError") {
-          writeSSE(controller, { type: "done", stopReason: "cancelled" });
-          controller.close();
-          return;
-        }
-        const message = `Stream error: ${(error as Error).message}`;
-        writeSSE(controller, {
-          message,
-          problem: problemDetails("upstreamFailure", message),
-          type: "error",
-        });
-        controller.close();
-      }
-    },
-  });
-
-  return new Response(stream, {
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive",
-    },
-  });
+/** Handle POST /__studio/ai/chat — proxy chat completions to OpenAI via SSE. */
+export async function handleChat(req: Request): Promise<Response> {
+  return chatHandler(req, { signal: req.signal });
 }
 
 // ─── /__studio/ai/models — model listing ────────────────────────────────────
@@ -500,7 +221,7 @@ export async function handleChat(req: Request): Promise<Response> {
 export async function handleModels(req: Request): Promise<Response> {
   const { apiKey, baseUrl, missingKey, reject } = getConfig(req);
   if (reject) {
-    return jsonError(reject.status, reject.message);
+    return problemResponse(refuse(reject.status, reject.message));
   }
 
   // No key available → return hardcoded defaults so the UI can at least render.
@@ -511,12 +232,7 @@ export async function handleModels(req: Request): Promise<Response> {
       { id: "gpt-4.1-mini", name: "GPT-4.1 Mini", contextWindow: 1_000_000 },
       { id: "gpt-4o-mini", name: "GPT-4o Mini", contextWindow: 128_000 },
     ];
-    return Response.json(
-      { models: defaults, configured: false, managed: false },
-      {
-        headers: { "Content-Type": "application/json" },
-      },
-    );
+    return modelsResponse({ models: defaults, configured: false, managed: false });
   }
 
   // Key is available — proxy to the upstream /models endpoint.
@@ -536,18 +252,13 @@ export async function handleModels(req: Request): Promise<Response> {
       }
       const upstreamMessage = extractUpstreamErrorMessage(errorBody, upstreamResp.statusText);
       const defaults = [{ id: "gpt-4o", name: "GPT-4o", contextWindow: 128_000 }];
-      return Response.json(
-        {
-          models: defaults,
-          configured: true,
-          managed: false,
-          upstreamError: upstreamResp.status,
-          upstreamMessage,
-        },
-        {
-          headers: { "Content-Type": "application/json" },
-        },
-      );
+      return modelsResponse({
+        models: defaults,
+        configured: true,
+        managed: false,
+        upstreamError: upstreamResp.status,
+        upstreamMessage,
+      });
     }
 
     const data = (await upstreamResp.json()) as { data?: ModelEntry[] } | ModelEntry[];
@@ -565,27 +276,17 @@ export async function handleModels(req: Request): Promise<Response> {
       ownedBy: owned_by,
     }));
 
-    return Response.json(
-      { models, configured: true, managed: false },
-      {
-        headers: { "Content-Type": "application/json" },
-      },
-    );
+    return modelsResponse({ models, configured: true, managed: false });
   } catch (error) {
     // Network error → return defaults.
     const defaults = [{ id: "gpt-4o", name: "GPT-4o", contextWindow: 128_000 }];
-    return Response.json(
-      {
-        models: defaults,
-        configured: true,
-        managed: false,
-        upstreamError: "network",
-        upstreamMessage: (error as Error).message,
-      },
-      {
-        headers: { "Content-Type": "application/json" },
-      },
-    );
+    return modelsResponse({
+      models: defaults,
+      configured: true,
+      managed: false,
+      upstreamError: "network",
+      upstreamMessage: (error as Error).message,
+    });
   }
 }
 

package/src/problem.ts

@@ -44,9 +44,12 @@ export function problem(
  * The declared type for a status a caller already computed.
  *
  * Two files need this and no more should: `data-api.ts`, whose `ApiError` predates the registry and
- * carries only a status, and `ai-api.ts`, which forwards an upstream provider's status because
- * collapsing it to the type's own would discard information. Everywhere else the type is named at
- * the call site, which is what keeps the registry meaningful — a status is not a failure kind.
+ * carries only a status, and `ai-api.ts`, whose key and base-URL refusals are written as statuses.
+ * Everywhere else the type is named at the call site, which is what keeps the registry meaningful —
+ * a status is not a failure kind. The AI proxy's other use, forwarding an upstream provider's
+ * status because collapsing it would discard information, moved with the stream normalizer into
+ * `@jxsuite/ai/gateway`, which carries its own copy of this table; `tests/ai-api-gateway.test.ts`
+ * holds the two to agreement for every status.
  *
  * @param {number} status
  * @returns {ProblemTypeName}

package/src/studio-api.ts

@@ -1206,6 +1206,33 @@ export async function handleStudioApi(
     }
   }
 
+  /* Read a file's raw BYTES.
+     The read side of `/__studio/file/upload`, and a separate route from `/__studio/file` rather
+     than a flag on it, because the two differ in more than encoding: that route answers a JSON
+     envelope `{ content, path }` with `max-age=5`, and both are wrong here. A caller wanting bytes
+     wants a body, and a caller about to overwrite the file must not be handed a five-second-old
+     copy of it — an edit applied to stale bytes is a silently wrong file.
+
+     `Bun.file` streams from disk and infers the media type from the extension, which is what makes
+     this a handful of lines rather than a decoder. */
+  if (path === "/__studio/file/bytes" && req.method === "GET") {
+    const fp = url.searchParams.get("path");
+    if (!fp) {
+      return problem("invalidRequest", "Missing path");
+    }
+    const abs = expandTilde(fp);
+    try {
+      assertAccessible(abs, root, activeProjectRoot);
+    } catch (error) {
+      return new Response(errorMessage(error), { status: 400 });
+    }
+    const file = Bun.file(abs);
+    if (!(await file.exists())) {
+      return problem("notFound", "Not found");
+    }
+    return new Response(file, { headers: { "Cache-Control": "no-store" } });
+  }
+
   // Write file
   if (path === "/__studio/file" && req.method === "PUT") {
     const fp = url.searchParams.get("path");