apple-local-llm 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parkerduff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,341 @@
 # apple-local-llm
 
-Call Apple's on-device Foundation Models using the OpenAI Responses API format — no servers, no setup.
+Call Apple's on-device Foundation Models from JavaScript — no servers, no setup.
 
-## Status
+Works with Node.js, Electron, and VS Code extensions.
 
-🚧 **Under development** — this package is reserved and not yet functional.
+## Requirements
 
-## Coming Soon
+- **macOS 26+** (Tahoe)
+- **Apple Silicon** (M Series)
+- **Apple Intelligence enabled** in System Settings
 
-- Drop-in OpenAI Responses API compatibility
-- Works with Node.js, Electron, and VS Code extensions
-- No localhost server required
-- Automatic fallback when unavailable
+## Installation
+
+```bash
+npm install apple-local-llm
+```
+
+## Quick Start
+
+### Simple API
+
+```typescript
+import { createClient } from "apple-local-llm";
+
+const client = createClient();
+
+// Check compatibility first
+const compat = await client.compatibility.check();
+if (!compat.compatible) {
+  console.log("Not available:", compat.reasonCode);
+  // Handle fallback to cloud API
+}
+
+// Generate a response
+const result = await client.responses.create({
+  input: "What is the capital of France?",
+});
+
+if (result.ok) {
+  console.log(result.text); // "The capital of France is Paris."
+}
+```
+
+### Streaming
+
+```typescript
+for await (const chunk of client.stream({ input: "Count from 1 to 5." })) {
+  if ("delta" in chunk) {
+    process.stdout.write(chunk.delta);
+  }
+}
+```
+
+## API Reference
+
+### `createClient(options?)`
+
+Creates a new client instance.
+
+```typescript
+const client = createClient({
+  model: "default",               // Optional: model identifier (currently only "default")
+  onLog: (msg) => console.log(msg), // Optional: debug logging
+  idleTimeoutMs: 5 * 60 * 1000,     // Optional: helper idle timeout (default: 5 min)
+});
+```
+
+**Defaults:**
+- Helper auto-shuts down after 5 minutes of inactivity
+- Helper auto-restarts up to 3 times on crash (with exponential backoff)
+- Request timeout: 60 seconds (configurable via `timeoutMs`)
+
+You can also import and instantiate the class directly:
+```typescript
+import { AppleLocalLLMClient } from "apple-local-llm";
+const client = new AppleLocalLLMClient(options);
+```
+
+### `client.compatibility.check()`
+
+Check if the local model is available. Always call this before making requests.
+
+```typescript
+const result = await client.compatibility.check();
+// { compatible: true }
+// or { compatible: false, reasonCode: "AI_DISABLED" }
+```
+
+**Reason codes:**
+| Code | Description |
+|------|-------------|
+| `NOT_DARWIN` | Not running on macOS |
+| `UNSUPPORTED_HARDWARE` | Not Apple Silicon |
+| `AI_DISABLED` | Apple Intelligence not enabled |
+| `MODEL_NOT_READY` | Model still downloading |
+| `SPAWN_FAILED` | Helper binary failed to start |
+| `HELPER_NOT_FOUND` | Helper binary not found |
+| `HELPER_UNHEALTHY` | Helper process not responding correctly |
+| `PROTOCOL_MISMATCH` | Helper version incompatible with client |
+
+### `client.capabilities.get()`
+
+Get detailed model capabilities (calls the helper).
+
+```typescript
+const caps = await client.capabilities.get();
+// { available: true, model: "apple-on-device" }
+// or { available: false, reasonCode: "AI_DISABLED" }
+```
+
+### `client.responses.create(params)`
+
+Generate a response.
+
+```typescript
+const result = await client.responses.create({
+  input: "Your prompt here",
+  model: "default",         // Optional: model identifier
+  max_output_tokens: 1000,  // Optional
+  stream: false,            // Optional
+  signal: abortController.signal, // Optional: AbortSignal
+  timeoutMs: 60000,         // Optional: request timeout (ms)
+  response_format: {        // Optional: structured JSON output
+    type: "json_schema",
+    json_schema: {
+      name: "Result",
+      schema: { type: "object", properties: { ... } }
+    }
+  }
+});
+```
+
+**Structured Output Example:**
+
+```typescript
+const result = await client.responses.create({
+  input: "List 3 colors",
+  response_format: {
+    type: "json_schema",
+    json_schema: {
+      name: "Colors",
+      schema: {
+        type: "object",
+        properties: {
+          colors: { type: "array", items: { type: "string" } }
+        }
+      }
+    }
+  }
+});
+const data = JSON.parse(result.text); // { colors: ["red", "blue", "green"] }
+```
+
+> `response_format` is not supported with streaming.
+
+Returns `ResponseResult` on success, or an error object:
+```typescript
+// Success:
+{ ok: true, text: "...", request_id: "..." }
+// Error:
+{ ok: false, error: { code: "...", detail: "..." } }
+```
+
+Note: The return type is a discriminated union, not the exported `ResponseResult` interface.
+
+**Error codes:**
+| Code | Description |
+|------|-------------|
+| `UNAVAILABLE` | Model not available (see reason codes above) |
+| `TIMEOUT` | Request timed out (default: 60s) |
+| `CANCELLED` | Request was cancelled via AbortSignal |
+| `RATE_LIMITED` | System rate limit exceeded |
+| `GUARDRAIL` | Content violated Apple's safety guidelines |
+| `INTERNAL` | Unexpected error |
+
+### `client.stream(params)`
+
+Async generator for streaming responses.
+
+```typescript
+for await (const chunk of client.stream({ input: "..." })) {
+  if ("delta" in chunk) {
+    // Partial content
+    console.log(chunk.delta);
+  } else if ("done" in chunk) {
+    // Final complete text
+    console.log(chunk.text);
+  }
+}
+```
+
+### `client.responses.cancel(requestId)`
+
+Cancel an in-progress request.
+
+```typescript
+const result = await client.responses.cancel("req_123");
+// { ok: true } or { ok: false, error: { code: "NOT_RUNNING", detail: "..." } }
+```
+
+### `client.shutdown()`
+
+Gracefully shut down the helper process.
+
+```typescript
+await client.shutdown();
+```
+
+## TypeScript Types
+
+All types are exported:
+
+```typescript
+import type {
+  ClientOptions,
+  ReasonCode,
+  CompatibilityResult,
+  CapabilitiesResult,
+  ResponsesCreateParams,
+  ResponseResult,
+  JSONSchema,
+  ResponseFormat,
+} from "apple-local-llm";
+```
+
+## CLI Usage
+
+The `fm-proxy` binary can also be used directly from the command line:
+
+```bash
+# Simple prompt
+fm-proxy "What is the capital of France?"
+
+# Streaming output
+fm-proxy --stream "Tell me a story"
+fm-proxy -s "Tell me a story"
+
+# Start HTTP server
+fm-proxy --serve
+fm-proxy --serve --port=3000
+
+# Other options
+fm-proxy --help      # Show usage (or -h)
+fm-proxy --version   # Show version (or -v)
+fm-proxy --stdio     # stdio mode (used internally by npm package)
+```
+
+### HTTP Server Mode
+
+Run `fm-proxy --serve` to start a local HTTP server:
+
+```bash
+fm-proxy --serve --port=8080
+```
+
+**Endpoints:**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check and availability status |
+| `/generate` | POST | Text generation (supports streaming) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--port=<PORT>` | Set server port (default: 8080) |
+| `--auth-token=<TOKEN>` | Require Bearer token for `/generate` |
+
+You can also set `AUTH_TOKEN` environment variable instead of `--auth-token`.
+
+**CORS:** All endpoints support CORS with `Access-Control-Allow-Origin: *`.
+
+**Examples:**
+
+```bash
+# Health check
+curl http://127.0.0.1:8080/health
+# Response: {"status":"ok","model":"apple-on-device","available":true}
+
+# Simple generation
+curl -X POST http://127.0.0.1:8080/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "What is 2+2?"}'
+# Response: {"text":"2+2 equals 4."}
+
+# With authentication
+curl -X POST http://127.0.0.1:8080/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"prompt": "Hello"}'
+```
+
+#### Streaming (SSE)
+
+Add `"stream": true` to get Server-Sent Events with OpenAI-compatible chunks:
+
+```bash
+curl -N -X POST http://127.0.0.1:8080/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Write a haiku", "stream": true}'
+```
+
+Response:
+```
+data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}
+data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}
+data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}
+data: [DONE]
+```
+
+## How It Works
+
+This package bundles a small native helper (`fm-proxy`) that communicates with Apple's Foundation Models framework over stdio. The helper is spawned on first request and stays alive to keep the model warm.
+
+- **No localhost server** — npm package uses stdio, not HTTP
+- **No user setup** — just `npm install`
+- **Fails gracefully** — check `compatibility.check()` and fall back to cloud
+
+## Runtime Support
+
+**JS API (`createClient()`):**
+| Environment | Supported |
+|-------------|-----------|
+| Node.js | ✅ |
+| Electron (main process) | ✅ |
+| VS Code extensions | ✅ |
+| Electron (renderer) | ❌ No `child_process` |
+| Browser | ❌ |
+
+**HTTP Server (`fm-proxy --serve`):**
+| Environment | Supported |
+|-------------|-----------|
+| Any HTTP client | ✅ |
+| Browser (fetch) | ✅ |
+| Electron (renderer) | ✅ |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,105 @@
+export type ReasonCode = "NOT_DARWIN" | "UNSUPPORTED_HARDWARE" | "AI_DISABLED" | "MODEL_NOT_READY" | "SPAWN_FAILED" | "HELPER_UNHEALTHY" | "HELPER_NOT_FOUND" | "PROTOCOL_MISMATCH";
+export interface CompatibilityResult {
+    compatible: boolean;
+    reasonCode?: ReasonCode;
+}
+export interface CapabilitiesResult {
+    available: boolean;
+    reasonCode?: string;
+    model?: string;
+}
+export interface JSONSchema {
+    type: "object" | "array" | "string" | "number" | "integer" | "boolean";
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    required?: string[];
+    description?: string;
+    enum?: string[];
+}
+export interface ResponseFormat {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        description?: string;
+        schema: JSONSchema;
+    };
+}
+export interface ResponsesCreateParams {
+    model?: string;
+    input: string;
+    max_output_tokens?: number;
+    stream?: boolean;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    response_format?: ResponseFormat;
+}
+export interface ResponseResult {
+    request_id: string;
+    text: string;
+    model?: string;
+}
+export interface StreamEvent {
+    request_id: string;
+    event: "delta" | "done" | "error";
+    delta?: string;
+    text?: string;
+    model?: string;
+    error?: {
+        code: string;
+        detail: string;
+    };
+}
+export declare const DEFAULT_MODEL = "default";
+export interface ClientOptions {
+    model?: string;
+    onLog?: (message: string) => void;
+    idleTimeoutMs?: number;
+}
+export declare class AppleLocalLLMClient {
+    private options;
+    private resolverResult;
+    private processManager;
+    private compatibilityCache;
+    constructor(options?: ClientOptions);
+    private getModel;
+    get compatibility(): {
+        check: () => Promise<CompatibilityResult>;
+    };
+    get capabilities(): {
+        get: () => Promise<CapabilitiesResult>;
+    };
+    get responses(): {
+        create: (params: ResponsesCreateParams) => Promise<{
+            ok: true;
+            text: string;
+            request_id: string;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                detail: string;
+            };
+        }>;
+        cancel: (requestId: string) => Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                detail: string;
+            };
+        }>;
+    };
+    private checkCompatibility;
+    private getCapabilities;
+    private createResponse;
+    stream(params: Omit<ResponsesCreateParams, "stream">): AsyncGenerator<{
+        delta: string;
+    } | {
+        done: true;
+        text: string;
+    }, void, unknown>;
+    private cancelResponse;
+    shutdown(): Promise<void>;
+}
+export declare function createClient(options?: ClientOptions): AppleLocalLLMClient;

package/dist/client.js

@@ -0,0 +1,249 @@
+import { resolveHelper } from "./resolver.js";
+import { ProcessManager } from "./process-manager.js";
+export const DEFAULT_MODEL = "default";
+export class AppleLocalLLMClient {
+    options;
+    resolverResult = null;
+    processManager = null;
+    compatibilityCache = null;
+    constructor(options = {}) {
+        this.options = { model: DEFAULT_MODEL, ...options };
+    }
+    getModel(override) {
+        return override ?? this.options.model ?? DEFAULT_MODEL;
+    }
+    get compatibility() {
+        return {
+            check: () => this.checkCompatibility(),
+        };
+    }
+    get capabilities() {
+        return {
+            get: () => this.getCapabilities(),
+        };
+    }
+    get responses() {
+        return {
+            create: (params) => this.createResponse(params),
+            cancel: (requestId) => this.cancelResponse(requestId),
+        };
+    }
+    async checkCompatibility() {
+        if (this.compatibilityCache) {
+            return this.compatibilityCache;
+        }
+        // Fast JS-side checks
+        this.resolverResult = resolveHelper();
+        if (!this.resolverResult.ok) {
+            const result = {
+                compatible: false,
+                reasonCode: this.resolverResult.reasonCode,
+            };
+            this.compatibilityCache = result;
+            return result;
+        }
+        // Spawn helper and check capabilities
+        try {
+            this.processManager = new ProcessManager(this.resolverResult.location, {
+                onLog: this.options.onLog,
+                idleTimeoutMs: this.options.idleTimeoutMs,
+            });
+            const transport = await this.processManager.getTransport();
+            const response = await transport.send("capabilities.get");
+            if (!response.ok) {
+                const result = {
+                    compatible: false,
+                    reasonCode: "HELPER_UNHEALTHY",
+                };
+                this.compatibilityCache = result;
+                return result;
+            }
+            const caps = response.result;
+            if (caps.available) {
+                const result = { compatible: true };
+                this.compatibilityCache = result;
+                return result;
+            }
+            else {
+                const result = {
+                    compatible: false,
+                    reasonCode: caps.reason_code,
+                };
+                this.compatibilityCache = result;
+                return result;
+            }
+        }
+        catch (err) {
+            const result = {
+                compatible: false,
+                reasonCode: "SPAWN_FAILED",
+            };
+            this.compatibilityCache = result;
+            return result;
+        }
+    }
+    async getCapabilities() {
+        const compat = await this.checkCompatibility();
+        if (!compat.compatible) {
+            return {
+                available: false,
+                reasonCode: compat.reasonCode,
+            };
+        }
+        const transport = await this.processManager.getTransport();
+        const response = await transport.send("capabilities.get");
+        if (!response.ok) {
+            return {
+                available: false,
+                reasonCode: response.error?.code,
+            };
+        }
+        const raw = response.result;
+        return {
+            available: raw.available,
+            reasonCode: raw.reason_code,
+            model: raw.model,
+        };
+    }
+    async createResponse(params) {
+        const compat = await this.checkCompatibility();
+        if (!compat.compatible) {
+            return {
+                ok: false,
+                error: {
+                    code: "UNAVAILABLE",
+                    detail: `Not compatible: ${compat.reasonCode}`,
+                },
+            };
+        }
+        const transport = await this.processManager.getTransport();
+        if (params.stream) {
+            // For streaming, collect all deltas
+            let fullText = "";
+            const response = await transport.sendStreaming("responses.create", {
+                model: this.getModel(params.model),
+                input: params.input,
+                max_output_tokens: params.max_output_tokens,
+                stream: true,
+                response_format: params.response_format,
+            }, (event) => {
+                const result = event.result;
+                if (result?.delta) {
+                    fullText += result.delta;
+                }
+            }, { signal: params.signal, timeoutMs: params.timeoutMs });
+            const result = response.result;
+            if (result.event === "error" || !response.ok) {
+                return {
+                    ok: false,
+                    error: result.error ?? response.error ?? { code: "INTERNAL", detail: "Unknown error" },
+                };
+            }
+            return {
+                ok: true,
+                text: result.text ?? fullText,
+                request_id: result.request_id,
+            };
+        }
+        else {
+            const response = await transport.send("responses.create", {
+                model: this.getModel(params.model),
+                input: params.input,
+                max_output_tokens: params.max_output_tokens,
+                response_format: params.response_format,
+            }, { signal: params.signal, timeoutMs: params.timeoutMs });
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    error: response.error ?? { code: "INTERNAL", detail: "Unknown error" },
+                };
+            }
+            const result = response.result;
+            return {
+                ok: true,
+                text: result.text,
+                request_id: result.request_id,
+            };
+        }
+    }
+    async *stream(params) {
+        const compat = await this.checkCompatibility();
+        if (!compat.compatible) {
+            throw new Error(`Not compatible: ${compat.reasonCode}`);
+        }
+        const transport = await this.processManager.getTransport();
+        // Create a queue for streaming events
+        const queue = [];
+        let resolveNext = null;
+        let finished = false;
+        transport.sendStreaming("responses.create", {
+            model: this.getModel(params.model),
+            input: params.input,
+            max_output_tokens: params.max_output_tokens,
+            stream: true,
+        }, (event) => {
+            queue.push(event);
+            resolveNext?.();
+        }, { signal: params.signal, timeoutMs: params.timeoutMs }).then(() => {
+            finished = true;
+            queue.push({ done: true });
+            resolveNext?.();
+        }).catch((err) => {
+            finished = true;
+            queue.push({ ok: false, error: { code: "INTERNAL", detail: err instanceof Error ? err.message : "Stream failed" } });
+            resolveNext?.();
+        });
+        while (!finished || queue.length > 0) {
+            if (queue.length === 0) {
+                await new Promise((r) => { resolveNext = r; });
+                continue;
+            }
+            const event = queue.shift();
+            if ("done" in event && event.done === true)
+                break;
+            // Handle error from .catch()
+            if ("ok" in event && event.ok === false) {
+                throw new Error(event.error?.detail ?? "Stream failed");
+            }
+            const result = event.result;
+            if (result.event === "delta" && result.delta) {
+                yield { delta: result.delta };
+            }
+            else if (result.event === "done") {
+                yield { done: true, text: result.text ?? "" };
+                break;
+            }
+            else if (result.event === "error") {
+                throw new Error(result.error?.detail ?? "Stream error");
+            }
+        }
+    }
+    async cancelResponse(requestId) {
+        if (!this.processManager) {
+            return { ok: false, error: { code: "NOT_RUNNING", detail: "No active session" } };
+        }
+        try {
+            const transport = await this.processManager.getTransport();
+            const response = await transport.send("responses.cancel", { request_id: requestId });
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    error: response.error ?? { code: "INTERNAL", detail: "Cancel failed" },
+                };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: { code: "INTERNAL", detail: err instanceof Error ? err.message : "Cancel failed" },
+            };
+        }
+    }
+    async shutdown() {
+        await this.processManager?.shutdown();
+    }
+}
+export function createClient(options) {
+    return new AppleLocalLLMClient(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createClient, AppleLocalLLMClient } from "./client.js";
+export type { ClientOptions, CompatibilityResult, CapabilitiesResult, ResponsesCreateParams, ResponseResult, StreamEvent, ReasonCode, JSONSchema, ResponseFormat, } from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createClient, AppleLocalLLMClient } from "./client.js";

package/dist/process-manager.d.ts

@@ -0,0 +1,25 @@
+import { RPCTransport } from "./transport.js";
+import { HelperLocation } from "./resolver.js";
+export interface ProcessManagerOptions {
+    idleTimeoutMs?: number;
+    maxRestarts?: number;
+    onLog?: (message: string) => void;
+}
+export declare class ProcessManager {
+    private location;
+    private options;
+    private process;
+    private transport;
+    private idleTimer;
+    private restartCount;
+    private healthy;
+    private backoffMs;
+    constructor(location: HelperLocation, options?: ProcessManagerOptions);
+    getTransport(): Promise<RPCTransport>;
+    private sleep;
+    private spawn;
+    private resetIdleTimer;
+    shutdown(): Promise<void>;
+    private kill;
+    isHealthy(): boolean;
+}

package/dist/process-manager.js

@@ -0,0 +1,122 @@
+import { spawn } from "child_process";
+import { RPCTransport } from "./transport.js";
+import { ensureExecutable } from "./resolver.js";
+const DEFAULT_IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_MAX_RESTARTS = 3;
+const PROTOCOL_VERSION = 1;
+const INITIAL_BACKOFF_MS = 100;
+const MAX_BACKOFF_MS = 5000;
+export class ProcessManager {
+    location;
+    options;
+    process = null;
+    transport = null;
+    idleTimer = null;
+    restartCount = 0;
+    healthy = false;
+    backoffMs = INITIAL_BACKOFF_MS;
+    constructor(location, options = {}) {
+        this.location = location;
+        this.options = options;
+    }
+    async getTransport() {
+        this.resetIdleTimer();
+        if (this.transport && this.healthy) {
+            return this.transport;
+        }
+        // Check if we need to wait (backoff after crash)
+        const maxRestarts = this.options.maxRestarts ?? DEFAULT_MAX_RESTARTS;
+        if (this.restartCount >= maxRestarts) {
+            throw new Error(`Helper crashed ${this.restartCount} times, giving up`);
+        }
+        if (this.restartCount > 0) {
+            this.options.onLog?.(`Restarting helper (attempt ${this.restartCount + 1}/${maxRestarts}) after ${this.backoffMs}ms`);
+            await this.sleep(this.backoffMs);
+            this.backoffMs = Math.min(this.backoffMs * 2, MAX_BACKOFF_MS);
+        }
+        return this.spawn();
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async spawn() {
+        await ensureExecutable(this.location);
+        this.process = spawn(this.location.executablePath, ["--stdio"], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.transport = new RPCTransport(this.process);
+        this.transport.on("log", (msg) => {
+            this.options.onLog?.(msg);
+        });
+        this.transport.on("exit", (code) => {
+            this.healthy = false;
+            this.transport = null;
+            this.process = null;
+            if (code !== 0) {
+                this.restartCount++;
+                this.options.onLog?.(`Helper exited with code ${code}, crash count: ${this.restartCount}`);
+            }
+        });
+        this.transport.on("error", (err) => {
+            this.options.onLog?.(`Transport error: ${err.message}`);
+            this.healthy = false;
+        });
+        // Handshake
+        let pingResponse;
+        try {
+            pingResponse = await this.transport.send("health.ping");
+        }
+        catch (err) {
+            this.kill();
+            throw err;
+        }
+        if (!pingResponse.ok) {
+            this.kill();
+            throw new Error("Handshake failed: health.ping returned error");
+        }
+        const result = pingResponse.result;
+        if (result.protocol_version !== PROTOCOL_VERSION) {
+            this.kill();
+            throw new Error(`Protocol mismatch: expected ${PROTOCOL_VERSION}, got ${result.protocol_version}`);
+        }
+        this.healthy = true;
+        this.restartCount = 0;
+        this.backoffMs = INITIAL_BACKOFF_MS; // Reset backoff on success
+        return this.transport;
+    }
+    resetIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+        }
+        const timeout = this.options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT;
+        this.idleTimer = setTimeout(() => {
+            this.shutdown();
+        }, timeout);
+    }
+    async shutdown() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (this.transport && this.healthy) {
+            try {
+                await this.transport.send("process.shutdown");
+            }
+            catch {
+                // Ignore errors during shutdown
+            }
+        }
+        this.kill();
+    }
+    kill() {
+        if (this.process) {
+            this.process.kill();
+            this.process = null;
+        }
+        this.transport = null;
+        this.healthy = false;
+    }
+    isHealthy() {
+        return this.healthy;
+    }
+}

package/dist/resolver.d.ts

@@ -0,0 +1,13 @@
+export interface HelperLocation {
+    type: "cli";
+    executablePath: string;
+}
+export type ResolverResult = {
+    ok: true;
+    location: HelperLocation;
+} | {
+    ok: false;
+    reasonCode: "NOT_DARWIN" | "UNSUPPORTED_HARDWARE" | "HELPER_NOT_FOUND";
+};
+export declare function resolveHelper(): ResolverResult;
+export declare function ensureExecutable(location: HelperLocation): Promise<void>;

package/dist/resolver.js

@@ -0,0 +1,49 @@
+import * as path from "path";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function resolveHelper() {
+    if (process.platform !== "darwin") {
+        return { ok: false, reasonCode: "NOT_DARWIN" };
+    }
+    if (process.arch !== "arm64") {
+        return { ok: false, reasonCode: "UNSUPPORTED_HARDWARE" };
+    }
+    const helperPath = findHelperBinary();
+    if (!helperPath) {
+        return { ok: false, reasonCode: "HELPER_NOT_FOUND" };
+    }
+    return {
+        ok: true,
+        location: {
+            type: "cli",
+            executablePath: helperPath,
+        },
+    };
+}
+function findHelperBinary() {
+    // Try bundled binary in main package (npm distribution)
+    const bundledPath = path.join(__dirname, "..", "bin", "fm-proxy");
+    if (fs.existsSync(bundledPath)) {
+        return bundledPath;
+    }
+    // Try development paths (for local testing)
+    const devPaths = [
+        path.join(__dirname, "..", "swift", ".build", "release", "fm-proxy"),
+        path.join(__dirname, "..", "swift", ".build", "debug", "fm-proxy"),
+    ];
+    for (const p of devPaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
+export async function ensureExecutable(location) {
+    try {
+        await fs.promises.access(location.executablePath, fs.constants.X_OK);
+    }
+    catch {
+        await fs.promises.chmod(location.executablePath, 0o755);
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,34 @@
+import { ChildProcess } from "child_process";
+import { EventEmitter } from "events";
+export interface RPCRequest {
+    id?: string;
+    method: string;
+    params?: unknown;
+}
+export interface SendOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface RPCResponse {
+    id?: string | null;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        detail: string;
+    };
+}
+export declare class RPCTransport extends EventEmitter {
+    private process;
+    private buffer;
+    private contentLength;
+    private requestId;
+    private pending;
+    constructor(proc: ChildProcess);
+    private onData;
+    private processBuffer;
+    private handleResponse;
+    send(method: string, params?: unknown, options?: SendOptions): Promise<RPCResponse>;
+    sendStreaming(method: string, params: unknown, onEvent: (event: RPCResponse) => void, options?: SendOptions): Promise<RPCResponse>;
+    close(): void;
+}

package/dist/transport.js

@@ -0,0 +1,204 @@
+import { EventEmitter } from "events";
+const DEFAULT_TIMEOUT_MS = 60_000; // 60 seconds
+export class RPCTransport extends EventEmitter {
+    process;
+    buffer = Buffer.alloc(0);
+    contentLength = null;
+    requestId = 0;
+    pending = new Map();
+    constructor(proc) {
+        super();
+        this.process = proc;
+        proc.stdout?.on("data", (chunk) => {
+            this.onData(chunk);
+        });
+        proc.stderr?.on("data", (chunk) => {
+            this.emit("log", chunk.toString());
+        });
+        proc.on("exit", (code) => {
+            this.emit("exit", code);
+            for (const [, { reject }] of this.pending) {
+                reject(new Error(`Helper process exited with code ${code}`));
+            }
+            this.pending.clear();
+        });
+        proc.on("error", (err) => {
+            this.emit("error", err);
+        });
+    }
+    onData(data) {
+        this.buffer = Buffer.concat([this.buffer, data]);
+        this.processBuffer();
+    }
+    processBuffer() {
+        while (true) {
+            if (this.contentLength === null) {
+                const headerEndMarker = Buffer.from("\r\n\r\n");
+                const headerEnd = this.buffer.indexOf(headerEndMarker);
+                if (headerEnd === -1)
+                    return;
+                const header = this.buffer.subarray(0, headerEnd).toString("utf8");
+                const match = header.match(/Content-Length:\s*(\d+)/i);
+                if (!match) {
+                    this.emit("error", new Error("Invalid LSP header"));
+                    return;
+                }
+                this.contentLength = parseInt(match[1], 10);
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+            }
+            if (this.buffer.length < this.contentLength)
+                return;
+            const body = this.buffer.subarray(0, this.contentLength).toString("utf8");
+            this.buffer = this.buffer.subarray(this.contentLength);
+            this.contentLength = null;
+            try {
+                const response = JSON.parse(body);
+                this.handleResponse(response);
+            }
+            catch (err) {
+                this.emit("error", new Error(`Invalid JSON response: ${body}`));
+            }
+        }
+    }
+    handleResponse(response) {
+        // Always emit as event first (for streaming handlers)
+        this.emit("event", response);
+        // Then resolve pending promise if this is a direct response
+        if (response.id && this.pending.has(response.id)) {
+            const { resolve } = this.pending.get(response.id);
+            this.pending.delete(response.id);
+            resolve(response);
+        }
+    }
+    async send(method, params, options = {}) {
+        const id = `req_${++this.requestId}`;
+        const request = { id, method, params };
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            let aborted = false;
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                this.pending.delete(id);
+            };
+            // Timeout handling
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Request timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            // AbortSignal handling
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    cleanup();
+                    reject(new Error("Request aborted"));
+                    return;
+                }
+                options.signal.addEventListener("abort", () => {
+                    aborted = true;
+                    cleanup();
+                    reject(new Error("Request aborted"));
+                }, { once: true });
+            }
+            this.pending.set(id, {
+                resolve: (response) => {
+                    if (!aborted) {
+                        cleanup();
+                        resolve(response);
+                    }
+                },
+                reject: (err) => {
+                    cleanup();
+                    reject(err);
+                },
+            });
+            const body = JSON.stringify(request);
+            const message = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+            this.process.stdin?.write(message, (err) => {
+                if (err) {
+                    cleanup();
+                    reject(err);
+                }
+            });
+        });
+    }
+    async sendStreaming(method, params, onEvent, options = {}) {
+        const id = `req_${++this.requestId}`;
+        const request = { id, method, params };
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS * 2; // Longer timeout for streaming
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            let aborted = false;
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                this.pending.delete(id);
+                this.off("event", eventHandler);
+            };
+            // Timeout handling
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Streaming request timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            // Reset timeout on each event (progress)
+            const resetTimeout = () => {
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error(`No streaming progress for ${timeoutMs}ms`));
+                }, timeoutMs);
+            };
+            // AbortSignal handling
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    cleanup();
+                    reject(new Error("Request aborted"));
+                    return;
+                }
+                options.signal.addEventListener("abort", () => {
+                    aborted = true;
+                    cleanup();
+                    reject(new Error("Request aborted"));
+                }, { once: true });
+            }
+            const eventHandler = (event) => {
+                const result = event.result;
+                if (result?.request_id === id) {
+                    resetTimeout(); // Got progress, reset timeout
+                    if (!aborted) {
+                        onEvent(event);
+                    }
+                    if (result.event === "done" || result.event === "error") {
+                        cleanup();
+                        resolve(event);
+                    }
+                }
+            };
+            this.on("event", eventHandler);
+            this.pending.set(id, {
+                resolve: (response) => {
+                    if (!aborted) {
+                        cleanup();
+                        resolve(response);
+                    }
+                },
+                reject: (err) => {
+                    cleanup();
+                    reject(err);
+                },
+            });
+            const body = JSON.stringify(request);
+            const message = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+            this.process.stdin?.write(message, (err) => {
+                if (err) {
+                    cleanup();
+                    reject(err);
+                }
+            });
+        });
+    }
+    close() {
+        this.process.stdin?.end();
+    }
+}

package/package.json

@@ -1,21 +1,53 @@
 {
   "name": "apple-local-llm",
-  "version": "0.0.1",
-  "description": "Call Apple's on-device Foundation Models using the OpenAI Responses API format — no servers, no setup.",
-  "main": "index.js",
+  "version": "0.0.2",
+  "description": "Call Apple's on-device Foundation Models — no servers, no setup.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:swift": "cd swift && swift build -c release",
+    "build:all": "npm run build:swift && npm run copy:bin && npm run build",
+    "copy:bin": "mkdir -p bin && cp swift/.build/release/fm-proxy bin/fm-proxy",
+    "test": "npx tsx test-all-interactions.ts",
+    "prepublishOnly": "npm run build:all"
+  },
   "keywords": [
     "apple",
     "llm",
     "foundation-models",
-    "openai",
     "local",
     "on-device",
-    "macos"
+    "macos",
+    "apple-intelligence"
   ],
   "author": "parkerduff",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/parkerduff/apple-local-llm"
+  },
+  "bin": {
+    "fm-proxy": "./bin/fm-proxy"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/index.js

@@ -1,3 +0,0 @@
-// apple-local-llm - placeholder
-// Full implementation coming soon
-throw new Error("apple-local-llm is not yet implemented. Check back soon!");