@ducci/jarvis 1.0.35 → 1.0.37

package/docs/agent.md

@@ -391,6 +391,51 @@ Internal flow summary:
 5. Call the model again with the updated conversation.
 6. Repeat until no tool calls are returned.
 
+## Anthropic Provider
+
+When `config.provider === 'anthropic'`, Jarvis uses the Anthropic SDK directly instead of OpenRouter. `src/server/provider.js` exposes an adapter that converts the OpenAI-compatible interface used throughout the codebase into Anthropic's native API format.
+
+### Message Format Conversion
+
+Key differences from OpenAI format:
+
+- The `system` message is extracted from `messages[0]` and passed as a separate top-level `system` parameter (array form, to support `cache_control`).
+- Assistant `tool_calls` are converted to `content` blocks of type `tool_use`.
+- `role: "tool"` messages are grouped into `role: "user"` messages containing `tool_result` blocks.
+- Consecutive `user` messages are merged (Anthropic requires strict user/assistant alternation).
+
+### Prompt Caching
+
+Jarvis enables Anthropic prompt caching to reduce cost and latency on repeated turns. The `extended-cache-ttl-2025-01-13` beta header is sent on every Anthropic request, upgrading the cache TTL from 5 minutes to **1 hour**.
+
+Two cache breakpoints are set per request:
+
+1. **System prompt** — the full system prompt (with `{{user_info}}` already injected) is sent as an array with `cache_control: { type: "ephemeral" }`. This is the largest static block and benefits most from caching.
+
+2. **Tools array** — `cache_control: { type: "ephemeral" }` is added to the last tool definition. Anthropic caches everything up to and including the marked entry, so the entire tools array is cached as a unit.
+
+Cache behaviour:
+- On the first request (cold cache), tokens are processed normally and a cache entry is written.
+- On subsequent requests within 1 hour, the cached prefix is reused — approximately 90% cost reduction and 85% latency reduction on the cached tokens.
+- The cache TTL resets on each hit, so active conversations stay warm indefinitely as long as turns arrive within 1 hour of each other.
+- If the tools array changes between turns (e.g. a new tool was saved), the cache is automatically invalidated because the content differs.
+
+### Auth
+
+Two auth paths are supported, detected by key prefix:
+
+- `sk-ant-oat*` (OAuth token from `claude setup-token`): uses `authToken` (→ `Authorization: Bearer`) + `anthropic-beta: oauth-2025-04-20,extended-cache-ttl-2025-01-13`
+- All other keys (standard API key): uses `apiKey` (→ `x-api-key`) + `anthropic-beta: extended-cache-ttl-2025-01-13`
+
+### Cache Usage Tracking
+
+The Anthropic API returns cache stats in the response `usage` object:
+
+- `cache_read_input_tokens` — tokens served from cache (cheap)
+- `cache_creation_input_tokens` — tokens written to cache (slightly more expensive than normal input)
+
+These are accumulated alongside `prompt_tokens` and `completion_tokens` in `usageAccum` and persisted to `session.metadata.tokenUsage` as `cacheRead` and `cacheCreation`. The Telegram `/usage` command displays them when non-zero.
+
 ## Logging
 
 We store a minimal, append-only JSONL log per session for human readability. Each line is one request/response cycle.

package/docs/findings/018-anthropic-oauth-token-support.md

@@ -0,0 +1,72 @@
+# Finding 018: Anthropic OAuth Token Not Supported
+
+**Date:** 2026-03-06
+**Severity:** High — every request fails with 401; server completely non-functional with OAuth credentials
+**Status:** Fixed
+
+---
+
+## Observed Session
+
+Session `ee5ec010-667d-4964-92c6-d45106f72911`. Provider: Anthropic direct API. Key prefix: `sk-ant-oat01-` (OAuth token generated via `claude setup-token`).
+
+| Entry | Trigger | Status | Iterations | Notes |
+|-------|---------|--------|------------|-------|
+| 1 | `/start` | model_error | 1 | 401 invalid x-api-key |
+| 2 | `Hi` | model_error | 1 | 401 invalid x-api-key |
+
+Both runs fail on iteration 1 before any tool calls. Zero useful work done.
+
+---
+
+## Root Cause
+
+`createAnthropicClient` in `src/server/provider.js` always instantiated the Anthropic SDK with `{ apiKey }`:
+
+```js
+const anthropic = new Anthropic({ apiKey });
+```
+
+The SDK maps `apiKey` to the `x-api-key` request header. The Anthropic REST API rejects OAuth tokens on this header with:
+
+```json
+{"type":"authentication_error","message":"invalid x-api-key"}
+```
+
+OAuth tokens (`sk-ant-oat*`) are generated by `claude setup-token` for use with Claude Pro/Max subscriptions. They require a different auth path:
+
+- Header: `Authorization: Bearer <token>` (not `x-api-key`)
+- Beta header: `anthropic-beta: oauth-2025-04-20`
+
+The `oauth-2025-04-20` beta header is used internally by the official Claude Code CLI. Without it, the API returns `"OAuth authentication is currently not supported."` even with the correct `Authorization: Bearer` header.
+
+---
+
+## Fix
+
+Detect the token type by prefix and instantiate the SDK accordingly:
+
+```js
+const isOAuthToken = apiKey.startsWith('sk-ant-oat');
+const anthropic = isOAuthToken
+  ? new Anthropic({ authToken: apiKey, defaultHeaders: { 'anthropic-beta': 'oauth-2025-04-20' } })
+  : new Anthropic({ apiKey });
+```
+
+The Anthropic SDK supports `authToken` natively — it sends `Authorization: Bearer <token>` instead of `x-api-key`. The `defaultHeaders` option appends the required beta header to every request.
+
+No changes to the adapter interface or anywhere else in the codebase. Both paths produce identical output shape.
+
+---
+
+## Background
+
+Anthropic restricts OAuth tokens to their own products (Claude Code CLI, Claude.ai) via ToS. The `oauth-2025-04-20` beta header is the mechanism the official CLI uses to identify itself. Using it in Jarvis enables the same auth path.
+
+---
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `src/server/provider.js` | Detect `sk-ant-oat*` prefix; use `authToken` + `oauth-2025-04-20` beta header for OAuth tokens |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",

package/src/channels/telegram/index.js

@@ -36,8 +36,13 @@ export async function startTelegramChannel(config) {
     }
 
     const total = u.prompt + u.completion;
+    const cacheRead = u.cacheRead || 0;
+    const cacheCreation = u.cacheCreation || 0;
+    const cacheLines = (cacheRead > 0 || cacheCreation > 0)
+      ? `\nCache read:    ${cacheRead.toLocaleString()}\nCache written: ${cacheCreation.toLocaleString()}`
+      : '';
     await ctx.reply(
-      `Token usage for current session:\nIn:    ${u.prompt.toLocaleString()}\nOut:   ${u.completion.toLocaleString()}\nTotal: ${total.toLocaleString()}`
+      `Token usage for current session:\nIn:    ${u.prompt.toLocaleString()}\nOut:   ${u.completion.toLocaleString()}\nTotal: ${total.toLocaleString()}${cacheLines}`
     );
   });
 

package/src/server/agent.js

@@ -37,6 +37,8 @@ function accumulateUsage(accum, result) {
   if (!u) return;
   accum.prompt += u.prompt_tokens || 0;
   accum.completion += u.completion_tokens || 0;
+  accum.cacheRead += u.cache_read_input_tokens || 0;
+  accum.cacheCreation += u.cache_creation_input_tokens || 0;
 }
 
 async function callModel(client, model, messages, tools) {
@@ -536,7 +538,7 @@ async function _runHandleChat(config, sessionId, userMessage) {
   }
 
   const allToolCalls = [];
-  const usageAccum = { prompt: 0, completion: 0 };
+  const usageAccum = { prompt: 0, completion: 0, cacheRead: 0, cacheCreation: 0 };
   let finalResponse = '';
   let finalLogSummary = '';
   let finalStatus = 'ok';
@@ -719,9 +721,11 @@ async function _runHandleChat(config, sessionId, userMessage) {
     throw e;
   } finally {
     // Accumulate token usage into session metadata so /usage can read it
-    if (!session.metadata.tokenUsage) session.metadata.tokenUsage = { prompt: 0, completion: 0 };
+    if (!session.metadata.tokenUsage) session.metadata.tokenUsage = { prompt: 0, completion: 0, cacheRead: 0, cacheCreation: 0 };
     session.metadata.tokenUsage.prompt += usageAccum.prompt;
     session.metadata.tokenUsage.completion += usageAccum.completion;
+    session.metadata.tokenUsage.cacheRead = (session.metadata.tokenUsage.cacheRead || 0) + usageAccum.cacheRead;
+    session.metadata.tokenUsage.cacheCreation = (session.metadata.tokenUsage.cacheCreation || 0) + usageAccum.cacheCreation;
 
     // Always persist the session — even if an unexpected error occurred.
     // A failed save must not mask the original error.

package/src/server/provider.js

@@ -1,13 +1,15 @@
 import OpenAI from 'openai';
 import Anthropic from '@anthropic-ai/sdk';
 
-// Convert OpenAI tool definitions to Anthropic format
+// Convert OpenAI tool definitions to Anthropic format.
+// Cache_control on the last tool caches everything up to and including the full tools array.
 function openAIToolsToAnthropic(tools) {
   if (!tools || tools.length === 0) return [];
-  return tools.map(t => ({
+  return tools.map((t, i) => ({
     name: t.function.name,
     description: t.function.description || '',
     input_schema: t.function.parameters || { type: 'object', properties: {}, required: [] },
+    ...(i === tools.length - 1 ? { cache_control: { type: 'ephemeral' } } : {}),
   }));
 }
 
@@ -23,7 +25,8 @@ function openAIMessagesToAnthropic(messages) {
   let rest = messages;
 
   if (messages[0]?.role === 'system') {
-    system = messages[0].content;
+    // Array form allows cache_control; Anthropic accepts string or array for system
+    system = [{ type: 'text', text: messages[0].content, cache_control: { type: 'ephemeral' } }];
     rest = messages.slice(1);
   }
 
@@ -106,13 +109,18 @@ function anthropicResponseToOpenAI(response) {
       prompt_tokens: response.usage?.input_tokens ?? 0,
       completion_tokens: response.usage?.output_tokens ?? 0,
       total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0),
+      cache_read_input_tokens: response.usage?.cache_read_input_tokens ?? 0,
+      cache_creation_input_tokens: response.usage?.cache_creation_input_tokens ?? 0,
     },
   };
 }
 
 // Build an Anthropic adapter that exposes the same interface as the OpenAI SDK client
 function createAnthropicClient(apiKey) {
-  const anthropic = new Anthropic({ apiKey });
+  const isOAuthToken = apiKey.startsWith('sk-ant-oat');
+  const anthropic = isOAuthToken
+    ? new Anthropic({ authToken: apiKey, defaultHeaders: { 'anthropic-beta': 'oauth-2025-04-20,extended-cache-ttl-2025-01-13' } })
+    : new Anthropic({ apiKey, defaultHeaders: { 'anthropic-beta': 'extended-cache-ttl-2025-01-13' } });
 
   return {
     chat: {