Improve Xcode local provider compatibility

Author: Fil Sviatoslav

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on Keep a Changelog, and Esh follows Semantic Versioning.
 
 ## [Unreleased]
 
+## [0.1.31] - 2026-04-25
+
+### Fixed
+- Xcode local model provider compatibility by keeping `/v1/models` text-only and adding local-provider probes.
+
+### Added
+- OpenAI-compatible server now exposes `/v1/tools`, `/api/tags`, root health, query-safe routing, CORS headers, and port `11435` defaults for Xcode.
+
 ## [0.1.30] - 2026-04-25
 
 ### Fixed

README.md

@@ -123,10 +123,10 @@ JSON
 Use `esh serve` to expose a local OpenAI-compatible HTTP surface for editors, scripts, and desktop apps.
 
 ```bash
-./esh serve --host 127.0.0.1 --port 11434
-curl http://127.0.0.1:11434/v1/models
-curl http://127.0.0.1:11434/v1/audio/models
-curl http://127.0.0.1:11434/v1/chat/completions \
+./esh serve --host 127.0.0.1 --port 11435
+curl http://127.0.0.1:11435/v1/models
+curl http://127.0.0.1:11435/v1/audio/models
+curl http://127.0.0.1:11435/v1/chat/completions \
   -H 'Content-Type: application/json' \
   -d '{
     "model": "mlx-community--qwen2.5-0.5b-instruct-4bit",
@@ -139,16 +139,19 @@ curl http://127.0.0.1:11434/v1/chat/completions \
 Supported routes in v1:
 - `GET /health`
 - `GET /v1/models`
+- `GET /v1/tools`
 - `GET /v1/audio/models`
+- `GET /api/tags`
 - `POST /v1/chat/completions`
 - `POST /v1/responses`
 
 Notes:
 - unsupported request fields are ignored when safe
 - `stream` is not supported yet
 - text inputs are supported for chat/responses in v1
-- `/v1/models` includes installed text models and MLX TTS models; audio entries include `modality: "audio"` and `tts` capability metadata
+- `/v1/models` includes installed text models only for strict OpenAI-compatible clients such as Xcode
 - `/v1/audio/models` returns the reusable MLX TTS model catalog with voices, languages, output formats, and capabilities so external agents can present and reuse voice choices
+- `/v1/tools` advertises request-side tool support and `/api/tags` provides an Ollama-compatible model list for local-provider probes
 - set `ESH_API_KEY` or pass `--api-key <token>` to require `Authorization: Bearer <token>`
 
 In the interactive TUI (`./esh`), select **OpenAI server** to toggle the same local API while the TUI process stays open. In chat, use `/serve toggle`, `/serve start`, `/serve stop`, or `/serve status`; the header shows whether the local API is on.

Sources/EshCore/Services/OpenAICompatibleHTTPHandler.swift

@@ -39,13 +39,26 @@ public struct OpenAICompatibleHTTPHandler: Sendable {
         do {
             try validateAuthorization(headers: request.headers)
 
-            switch (request.method.uppercased(), request.path) {
-            case ("GET", "/health"):
-                return try jsonResponse(statusCode: 200, payload: ["status": "ok"])
+            let path = normalizedPath(request.path)
+            switch (request.method.uppercased(), path) {
+            case ("OPTIONS", _):
+                return emptyResponse(statusCode: 204)
+            case ("GET", "/"), ("GET", "/health"), ("GET", "/v1"):
+                return try jsonResponse(
+                    statusCode: 200,
+                    payload: [
+                        "status": "ok",
+                        "routes": "/v1/models,/v1/chat/completions,/v1/responses,/v1/tools,/v1/audio/models,/api/tags"
+                    ]
+                )
             case ("GET", "/v1/models"):
                 return try jsonResponse(statusCode: 200, payload: service.models())
             case ("GET", "/v1/audio/models"):
                 return try jsonResponse(statusCode: 200, payload: service.audioModels())
+            case ("GET", "/v1/tools"):
+                return try jsonResponse(statusCode: 200, payload: service.tools())
+            case ("GET", "/api/tags"):
+                return try jsonResponse(statusCode: 200, payload: service.ollamaTags())
             case ("POST", "/v1/chat/completions"):
                 let decoded = try JSONCoding.decoder.decode(OpenAIChatCompletionsRequest.self, from: request.body)
                 let response = try await service.chatCompletions(decoded)
@@ -68,6 +81,13 @@ public struct OpenAICompatibleHTTPHandler: Sendable {
         }
     }
 
+    private func normalizedPath(_ path: String) -> String {
+        guard let queryStart = path.firstIndex(of: "?") else {
+            return path
+        }
+        return String(path[..<queryStart])
+    }
+
     private func validateAuthorization(headers: [String: String]) throws {
         guard let bearerToken, bearerToken.isEmpty == false else { return }
         let authorization = headers.first { $0.key.lowercased() == "authorization" }?.value
@@ -79,15 +99,35 @@ public struct OpenAICompatibleHTTPHandler: Sendable {
     private func jsonResponse<T: Encodable>(statusCode: Int, payload: T) throws -> OpenAICompatibleHTTPResponse {
         let body = try JSONCoding.encoder.encode(payload)
         return OpenAICompatibleHTTPResponse(
+            statusCode: statusCode,
+            headers: jsonHeaders(contentLength: body.count),
+            body: body
+        )
+    }
+
+    private func emptyResponse(statusCode: Int) -> OpenAICompatibleHTTPResponse {
+        OpenAICompatibleHTTPResponse(
             statusCode: statusCode,
             headers: [
-                "content-type": "application/json; charset=utf-8",
-                "content-length": String(body.count)
+                "access-control-allow-origin": "*",
+                "access-control-allow-methods": "GET,POST,OPTIONS",
+                "access-control-allow-headers": "authorization,content-type",
+                "content-length": "0"
             ],
-            body: body
+            body: Data()
         )
     }
 
+    private func jsonHeaders(contentLength: Int) -> [String: String] {
+        [
+            "access-control-allow-origin": "*",
+            "access-control-allow-methods": "GET,POST,OPTIONS",
+            "access-control-allow-headers": "authorization,content-type",
+            "content-type": "application/json; charset=utf-8",
+            "content-length": String(contentLength)
+        ]
+    }
+
     private func errorResponse(for error: OpenAICompatibleError) -> OpenAICompatibleHTTPResponse {
         let statusCode: Int
         let type: String
@@ -112,10 +152,7 @@ public struct OpenAICompatibleHTTPHandler: Sendable {
         let body = (try? JSONCoding.encoder.encode(payload)) ?? Data(#"{"error":{"message":"Unknown error","type":"server_error"}}"#.utf8)
         return OpenAICompatibleHTTPResponse(
             statusCode: statusCode,
-            headers: [
-                "content-type": "application/json; charset=utf-8",
-                "content-length": String(body.count)
-            ],
+            headers: jsonHeaders(contentLength: body.count),
             body: body
         )
     }

Sources/EshCore/Services/OpenAICompatibleLocalServer.swift

@@ -142,12 +142,22 @@ public final class OpenAICompatibleLocalServer: @unchecked Sendable {
         let body = Data(data[bodyStart..<(bodyStart + contentLength)])
         return OpenAICompatibleHTTPRequest(
             method: String(requestLineParts[0]),
-            path: String(requestLineParts[1]),
+            path: normalizedRequestPath(String(requestLineParts[1])),
             headers: headers,
             body: body
         )
     }
 
+    private func normalizedRequestPath(_ path: String) -> String {
+        guard let url = URL(string: path), url.path.isEmpty == false else {
+            return path
+        }
+        if let query = url.query, query.isEmpty == false {
+            return "\(url.path)?\(query)"
+        }
+        return url.path
+    }
+
     private func serialize(response: OpenAICompatibleHTTPResponse) -> Data {
         let reasonPhrase = switch response.statusCode {
         case 200: "OK"

Sources/EshCore/Services/OpenAICompatibleService.swift

@@ -227,20 +227,75 @@ public struct OpenAIModelsResponse: Codable, Hashable, Sendable {
         public var object: String
         public var created: Int
         public var ownedBy: String
-        public var modality: String?
-        public var capabilities: [String]?
 
         enum CodingKeys: String, CodingKey {
             case id
             case object
             case created
             case ownedBy = "owned_by"
-            case modality
-            case capabilities
         }
     }
 }
 
+public struct OllamaTagsResponse: Codable, Hashable, Sendable {
+    public var models: [Model]
+
+    public struct Model: Codable, Hashable, Sendable {
+        public var name: String
+        public var model: String
+        public var modifiedAt: String
+        public var size: Int
+        public var digest: String
+        public var details: Details
+
+        enum CodingKeys: String, CodingKey {
+            case name
+            case model
+            case modifiedAt = "modified_at"
+            case size
+            case digest
+            case details
+        }
+    }
+
+    public struct Details: Codable, Hashable, Sendable {
+        public var format: String
+        public var family: String
+        public var parameterSize: String
+        public var quantizationLevel: String
+
+        enum CodingKeys: String, CodingKey {
+            case format
+            case family
+            case parameterSize = "parameter_size"
+            case quantizationLevel = "quantization_level"
+        }
+    }
+}
+
+public struct OpenAIToolsResponse: Codable, Hashable, Sendable {
+    public var object: String
+    public var data: [Tool]
+    public var supportsRequestTools: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case object
+        case data
+        case supportsRequestTools = "supports_request_tools"
+    }
+
+    public struct Tool: Codable, Hashable, Sendable {
+        public var type: String
+        public var function: Function
+    }
+
+    public struct Function: Codable, Hashable, Sendable {
+        public var name: String
+        public var description: String
+        public var parameters: [String: String]
+    }
+}
+
 public struct OpenAIAudioModelsResponse: Codable, Hashable, Sendable {
     public var object: String
     public var data: [OpenAIAudioModel]
@@ -456,24 +511,10 @@ public struct OpenAICompatibleService: Sendable {
                     id: $0.id,
                     object: "model",
                     created: 0,
-                    ownedBy: "esh",
-                    modality: "text",
-                    capabilities: ["chat", "responses"]
+                    ownedBy: "esh"
                 )
             }
-        let audioModels = try audioModelsClosure()
-            .sorted { $0.id.localizedCaseInsensitiveCompare($1.id) == .orderedAscending }
-            .map {
-                OpenAIModelsResponse.Model(
-                    id: $0.id,
-                    object: $0.object,
-                    created: $0.created,
-                    ownedBy: $0.ownedBy,
-                    modality: "audio",
-                    capabilities: $0.capabilities
-                )
-            }
-        return OpenAIModelsResponse(object: "list", data: textModels + audioModels)
+        return OpenAIModelsResponse(object: "list", data: textModels)
     }
 
     public func audioModels() throws -> OpenAIAudioModelsResponse {
@@ -482,6 +523,31 @@ public struct OpenAICompatibleService: Sendable {
         return OpenAIAudioModelsResponse(object: "list", data: models)
     }
 
+    public func ollamaTags() throws -> OllamaTagsResponse {
+        let models = try installedModelsClosure()
+            .sorted { $0.id.localizedCaseInsensitiveCompare($1.id) == .orderedAscending }
+            .map { model in
+                OllamaTagsResponse.Model(
+                    name: model.id,
+                    model: model.id,
+                    modifiedAt: "1970-01-01T00:00:00Z",
+                    size: 0,
+                    digest: model.id,
+                    details: .init(
+                        format: model.backend.rawValue,
+                        family: "esh",
+                        parameterSize: "unknown",
+                        quantizationLevel: model.variant ?? "unknown"
+                    )
+                )
+            }
+        return OllamaTagsResponse(models: models)
+    }
+
+    public func tools() -> OpenAIToolsResponse {
+        OpenAIToolsResponse(object: "list", data: [], supportsRequestTools: true)
+    }
+
     private func externalMessage(from message: OpenAIInputMessage) throws -> ExternalInferenceMessage {
         guard let role = Message.Role(rawValue: message.role) else {
             throw OpenAICompatibleError.invalidRequest("Unsupported message role: \(message.role)")

Sources/esh/App/OpenAICompatibleServerController.swift

@@ -7,7 +7,7 @@ final class OpenAICompatibleServerController: @unchecked Sendable {
     private let lock = NSLock()
     private var server: OpenAICompatibleLocalServer?
     private var activeHost = "127.0.0.1"
-    private var activePort: UInt16 = 11434
+    private var activePort: UInt16 = ServeCommand.defaultPort
 
     var isRunning: Bool {
         lock.lock()
@@ -26,7 +26,7 @@ final class OpenAICompatibleServerController: @unchecked Sendable {
         root: PersistenceRoot,
         toolVersion: String?,
         host: String = "127.0.0.1",
-        port: UInt16 = 11434,
+        port: UInt16 = ServeCommand.defaultPort,
         apiKey: String? = nil
     ) throws {
         lock.lock()

Sources/esh/App/TUIApplication.swift

@@ -963,7 +963,7 @@ struct TUIApplication {
                 lines: [
                     "status: off",
                     "toggle: /serve toggle",
-                    "cli: esh serve --host 127.0.0.1 --port 11434"
+                    "cli: esh serve --host 127.0.0.1 --port \(ServeCommand.defaultPort)"
                 ]
             )
         }

Sources/esh/Commands/ServeCommand.swift

@@ -3,6 +3,7 @@ import Darwin
 import EshCore
 
 enum ServeCommand {
+    static let defaultPort: UInt16 = 11435
     private static let usage = "Usage: esh serve [--host 127.0.0.1|localhost|::1|0.0.0.0|::] [--port <1-65535>] [--api-key <token>]"
 
     static func run(arguments: [String], root: PersistenceRoot, toolVersion: String?) async throws {
@@ -30,7 +31,7 @@ enum ServeCommand {
         let redactedAuth = apiKey == nil ? "disabled" : "enabled"
         print("esh OpenAI-compatible server listening on http://\(host):\(port)")
         print("auth: \(redactedAuth)")
-        print("routes: GET /health, GET /v1/models, GET /v1/audio/models, POST /v1/chat/completions, POST /v1/responses")
+        print("routes: GET /health, GET /v1/models, GET /v1/tools, GET /v1/audio/models, GET /api/tags, POST /v1/chat/completions, POST /v1/responses")
         print("press Ctrl+C to stop")
 
         let signalHandler = SignalHandler()
@@ -40,7 +41,7 @@ enum ServeCommand {
 
     private static func resolvePort(arguments: [String]) throws -> UInt16 {
         guard let rawPort = CommandSupport.optionalValue(flag: "--port", in: arguments) else {
-            return 11434
+            return defaultPort
         }
         guard let parsed = UInt16(rawPort), parsed > 0 else {
             throw StoreError.invalidManifest("Invalid port `\(rawPort)`. " + usage)

Tests/EshCoreTests/OpenAICompatibleServiceTests.swift

@@ -187,15 +187,27 @@ struct OpenAICompatibleServiceTests {
         let models = try await handler.handle(.init(method: "GET", path: "/v1/models", headers: [:], body: Data()))
         let modelsPayload = try JSONCoding.decoder.decode(OpenAIModelsResponse.self, from: models.body)
         #expect(models.statusCode == 200)
-        #expect(modelsPayload.data.map(\.id) == ["a-model", "b-model", "voice-model"])
-        #expect(modelsPayload.data.last?.modality == "audio")
+        #expect(modelsPayload.data.map(\.id) == ["a-model", "b-model"])
+
+        let queryModels = try await handler.handle(.init(method: "GET", path: "/v1/models?source=xcode", headers: [:], body: Data()))
+        #expect(queryModels.statusCode == 200)
 
         let audioModels = try await handler.handle(.init(method: "GET", path: "/v1/audio/models", headers: [:], body: Data()))
         let audioPayload = try JSONCoding.decoder.decode(OpenAIAudioModelsResponse.self, from: audioModels.body)
         #expect(audioModels.statusCode == 200)
         #expect(audioPayload.data.first?.voices.first?.id == "alba")
         #expect(audioPayload.data.first?.languages.first?.id == "en")
 
+        let tools = try await handler.handle(.init(method: "GET", path: "/v1/tools", headers: [:], body: Data()))
+        let toolsPayload = try JSONCoding.decoder.decode(OpenAIToolsResponse.self, from: tools.body)
+        #expect(tools.statusCode == 200)
+        #expect(toolsPayload.supportsRequestTools)
+
+        let tags = try await handler.handle(.init(method: "GET", path: "/api/tags", headers: [:], body: Data()))
+        let tagsPayload = try JSONCoding.decoder.decode(OllamaTagsResponse.self, from: tags.body)
+        #expect(tags.statusCode == 200)
+        #expect(tagsPayload.models.map(\.name) == ["a-model", "b-model"])
+
         let chatRequestBody = Data(
             """
             {

VERSION

@@ -1 +1 @@
-0.1.30
+0.1.31