catalyst-core 1.0.0 → 1.0.1-canary.1

package/dist/native/bridge/hooks/useNativeTransition.js

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useNativeTransition = void 0;
 var _react = require("react");
-var _reactRouter = require("react-router");
+var _useSafeNavigate = require("./useSafeNavigate.js");
 var _NativeBridge = _interopRequireDefault(require("../utils/NativeBridge.js"));
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
@@ -40,7 +40,7 @@ const MIN_TIMEOUT = 800;
  * @param defaults - Default transition options applied to every navigate call
  */
 const useNativeTransition = (defaults = {}) => {
-  const router = (0, _reactRouter.useNavigate)();
+  const router = (0, _useSafeNavigate.useSafeNavigate)();
   const isNative = typeof window !== "undefined" && _NativeBridge.default.isAvailable();
   const [transitioning, setTransitioning] = (0, _react.useState)(false);
   const overlayRef = (0, _react.useRef)(null);

package/dist/native/bridge/hooks/useSafeNavigate.d.ts

@@ -0,0 +1,10 @@
+import { useNavigate } from "react-router";
+/**
+ * useNavigate() that is safe to call while server rendering.
+ *
+ * Server rendering never navigates, so it skips useNavigate there. In dev SSR src/native is compiled to
+ * CommonJS while the server's StaticRouter is ESM, which can load a second copy of react-router with no
+ * Router context; useNavigate would then throw and take the request, and the dev server, down. `window`
+ * is fixed per environment, so the hook order is stable.
+ */
+export declare const useSafeNavigate: () => ReturnType<typeof useNavigate>;

package/dist/native/bridge/hooks/useSafeNavigate.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSafeNavigate = void 0;
+var _reactRouter = require("react-router");
+// Stand-in for useNavigate() during server rendering, where nothing can navigate.
+const ssrNavigate = () => {};
+
+/**
+ * useNavigate() that is safe to call while server rendering.
+ *
+ * Server rendering never navigates, so it skips useNavigate there. In dev SSR src/native is compiled to
+ * CommonJS while the server's StaticRouter is ESM, which can load a second copy of react-router with no
+ * Router context; useNavigate would then throw and take the request, and the dev server, down. `window`
+ * is fixed per environment, so the hook order is stable.
+ */
+const useSafeNavigate = () =>
+// eslint-disable-next-line react-hooks/rules-of-hooks
+typeof window === "undefined" ? ssrNavigate : (0, _reactRouter.useNavigate)();
+exports.useSafeNavigate = useSafeNavigate;

package/dist/native/buildAppIos.js

@@ -10,7 +10,8 @@ const {
 } = require("./pluginComposerIos.js");
 const {
   resolveInternalPluginsRoot,
-  resolvePluginConfig
+  resolvePluginConfig,
+  resolveAIPluginSource
 } = require("./internalPluginUtils.js");
 const {
   formatBuildError
@@ -36,9 +37,14 @@ async function main() {
   } = build;
   try {
     progress.log("Starting build process...", "info");
-    const pluginConfig = resolvePluginConfig(WEBVIEW_CONFIG);
+    const aiPlugin = resolveAIPluginSource(WEBVIEW_CONFIG, process.cwd(), (message, status = "info") => progress.log(message, status));
+    const pluginConfig = {
+      ...resolvePluginConfig(WEBVIEW_CONFIG),
+      ...aiPlugin.toggles
+    };
     const pluginComposition = composeIosPlugins({
       corePluginsRoot: resolveInternalPluginsRoot(catalystCorePath),
+      externalPluginRoots: aiPlugin.roots,
       iosProjectPath: PROJECT_DIR,
       pluginConfig,
       log: (message, status = "info") => progress.log(message, status)

package/dist/native/buildIos/plugins.js

@@ -38,7 +38,9 @@ function formatSwiftPackageRequirement(dependency) {
   throw new Error(`Unsupported iOS package requirement type: ${dependency.requirement.type}`);
 }
 function formatSwiftPackageEntries(dependencies) {
-  return dependencies.map(d => `        .package(url: "${d.url}", ${formatSwiftPackageRequirement(d)})`);
+  return dependencies.map(d =>
+  // Local packages (requirement.type "path") are addressed by directory, not URL + version.
+  d.requirement.type === "path" ? `        .package(path: ${JSON.stringify(d.url)})` : `        .package(url: "${d.url}", ${formatSwiftPackageRequirement(d)})`);
 }
 function formatSwiftProductEntries(dependencies) {
   return dependencies.flatMap(d => d.products.map(p => `                .product(name: "${p}", package: "${d.package}")`));

package/dist/native/internalPluginUtils.js

@@ -64,6 +64,45 @@ function readIosUrlSchemes(value, fieldName, sourcePath) {
     };
   });
 }
+function readLocalIosDependency(entry, entryField, sourcePath) {
+  const pluginDir = path.dirname(sourcePath);
+  const relativePath = mustBeNonEmptyString(entry.path, `${entryField}.path`, sourcePath);
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - containment within pluginDir is enforced immediately below.
+  const resolved = path.resolve(pluginDir, relativePath);
+  if (resolved !== pluginDir && !resolved.startsWith(`${pluginDir}${path.sep}`)) {
+    throw new Error(`'${entryField}.path' must stay within the plugin directory: ${relativePath} in ${sourcePath}`);
+  }
+  if (!isDir(resolved)) {
+    throw new Error(`'${entryField}.path' does not exist: ${relativePath} in ${sourcePath}`);
+  }
+  // The lexical check above does not see symlinks: re-check containment on canonical paths so a link
+  // inside the plugin cannot point the Swift package outside it, and return the canonical path.
+  const realPluginDir = fs.realpathSync(pluginDir);
+  const realResolved = fs.realpathSync(resolved);
+  if (realResolved !== realPluginDir && !realResolved.startsWith(`${realPluginDir}${path.sep}`)) {
+    throw new Error(`'${entryField}.path' resolves outside the plugin directory: ${relativePath} in ${sourcePath}`);
+  }
+  if (entry.from != null || entry.exact != null || entry.url != null) {
+    throw new Error(`'${entryField}' with 'path' must not also set 'url', 'from' or 'exact' in ${sourcePath}`);
+  }
+  const products = readStringArray(entry.products, `${entryField}.products`, sourcePath, {
+    required: true,
+    nonEmpty: true
+  });
+  if (new Set(products).size !== products.length) {
+    throw new Error(`Duplicate product(s) found in '${entryField}.products' in ${sourcePath}`);
+  }
+  return {
+    // The absolute path doubles as the identity key the composer merges dependencies on.
+    url: realResolved,
+    package: entry.package == null ? path.basename(realResolved) : mustBeNonEmptyString(entry.package, `${entryField}.package`, sourcePath),
+    products,
+    requirement: {
+      type: "path",
+      version: "local"
+    }
+  };
+}
 function readIosDependencies(value, fieldName, sourcePath) {
   if (value == null) {
     return [];
@@ -76,6 +115,13 @@ function readIosDependencies(value, fieldName, sourcePath) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
       throw new Error(`'${entryField}' must be an object in ${sourcePath}`);
     }
+
+    // A dependency is either a remote package ({ url, from|exact }) or a Swift package shipped inside
+    // the plugin itself ({ path }, relative to the plugin directory). Local packages let a plugin
+    // pin a vendored copy instead of cloning a large or LFS-backed upstream repo.
+    if (entry.path != null) {
+      return readLocalIosDependency(entry, entryField, sourcePath);
+    }
     const url = mustBeNonEmptyString(entry.url, `${entryField}.url`, sourcePath);
     const packageIdentity = entry.package == null ? derivePackageIdentityFromUrl(url, `${entryField}.url`, sourcePath) : mustBeNonEmptyString(entry.package, `${entryField}.package`, sourcePath);
     const products = readStringArray(entry.products, `${entryField}.products`, sourcePath, {
@@ -224,7 +270,39 @@ function resolvePluginConfig(WEBVIEW_CONFIG) {
   }
   return pluginConfig;
 }
+
+/**
+ * catalyst-ai ships its native iOS module as a plugin (plugins/ai in the npm package). It is
+ * composed only when the app opts in with WEBVIEW_CONFIG.ai.enabled, mirroring Android's
+ * syncAIPackageIfEnabled. Returns the extra plugin roots plus the toggle to merge into the
+ * plugin config; when the package is missing it warns and leaves the build untouched.
+ */
+function resolveAIPluginSource(WEBVIEW_CONFIG, projectRoot, log = () => {}) {
+  if (WEBVIEW_CONFIG?.ai?.enabled !== true) {
+    return {
+      roots: [],
+      toggles: {}
+    };
+  }
+
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - fixed package-relative path under the app's node_modules.
+  const aiPluginsRoot = path.join(projectRoot, "node_modules", "catalyst-ai", "plugins");
+  if (!isDir(aiPluginsRoot)) {
+    log("ai.enabled=true but catalyst-ai not found in node_modules — skipping native AI plugin", "warning");
+    return {
+      roots: [],
+      toggles: {}
+    };
+  }
+  return {
+    roots: [aiPluginsRoot],
+    toggles: {
+      ai: true
+    }
+  };
+}
 module.exports = {
+  resolveAIPluginSource,
   discoverInternalPlugins,
   parsePluginManifest,
   resolvePluginConfig,

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils+NativeAI.swift

@@ -0,0 +1,221 @@
+//
+//  FrameworkServerUtils+NativeAI.swift
+//  iosnativeWebView
+//
+//  Native-AI routes (/ai/stream, /ai/generate) and their supplier API, split out of FrameworkServerUtils.swift
+//  to keep that file within the lint limits. Kotlin equivalent: the AI routes in startKtorServer().
+//
+
+import Foundation
+import Network
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "FrameworkServer")
+
+extension FrameworkServerUtils {
+    // MARK: - Native AI API
+
+    /// Installs the engine that answers `POST /ai/stream` and `POST /ai/generate`. Each request calls the supplier
+    /// with the (system-prompt-prefixed) prompt, the request's `genConfig` and its conversation id. While it is
+    /// `nil` (the default, and after passing `nil`) both routes answer "not ready" (`AI-005`) instead of running.
+    /// Set by the AI plugin once its engine has loaded.
+    public func setNativeAiSupplier(_ supplier: NativeAISupplier?) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        nativeAiSupplier = supplier
+    }
+
+    /// Sets the system prompt the server prepends (as `"<prompt>\n\n<user prompt>"`) to every AI request before it
+    /// reaches the supplier. Pass an empty string to prepend nothing, for engines that keep their instructions in
+    /// their own session. Read per request, so changes apply to the next one.
+    public func setNativeSystemPrompt(_ systemPrompt: String) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        nativeSystemPrompt = systemPrompt
+    }
+
+    /// URL JS posts to for streaming; scheme follows whatever the listener actually runs (HTTP/HTTPS),
+    /// built the same way as served-file URLs.
+    public func nativeAIStreamURL() -> String? {
+        guard isServerRunning else { return nil }
+        let scheme = isHTTPS ? "https" : "http"
+        return "\(scheme)://localhost:\(serverPort)/framework-\(sessionId)/ai/stream"
+    }
+
+
+    // MARK: - Native AI routes
+    // Kotlin equivalent: the post("/ai/stream"), post("/ai/generate") and options(...) routes in
+    // startKtorServer(). The engine behind the supplier lives in catalyst-ai, not here.
+
+    private func aiSnapshot() -> (supplier: NativeAISupplier?, systemPrompt: String) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        return (nativeAiSupplier, nativeSystemPrompt)
+    }
+
+    /// The server prepends the engine-provided system prompt, exactly like Android.
+    /// Engines that manage their own instructions simply never call setNativeSystemPrompt.
+    private func composePrompt(_ request: NativeAIRequest, systemPrompt: String) -> String {
+        systemPrompt.isEmpty ? request.prompt : "\(systemPrompt)\n\n\(request.prompt)"
+    }
+
+    func sendAIPreflight(on connection: NWConnection) {
+        sendHTTPResponse(on: connection, statusCode: 200, body: Data(), headers: [
+            "Access-Control-Allow-Methods": "POST, OPTIONS",
+            "Access-Control-Max-Age": "86400",
+        ])
+    }
+
+    func cancelAIStream(for connection: NWConnection) {
+        requestStateLock.lock()
+        let task = aiStreamTasks.removeValue(forKey: ObjectIdentifier(connection))
+        requestStateLock.unlock()
+        task?.cancel()
+    }
+
+    /// A client that stops reading must not keep the model running: if a write is not accepted within this long,
+    /// the connection is dropped, which fails the send, ends the stream and cancels generation upstream.
+    static let aiWriteTimeout: TimeInterval = 30
+
+    private func sendRaw(_ data: Data, on connection: NWConnection) async -> Bool {
+        await withCheckedContinuation { continuation in
+            let deadline = DispatchWorkItem { connection.cancel() }
+            DispatchQueue.global().asyncAfter(deadline: .now() + Self.aiWriteTimeout, execute: deadline)
+            connection.send(content: data, completion: .contentProcessed { error in
+                deadline.cancel()
+                if let error = error {
+                    logger.debug("AI stream send failed: \(error.localizedDescription)")
+                }
+                continuation.resume(returning: error == nil)
+            })
+        }
+    }
+
+    private func sseHeaders() -> Data {
+        var head = "HTTP/1.1 200 OK\r\n"
+        head += "Access-Control-Allow-Origin: \(allowedOrigin)\r\n"
+        head += "Access-Control-Allow-Methods: POST, OPTIONS\r\n"
+        head += "Access-Control-Allow-Headers: *\r\n"
+        head += "Content-Type: text/event-stream\r\n"
+        head += "Cache-Control: no-cache\r\n"
+        head += "X-Accel-Buffering: no\r\n"
+        head += "Connection: close\r\n"
+        head += "\r\n"
+        return Data(head.utf8)
+    }
+
+    func startAIStream(_ request: NativeAIRequest, on connection: NWConnection) {
+        cancelConnectionTimeout(for: connection)
+        let key = ObjectIdentifier(connection)
+
+        // Held across Task creation so the task's own cleanup cannot run before it is registered.
+        requestStateLock.lock()
+        aiStreamTasks[key] = Task { [weak self] in
+            guard let self = self else { connection.cancel(); return }
+            await self.runAIStream(request, on: connection)
+            self.cancelAIStream(for: connection)
+            connection.cancel()
+        }
+        requestStateLock.unlock()
+    }
+
+    private func runAIStream(_ request: NativeAIRequest, on connection: NWConnection) async {
+        guard await sendRaw(sseHeaders(), on: connection) else { return }
+
+        let (supplier, systemPrompt) = aiSnapshot()
+        let prompt = composePrompt(request, systemPrompt: systemPrompt)
+
+        guard let supplier = supplier else {
+            _ = await sendRaw(NativeAISSE.error("Native AI not initialised — call initAI() first", code: NativeAIErrorCode.streamNotReady), on: connection)
+            return
+        }
+        guard !request.prompt.isEmpty else {
+            _ = await sendRaw(NativeAISSE.error("prompt is empty", code: NativeAIErrorCode.invalidRequestBody), on: connection)
+            return
+        }
+
+        do {
+            let stream = try await supplier(prompt, request.genConfig, request.conversationId)
+            guard await sendRaw(NativeAISSE.conversationId(stream.conversationId), on: connection) else { return }
+            for try await token in stream.tokens {
+                // A failed send means the client disconnected; leaving the loop terminates the
+                // token stream, which is what stops generation upstream.
+                guard await sendRaw(NativeAISSE.token(token), on: connection) else { return }
+            }
+            _ = await sendRaw(NativeAISSE.done(), on: connection)
+        } catch is CancellationError {
+            logger.debug("Native AI stream cancelled (client disconnected)")
+        } catch {
+            let code = (error as? NativeAIError)?.code ?? NativeAIErrorCode.requestFailed
+            logger.error("Native AI stream error [\(code)] conversation=\(request.conversationId ?? "<new>"): \(error.localizedDescription)")
+            _ = await sendRaw(NativeAISSE.error(error.localizedDescription, code: code), on: connection)
+        }
+    }
+
+    private static let aiGenerateTimeout: TimeInterval = 120
+
+    /// Drains the token stream fully, then answers with one JSON body: { output, conversationId, tokenCount }.
+    func runAIGenerate(_ request: NativeAIRequest, on connection: NWConnection) {
+        cancelConnectionTimeout(for: connection)
+        let key = ObjectIdentifier(connection)
+
+        requestStateLock.lock()
+        aiStreamTasks[key] = Task { [weak self] in
+            guard let self = self else { connection.cancel(); return }
+            await self.respondAIGenerate(request, on: connection)
+            self.cancelAIStream(for: connection)
+        }
+        requestStateLock.unlock()
+    }
+
+    private func respondAIGenerate(_ request: NativeAIRequest, on connection: NWConnection) async {
+        func fail(_ status: Int, _ message: String, _ code: String) {
+            let body = (try? JSONSerialization.data(withJSONObject: ["error": message, "code": code])) ?? Data()
+            sendHTTPResponse(on: connection, statusCode: status, body: body, headers: ["Content-Type": "application/json"])
+        }
+
+        let (supplier, systemPrompt) = aiSnapshot()
+        guard let supplier = supplier else {
+            fail(503, "Native AI not initialised — call initAI() first", NativeAIErrorCode.streamNotReady)
+            return
+        }
+        guard !request.prompt.isEmpty else {
+            fail(400, "prompt is empty", NativeAIErrorCode.invalidRequestBody)
+            return
+        }
+
+        let prompt = composePrompt(request, systemPrompt: systemPrompt)
+        do {
+            let result: (output: String, conversationId: String, tokenCount: Int) = try await withThrowingTaskGroup(of: (String, String, Int)?.self) { group in
+                group.addTask {
+                    let stream = try await supplier(prompt, request.genConfig, request.conversationId)
+                    var output = ""
+                    var count = 0
+                    for try await token in stream.tokens { output += token; count += 1 }
+                    return (output, stream.conversationId, count)
+                }
+                group.addTask {
+                    try await Task.sleep(nanoseconds: UInt64(Self.aiGenerateTimeout * 1_000_000_000))
+                    return nil
+                }
+                defer { group.cancelAll() }
+                guard let first = try await group.next(), let value = first else {
+                    throw NativeAIError(message: "generate timed out after \(Int(Self.aiGenerateTimeout))s")
+                }
+                return value
+            }
+            let body = try JSONSerialization.data(withJSONObject: [
+                "output": result.output,
+                "conversationId": result.conversationId,
+                "tokenCount": result.tokenCount,
+            ])
+            sendHTTPResponse(on: connection, statusCode: 200, body: body, headers: ["Content-Type": "application/json"])
+        } catch is CancellationError {
+            connection.cancel()
+        } catch let error as NativeAIError where error.message.hasPrefix("generate timed out") {
+            fail(504, error.message, error.code)
+        } catch {
+            let code = (error as? NativeAIError)?.code ?? NativeAIErrorCode.requestFailed
+            logger.error("Native AI generate error [\(code)] conversation=\(request.conversationId ?? "<new>"): \(error.localizedDescription)")
+            fail(500, error.localizedDescription, code)
+        }
+    }
+
+}

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils+Requests.swift

@@ -0,0 +1,215 @@
+//
+//  FrameworkServerUtils+Requests.swift
+//  iosnativeWebView
+//
+//  HTTP request assembly (headers + Content-Length body across reads) and routing for the framework server,
+//  split out of FrameworkServerUtils.swift to keep that type within the lint limits.
+//
+
+import Foundation
+import Network
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "FrameworkServer")
+
+extension FrameworkServerUtils {
+    /// Completion body of receiveHTTPRequest. Internal so tests can drive the
+    /// error branch directly; a real receive error is timing-dependent.
+    ///
+    /// A POST's headers and body can arrive in separate reads, so bytes are
+    /// buffered per connection until the headers end (CRLFCRLF) and Content-Length
+    /// bytes of body are present. A GET has no body and dispatches immediately.
+    func handleReceivedData(_ data: Data?, isComplete: Bool, error: NWError?, on connection: NWConnection) {
+        if let error = error {
+            discardPendingRequest(for: connection)
+            handleReceiveError(error, on: connection)
+            return
+        }
+
+        guard let data = data else {
+            discardPendingRequest(for: connection)
+            sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+            return
+        }
+
+        let key = ObjectIdentifier(connection)
+        // Append to the connection's own buffer in place: `old + new` would copy every byte received so far on
+        // each 8 KB read.
+        requestStateLock.lock()
+        var buffer = pendingRequests.removeValue(forKey: key) ?? Data()
+        buffer.append(data)
+        requestStateLock.unlock()
+
+        let terminator = Data("\r\n\r\n".utf8)
+        guard let headerEnd = buffer.range(of: terminator) else {
+            if buffer.count > Self.maxHeaderBytes {
+                discardPendingRequest(for: connection)
+                sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+            } else if isComplete {
+                // Client closed mid-headers: fall through to the legacy single-read behaviour.
+                discardPendingRequest(for: connection)
+                dispatchRequest(headerData: buffer, body: Data(), isComplete: isComplete, on: connection)
+            } else {
+                requestStateLock.lock(); pendingRequests[key] = buffer; requestStateLock.unlock()
+                receiveHTTPRequest(on: connection)
+            }
+            return
+        }
+
+        let headerData = buffer[buffer.startIndex..<headerEnd.lowerBound]
+        let body = buffer[headerEnd.upperBound...]
+        guard let expected = Self.contentLength(inHeaders: headerData) else {
+            discardPendingRequest(for: connection)
+            sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+            return
+        }
+
+        if expected > Self.maxBodyBytes {
+            discardPendingRequest(for: connection)
+            sendHTTPResponse(on: connection, statusCode: 413, body: "Payload Too Large")
+            return
+        }
+        if body.count < expected {
+            if isComplete {
+                // The client closed the connection before sending the declared body: reject rather than
+                // handle a truncated request.
+                discardPendingRequest(for: connection)
+                sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+                return
+            }
+            requestStateLock.lock(); pendingRequests[key] = buffer; requestStateLock.unlock()
+            receiveHTTPRequest(on: connection)
+            return
+        }
+
+        discardPendingRequest(for: connection)
+        dispatchRequest(headerData: Data(headerData), body: Data(body.prefix(max(expected, 0))), isComplete: isComplete, on: connection)
+    }
+
+    func discardPendingRequest(for connection: NWConnection) {
+        requestStateLock.lock()
+        pendingRequests.removeValue(forKey: ObjectIdentifier(connection))
+        requestStateLock.unlock()
+    }
+
+    /// The declared body length: 0 when there is no Content-Length header, nil when it is malformed or negative
+    /// (the request is then rejected instead of being read as an empty body).
+    static func contentLength(inHeaders headerData: Data) -> Int? {
+        guard let text = String(data: headerData, encoding: .utf8) else { return nil }
+        for line in text.components(separatedBy: "\r\n") {
+            let parts = line.split(separator: ":", maxSplits: 1)
+            if parts.count == 2, parts[0].trimmingCharacters(in: .whitespaces).lowercased() == "content-length" {
+                guard let length = Int(parts[1].trimmingCharacters(in: .whitespaces)), length >= 0 else { return nil }
+                return length
+            }
+        }
+        return 0
+    }
+
+    /// True when the peer is on this device. The listener is not bound to loopback only (that predates the AI
+    /// routes and also serves files), so the AI routes — which run the on-device model — check the peer themselves.
+    static func isLoopbackPeer(_ endpoint: NWEndpoint) -> Bool {
+        guard case let .hostPort(host, _) = endpoint else { return false }
+        switch host {
+        case .ipv4(let address):
+            return address.isLoopback
+        case .ipv6(let address):
+            return address.isLoopback || address.asIPv4?.isLoopback == true
+        case .name(let name, _):
+            return name == "localhost"
+        @unknown default:
+            return false
+        }
+    }
+
+    func dispatchRequest(headerData: Data, body: Data, isComplete: Bool, on connection: NWConnection) {
+        guard let requestString = String(data: headerData, encoding: .utf8) else {
+            sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+            return
+        }
+
+        let keepOpen = processHTTPRequest(requestString, body: body, on: connection)
+
+        // A client half-closing after sending its request must not kill an SSE stream we are still writing.
+        if isComplete && !keepOpen {
+            connection.cancel()
+        }
+    }
+
+    /// Returns true when the connection is now owned by a long-lived AI stream and must stay open.
+    @discardableResult
+    func processHTTPRequest(_ requestString: String, body: Data = Data(), on connection: NWConnection) -> Bool {
+        let lines = requestString.components(separatedBy: "\r\n")
+        guard let requestLine = lines.first else {
+            sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
+            return false
+        }
+
+        let components = requestLine.components(separatedBy: " ")
+        guard components.count >= 2 else {
+            sendHTTPResponse(on: connection, statusCode: 405, body: "Method Not Allowed")
+            return false
+        }
+
+        let method = components[0]
+        let aiPrefix = "/framework-\(self.sessionId)/ai/"
+        let isAIRoute = components[1] == aiPrefix + "stream" || components[1] == aiPrefix + "generate"
+
+        if isAIRoute {
+            guard Self.isLoopbackPeer(connection.endpoint) else {
+                logger.warning("Rejected AI request from a non-loopback peer")
+                sendHTTPResponse(on: connection, statusCode: 403, body: "Forbidden")
+                return false
+            }
+            switch method {
+            case "OPTIONS":
+                sendAIPreflight(on: connection)
+                return false
+            case "POST":
+                if components[1] == aiPrefix + "stream" {
+                    startAIStream(NativeAIRequest(body: body), on: connection)
+                    return true
+                }
+                runAIGenerate(NativeAIRequest(body: body), on: connection)
+                return true
+            default:
+                sendHTTPResponse(on: connection, statusCode: 405, body: "Method Not Allowed")
+                return false
+            }
+        }
+
+        guard method == "GET" else {
+            sendHTTPResponse(on: connection, statusCode: 405, body: "Method Not Allowed")
+            return false
+        }
+
+        let path = components[1]
+
+        // Handle status endpoint
+        if path == "/framework-\(self.sessionId)/status" {
+            fileQueue.sync {
+                let statusResponse = """
+                {
+                    "status": "running",
+                    "sessionId": "\(self.sessionId)",
+                    "port": \(self.serverPort),
+                    "servedFiles": \(self.servedFiles.count)
+                }
+                """
+                sendHTTPResponse(on: connection, statusCode: 200, body: statusResponse, contentType: "application/json")
+            }
+            return false
+        }
+
+        // Handle file requests
+        if path.hasPrefix("/framework-\(self.sessionId)/file-") {
+            let fileId = String(path.dropFirst("/framework-\(self.sessionId)/file-".count))
+            serveFile(fileId: fileId, on: connection)
+            return false
+        }
+
+        // Invalid route
+        sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.fileNotFound, body: "Not Found")
+        return false
+    }
+}