@octocodeai/freellama-mcp-server 0.5.0 → 0.6.0

package/native/index.d.ts

@@ -1,189 +1,194 @@
-// Hand-written type declarations for the native module (see index.js for why these are
-// hand-written rather than tool-generated). Mirrors packages/rust-core/src/napi.rs's public function signatures
-// exactly — keep the two in sync if you change one. `npm run build` no longer overwrites this
-// file (it previously did, silently emptying it — see package.json's build script comment).
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Cancels one deferred task and waits for its local admission permits to be released.
+ *
+ * # Errors
+ * Returns an error for an invalid ID, an expired job, or an unavailable server.
+ */
+export declare function cancelTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>
+
+/**
+ * Creates opt-in, bounded process-local conversation history.
+ * # Errors
+ * Returns an error if the server is unavailable or rejects the scope limits or messages.
+ */
+export declare function createScope(endpoint: string | undefined | null, request: unknown): Promise<string>
+
+/**
+ * Create a bounded, expiring model-affinity handle. It stores no prompt history or Ollama KV.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable or its session limit is full.
+ */
+export declare function createSession(endpoint?: string | undefined | null): Promise<string>
 
-/** Crate version this native addon was compiled from. */
-export function version(): string;
+/**
+ * Deletes history and invalidates in-flight commits for this scope.
+ * # Errors
+ * Returns an error for an invalid ID or unavailable server.
+ */
+export declare function deleteScope(endpoint: string | undefined | null, scopeId: string): Promise<void>
+
+/**
+ * Release a model-affinity handle when an agent has finished related work.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable or the handle has expired or was deleted.
+ */
+export declare function deleteSession(endpoint: string | undefined | null, sessionId: string): Promise<void>
 
 /**
  * Runs `freellama doctor` against Ollama directly — no running `freellama serve` required.
  * Cross-checks the Ollama CLI and server versions and confirms the endpoint is reachable.
- * @param endpoint Ollama endpoint, defaults to http://127.0.0.1:11434
- * @returns Pretty-printed JSON string
+ *
+ * # Errors
+ *
+ * Returns an error if Ollama is unreachable at `endpoint`.
+ */
+export declare function doctor(endpoint?: string | undefined | null): Promise<string>
+
+/**
+ * Copies a specified revision into an independent scope.
+ * # Errors
+ * Returns an error for an invalid ID, stale revision, or rejected limits.
+ */
+export declare function forkScope(endpoint: string | undefined | null, scopeId: string, request: unknown): Promise<string>
+
+/**
+ * Reads scope metadata; history is returned only when explicitly requested.
+ * # Errors
+ * Returns an error for an invalid ID or missing/expired scope.
+ */
+export declare function getScope(endpoint: string | undefined | null, scopeId: string, includeMessages?: boolean | undefined | null): Promise<string>
+
+/**
+ * Reads a deferred task receipt and its retained result, if completed.
+ *
+ * # Errors
+ * Returns an error for an invalid ID, an expired job, or an unavailable server.
+ */
+export declare function getTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>
+
+/**
+ * Current managed-platform health, including admission and session bounds.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable or returns a non-2xx response.
+ */
+export declare function health(endpoint?: string | undefined | null): Promise<string>
+
+/**
+ * Cancel managed requests for one session and invalidate its affinity handle.
+ *
+ * # Errors
+ * Returns an error if the server is unreachable or the session does not exist.
+ */
+export declare function killSession(endpoint: string | undefined | null, sessionId: string): Promise<string>
+
+/**
+ * Installed-model inventory with capabilities, residency, and advertised context, as discovered
+ * by a running `freellama serve`.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` isn't reachable at `endpoint`, or returns a non-2xx
+ * response.
+ */
+export declare function listModels(endpoint?: string | undefined | null): Promise<string>
+
+/**
+ * Lists bounded process-local deferred task receipts, without prompts or retained results.
+ *
+ * # Errors
+ * Returns an error if the managed server is unreachable or refuses the request.
  */
-export function doctor(endpoint?: string | undefined | null): Promise<string>;
+export declare function listTaskJobs(endpoint?: string | undefined | null): Promise<string>
 
 /**
  * Machine profile (chip, host memory, memory kind, CPU count, and disk) from `freellama serve`.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` isn't reachable at `endpoint`, or returns a non-2xx
+ * response.
  */
-export function machine(endpoint?: string | undefined | null): Promise<string>;
+export declare function machine(endpoint?: string | undefined | null): Promise<string>
 
-/** Current managed-platform health, including admission and session bounds. */
-export function health(endpoint?: string | undefined | null): Promise<string>;
+/**
+ * Stops one deferred task, waits for local permits, and removes its retained record.
+ *
+ * # Errors
+ * Returns an error for an invalid ID, a missing job, or an unavailable server.
+ */
+export declare function removeTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>
 
 /**
- * Live platform view: admission, queues, adaptive limits and circuit breakers per backend,
+ * Deterministic model selection for a task, via `POST /_freellama/v1/routes` on a running
+ * `freellama serve`. `task` and `objective` are passed through as strings and validated
+ * server-side (e.g. task: `completion` | `code_repair` | `vision` | `embedding` | ...;
+ * objective: `fastest` | `balanced` | `quality`).
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` isn't reachable at `endpoint`, or rejects the request
+ * (e.g. an unknown task/objective, or no eligible model).
+ */
+export declare function route(endpoint: string | undefined | null, task: string, objective?: string | undefined | null, model?: string | undefined | null, sessionId?: string | undefined | null, contextTokens?: number | undefined | null, requiredCapabilities?: Array<string> | undefined | null, minConfidence?: string | undefined | null, executionPreference?: string | undefined | null, minPlacementEvidence?: string | undefined | null): Promise<string>
+
+/**
+ * Executes caller-declared independent managed tasks with bounded, priority-fair dispatch.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable or rejects the batch envelope. Individual
+ * task failures remain explicit entries in the successful batch response so sibling work is not
+ * discarded.
+ */
+export declare function runTaskBatchRequest(endpoint: string | undefined | null, request: unknown): Promise<string>
+
+/**
+ * Object-based managed task API for callers that need the complete task contract without a long,
+ * ABI-fragile positional argument list. The request is forwarded to `/_freellama/v1/tasks`, where
+ * the typed Rust server validates routing fields, message history, and advanced Ollama controls.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable or rejects the request.
+ */
+export declare function runTaskRequest(endpoint: string | undefined | null, request: unknown): Promise<string>
+
+/**
+ * Live platform view: per-backend admission, queues, adaptive limits and circuit breakers,
  * loaded models, host memory, Ollama's effective settings, and today's usage.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable.
+ */
+export declare function status(endpoint?: string | undefined | null): Promise<string>
+
+/**
+ * Usage totals for the last `days` days (default 7), per day and per model.
+ *
+ * # Errors
+ *
+ * Returns an error if `freellama serve` is unreachable.
+ */
+export declare function usage(endpoint?: string | undefined | null, days?: number | undefined | null): Promise<string>
+
+/**
+ * Crate version this addon was compiled from; release verification requires it to match the
+ * npm package version.
+ */
+export declare function version(): string
+
+/**
+ * Preloads an exact installed model through managed admission and deadlines.
+ * # Errors
+ * Returns an error if the server refuses placement, capacity, or the request.
  */
-export function status(endpoint?: string | undefined | null): Promise<string>;
-
-/** Usage totals per day and per model over the last `days` days (default 7). */
-export function usage(endpoint?: string | undefined | null, days?: number | undefined | null): Promise<string>;
-
-/** Create a bounded, idle-expiring model-affinity handle; it stores no prompt history or KV. */
-export function createSession(endpoint?: string | undefined | null): Promise<string>;
-
-export function killSession(endpoint: string | undefined | null, sessionId: string): Promise<string>;
-
-/** Release a model-affinity handle after related work has completed. */
-export function deleteSession(
-  endpoint: string | undefined | null,
-  sessionId: string,
-): Promise<void>;
-
-/**
- * Installed-model inventory with capabilities, residency, and advertised context.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- */
-export function listModels(endpoint?: string | undefined | null): Promise<string>;
-
-/**
- * Deterministic model selection for a task.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param task e.g. "completion" | "code_repair" | "vision" | "embedding"
- * @param objective "fastest" | "balanced" | "quality", defaults to "balanced"
- * @param model Optional explicit model name to force
- * @param sessionId Optional session id for model affinity
- * @param contextTokens Optional minimum context window required
- * @param requiredCapabilities Optional list of capabilities the model must advertise (e.g. ["vision"])
- * @param minConfidence Optional floor ("low" | "medium"); the core gate refuses below it
- * @param executionPreference Guarded backend hint: "auto" | "prefer_cpu" | "prefer_gpu"
- * @param minPlacementEvidence "configured" (default) or fail-closed physical "observed"
- * @param minPlacementEvidence "configured" (default) or fail-closed physical "observed"
- */
-export function route(
-  endpoint: string | undefined | null,
-  task: string,
-  objective?: string | undefined | null,
-  model?: string | undefined | null,
-  sessionId?: string | undefined | null,
-  contextTokens?: number | undefined | null,
-  requiredCapabilities?: Array<string> | undefined | null,
-  minConfidence?: string | undefined | null,
-  executionPreference?: string | undefined | null,
-  minPlacementEvidence?: string | undefined | null,
-): Promise<string>;
-
-/**
- * Side-effect-free install recommendation for a task. Never runs `ollama pull` itself.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param task e.g. "completion" | "code_repair" | "vision" | "embedding"
- * @param objective "fastest" | "balanced" | "quality", defaults to "balanced"
- * @param model Optional explicit model name to filter to
- * @param contextTokens Optional minimum context window required
- * @param requiredCapabilities Optional list of capabilities the model must advertise (e.g. ["vision"])
- * @param executionPreference Guarded backend hint: "auto" | "prefer_cpu" | "prefer_gpu"
- * @param minPlacementEvidence "configured" (default) or fail-closed physical "observed"
- */
-export function recommend(
-  endpoint: string | undefined | null,
-  task: string,
-  objective?: string | undefined | null,
-  model?: string | undefined | null,
-  contextTokens?: number | undefined | null,
-  requiredCapabilities?: Array<string> | undefined | null,
-  executionPreference?: string | undefined | null,
-  minPlacementEvidence?: string | undefined | null,
-): Promise<string>;
-
-/**
- * Routes AND executes a chat/generate/embed call in one shot — unlike `route`/`recommend`, this
- * actually does work. Provide `prompt` for a single message, or `messages` (an array of
- * `{role, content}` objects) for multi-turn history. For task "embedding", set `input` instead.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param task e.g. "completion" | "code_repair" | "vision" | "embedding"
- * @param objective "fastest" | "balanced" | "quality", defaults to "balanced"
- * @param model Optional explicit model name to force
- * @param sessionId Optional session id for model affinity
- * @param contextTokens Optional minimum context window required
- * @param requiredCapabilities Optional list of capabilities the model must advertise
- * @param prompt Single-turn user message
- * @param images Base64-encoded images (no data-URI prefix) attached to the `prompt` message — pair with requiredCapabilities: ["vision"]
- * @param messages Multi-turn message history, wins over `prompt` if both are set
- * @param input Embedding input (string or array of strings), for task "embedding"
- * @param tools Optional tool/function definitions for function-calling tasks
- * @param keepAlive Overrides Ollama's model residency window, e.g. "0" or "-1"
- * @param minConfidence Optional floor ("low" | "medium"); the core gate refuses before generation
- * @param executionPreference Guarded backend hint: "auto" | "prefer_cpu" | "prefer_gpu"
- */
-export function runTask(
-  endpoint: string | undefined | null,
-  task: string,
-  objective?: string | undefined | null,
-  model?: string | undefined | null,
-  sessionId?: string | undefined | null,
-  contextTokens?: number | undefined | null,
-  requiredCapabilities?: Array<string> | undefined | null,
-  prompt?: string | undefined | null,
-  images?: Array<string> | undefined | null,
-  messages?: unknown | undefined | null,
-  input?: unknown | undefined | null,
-  tools?: unknown | undefined | null,
-  keepAlive?: string | undefined | null,
-  minConfidence?: string | undefined | null,
-  executionPreference?: string | undefined | null,
-  minPlacementEvidence?: string | undefined | null,
-): Promise<string>;
-
-/**
- * Object-based managed task API. Supports the full typed task request including lossless message
- * history and request_options (format, think, runtime options, logprobs).
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param request Complete `/_freellama/v1/tasks` request object
- */
-export function runTaskRequest(
-  endpoint: string | undefined | null,
-  request: unknown,
-): Promise<string>;
-
-/**
- * Executes explicitly independent tasks with a bounded, priority-fair dispatcher. Individual
- * task failures are returned as result entries so unaffected sibling work is preserved.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param request Complete `/_freellama/v1/task-batches` request object
- */
-export function runTaskBatchRequest(
-  endpoint: string | undefined | null,
-  request: unknown,
-): Promise<string>;
-
-/** Lists process-local job metadata without prompts or results. */
-export function listTaskJobs(endpoint?: string | undefined | null): Promise<string>;
-/** Reads one deferred job and its retained result. */
-export function getTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>;
-/** Cancels one deferred job and waits for its local permits to be released. */
-export function cancelTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>;
-/** Stop one deferred task, release local permits, then discard its retained record. */
-export function removeTaskJob(endpoint: string | undefined | null, jobId: string): Promise<string>;
-
-/**
- * Converts a free-text natural-language intent into a route.
- * @param endpoint FreeLlama serve endpoint, defaults to http://127.0.0.1:11435
- * @param text Free-text description of what's needed
- * @param sessionId Optional session id for model affinity
- */
-export function naturalRoute(
-  endpoint: string | undefined | null,
-  text: string,
-  sessionId?: string | undefined | null,
-): Promise<string>;
-
-/** Opt-in bounded process-local history. Metadata by default. */
-export function createScope(endpoint: string | undefined | null, request: unknown): Promise<string>;
-export function getScope(endpoint: string | undefined | null, scopeId: string, includeMessages?: boolean | null): Promise<string>;
-export function forkScope(endpoint: string | undefined | null, scopeId: string, request: unknown): Promise<string>;
-export function deleteScope(endpoint: string | undefined | null, scopeId: string): Promise<void>;
-/** Empty-payload preload through managed admission and deadlines. */
-export function warmModelRequest(endpoint: string | undefined | null, request: unknown): Promise<string>;
+export declare function warmModelRequest(endpoint: string | undefined | null, request: unknown): Promise<string>

package/native/index.js

@@ -1,6 +1,6 @@
-// Hand-written glue: napi-rs CLI did not emit JS bindings for this crate/cli pair, so this
-// file re-exports the compiled `.node`. Rebuild with `npm run build` from the repo root.
-// See packages/mcp/README.md.
+// Loads the local development addon first, then the matching optional platform package. Kept
+// as a small loader instead of napi-rs's generated one; index.d.ts is generated by
+// `yarn build:native` (scripts/build-native.mjs). See packages/mcp/DEVELOPING.md.
 const { existsSync } = require("node:fs");
 const path = require("node:path");
 const { createRequire } = require("node:module");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octocodeai/freellama-mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server exposing FreeLlama core as tools, via native NAPI bindings into packages/rust-core.",
   "repository": {
     "type": "git",
@@ -26,9 +26,10 @@
     "native/index.js",
     "native/index.d.ts",
     "native/package.json",
-    "adapters/*.py",
     "docs",
     "README.md",
+    "CONFIGURATION.md",
+    "DEVELOPING.md",
     "LICENSE-APACHE",
     "LICENSE-MIT",
     "assets/logo.jpg"
@@ -49,14 +50,14 @@
     "zod": "^3.24.1"
   },
   "optionalDependencies": {
-    "@octocodeai/freellama-native-darwin-arm64": "0.5.0",
-    "@octocodeai/freellama-native-darwin-x64": "0.5.0",
-    "@octocodeai/freellama-native-linux-arm64-gnu": "0.5.0",
-    "@octocodeai/freellama-native-linux-arm64-musl": "0.5.0",
-    "@octocodeai/freellama-native-linux-x64-gnu": "0.5.0",
-    "@octocodeai/freellama-native-linux-x64-musl": "0.5.0",
-    "@octocodeai/freellama-native-win32-arm64-msvc": "0.5.0",
-    "@octocodeai/freellama-native-win32-x64-msvc": "0.5.0"
+    "@octocodeai/freellama-native-darwin-arm64": "0.6.0",
+    "@octocodeai/freellama-native-darwin-x64": "0.6.0",
+    "@octocodeai/freellama-native-linux-arm64-gnu": "0.6.0",
+    "@octocodeai/freellama-native-linux-arm64-musl": "0.6.0",
+    "@octocodeai/freellama-native-linux-x64-gnu": "0.6.0",
+    "@octocodeai/freellama-native-linux-x64-musl": "0.6.0",
+    "@octocodeai/freellama-native-win32-arm64-msvc": "0.6.0",
+    "@octocodeai/freellama-native-win32-x64-msvc": "0.6.0"
   },
   "license": "Apache-2.0 OR MIT",
   "publishConfig": {