@graphorin/provider-llamacpp-node 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# @graphorin/provider-llamacpp-node
+
+## 0.1.0
+
+Initial release. See the root `CHANGELOG.md` and the corresponding
+changeset for the full list of features.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+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

@@ -0,0 +1,82 @@
+# `@graphorin/provider-llamacpp-node`
+
+> Companion package to
+> [`@graphorin/provider`](../provider/README.md) — in-process GGUF
+> execution for the
+> [**Graphorin**](https://github.com/o-stepper/graphorin) framework.
+
+Wraps `node-llama-cpp@^3.5` to load `.gguf` model files directly into
+the same Node process. No daemon, no port to manage, no GPU contention
+with other processes. Trust class is permanent `loopback` because the
+model lives in the same trust boundary as the host process.
+
+## Installation
+
+```bash
+pnpm add @graphorin/provider-llamacpp-node node-llama-cpp
+```
+
+## Quick start
+
+```ts
+import { llamaCppNodeAdapter } from '@graphorin/provider-llamacpp-node';
+import { createProvider } from '@graphorin/provider';
+
+const provider = createProvider(
+  llamaCppNodeAdapter({
+    modelPath: '/path/to/qwen2.5-7b-instruct-q4_k_m.gguf',
+    gpuLayers: 'auto',
+  }),
+);
+```
+
+## Native token counting
+
+```ts
+import { LlamaCppNativeCounter } from '@graphorin/provider-llamacpp-node';
+import { setGlobalTokenCounter } from '@graphorin/provider/counters';
+
+setGlobalTokenCounter(
+  new LlamaCppNativeCounter({
+    model: loadedGgufModel,
+    modelPath: '/path/to/qwen2.5-7b.gguf',
+  }),
+);
+```
+
+The counter wraps the GGUF tokenizer directly, which is strictly
+tighter than the cl100k_base proxy used by the HTTP-shaped adapters.
+
+## HITL durable-resume tradeoff
+
+The in-process adapter does **not** survive a process restart
+mid-stream — the model context lives in the running process and is
+lost on exit. For human-in-the-loop workflows that need durable
+mid-stream resume across restarts, prefer one of the HTTP-shaped
+adapters instead:
+
+- `ollamaAdapter` — Ollama HTTP daemon
+- `llamaCppServerAdapter` — upstream `llama-server` binary
+- `openAICompatibleAdapter` — LMStudio / LocalAI / vLLM /
+  Together-style endpoints
+
+## GGUF model provenance
+
+`.gguf` model files are not signed by default. Pull only from trusted
+publishers and verify the SHA-256 of the downloaded file against the
+publisher's manifest:
+
+- `huggingface.co/ggml-org`
+- `huggingface.co/TheBloke`
+- `huggingface.co/bartowski`
+- `huggingface.co/unsloth`
+- `huggingface.co/Qwen` (official Qwen distributions)
+
+Full provenance enforcement (allowlist + Sigstore signature
+verification) is a future Graphorin work item; v0.1 documents the
+discipline rather than enforcing it at runtime.
+
+## Project metadata
+
+- **Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko
+- Repository: <https://github.com/o-stepper/graphorin>

package/dist/adapter.d.ts

@@ -0,0 +1,55 @@
+import { LlamaCppNodeRuntimeOverrides, LlamaModelInstance, LlamaSessionInstance } from "./runtime.js";
+import { Provider, ProviderCapabilities, Sensitivity } from "@graphorin/core";
+
+//#region src/adapter.d.ts
+
+/**
+ * Options accepted by {@link llamaCppNodeAdapter}.
+ *
+ * @stable
+ */
+interface LlamaCppNodeAdapterOptions {
+  /** Filesystem path to the `.gguf` model file. */
+  readonly modelPath: string;
+  /** Number of layers to offload to the GPU. Default `'auto'`. */
+  readonly gpuLayers?: number | 'auto';
+  /** Optional context-window override. */
+  readonly contextSize?: number;
+  /** Provider name attached to spans / log lines. */
+  readonly name?: string;
+  /** Capability declaration. Merged on top of the defaults table. */
+  readonly capabilities?: Partial<ProviderCapabilities>;
+  /** Sensitivity override (defaults to the loopback envelope). */
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  /**
+   * Test-only runtime override. When unset the adapter loads
+   * `node-llama-cpp` lazily on first call.
+   */
+  readonly runtimeOverrides?: LlamaCppNodeRuntimeOverrides;
+  /**
+   * Optional `model` override that short-circuits the
+   * `loadLlamaModule(...).loadModel(...)` flow. Tests pass a fixture
+   * shaped instance.
+   */
+  readonly modelOverride?: LlamaModelInstance;
+  /**
+   * Optional session factory override. When unset, the adapter builds a
+   * real session from the peer (PS-3): `model.createContext()` →
+   * `new LlamaChatSession({ contextSequence })`, streaming through
+   * `prompt(text, { onTextChunk })`. Overrides
+   * (`runtimeOverrides.createSession` or this option) keep the test
+   * seam.
+   */
+  readonly sessionFactory?: (model: LlamaModelInstance, system?: string) => Promise<LlamaSessionInstance>;
+}
+/**
+ * Build a Graphorin {@link Provider} backed by an in-process GGUF
+ * model. The first call lazily loads the `node-llama-cpp` peer + the
+ * model file; subsequent calls reuse the cached instances.
+ *
+ * @stable
+ */
+declare function llamaCppNodeAdapter(options: LlamaCppNodeAdapterOptions): Provider;
+//#endregion
+export { LlamaCppNodeAdapterOptions, llamaCppNodeAdapter };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../src/adapter.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UA8CiB,0BAAA;;;;;;;;;;0BAUS,QAAQ;;gCAEF,cAAc;;;;;8BAKhB;;;;;;2BAMH;;;;;;;;;oCAUhB,wCAEJ,QAAQ;;;;;;;;;iBAsBC,mBAAA,UAA6B,6BAA6B"}

package/dist/adapter.js

@@ -0,0 +1,255 @@
+import { loadLlamaChatSessionCtor, loadLlamaModule } from "./runtime.js";
+import { ProviderHttpError } from "@graphorin/provider/errors";
+import { applyReasoningPolicy, resolveReasoningRetention } from "@graphorin/provider/reasoning";
+
+//#region src/adapter.ts
+/**
+* Default sensitivity envelope for the in-process adapter — same as
+* the loopback HTTP path.
+*
+* @stable
+*/
+const LLAMA_CPP_NODE_ACCEPTS_SENSITIVITY = Object.freeze([
+	"public",
+	"internal",
+	"secret"
+]);
+const DEFAULT_CAPABILITIES = {
+	streaming: true,
+	toolCalling: false,
+	parallelToolCalls: false,
+	multimodal: false,
+	structuredOutput: false,
+	reasoning: false,
+	contextWindow: 8192,
+	maxOutput: 4096,
+	reasoningContract: "optional"
+};
+/**
+* Build a Graphorin {@link Provider} backed by an in-process GGUF
+* model. The first call lazily loads the `node-llama-cpp` peer + the
+* model file; subsequent calls reuse the cached instances.
+*
+* @stable
+*/
+function llamaCppNodeAdapter(options) {
+	const providerName = options.name ?? `llama-cpp-node-${basename(options.modelPath)}`;
+	const capabilities = {
+		...DEFAULT_CAPABILITIES,
+		...options.capabilities
+	};
+	const acceptsSensitivity = options.acceptsSensitivity ?? LLAMA_CPP_NODE_ACCEPTS_SENSITIVITY;
+	let resolved = null;
+	let resolving = null;
+	const ensureModel = async () => {
+		if (resolved !== null) return resolved;
+		if (resolving !== null) return resolving;
+		resolving = (async () => {
+			resolved = { model: options.modelOverride ?? await resolveModel(options) };
+			resolving = null;
+			return resolved;
+		})();
+		return resolving;
+	};
+	const sessionFactory = options.sessionFactory ?? options.runtimeOverrides?.createSession ?? ((model, system) => defaultSessionFactory(model, system, options));
+	return {
+		name: providerName,
+		modelId: options.modelPath,
+		capabilities,
+		acceptsSensitivity,
+		stream(req) {
+			return streamLlamaCppNode(ensureModel, sessionFactory, providerName, options, applyLlamaCppNodePreflight(req, capabilities));
+		},
+		async generate(req) {
+			const events = streamLlamaCppNode(ensureModel, sessionFactory, providerName, options, applyLlamaCppNodePreflight(req, capabilities));
+			const collected = [];
+			let usage = {
+				promptTokens: 0,
+				completionTokens: 0,
+				totalTokens: 0
+			};
+			let finishReason = "stop";
+			let streamError;
+			for await (const event of events) {
+				if (event.type === "text-delta") collected.push(event.delta);
+				if (event.type === "error") streamError = event.error;
+				if (event.type === "finish") {
+					usage = event.usage;
+					finishReason = event.finishReason;
+				}
+			}
+			if (streamError !== void 0) throw new ProviderHttpError({
+				providerName,
+				status: 0,
+				message: streamError.message
+			});
+			return {
+				text: collected.join(""),
+				usage,
+				finishReason
+			};
+		}
+	};
+}
+function applyLlamaCppNodePreflight(req, capabilities) {
+	const retention = resolveReasoningRetention({
+		...req.reasoningRetention !== void 0 ? { requested: req.reasoningRetention } : {},
+		...capabilities.reasoningContract !== void 0 ? { contract: capabilities.reasoningContract } : {}
+	});
+	if (retention === "pass-through-all") return req;
+	const filtered = applyReasoningPolicy({
+		messages: req.messages,
+		retention
+	});
+	if (filtered === req.messages) return req;
+	return {
+		...req,
+		messages: filtered
+	};
+}
+async function* streamLlamaCppNode(ensureModel, sessionFactory, providerName, options, req) {
+	const { model } = await ensureModel();
+	const session = await sessionFactory(model, typeof req.systemMessage === "string" ? req.systemMessage : void 0);
+	const prompt = renderPrompt(req);
+	const promptTokens = lengthOf(model.tokenize(prompt));
+	yield {
+		type: "stream-start",
+		metadata: {
+			providerName,
+			modelId: options.modelPath,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		}
+	};
+	let completionTokens = 0;
+	let errored = false;
+	try {
+		const streamOptions = {};
+		if (req.signal !== void 0) streamOptions.signal = req.signal;
+		if (req.maxTokens !== void 0) streamOptions.maxTokens = req.maxTokens;
+		if (req.temperature !== void 0) streamOptions.temperature = req.temperature;
+		for await (const piece of session.promptStreamingResponse(prompt, streamOptions)) {
+			if (typeof piece !== "string" || piece.length === 0) continue;
+			completionTokens += lengthOf(model.tokenize(piece));
+			yield {
+				type: "text-delta",
+				delta: piece
+			};
+			if (req.signal?.aborted) break;
+		}
+	} catch (err) {
+		errored = true;
+		yield {
+			type: "error",
+			error: {
+				kind: "unknown",
+				message: err.message
+			}
+		};
+	}
+	yield {
+		type: "finish",
+		finishReason: errored ? "error" : "stop",
+		usage: {
+			promptTokens,
+			completionTokens,
+			totalTokens: promptTokens + completionTokens
+		}
+	};
+}
+async function resolveModel(options) {
+	return (await loadLlamaModule(options.runtimeOverrides)).loadModel({
+		modelPath: options.modelPath,
+		...options.gpuLayers !== void 0 ? { gpuLayers: options.gpuLayers } : {}
+	});
+}
+/**
+* The REAL default session factory (PS-3): `model.createContext()` →
+* `context.getSequence()` → `new LlamaChatSession({ contextSequence })`
+* from the lazily-loaded peer, adapting its callback-streaming
+* `prompt(text, { onTextChunk })` to the adapter's
+* `promptStreamingResponse` AsyncIterable contract.
+*/
+async function defaultSessionFactory(model, system, options) {
+	const session = new (await (loadLlamaChatSessionCtor(options.runtimeOverrides)))({
+		contextSequence: (await model.createContext(options.contextSize !== void 0 ? { contextSize: options.contextSize } : void 0)).getSequence(),
+		...system !== void 0 ? { systemPrompt: system } : {}
+	});
+	return { promptStreamingResponse(prompt, streamOptions) {
+		return promptToIterable(session, prompt, streamOptions);
+	} };
+}
+/**
+* Bridge the peer's callback-streaming `prompt(...)` into the
+* AsyncIterable the adapter consumes. A rejection from `prompt`
+* rejects the pending/next iteration so the stream's error path
+* (PS-4) observes it.
+*/
+function promptToIterable(session, prompt, streamOptions) {
+	const queue = [];
+	let done = false;
+	let failure;
+	let wake = null;
+	const notify = () => {
+		if (wake !== null) {
+			const w = wake;
+			wake = null;
+			w();
+		}
+	};
+	session.prompt(prompt, {
+		...streamOptions?.signal !== void 0 ? { signal: streamOptions.signal } : {},
+		...streamOptions?.maxTokens !== void 0 ? { maxTokens: streamOptions.maxTokens } : {},
+		...streamOptions?.temperature !== void 0 ? { temperature: streamOptions.temperature } : {},
+		onTextChunk: (chunk) => {
+			if (typeof chunk === "string" && chunk.length > 0) queue.push(chunk);
+			notify();
+		}
+	}).then(() => {
+		done = true;
+		notify();
+	}, (err) => {
+		failure = err instanceof Error ? err : new Error(String(err));
+		done = true;
+		notify();
+	});
+	return { [Symbol.asyncIterator]() {
+		return { async next() {
+			for (;;) {
+				const head = queue.shift();
+				if (head !== void 0) return {
+					done: false,
+					value: head
+				};
+				if (failure !== void 0) throw failure;
+				if (done) return {
+					done: true,
+					value: void 0
+				};
+				await new Promise((resolve) => {
+					wake = resolve;
+				});
+			}
+		} };
+	} };
+}
+function renderPrompt(req) {
+	const parts = [];
+	if (req.systemMessage !== void 0) parts.push(`[system] ${req.systemMessage}`);
+	for (const msg of req.messages) {
+		const text = typeof msg.content === "string" ? msg.content : msg.content.map((p) => p.type === "text" ? p.text : p.type === "reasoning" ? p.text : "").join("");
+		parts.push(`[${msg.role}] ${text}`);
+	}
+	return parts.join("\n");
+}
+function basename(path) {
+	const idx = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return idx === -1 ? path : path.slice(idx + 1);
+}
+function lengthOf(tokens) {
+	if (tokens === null || tokens === void 0) return 0;
+	return tokens.length ?? 0;
+}
+
+//#endregion
+export { llamaCppNodeAdapter };
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["LLAMA_CPP_NODE_ACCEPTS_SENSITIVITY: ReadonlyArray<Sensitivity>","DEFAULT_CAPABILITIES: ProviderCapabilities","capabilities: ProviderCapabilities","resolved: { model: LlamaModelInstance } | null","resolving: Promise<{ model: LlamaModelInstance }> | null","collected: string[]","usage: Usage","finishReason: ProviderResponse['finishReason']","streamError: { message: string } | undefined","streamOptions: { signal?: AbortSignal; maxTokens?: number; temperature?: number }","queue: string[]","failure: unknown","wake: (() => void) | null","parts: string[]"],"sources":["../src/adapter.ts"],"sourcesContent":["/**\n * `llamaCppNodeAdapter` — in-process GGUF adapter built on\n * `node-llama-cpp@^3.5`. The adapter declares `trust: 'loopback'`\n * permanently because the model lives in the same trust boundary as\n * the host process.\n *\n * @packageDocumentation\n */\n\nimport type {\n  Provider,\n  ProviderCapabilities,\n  ProviderEvent,\n  ProviderRequest,\n  ProviderResponse,\n  Sensitivity,\n  Usage,\n} from '@graphorin/core';\nimport { ProviderHttpError } from '@graphorin/provider/errors';\nimport { applyReasoningPolicy, resolveReasoningRetention } from '@graphorin/provider/reasoning';\nimport {\n  type LlamaChatSessionPeer,\n  type LlamaCppNodeRuntimeOverrides,\n  type LlamaModelInstance,\n  type LlamaSessionInstance,\n  loadLlamaChatSessionCtor,\n  loadLlamaModule,\n} from './runtime.js';\n\n/**\n * Default sensitivity envelope for the in-process adapter — same as\n * the loopback HTTP path.\n *\n * @stable\n */\nexport const LLAMA_CPP_NODE_ACCEPTS_SENSITIVITY: ReadonlyArray<Sensitivity> = Object.freeze([\n  'public',\n  'internal',\n  'secret',\n]);\n\n/**\n * Options accepted by {@link llamaCppNodeAdapter}.\n *\n * @stable\n */\nexport interface LlamaCppNodeAdapterOptions {\n  /** Filesystem path to the `.gguf` model file. */\n  readonly modelPath: string;\n  /** Number of layers to offload to the GPU. Default `'auto'`. */\n  readonly gpuLayers?: number | 'auto';\n  /** Optional context-window override. */\n  readonly contextSize?: number;\n  /** Provider name attached to spans / log lines. */\n  readonly name?: string;\n  /** Capability declaration. Merged on top of the defaults table. */\n  readonly capabilities?: Partial<ProviderCapabilities>;\n  /** Sensitivity override (defaults to the loopback envelope). */\n  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;\n  /**\n   * Test-only runtime override. When unset the adapter loads\n   * `node-llama-cpp` lazily on first call.\n   */\n  readonly runtimeOverrides?: LlamaCppNodeRuntimeOverrides;\n  /**\n   * Optional `model` override that short-circuits the\n   * `loadLlamaModule(...).loadModel(...)` flow. Tests pass a fixture\n   * shaped instance.\n   */\n  readonly modelOverride?: LlamaModelInstance;\n  /**\n   * Optional session factory override. When unset, the adapter builds a\n   * real session from the peer (PS-3): `model.createContext()` →\n   * `new LlamaChatSession({ contextSequence })`, streaming through\n   * `prompt(text, { onTextChunk })`. Overrides\n   * (`runtimeOverrides.createSession` or this option) keep the test\n   * seam.\n   */\n  readonly sessionFactory?: (\n    model: LlamaModelInstance,\n    system?: string,\n  ) => Promise<LlamaSessionInstance>;\n}\n\nconst DEFAULT_CAPABILITIES: ProviderCapabilities = {\n  streaming: true,\n  toolCalling: false,\n  parallelToolCalls: false,\n  multimodal: false,\n  structuredOutput: false,\n  reasoning: false,\n  contextWindow: 8_192,\n  maxOutput: 4_096,\n  reasoningContract: 'optional',\n};\n\n/**\n * Build a Graphorin {@link Provider} backed by an in-process GGUF\n * model. The first call lazily loads the `node-llama-cpp` peer + the\n * model file; subsequent calls reuse the cached instances.\n *\n * @stable\n */\nexport function llamaCppNodeAdapter(options: LlamaCppNodeAdapterOptions): Provider {\n  const providerName = options.name ?? `llama-cpp-node-${basename(options.modelPath)}`;\n  const capabilities: ProviderCapabilities = {\n    ...DEFAULT_CAPABILITIES,\n    ...options.capabilities,\n  };\n  const acceptsSensitivity = options.acceptsSensitivity ?? LLAMA_CPP_NODE_ACCEPTS_SENSITIVITY;\n  let resolved: { model: LlamaModelInstance } | null = null;\n  let resolving: Promise<{ model: LlamaModelInstance }> | null = null;\n  const ensureModel = async (): Promise<{ model: LlamaModelInstance }> => {\n    if (resolved !== null) return resolved;\n    if (resolving !== null) return resolving;\n    resolving = (async () => {\n      const model = options.modelOverride ?? (await resolveModel(options));\n      resolved = { model };\n      resolving = null;\n      return resolved;\n    })();\n    return resolving;\n  };\n  const sessionFactory =\n    options.sessionFactory ??\n    options.runtimeOverrides?.createSession ??\n    ((model: LlamaModelInstance, system?: string) => defaultSessionFactory(model, system, options));\n  return {\n    name: providerName,\n    modelId: options.modelPath,\n    capabilities,\n    acceptsSensitivity,\n    stream(req) {\n      return streamLlamaCppNode(\n        ensureModel,\n        sessionFactory,\n        providerName,\n        options,\n        applyLlamaCppNodePreflight(req, capabilities),\n      );\n    },\n    async generate(req) {\n      const events = streamLlamaCppNode(\n        ensureModel,\n        sessionFactory,\n        providerName,\n        options,\n        applyLlamaCppNodePreflight(req, capabilities),\n      );\n      const collected: string[] = [];\n      let usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n      let finishReason: ProviderResponse['finishReason'] = 'stop';\n      let streamError: { message: string } | undefined;\n      for await (const event of events) {\n        if (event.type === 'text-delta') collected.push(event.delta);\n        if (event.type === 'error') streamError = event.error;\n        if (event.type === 'finish') {\n          usage = event.usage;\n          finishReason = event.finishReason;\n        }\n      }\n      // PS-4: a swallowed mid-stream error returned truncated text\n      // indistinguishable from success — and a never-throwing\n      // generate() bypasses withRetry / withFallback entirely.\n      if (streamError !== undefined) {\n        throw new ProviderHttpError({\n          providerName,\n          status: 0,\n          message: streamError.message,\n        });\n      }\n      return {\n        text: collected.join(''),\n        usage,\n        finishReason,\n      };\n    },\n  };\n}\n\nfunction applyLlamaCppNodePreflight(\n  req: ProviderRequest,\n  capabilities: ProviderCapabilities,\n): ProviderRequest {\n  const retention = resolveReasoningRetention({\n    ...(req.reasoningRetention !== undefined ? { requested: req.reasoningRetention } : {}),\n    ...(capabilities.reasoningContract !== undefined\n      ? { contract: capabilities.reasoningContract }\n      : {}),\n  });\n  if (retention === 'pass-through-all') return req;\n  const filtered = applyReasoningPolicy({ messages: req.messages, retention });\n  if (filtered === req.messages) return req;\n  return { ...req, messages: filtered };\n}\n\nasync function* streamLlamaCppNode(\n  ensureModel: () => Promise<{ model: LlamaModelInstance }>,\n  sessionFactory: (model: LlamaModelInstance, system?: string) => Promise<LlamaSessionInstance>,\n  providerName: string,\n  options: LlamaCppNodeAdapterOptions,\n  req: ProviderRequest,\n): AsyncIterable<ProviderEvent> {\n  const { model } = await ensureModel();\n  const session = await sessionFactory(\n    model,\n    typeof req.systemMessage === 'string' ? req.systemMessage : undefined,\n  );\n  const prompt = renderPrompt(req);\n  const promptTokens = lengthOf(model.tokenize(prompt));\n  yield {\n    type: 'stream-start',\n    metadata: {\n      providerName,\n      modelId: options.modelPath,\n      createdAt: new Date().toISOString(),\n    },\n  };\n  let completionTokens = 0;\n  let errored = false;\n  try {\n    const streamOptions: { signal?: AbortSignal; maxTokens?: number; temperature?: number } = {};\n    if (req.signal !== undefined) streamOptions.signal = req.signal;\n    if (req.maxTokens !== undefined) streamOptions.maxTokens = req.maxTokens;\n    if (req.temperature !== undefined) streamOptions.temperature = req.temperature;\n    for await (const piece of session.promptStreamingResponse(prompt, streamOptions)) {\n      if (typeof piece !== 'string' || piece.length === 0) continue;\n      completionTokens += lengthOf(model.tokenize(piece));\n      yield { type: 'text-delta', delta: piece };\n      if (req.signal?.aborted) break;\n    }\n  } catch (err) {\n    errored = true;\n    yield { type: 'error', error: { kind: 'unknown', message: (err as Error).message } };\n  }\n  yield {\n    type: 'finish',\n    // PS-4: a mid-stream failure must not masquerade as a clean stop —\n    // partial text would be indistinguishable from success.\n    finishReason: errored ? 'error' : 'stop',\n    usage: {\n      promptTokens,\n      completionTokens,\n      totalTokens: promptTokens + completionTokens,\n    },\n  };\n}\n\nasync function resolveModel(options: LlamaCppNodeAdapterOptions): Promise<LlamaModelInstance> {\n  const llama = await loadLlamaModule(options.runtimeOverrides);\n  return llama.loadModel({\n    modelPath: options.modelPath,\n    ...(options.gpuLayers !== undefined ? { gpuLayers: options.gpuLayers } : {}),\n  });\n}\n\n/**\n * The REAL default session factory (PS-3): `model.createContext()` →\n * `context.getSequence()` → `new LlamaChatSession({ contextSequence })`\n * from the lazily-loaded peer, adapting its callback-streaming\n * `prompt(text, { onTextChunk })` to the adapter's\n * `promptStreamingResponse` AsyncIterable contract.\n */\nasync function defaultSessionFactory(\n  model: LlamaModelInstance,\n  system: string | undefined,\n  options: LlamaCppNodeAdapterOptions,\n): Promise<LlamaSessionInstance> {\n  const ChatSession = await loadLlamaChatSessionCtor(options.runtimeOverrides);\n  const context = await model.createContext(\n    options.contextSize !== undefined ? { contextSize: options.contextSize } : undefined,\n  );\n  const sequence = context.getSequence();\n  const session = new ChatSession({\n    contextSequence: sequence,\n    ...(system !== undefined ? { systemPrompt: system } : {}),\n  });\n  return {\n    promptStreamingResponse(prompt, streamOptions) {\n      return promptToIterable(session, prompt, streamOptions);\n    },\n  };\n}\n\n/**\n * Bridge the peer's callback-streaming `prompt(...)` into the\n * AsyncIterable the adapter consumes. A rejection from `prompt`\n * rejects the pending/next iteration so the stream's error path\n * (PS-4) observes it.\n */\nfunction promptToIterable(\n  session: LlamaChatSessionPeer,\n  prompt: string,\n  streamOptions?: {\n    readonly signal?: AbortSignal;\n    readonly maxTokens?: number;\n    readonly temperature?: number;\n  },\n): AsyncIterable<string> {\n  const queue: string[] = [];\n  let done = false;\n  let failure: unknown;\n  let wake: (() => void) | null = null;\n  const notify = (): void => {\n    if (wake !== null) {\n      const w = wake;\n      wake = null;\n      w();\n    }\n  };\n  void session\n    .prompt(prompt, {\n      ...(streamOptions?.signal !== undefined ? { signal: streamOptions.signal } : {}),\n      ...(streamOptions?.maxTokens !== undefined ? { maxTokens: streamOptions.maxTokens } : {}),\n      ...(streamOptions?.temperature !== undefined\n        ? { temperature: streamOptions.temperature }\n        : {}),\n      onTextChunk: (chunk: string) => {\n        if (typeof chunk === 'string' && chunk.length > 0) queue.push(chunk);\n        notify();\n      },\n    })\n    .then(\n      () => {\n        done = true;\n        notify();\n      },\n      (err: unknown) => {\n        failure = err instanceof Error ? err : new Error(String(err));\n        done = true;\n        notify();\n      },\n    );\n  return {\n    [Symbol.asyncIterator](): AsyncIterator<string> {\n      return {\n        async next(): Promise<IteratorResult<string>> {\n          for (;;) {\n            const head = queue.shift();\n            if (head !== undefined) return { done: false, value: head };\n            if (failure !== undefined) throw failure;\n            if (done) return { done: true, value: undefined };\n            await new Promise<void>((resolve) => {\n              wake = resolve;\n            });\n          }\n        },\n      };\n    },\n  };\n}\n\nfunction renderPrompt(req: ProviderRequest): string {\n  const parts: string[] = [];\n  if (req.systemMessage !== undefined) parts.push(`[system] ${req.systemMessage}`);\n  for (const msg of req.messages) {\n    const text =\n      typeof msg.content === 'string'\n        ? msg.content\n        : msg.content\n            .map((p) => (p.type === 'text' ? p.text : p.type === 'reasoning' ? p.text : ''))\n            .join('');\n    parts.push(`[${msg.role}] ${text}`);\n  }\n  return parts.join('\\n');\n}\n\nfunction basename(path: string): string {\n  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\\\'));\n  return idx === -1 ? path : path.slice(idx + 1);\n}\n\nfunction lengthOf(tokens: readonly number[] | Uint32Array | Uint8Array | null | undefined): number {\n  if (tokens === null || tokens === undefined) return 0;\n  return (tokens as { length?: number }).length ?? 0;\n}\n"],"mappings":";;;;;;;;;;;AAmCA,MAAaA,qCAAiE,OAAO,OAAO;CAC1F;CACA;CACA;CACD,CAAC;AA6CF,MAAMC,uBAA6C;CACjD,WAAW;CACX,aAAa;CACb,mBAAmB;CACnB,YAAY;CACZ,kBAAkB;CAClB,WAAW;CACX,eAAe;CACf,WAAW;CACX,mBAAmB;CACpB;;;;;;;;AASD,SAAgB,oBAAoB,SAA+C;CACjF,MAAM,eAAe,QAAQ,QAAQ,kBAAkB,SAAS,QAAQ,UAAU;CAClF,MAAMC,eAAqC;EACzC,GAAG;EACH,GAAG,QAAQ;EACZ;CACD,MAAM,qBAAqB,QAAQ,sBAAsB;CACzD,IAAIC,WAAiD;CACrD,IAAIC,YAA2D;CAC/D,MAAM,cAAc,YAAoD;AACtE,MAAI,aAAa,KAAM,QAAO;AAC9B,MAAI,cAAc,KAAM,QAAO;AAC/B,eAAa,YAAY;AAEvB,cAAW,EAAE,OADC,QAAQ,iBAAkB,MAAM,aAAa,QAAQ,EAC/C;AACpB,eAAY;AACZ,UAAO;MACL;AACJ,SAAO;;CAET,MAAM,iBACJ,QAAQ,kBACR,QAAQ,kBAAkB,mBACxB,OAA2B,WAAoB,sBAAsB,OAAO,QAAQ,QAAQ;AAChG,QAAO;EACL,MAAM;EACN,SAAS,QAAQ;EACjB;EACA;EACA,OAAO,KAAK;AACV,UAAO,mBACL,aACA,gBACA,cACA,SACA,2BAA2B,KAAK,aAAa,CAC9C;;EAEH,MAAM,SAAS,KAAK;GAClB,MAAM,SAAS,mBACb,aACA,gBACA,cACA,SACA,2BAA2B,KAAK,aAAa,CAC9C;GACD,MAAMC,YAAsB,EAAE;GAC9B,IAAIC,QAAe;IAAE,cAAc;IAAG,kBAAkB;IAAG,aAAa;IAAG;GAC3E,IAAIC,eAAiD;GACrD,IAAIC;AACJ,cAAW,MAAM,SAAS,QAAQ;AAChC,QAAI,MAAM,SAAS,aAAc,WAAU,KAAK,MAAM,MAAM;AAC5D,QAAI,MAAM,SAAS,QAAS,eAAc,MAAM;AAChD,QAAI,MAAM,SAAS,UAAU;AAC3B,aAAQ,MAAM;AACd,oBAAe,MAAM;;;AAMzB,OAAI,gBAAgB,OAClB,OAAM,IAAI,kBAAkB;IAC1B;IACA,QAAQ;IACR,SAAS,YAAY;IACtB,CAAC;AAEJ,UAAO;IACL,MAAM,UAAU,KAAK,GAAG;IACxB;IACA;IACD;;EAEJ;;AAGH,SAAS,2BACP,KACA,cACiB;CACjB,MAAM,YAAY,0BAA0B;EAC1C,GAAI,IAAI,uBAAuB,SAAY,EAAE,WAAW,IAAI,oBAAoB,GAAG,EAAE;EACrF,GAAI,aAAa,sBAAsB,SACnC,EAAE,UAAU,aAAa,mBAAmB,GAC5C,EAAE;EACP,CAAC;AACF,KAAI,cAAc,mBAAoB,QAAO;CAC7C,MAAM,WAAW,qBAAqB;EAAE,UAAU,IAAI;EAAU;EAAW,CAAC;AAC5E,KAAI,aAAa,IAAI,SAAU,QAAO;AACtC,QAAO;EAAE,GAAG;EAAK,UAAU;EAAU;;AAGvC,gBAAgB,mBACd,aACA,gBACA,cACA,SACA,KAC8B;CAC9B,MAAM,EAAE,UAAU,MAAM,aAAa;CACrC,MAAM,UAAU,MAAM,eACpB,OACA,OAAO,IAAI,kBAAkB,WAAW,IAAI,gBAAgB,OAC7D;CACD,MAAM,SAAS,aAAa,IAAI;CAChC,MAAM,eAAe,SAAS,MAAM,SAAS,OAAO,CAAC;AACrD,OAAM;EACJ,MAAM;EACN,UAAU;GACR;GACA,SAAS,QAAQ;GACjB,4BAAW,IAAI,MAAM,EAAC,aAAa;GACpC;EACF;CACD,IAAI,mBAAmB;CACvB,IAAI,UAAU;AACd,KAAI;EACF,MAAMC,gBAAoF,EAAE;AAC5F,MAAI,IAAI,WAAW,OAAW,eAAc,SAAS,IAAI;AACzD,MAAI,IAAI,cAAc,OAAW,eAAc,YAAY,IAAI;AAC/D,MAAI,IAAI,gBAAgB,OAAW,eAAc,cAAc,IAAI;AACnE,aAAW,MAAM,SAAS,QAAQ,wBAAwB,QAAQ,cAAc,EAAE;AAChF,OAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG;AACrD,uBAAoB,SAAS,MAAM,SAAS,MAAM,CAAC;AACnD,SAAM;IAAE,MAAM;IAAc,OAAO;IAAO;AAC1C,OAAI,IAAI,QAAQ,QAAS;;UAEpB,KAAK;AACZ,YAAU;AACV,QAAM;GAAE,MAAM;GAAS,OAAO;IAAE,MAAM;IAAW,SAAU,IAAc;IAAS;GAAE;;AAEtF,OAAM;EACJ,MAAM;EAGN,cAAc,UAAU,UAAU;EAClC,OAAO;GACL;GACA;GACA,aAAa,eAAe;GAC7B;EACF;;AAGH,eAAe,aAAa,SAAkE;AAE5F,SADc,MAAM,gBAAgB,QAAQ,iBAAiB,EAChD,UAAU;EACrB,WAAW,QAAQ;EACnB,GAAI,QAAQ,cAAc,SAAY,EAAE,WAAW,QAAQ,WAAW,GAAG,EAAE;EAC5E,CAAC;;;;;;;;;AAUJ,eAAe,sBACb,OACA,QACA,SAC+B;CAM/B,MAAM,UAAU,KALI,OAAM,yBAAyB,QAAQ,iBAAiB,GAK5C;EAC9B,kBALc,MAAM,MAAM,cAC1B,QAAQ,gBAAgB,SAAY,EAAE,aAAa,QAAQ,aAAa,GAAG,OAC5E,EACwB,aAAa;EAGpC,GAAI,WAAW,SAAY,EAAE,cAAc,QAAQ,GAAG,EAAE;EACzD,CAAC;AACF,QAAO,EACL,wBAAwB,QAAQ,eAAe;AAC7C,SAAO,iBAAiB,SAAS,QAAQ,cAAc;IAE1D;;;;;;;;AASH,SAAS,iBACP,SACA,QACA,eAKuB;CACvB,MAAMC,QAAkB,EAAE;CAC1B,IAAI,OAAO;CACX,IAAIC;CACJ,IAAIC,OAA4B;CAChC,MAAM,eAAqB;AACzB,MAAI,SAAS,MAAM;GACjB,MAAM,IAAI;AACV,UAAO;AACP,MAAG;;;AAGP,CAAK,QACF,OAAO,QAAQ;EACd,GAAI,eAAe,WAAW,SAAY,EAAE,QAAQ,cAAc,QAAQ,GAAG,EAAE;EAC/E,GAAI,eAAe,cAAc,SAAY,EAAE,WAAW,cAAc,WAAW,GAAG,EAAE;EACxF,GAAI,eAAe,gBAAgB,SAC/B,EAAE,aAAa,cAAc,aAAa,GAC1C,EAAE;EACN,cAAc,UAAkB;AAC9B,OAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAAG,OAAM,KAAK,MAAM;AACpE,WAAQ;;EAEX,CAAC,CACD,WACO;AACJ,SAAO;AACP,UAAQ;KAET,QAAiB;AAChB,YAAU,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,IAAI,CAAC;AAC7D,SAAO;AACP,UAAQ;GAEX;AACH,QAAO,EACL,CAAC,OAAO,iBAAwC;AAC9C,SAAO,EACL,MAAM,OAAwC;AAC5C,YAAS;IACP,MAAM,OAAO,MAAM,OAAO;AAC1B,QAAI,SAAS,OAAW,QAAO;KAAE,MAAM;KAAO,OAAO;KAAM;AAC3D,QAAI,YAAY,OAAW,OAAM;AACjC,QAAI,KAAM,QAAO;KAAE,MAAM;KAAM,OAAO;KAAW;AACjD,UAAM,IAAI,SAAe,YAAY;AACnC,YAAO;MACP;;KAGP;IAEJ;;AAGH,SAAS,aAAa,KAA8B;CAClD,MAAMC,QAAkB,EAAE;AAC1B,KAAI,IAAI,kBAAkB,OAAW,OAAM,KAAK,YAAY,IAAI,gBAAgB;AAChF,MAAK,MAAM,OAAO,IAAI,UAAU;EAC9B,MAAM,OACJ,OAAO,IAAI,YAAY,WACnB,IAAI,UACJ,IAAI,QACD,KAAK,MAAO,EAAE,SAAS,SAAS,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,OAAO,GAAI,CAC/E,KAAK,GAAG;AACjB,QAAM,KAAK,IAAI,IAAI,KAAK,IAAI,OAAO;;AAErC,QAAO,MAAM,KAAK,KAAK;;AAGzB,SAAS,SAAS,MAAsB;CACtC,MAAM,MAAM,KAAK,IAAI,KAAK,YAAY,IAAI,EAAE,KAAK,YAAY,KAAK,CAAC;AACnE,QAAO,QAAQ,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE;;AAGhD,SAAS,SAAS,QAAiF;AACjG,KAAI,WAAW,QAAQ,WAAW,OAAW,QAAO;AACpD,QAAQ,OAA+B,UAAU"}

package/dist/counter.d.ts

@@ -0,0 +1,34 @@
+import { LlamaModelInstance } from "./runtime.js";
+import { Message, TokenCounter } from "@graphorin/core";
+
+//#region src/counter.d.ts
+
+/**
+ * Options for {@link LlamaCppNativeCounter}.
+ *
+ * @stable
+ */
+interface LlamaCppNativeCounterOptions {
+  readonly model: LlamaModelInstance;
+  readonly modelPath?: string;
+  readonly id?: string;
+}
+/**
+ * Counter that delegates to `model.tokenize(text)` from the loaded
+ * GGUF instance. Cache invalidation is keyed on the model file path
+ * (when supplied) so swapping models invalidates per-message caches
+ * upstream.
+ *
+ * @stable
+ */
+declare class LlamaCppNativeCounter implements TokenCounter {
+  #private;
+  readonly id: string;
+  readonly version: string;
+  constructor(options: LlamaCppNativeCounterOptions);
+  count(messages: ReadonlyArray<Message>): Promise<number>;
+  countText(text: string): Promise<number>;
+}
+//#endregion
+export { LlamaCppNativeCounter, LlamaCppNativeCounterOptions };
+//# sourceMappingURL=counter.d.ts.map

package/dist/counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter.d.ts","names":[],"sources":["../src/counter.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UAmBiB,4BAAA;kBACC;;;;;;;;;;;;cAaL,qBAAA,YAAiC;;;;uBAKvB;kBAOC,cAAc,WAAW;2BAShB"}

package/dist/counter.js

@@ -0,0 +1,50 @@
+import { serialiseMessageForCount, serializedToString } from "@graphorin/provider/counters";
+
+//#region src/counter.ts
+/**
+* Counter that delegates to `model.tokenize(text)` from the loaded
+* GGUF instance. Cache invalidation is keyed on the model file path
+* (when supplied) so swapping models invalidates per-message caches
+* upstream.
+*
+* @stable
+*/
+var LlamaCppNativeCounter = class {
+	id;
+	version;
+	#model;
+	constructor(options) {
+		this.#model = options.model;
+		const fingerprint = options.modelPath !== void 0 ? hash(options.modelPath) : "unknown";
+		this.id = options.id ?? `llama-cpp-native@${fingerprint}`;
+		this.version = `llama-cpp-native-${fingerprint}-v1`;
+	}
+	async count(messages) {
+		let total = 0;
+		for (const msg of messages) {
+			const serialised = serialiseMessageForCount(msg);
+			total += this.#tokenLengthOf(serializedToString(serialised));
+		}
+		return total;
+	}
+	async countText(text) {
+		if (text.length === 0) return 0;
+		return this.#tokenLengthOf(text);
+	}
+	#tokenLengthOf(text) {
+		if (text.length === 0) return 0;
+		const tokens = this.#model.tokenize(text);
+		if (tokens === null || tokens === void 0) return 0;
+		if (typeof tokens.length === "number") return tokens.length;
+		return 0;
+	}
+};
+function hash(value) {
+	let h = 0;
+	for (let i = 0; i < value.length; i++) h = h * 31 + value.charCodeAt(i) | 0;
+	return Math.abs(h).toString(16);
+}
+
+//#endregion
+export { LlamaCppNativeCounter };
+//# sourceMappingURL=counter.js.map

package/dist/counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter.js","names":["#model","#tokenLengthOf"],"sources":["../src/counter.ts"],"sourcesContent":["/**\n * `LlamaCppNativeCounter` — token counter that wraps the loaded\n * `node-llama-cpp` model's `tokenize(text)` function. The counter is\n * strictly tighter than the cl100k_base proxy because it uses the\n * exact tokenizer the GGUF file embeds.\n *\n * @packageDocumentation\n */\n\nimport type { Message, TokenCounter } from '@graphorin/core';\nimport { serialiseMessageForCount, serializedToString } from '@graphorin/provider/counters';\n\nimport type { LlamaModelInstance } from './runtime.js';\n\n/**\n * Options for {@link LlamaCppNativeCounter}.\n *\n * @stable\n */\nexport interface LlamaCppNativeCounterOptions {\n  readonly model: LlamaModelInstance;\n  readonly modelPath?: string;\n  readonly id?: string;\n}\n\n/**\n * Counter that delegates to `model.tokenize(text)` from the loaded\n * GGUF instance. Cache invalidation is keyed on the model file path\n * (when supplied) so swapping models invalidates per-message caches\n * upstream.\n *\n * @stable\n */\nexport class LlamaCppNativeCounter implements TokenCounter {\n  readonly id: string;\n  readonly version: string;\n  readonly #model: LlamaModelInstance;\n\n  constructor(options: LlamaCppNativeCounterOptions) {\n    this.#model = options.model;\n    const fingerprint = options.modelPath !== undefined ? hash(options.modelPath) : 'unknown';\n    this.id = options.id ?? `llama-cpp-native@${fingerprint}`;\n    this.version = `llama-cpp-native-${fingerprint}-v1`;\n  }\n\n  async count(messages: ReadonlyArray<Message>): Promise<number> {\n    let total = 0;\n    for (const msg of messages) {\n      const serialised = serialiseMessageForCount(msg);\n      total += this.#tokenLengthOf(serializedToString(serialised));\n    }\n    return total;\n  }\n\n  async countText(text: string): Promise<number> {\n    if (text.length === 0) return 0;\n    return this.#tokenLengthOf(text);\n  }\n\n  #tokenLengthOf(text: string): number {\n    if (text.length === 0) return 0;\n    const tokens = this.#model.tokenize(text);\n    if (tokens === null || tokens === undefined) return 0;\n    if (typeof (tokens as { length?: number }).length === 'number') {\n      return (tokens as { length: number }).length;\n    }\n    return 0;\n  }\n}\n\nfunction hash(value: string): string {\n  // Lightweight deterministic fingerprint — the framework only needs\n  // it for cache invalidation, not for cryptographic purposes.\n  let h = 0;\n  for (let i = 0; i < value.length; i++) {\n    h = (h * 31 + value.charCodeAt(i)) | 0;\n  }\n  return Math.abs(h).toString(16);\n}\n"],"mappings":";;;;;;;;;;;AAiCA,IAAa,wBAAb,MAA2D;CACzD,AAAS;CACT,AAAS;CACT,CAASA;CAET,YAAY,SAAuC;AACjD,QAAKA,QAAS,QAAQ;EACtB,MAAM,cAAc,QAAQ,cAAc,SAAY,KAAK,QAAQ,UAAU,GAAG;AAChF,OAAK,KAAK,QAAQ,MAAM,oBAAoB;AAC5C,OAAK,UAAU,oBAAoB,YAAY;;CAGjD,MAAM,MAAM,UAAmD;EAC7D,IAAI,QAAQ;AACZ,OAAK,MAAM,OAAO,UAAU;GAC1B,MAAM,aAAa,yBAAyB,IAAI;AAChD,YAAS,MAAKC,cAAe,mBAAmB,WAAW,CAAC;;AAE9D,SAAO;;CAGT,MAAM,UAAU,MAA+B;AAC7C,MAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,SAAO,MAAKA,cAAe,KAAK;;CAGlC,eAAe,MAAsB;AACnC,MAAI,KAAK,WAAW,EAAG,QAAO;EAC9B,MAAM,SAAS,MAAKD,MAAO,SAAS,KAAK;AACzC,MAAI,WAAW,QAAQ,WAAW,OAAW,QAAO;AACpD,MAAI,OAAQ,OAA+B,WAAW,SACpD,QAAQ,OAA8B;AAExC,SAAO;;;AAIX,SAAS,KAAK,OAAuB;CAGnC,IAAI,IAAI;AACR,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,KAAK,IAAI,KAAK,MAAM,WAAW,EAAE,GAAI;AAEvC,QAAO,KAAK,IAAI,EAAE,CAAC,SAAS,GAAG"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { LlamaCppNodeRuntimeOverrides, LlamaInstance, LlamaModelInstance, LlamaSessionInstance } from "./runtime.js";
+import { LlamaCppNodeAdapterOptions, llamaCppNodeAdapter } from "./adapter.js";
+import { LlamaCppNativeCounter, LlamaCppNativeCounterOptions } from "./counter.js";
+
+//#region src/index.d.ts
+
+/**
+ * @graphorin/provider-llamacpp-node — in-process GGUF execution
+ * adapter for the Graphorin framework. The package wraps
+ * `node-llama-cpp@^3.5` to load `.gguf` model files directly into the
+ * same Node process — no daemon, no port to manage, no GPU contention
+ * with other processes.
+ *
+ * The adapter declares `trust: 'loopback'` permanently because the
+ * model lives in the same trust boundary as the host process; the
+ * symmetry mirrors `@graphorin/embedder-transformersjs` (in-process
+ * embedder; same trust boundary).
+ *
+ * The companion package is operationally simpler than the HTTP-shaped
+ * adapters but does NOT survive a process restart mid-stream — the
+ * model context lives in the process and is lost on exit. For HITL
+ * durable mid-stream resume, one of the HTTP-shaped adapters
+ * (`ollamaAdapter`, `llamaCppServerAdapter`, `openAICompatibleAdapter`)
+ * is the better choice.
+ *
+ * @packageDocumentation
+ */
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { LlamaCppNativeCounter, type LlamaCppNativeCounterOptions, type LlamaCppNodeAdapterOptions, type LlamaCppNodeRuntimeOverrides, type LlamaInstance, type LlamaModelInstance, type LlamaSessionInstance, VERSION, llamaCppNodeAdapter };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAuBA;;;;;;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import { llamaCppNodeAdapter } from "./adapter.js";
+import { LlamaCppNativeCounter } from "./counter.js";
+
+//#region src/index.ts
+/**
+* @graphorin/provider-llamacpp-node — in-process GGUF execution
+* adapter for the Graphorin framework. The package wraps
+* `node-llama-cpp@^3.5` to load `.gguf` model files directly into the
+* same Node process — no daemon, no port to manage, no GPU contention
+* with other processes.
+*
+* The adapter declares `trust: 'loopback'` permanently because the
+* model lives in the same trust boundary as the host process; the
+* symmetry mirrors `@graphorin/embedder-transformersjs` (in-process
+* embedder; same trust boundary).
+*
+* The companion package is operationally simpler than the HTTP-shaped
+* adapters but does NOT survive a process restart mid-stream — the
+* model context lives in the process and is lost on exit. For HITL
+* durable mid-stream resume, one of the HTTP-shaped adapters
+* (`ollamaAdapter`, `llamaCppServerAdapter`, `openAICompatibleAdapter`)
+* is the better choice.
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { LlamaCppNativeCounter, VERSION, llamaCppNodeAdapter };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/provider-llamacpp-node — in-process GGUF execution\n * adapter for the Graphorin framework. The package wraps\n * `node-llama-cpp@^3.5` to load `.gguf` model files directly into the\n * same Node process — no daemon, no port to manage, no GPU contention\n * with other processes.\n *\n * The adapter declares `trust: 'loopback'` permanently because the\n * model lives in the same trust boundary as the host process; the\n * symmetry mirrors `@graphorin/embedder-transformersjs` (in-process\n * embedder; same trust boundary).\n *\n * The companion package is operationally simpler than the HTTP-shaped\n * adapters but does NOT survive a process restart mid-stream — the\n * model context lives in the process and is lost on exit. For HITL\n * durable mid-stream resume, one of the HTTP-shaped adapters\n * (`ollamaAdapter`, `llamaCppServerAdapter`, `openAICompatibleAdapter`)\n * is the better choice.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\nexport { type LlamaCppNodeAdapterOptions, llamaCppNodeAdapter } from './adapter.js';\nexport {\n  LlamaCppNativeCounter,\n  type LlamaCppNativeCounterOptions,\n} from './counter.js';\nexport type {\n  LlamaCppNodeRuntimeOverrides,\n  LlamaInstance,\n  LlamaModelInstance,\n  LlamaSessionInstance,\n} from './runtime.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,UAAU"}

package/dist/runtime.d.ts

@@ -0,0 +1,94 @@
+//#region src/runtime.d.ts
+/**
+ * Loose structural shapes covering the slice of `node-llama-cpp` we
+ * use. Re-declared here to avoid pulling the heavy native peer at
+ * type-check time.
+ *
+ * @internal
+ */
+/**
+ * `Llama` engine instance (returned by `getLlama()`).
+ *
+ * @internal
+ */
+interface LlamaInstance {
+  loadModel(args: {
+    modelPath: string;
+    gpuLayers?: number | 'auto';
+  }): Promise<LlamaModelInstance>;
+}
+/**
+ * Loaded GGUF model.
+ *
+ * @internal
+ */
+interface LlamaModelInstance {
+  readonly trainContextSize?: number;
+  tokenize(text: string): readonly number[] | Uint32Array | Uint8Array;
+  createContext(args?: {
+    contextSize?: number;
+  }): Promise<{
+    getSequence(): {
+      dispose?: () => void;
+    };
+    dispose?: () => void;
+  }>;
+  dispose?(): Promise<void>;
+}
+/**
+ * Loaded chat session capable of streaming responses.
+ *
+ * @internal
+ */
+interface LlamaSessionInstance {
+  promptStreamingResponse(prompt: string, options?: {
+    readonly signal?: AbortSignal;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+  }): AsyncIterable<string>;
+}
+/**
+ * Test-only shape for injecting fixture-driven runtime behaviour.
+ *
+ * @stable
+ */
+interface LlamaCppNodeRuntimeOverrides {
+  /** Returns a `LlamaInstance` (the result of `getLlama()`). */
+  readonly getLlama?: () => Promise<LlamaInstance>;
+  /**
+   * Build a streaming chat session against an already-loaded model
+   * instance. Used by the adapter to wire `model.tokenize` and
+   * `session.promptStreamingResponse` to the per-test fixture.
+   */
+  readonly createSession?: (model: LlamaModelInstance, system?: string) => Promise<LlamaSessionInstance>;
+  /**
+   * Override the `LlamaChatSession` constructor used by the REAL
+   * default session factory (PS-3). Tests stub it; production loads it
+   * from the `node-llama-cpp` peer.
+   */
+  readonly LlamaChatSession?: LlamaChatSessionCtor;
+}
+/**
+ * Structural slice of the peer's `LlamaChatSession` class used by the
+ * default session factory (PS-3): `prompt(text, { onTextChunk })`
+ * resolves with the full response while streaming chunks through the
+ * callback.
+ *
+ * @internal
+ */
+interface LlamaChatSessionPeer {
+  prompt(text: string, options?: {
+    readonly signal?: AbortSignal;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly onTextChunk?: (chunk: string) => void;
+  }): Promise<string>;
+}
+/** @internal */
+type LlamaChatSessionCtor = new (args: {
+  readonly contextSequence: unknown;
+  readonly systemPrompt?: string;
+}) => LlamaChatSessionPeer;
+//#endregion
+export { LlamaCppNodeRuntimeOverrides, LlamaInstance, LlamaModelInstance, LlamaSessionInstance };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","names":[],"sources":["../src/runtime.ts"],"sourcesContent":[],"mappings":";;AAaA;AASA;;;;;;AAeA;AAgBA;;;AASW,UAjDM,aAAA,CAiDN;EAEI,SAAA,CAAA,IAAA,EAAA;IAAR,SAAA,EAAA,MAAA;IAMuB,SAAA,CAAA,EAAA,MAAA,GAAA,MAAA;EAAoB,CAAA,CAAA,EAxDqB,OAwDrB,CAxD6B,kBAwD7B,CAAA;AAWlD;AAaA;;;;;UAxEiB,kBAAA;;8CAE6B,cAAc;;;MACV;;;;;;cAIpC;;;;;;;UAQG,oBAAA;;sBAIO;;;MAInB;;;;;;;UAQY,4BAAA;;4BAEW,QAAQ;;;;;;mCAOzB,wCAEJ,QAAQ;;;;;;8BAMe;;;;;;;;;;UAWb,oBAAA;;sBAIO;;;;MAKnB;;;KAIO,oBAAA;;;MAGN"}

package/dist/runtime.js

@@ -0,0 +1,47 @@
+//#region src/runtime.ts
+let cachedLlama = null;
+let cachedChatSessionCtor = null;
+/**
+* Lazily load the `node-llama-cpp` peer and return the `Llama` engine
+* instance. Cached per process.
+*
+* @internal
+*/
+async function loadLlamaModule(overrides) {
+	if (overrides?.getLlama !== void 0) return overrides.getLlama();
+	if (cachedLlama !== null) return cachedLlama;
+	let mod;
+	try {
+		mod = await import("node-llama-cpp");
+	} catch (cause) {
+		throw new Error("[graphorin/provider-llamacpp-node] missing peer dependency 'node-llama-cpp'. Install it with `pnpm add node-llama-cpp`.", { cause });
+	}
+	if (typeof mod.getLlama !== "function") throw new Error("[graphorin/provider-llamacpp-node] installed node-llama-cpp does not expose getLlama().");
+	const instance = await mod.getLlama();
+	cachedLlama = instance;
+	return instance;
+}
+/**
+* Lazily resolve the peer's `LlamaChatSession` constructor for the
+* real default session factory (PS-3). Cached per process; the
+* override wins for tests.
+*
+* @internal
+*/
+async function loadLlamaChatSessionCtor(overrides) {
+	if (overrides?.LlamaChatSession !== void 0) return overrides.LlamaChatSession;
+	if (cachedChatSessionCtor !== null) return cachedChatSessionCtor;
+	let mod;
+	try {
+		mod = await import("node-llama-cpp");
+	} catch (cause) {
+		throw new Error("[graphorin/provider-llamacpp-node] missing peer dependency 'node-llama-cpp'. Install it with `pnpm add node-llama-cpp`.", { cause });
+	}
+	if (typeof mod.LlamaChatSession !== "function") throw new Error("[graphorin/provider-llamacpp-node] installed node-llama-cpp does not expose LlamaChatSession.");
+	cachedChatSessionCtor = mod.LlamaChatSession;
+	return cachedChatSessionCtor;
+}
+
+//#endregion
+export { loadLlamaChatSessionCtor, loadLlamaModule };
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","names":["cachedLlama: LlamaInstance | null","cachedChatSessionCtor: LlamaChatSessionCtor | null","mod: { getLlama?: unknown }","mod: { LlamaChatSession?: unknown }"],"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * Loose structural shapes covering the slice of `node-llama-cpp` we\n * use. Re-declared here to avoid pulling the heavy native peer at\n * type-check time.\n *\n * @internal\n */\n\n/**\n * `Llama` engine instance (returned by `getLlama()`).\n *\n * @internal\n */\nexport interface LlamaInstance {\n  loadModel(args: { modelPath: string; gpuLayers?: number | 'auto' }): Promise<LlamaModelInstance>;\n}\n\n/**\n * Loaded GGUF model.\n *\n * @internal\n */\nexport interface LlamaModelInstance {\n  readonly trainContextSize?: number;\n  tokenize(text: string): readonly number[] | Uint32Array | Uint8Array;\n  createContext(args?: { contextSize?: number }): Promise<{\n    getSequence(): { dispose?: () => void };\n    dispose?: () => void;\n  }>;\n  dispose?(): Promise<void>;\n}\n\n/**\n * Loaded chat session capable of streaming responses.\n *\n * @internal\n */\nexport interface LlamaSessionInstance {\n  promptStreamingResponse(\n    prompt: string,\n    options?: {\n      readonly signal?: AbortSignal;\n      readonly maxTokens?: number;\n      readonly temperature?: number;\n    },\n  ): AsyncIterable<string>;\n}\n\n/**\n * Test-only shape for injecting fixture-driven runtime behaviour.\n *\n * @stable\n */\nexport interface LlamaCppNodeRuntimeOverrides {\n  /** Returns a `LlamaInstance` (the result of `getLlama()`). */\n  readonly getLlama?: () => Promise<LlamaInstance>;\n  /**\n   * Build a streaming chat session against an already-loaded model\n   * instance. Used by the adapter to wire `model.tokenize` and\n   * `session.promptStreamingResponse` to the per-test fixture.\n   */\n  readonly createSession?: (\n    model: LlamaModelInstance,\n    system?: string,\n  ) => Promise<LlamaSessionInstance>;\n  /**\n   * Override the `LlamaChatSession` constructor used by the REAL\n   * default session factory (PS-3). Tests stub it; production loads it\n   * from the `node-llama-cpp` peer.\n   */\n  readonly LlamaChatSession?: LlamaChatSessionCtor;\n}\n\n/**\n * Structural slice of the peer's `LlamaChatSession` class used by the\n * default session factory (PS-3): `prompt(text, { onTextChunk })`\n * resolves with the full response while streaming chunks through the\n * callback.\n *\n * @internal\n */\nexport interface LlamaChatSessionPeer {\n  prompt(\n    text: string,\n    options?: {\n      readonly signal?: AbortSignal;\n      readonly maxTokens?: number;\n      readonly temperature?: number;\n      readonly onTextChunk?: (chunk: string) => void;\n    },\n  ): Promise<string>;\n}\n\n/** @internal */\nexport type LlamaChatSessionCtor = new (args: {\n  readonly contextSequence: unknown;\n  readonly systemPrompt?: string;\n}) => LlamaChatSessionPeer;\n\nlet cachedLlama: LlamaInstance | null = null;\nlet cachedChatSessionCtor: LlamaChatSessionCtor | null = null;\n\n/**\n * Lazily load the `node-llama-cpp` peer and return the `Llama` engine\n * instance. Cached per process.\n *\n * @internal\n */\nexport async function loadLlamaModule(\n  overrides: LlamaCppNodeRuntimeOverrides | undefined,\n): Promise<LlamaInstance> {\n  if (overrides?.getLlama !== undefined) return overrides.getLlama();\n  if (cachedLlama !== null) return cachedLlama;\n  let mod: { getLlama?: unknown };\n  try {\n    mod = (await import('node-llama-cpp')) as { getLlama?: unknown };\n  } catch (cause) {\n    throw new Error(\n      \"[graphorin/provider-llamacpp-node] missing peer dependency 'node-llama-cpp'. \" +\n        'Install it with `pnpm add node-llama-cpp`.',\n      { cause },\n    );\n  }\n  if (typeof mod.getLlama !== 'function') {\n    throw new Error(\n      '[graphorin/provider-llamacpp-node] installed node-llama-cpp does not expose getLlama().',\n    );\n  }\n  const instance = (await (mod.getLlama as () => Promise<LlamaInstance>)()) as LlamaInstance;\n  cachedLlama = instance;\n  return instance;\n}\n\n/**\n * Lazily resolve the peer's `LlamaChatSession` constructor for the\n * real default session factory (PS-3). Cached per process; the\n * override wins for tests.\n *\n * @internal\n */\nexport async function loadLlamaChatSessionCtor(\n  overrides: LlamaCppNodeRuntimeOverrides | undefined,\n): Promise<LlamaChatSessionCtor> {\n  if (overrides?.LlamaChatSession !== undefined) return overrides.LlamaChatSession;\n  if (cachedChatSessionCtor !== null) return cachedChatSessionCtor;\n  let mod: { LlamaChatSession?: unknown };\n  try {\n    mod = (await import('node-llama-cpp')) as { LlamaChatSession?: unknown };\n  } catch (cause) {\n    throw new Error(\n      \"[graphorin/provider-llamacpp-node] missing peer dependency 'node-llama-cpp'. \" +\n        'Install it with `pnpm add node-llama-cpp`.',\n      { cause },\n    );\n  }\n  if (typeof mod.LlamaChatSession !== 'function') {\n    throw new Error(\n      '[graphorin/provider-llamacpp-node] installed node-llama-cpp does not expose LlamaChatSession.',\n    );\n  }\n  cachedChatSessionCtor = mod.LlamaChatSession as LlamaChatSessionCtor;\n  return cachedChatSessionCtor;\n}\n\n/**\n * Test-only hook that resets the cached `getLlama()` result.\n *\n * @internal\n */\nexport function __resetLlamaCache(): void {\n  cachedLlama = null;\n  cachedChatSessionCtor = null;\n}\n"],"mappings":";AAmGA,IAAIA,cAAoC;AACxC,IAAIC,wBAAqD;;;;;;;AAQzD,eAAsB,gBACpB,WACwB;AACxB,KAAI,WAAW,aAAa,OAAW,QAAO,UAAU,UAAU;AAClE,KAAI,gBAAgB,KAAM,QAAO;CACjC,IAAIC;AACJ,KAAI;AACF,QAAO,MAAM,OAAO;UACb,OAAO;AACd,QAAM,IAAI,MACR,2HAEA,EAAE,OAAO,CACV;;AAEH,KAAI,OAAO,IAAI,aAAa,WAC1B,OAAM,IAAI,MACR,0FACD;CAEH,MAAM,WAAY,MAAO,IAAI,UAA2C;AACxE,eAAc;AACd,QAAO;;;;;;;;;AAUT,eAAsB,yBACpB,WAC+B;AAC/B,KAAI,WAAW,qBAAqB,OAAW,QAAO,UAAU;AAChE,KAAI,0BAA0B,KAAM,QAAO;CAC3C,IAAIC;AACJ,KAAI;AACF,QAAO,MAAM,OAAO;UACb,OAAO;AACd,QAAM,IAAI,MACR,2HAEA,EAAE,OAAO,CACV;;AAEH,KAAI,OAAO,IAAI,qBAAqB,WAClC,OAAM,IAAI,MACR,gGACD;AAEH,yBAAwB,IAAI;AAC5B,QAAO"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@graphorin/provider-llamacpp-node",
+  "version": "0.5.0",
+  "description": "In-process GGUF execution adapter for the Graphorin framework. Wraps node-llama-cpp@^3.5 to load .gguf model files directly into the same Node process — no daemon, no port to manage, no GPU contention with other processes. Declares trust: 'loopback' permanently because the model lives in the same trust boundary as the host process. Ships LlamaCppNativeCounter that wraps model.tokenize() from the loaded GGUF for byte-exact token counts.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/provider-llamacpp-node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/provider-llamacpp-node"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "provider",
+    "llm",
+    "llama-cpp",
+    "node-llama-cpp",
+    "gguf",
+    "in-process",
+    "local-first",
+    "loopback"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0",
+    "@graphorin/provider": "0.5.0"
+  },
+  "peerDependencies": {
+    "node-llama-cpp": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "node-llama-cpp": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}