updates

Author: lalalune

bun.lock

@@ -68,6 +68,16 @@ export interface PlannerInvocationResult {
     promptTokens?: number;
     completionTokens?: number;
     totalTokens?: number;
+    /**
+     * Provider-reported prompt-cache reads (Anthropic
+     * ``cache_read_input_tokens`` / OpenAI + Cerebras
+     * ``prompt_tokens_details.cached_tokens``). Optional because not every
+     * provider supports prompt caching; nullable upstream stays nullable
+     * here — no silent 0 fallback, per AGENTS.md Cmd #8.
+     */
+    cacheReadInputTokens?: number;
+    /** Anthropic-only ``cache_creation_input_tokens``. */
+    cacheCreationInputTokens?: number;
   };
 }
 

packages/app-core/src/benchmark/lifeops-bench-handler.ts

@@ -1036,13 +1036,34 @@ export async function startBenchmarkServer() {
         };
       });
 
+      // Sum the per-call cache-read tokens across every LLM call that fired
+      // during this turn. A call with `cachedTokens === undefined` means the
+      // provider didn't report it — those calls do NOT contribute to the sum
+      // and do NOT collapse the value to 0. If no call in the turn reported
+      // cache info, we pass `undefined` through so the wire shape preserves
+      // "we don't know" (AGENTS.md Cmd #8). Cerebras gpt-oss-120b reports
+      // `prompt_tokens_details.cached_tokens` default-on; Anthropic reports
+      // `cache_read_input_tokens` natively.
+      const anyCacheReported = turnUsageBuffer.some(
+        (c) => typeof c.cachedTokens === "number",
+      );
+      const cacheReadInputTokens = anyCacheReported
+        ? turnUsageBuffer.reduce(
+            (s, c) =>
+              s + (typeof c.cachedTokens === "number" ? c.cachedTokens : 0),
+            0,
+          )
+        : undefined;
       const usage = {
         promptTokens: turnUsageBuffer.reduce((s, c) => s + c.promptTokens, 0),
         completionTokens: turnUsageBuffer.reduce(
           (s, c) => s + c.completionTokens,
           0,
         ),
         totalTokens: turnUsageBuffer.reduce((s, c) => s + c.totalTokens, 0),
+        ...(cacheReadInputTokens !== undefined
+          ? { cacheReadInputTokens }
+          : {}),
       };
 
       // Touch the backend so unused-import linters do not strip the

packages/app-core/src/benchmark/server.ts

@@ -80,7 +80,8 @@ export type LiveProviderName =
   | "openai"
   | "anthropic"
   | "google"
-  | "openrouter";
+  | "openrouter"
+  | "local-llama-cpp";
 
 export type LiveProviderConfig = {
   name: LiveProviderName;
@@ -194,6 +195,24 @@ const PROVIDERS: Array<{
     defaultSmallModel: "google/gemini-2.0-flash-001",
     defaultLargeModel: "google/gemini-2.0-flash-001",
   },
+  {
+    // Local OpenAI-compatible server (dflash llama-server fork or Ollama).
+    // The dflash fork at ~/.cache/eliza-dflash/milady-llama-cpp is preferred
+    // when present; otherwise PARALLAX_OPENCODE_BASE_URL points at Ollama
+    // (default http://localhost:11434/v1). No real API key is required, but
+    // the selector requires a non-empty key string, so callers must set
+    // LOCAL_LLAMA_CPP_API_KEY=local (or rely on the explicit
+    // selectLiveProvider("local-llama-cpp") path which seeds the sentinel).
+    name: "local-llama-cpp",
+    plugin: "@elizaos/plugin-openai",
+    keyEnvVars: ["LOCAL_LLAMA_CPP_API_KEY"],
+    baseUrlEnvVar: "OPENAI_BASE_URL",
+    defaultBaseUrl: "http://localhost:11434/v1",
+    smallModelEnvVar: "OPENAI_SMALL_MODEL",
+    largeModelEnvVar: "OPENAI_LARGE_MODEL",
+    defaultSmallModel: "qwen3-0.6b-q8_0",
+    defaultLargeModel: "qwen3-1.7b-q4_k_m",
+  },
 ];
 
 for (const provider of PROVIDERS) {

packages/app-core/test/helpers/live-provider.ts

@@ -147,6 +147,30 @@ async def _agent_fn(
                 value = usage.get(key)
                 if isinstance(value, (int, float)):
                     setattr(turn, attr, int(value))
+            # Cache telemetry comes from the TS bench server's MODEL_USED
+            # buffer rollup. `cacheReadInputTokens` is omitted when no LLM
+            # call in the turn reported cache info — we propagate that as
+            # ``None`` so the runner records "unknown" rather than a silent
+            # 0. Per AGENTS.md Cmd #8.
+            cache_read_raw = usage.get("cacheReadInputTokens")
+            cache_creation_raw = usage.get("cacheCreationInputTokens")
+            setattr(
+                turn,
+                "cache_read_input_tokens",
+                int(cache_read_raw)
+                if isinstance(cache_read_raw, (int, float))
+                else None,
+            )
+            setattr(
+                turn,
+                "cache_creation_input_tokens",
+                int(cache_creation_raw)
+                if isinstance(cache_creation_raw, (int, float))
+                else None,
+            )
+            # Eliza routes through plugin-openai (OpenAI / Cerebras) or
+            # plugin-anthropic — both support prompt caching.
+            setattr(turn, "cache_supported", True)
         # Stash model identity so result records can attribute spend.
         if model_name:
             setattr(turn, "model_name", model_name)

packages/benchmarks/eliza-adapter/eliza_adapter/lifeops_bench.py

@@ -310,11 +310,22 @@ def _send_in_process(
             for tc in tool_calls
             if getattr(getattr(tc, "function", None), "name", "")
         ]
+        # Surface the provider-reported usage block so the lifeops_bench adapter
+        # can parse cache_read_input_tokens (OpenAI / Cerebras shape:
+        # ``usage.prompt_tokens_details.cached_tokens``). Mirrors the subprocess
+        # path's payload shape; downstream callers read ``params['usage']``.
+        usage_obj = getattr(completion, "usage", None)
+        if usage_obj is not None and hasattr(usage_obj, "model_dump"):
+            usage_payload: dict[str, object] = usage_obj.model_dump()
+        elif isinstance(usage_obj, Mapping):
+            usage_payload = dict(usage_obj)
+        else:
+            usage_payload = {}
         return MessageResponse(
             text=str(msg.content or ""),
             thought=getattr(msg, "reasoning_content", None) or None,
             actions=actions,
-            params={"tool_calls": parsed_tool_calls},
+            params={"tool_calls": parsed_tool_calls, "usage": usage_payload},
         )
 
     @staticmethod

packages/benchmarks/hermes-adapter/hermes_adapter/client.py

@@ -107,6 +107,64 @@ async def _agent_fn(
         )
         if model_name:
             setattr(turn, "model_name", model_name)
+        # Surface usage + cache telemetry on the returned MessageTurn so the
+        # LifeOpsBench runner can populate TurnResult.cache_read_input_tokens
+        # / cache_creation_input_tokens / cache_hit_pct via getattr(). The
+        # hermes-agent OpenAI-compat surface exposes:
+        #   * OpenAI / Cerebras shape: usage.prompt_tokens_details.cached_tokens
+        # Anthropic-shaped responses (cache_read_input_tokens /
+        # cache_creation_input_tokens) are forwarded verbatim when present.
+        usage = resp.params.get("usage") if isinstance(resp.params, dict) else None
+        if isinstance(usage, dict):
+            _attach_usage_cache_fields(turn, usage)
         return turn
 
     return _agent_fn
+
+
+def _attach_usage_cache_fields(turn: Any, usage: dict[str, Any]) -> None:
+    """Parse OpenAI / Cerebras / Anthropic-shaped usage onto the MessageTurn.
+
+    Sets ``input_tokens`` / ``output_tokens`` / ``cache_read_input_tokens`` /
+    ``cache_creation_input_tokens`` / ``cache_supported`` as attributes on
+    ``turn`` (via ``setattr``) so the LifeOpsBench runner can pick them up
+    with ``getattr``. Cache fields stay ``None`` when the provider does not
+    report them — per AGENTS.md Cmd #8, no silent ``0`` fallback.
+    """
+    prompt = usage.get("prompt_tokens")
+    completion = usage.get("completion_tokens")
+    # Anthropic shape: input_tokens / output_tokens.
+    if not isinstance(prompt, (int, float)):
+        prompt = usage.get("input_tokens")
+    if not isinstance(completion, (int, float)):
+        completion = usage.get("output_tokens")
+    if isinstance(prompt, (int, float)):
+        setattr(turn, "input_tokens", int(prompt))
+    if isinstance(completion, (int, float)):
+        setattr(turn, "output_tokens", int(completion))
+
+    # OpenAI / Cerebras: usage.prompt_tokens_details.cached_tokens
+    prompt_details = usage.get("prompt_tokens_details") or {}
+    cache_read_raw = (
+        prompt_details.get("cached_tokens")
+        if isinstance(prompt_details, dict)
+        else None
+    )
+    # Anthropic: cache_read_input_tokens at the usage root.
+    if cache_read_raw is None:
+        cache_read_raw = usage.get("cache_read_input_tokens")
+    cache_creation_raw = usage.get("cache_creation_input_tokens")
+
+    cache_read_value: int | None = (
+        int(cache_read_raw) if isinstance(cache_read_raw, (int, float)) else None
+    )
+    cache_creation_value: int | None = (
+        int(cache_creation_raw)
+        if isinstance(cache_creation_raw, (int, float))
+        else None
+    )
+    setattr(turn, "cache_read_input_tokens", cache_read_value)
+    setattr(turn, "cache_creation_input_tokens", cache_creation_value)
+    # Hermes-template servers fronting Cerebras gpt-oss-120b or Anthropic
+    # support prompt caching; cache_supported is a hard-true here.
+    setattr(turn, "cache_supported", True)

packages/benchmarks/hermes-adapter/hermes_adapter/lifeops_bench.py

@@ -8,7 +8,9 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./metrics-schema": "./src/metrics-schema.ts"
+    "./metrics-schema": "./src/metrics-schema.ts",
+    "./model-tiers": "./src/model-tiers.ts",
+    "./local-llama-cpp": "./src/local-llama-cpp.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

packages/benchmarks/lib/package.json

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { existsSync } from "node:fs";
+
+import {
+  DFLASH_BINARY_PATH,
+  expandHome,
+  probeDflashFork,
+  resolveLocalBaseUrl,
+  startLocalServer,
+} from "../local-llama-cpp.ts";
+
+describe("expandHome", () => {
+  it("expands leading ~/ to the home dir", () => {
+    const expanded = expandHome("~/foo/bar");
+    expect(expanded).not.toContain("~");
+    expect(expanded.endsWith("/foo/bar")).toBe(true);
+  });
+
+  it("returns absolute paths verbatim", () => {
+    expect(expandHome("/abs/path")).toBe("/abs/path");
+  });
+
+  it("handles bare ~", () => {
+    const expanded = expandHome("~");
+    expect(expanded).not.toBe("~");
+  });
+});
+
+describe("probeDflashFork", () => {
+  it("returns null when the binary is absent, otherwise the absolute path", () => {
+    const result = probeDflashFork();
+    if (result === null) {
+      // Binary not present in this environment — confirm the default path
+      // was the one checked.
+      expect(existsSync(DFLASH_BINARY_PATH)).toBe(false);
+    } else {
+      expect(result).toBe(DFLASH_BINARY_PATH);
+      expect(existsSync(result)).toBe(true);
+    }
+  });
+});
+
+describe("resolveLocalBaseUrl", () => {
+  it("uses PARALLAX_OPENCODE_BASE_URL when set", () => {
+    const result = resolveLocalBaseUrl({
+      env: { PARALLAX_OPENCODE_BASE_URL: "http://example:5555/v1" },
+    });
+    expect(result.baseUrl).toBe("http://example:5555/v1");
+    expect(result.source).toBe("ollama-env");
+  });
+
+  it("falls back to localhost:11434 when no override is set", () => {
+    const result = resolveLocalBaseUrl({ env: {} });
+    expect(result.baseUrl).toBe("http://localhost:11434/v1");
+    expect(result.source).toBe("ollama-default");
+  });
+
+  it("ignores empty/whitespace override values", () => {
+    const result = resolveLocalBaseUrl({
+      env: { PARALLAX_OPENCODE_BASE_URL: "   " },
+    });
+    expect(result.source).toBe("ollama-default");
+  });
+});
+
+describe("startLocalServer", () => {
+  it("throws a helpful error when the dflash fork is not present", async () => {
+    if (probeDflashFork() !== null) {
+      // Binary IS present — skip this branch; the next test covers it.
+      return;
+    }
+    await expect(
+      startLocalServer({ bundlePath: "/nonexistent" }),
+    ).rejects.toThrow(/dflash llama-server binary not found/);
+  });
+
+  it("throws when the bundle path does not exist (binary present)", async () => {
+    if (probeDflashFork() === null) {
+      // No binary — covered above.
+      return;
+    }
+    await expect(
+      startLocalServer({ bundlePath: "/nonexistent-bundle-xyz.gguf" }),
+    ).rejects.toThrow(/dflash bundle path does not exist/);
+  });
+});