@omega.js/backend 0.1.0

package/dist/manager/libraries/ai/providers/anthropic-format.js

@@ -0,0 +1,297 @@
+/**
+ * Shared pure formatting helpers for the two Claude providers (anthropic,
+ * claude-code). Both hit the same Claude Messages API — only auth differs — so
+ * the option-shape → request-body mapping lives here once.
+ *
+ * Handles the unified cross-provider message conventions:
+ *   - { role: 'system'|'developer'|'user'|'assistant', content: string }
+ *   - { role: 'assistant', content?, toolCalls: [{ id, name, arguments }] }
+ *     → ctx turn with tool_use blocks
+ *   - { role: 'tool', toolCallId, content } → tool_result block; consecutive
+ *     tool turns merge into ONE user turn (the Messages API requires all
+ *     results for an ctx turn in a single following user message)
+ *   - raw Anthropic block arrays (content: [{ type, ... }]) pass through untouched
+ *
+ * All functions are pure — no network, no SDK — so they're unit-testable
+ * without an ctx.
+ */
+const { normalizePrompt, loadContent } = require('../prompt.js');
+
+// loadContent logs each prompt-file read through the caller's logger; the
+// formatters are pure and carry none
+function noopLog() {}
+
+/**
+ * Map normalized function-tool definitions to Anthropic tool definitions.
+ *
+ * Accepts entries shaped { name, description, parameters } (optionally with
+ * type: 'function'). Provider-specific hosted tools (any other `type`, e.g.
+ * OpenAI's { type: 'web_search' }) have no Anthropic equivalent — throw with a
+ * clear message instead of silently dropping them.
+ *
+ * @param {Array} list - options.tools.list
+ * @returns {Array<{name, description, input_schema}>}
+ */
+function buildToolDefs(list) {
+  if (!Array.isArray(list) || !list.length) {
+    return [];
+  }
+
+  return list.map((tool) => {
+    if (!tool || !tool.name || (tool.type && tool.type !== 'function')) {
+      throw new Error(`Anthropic tools must be function tools ({ name, description, parameters }) — got ${JSON.stringify(tool && (tool.type || tool.name) || tool)}`);
+    }
+
+    return {
+      name: tool.name,
+      description: tool.description || '',
+      input_schema: tool.parameters || { type: 'object', properties: {} },
+    };
+  });
+}
+
+/**
+ * Map the unified tools.choice value to Anthropic's tool_choice.
+ *
+ * 'auto' → { type: 'auto' }, 'required' → { type: 'any' },
+ * 'none' → { type: 'none' }, { name } → { type: 'tool', name }
+ */
+function buildToolChoice(choice) {
+  if (!choice) {
+    return undefined;
+  }
+
+  if (choice === 'auto') {
+    return { type: 'auto' };
+  }
+
+  if (choice === 'required') {
+    return { type: 'any' };
+  }
+
+  if (choice === 'none') {
+    return { type: 'none' };
+  }
+
+  if (typeof choice === 'object' && choice.name) {
+    return { type: 'tool', name: choice.name };
+  }
+
+  return undefined;
+}
+
+/**
+ * Build Anthropic { system, messages } from the unified option shape.
+ *
+ * Accepts either:
+ *   - options.messages: unified turns (see module header)
+ *   - options.prompt (object OR multi-role array form) + options.message.content
+ */
+function buildMessages(options) {
+  if (!Array.isArray(options.messages) || !options.messages.length) {
+    return buildFromPrompt(options);
+  }
+
+  // System: collect system + developer turns (Anthropic has no developer role —
+  // fold it into the system prompt, preserving order)
+  const system = options.messages
+    .filter((m) => m.role === 'system' || m.role === 'developer')
+    .map((m) => stringifyContent(m.content))
+    .filter(Boolean)
+    .join('\n\n');
+
+  const messages = [];
+
+  for (const m of options.messages) {
+    if (m.role === 'system' || m.role === 'developer') {
+      continue;
+    }
+
+    // Tool result turn → tool_result block; merge into the previous user turn
+    // if that turn is already a tool-result carrier (consecutive results)
+    if (m.role === 'tool') {
+      const block = {
+        type: 'tool_result',
+        tool_use_id: m.toolCallId,
+        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content || ''),
+      };
+
+      const last = messages[messages.length - 1];
+
+      if (last && last.role === 'user' && Array.isArray(last.content) && last.content.every((c) => c.type === 'tool_result')) {
+        last.content.push(block);
+      } else {
+        messages.push({ role: 'user', content: [block] });
+      }
+
+      continue;
+    }
+
+    // Raw Anthropic block arrays pass through untouched (callers may replay
+    // raw.content from a prior response verbatim)
+    if (Array.isArray(m.content) && m.content.some((c) => c && typeof c === 'object' && c.type)) {
+      messages.push({ role: m.role, content: m.content });
+      continue;
+    }
+
+    // Assistant turn with tool calls → text block (if any) + tool_use blocks
+    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
+      const content = [];
+      const text = stringifyContent(m.content || '');
+
+      if (text) {
+        content.push({ type: 'text', text });
+      }
+
+      for (const call of m.toolCalls) {
+        content.push({
+          type: 'tool_use',
+          id: call.id,
+          name: call.name,
+          input: parseArguments(call.arguments),
+        });
+      }
+
+      messages.push({ role: 'assistant', content });
+      continue;
+    }
+
+    // Plain text turn
+    messages.push({ role: m.role, content: stringifyContent(m.content) });
+  }
+
+  return { system, messages };
+}
+
+/**
+ * Build { system, messages } from the prompt/message form.
+ *
+ * The prompt resolves through the SAME segment loader the OpenAI provider uses,
+ * so both forms behave identically here: a prompt-file `path` is read and
+ * templated, the array form keeps every segment, and the object form is the
+ * single implicit 'system' segment. system + developer segments become the
+ * system prompt (Anthropic has no developer role); user + assistant segments
+ * become turns ahead of the user message.
+ */
+function buildFromPrompt(options) {
+  const segments = normalizePrompt(options.prompt).map((segment) => {
+    // Content blocks flatten before loading — loadContent templates strings
+    const input = segment.path ? segment : { ...segment, content: stringifyContent(segment.content) };
+    const content = loadContent(input, noopLog);
+
+    if (content instanceof Error) {
+      throw new Error(`Error loading prompt[${segment.role}]: ${content.message}`);
+    }
+
+    return { role: segment.role, content: content };
+  });
+
+  const system = segments
+    .filter((s) => s.role === 'system' || s.role === 'developer')
+    .map((s) => s.content)
+    .filter(Boolean)
+    .join('\n\n');
+
+  const messages = [];
+
+  for (const segment of segments) {
+    if (segment.role === 'user' || segment.role === 'assistant') {
+      pushTextTurn(messages, segment.role, segment.content);
+    }
+  }
+
+  const message = stringifyContent(options.message?.content || '');
+
+  // An empty message still gets its turn when nothing else carries the
+  // conversation — the Messages API requires at least one
+  if (message || !messages.length) {
+    pushTextTurn(messages, 'user', message);
+  }
+
+  return { system, messages };
+}
+
+// The Messages API rejects consecutive same-role turns, so text destined for
+// one that is already open joins it instead of opening a second
+function pushTextTurn(messages, role, content) {
+  const last = messages[messages.length - 1];
+
+  if (last && last.role === role && typeof last.content === 'string') {
+    last.content = [last.content, content].filter(Boolean).join('\n\n');
+    return;
+  }
+
+  messages.push({ role: role, content: content });
+}
+
+/**
+ * Extract normalized tool calls from a response's content blocks.
+ *
+ * @param {Array} content - raw.content from the Messages API
+ * @returns {Array<{id, name, arguments}>} arguments is the parsed input object
+ */
+function extractToolCalls(content) {
+  return (content || [])
+    .filter((c) => c.type === 'tool_use')
+    .map((c) => ({ id: c.id, name: c.name, arguments: c.input || {} }));
+}
+
+/**
+ * Map Anthropic stop_reason to the normalized stopReason.
+ */
+function mapStopReason(stopReason) {
+  if (stopReason === 'tool_use') {
+    return 'tool_use';
+  }
+
+  if (stopReason === 'max_tokens') {
+    return 'max_tokens';
+  }
+
+  return 'end';
+}
+
+function parseArguments(args) {
+  if (args && typeof args === 'object') {
+    return args;
+  }
+
+  if (typeof args === 'string' && args.trim()) {
+    try {
+      return JSON.parse(args);
+    } catch (e) {
+      return {};
+    }
+  }
+
+  return {};
+}
+
+function stringifyContent(content) {
+  if (!content) {
+    return '';
+  }
+
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  // OpenAI sometimes uses [{ type: 'input_text', text: '...' }] — flatten to string
+  if (Array.isArray(content)) {
+    return content
+      .filter((c) => c.type === 'input_text' || c.type === 'text')
+      .map((c) => c.text || '')
+      .join('\n');
+  }
+
+  return String(content);
+}
+
+module.exports = {
+  buildToolDefs,
+  buildToolChoice,
+  buildMessages,
+  extractToolCalls,
+  mapStopReason,
+  stringifyContent,
+};

package/dist/manager/libraries/ai/providers/anthropic.js

@@ -0,0 +1,169 @@
+/**
+ * Anthropic provider for the unified AI library.
+ *
+ * Public surface matches the OpenAI provider:
+ *   new Anthropic(ctx, key).request(options) → { content, output, tokens, raw }
+ *
+ * Maps the Claude Messages API onto the OpenAI provider's option shape so callers
+ * can swap providers without rewriting call sites.
+ */
+const _ = require('lodash');
+const JSON5 = require('json5');
+const format = require('./anthropic-format.js');
+const { emptyTokens, buildTokens, addTokens } = require('../tokens.js');
+const env = require('../../env.js');
+
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+// Pricing per 1M tokens (USD). Update when Anthropic changes their pricing page.
+const MODEL_TABLE = {
+  'claude-opus-4-7':   { input: 15.00, output: 75.00, features: { json: true, temperature: true, reasoning: true } },
+  'claude-opus-4-6':   { input: 15.00, output: 75.00, features: { json: true, temperature: true, reasoning: true } },
+  'claude-sonnet-4-6': { input: 3.00,  output: 15.00, features: { json: true, temperature: true, reasoning: true } },
+  'claude-haiku-4-5':  { input: 1.00,  output: 5.00,  features: { json: true, temperature: true, reasoning: false } },
+};
+
+function Anthropic(ctx, key) {
+  const self = this;
+
+  self.ctx = ctx;
+  self.Manager = ctx?.Manager;
+  self.user = ctx?.user;
+  self.key = key
+    || self.Manager?.config?.anthropic?.key
+    || env.get('ANTHROPIC_API_KEY');
+
+  // Running counter across every call this provider instance makes. Each call
+  // reports its OWN usage — this is the instance total.
+  self.tokens = emptyTokens();
+
+  return self;
+}
+
+Anthropic.prototype.request = async function (options) {
+  const self = this;
+  const ctx = self.ctx;
+
+  options = _.merge({}, options);
+  options.model = options.model || DEFAULT_MODEL;
+  options.maxTokens = options.maxTokens || 2048;
+  options.temperature = typeof options.temperature === 'undefined' ? 0.7 : options.temperature;
+  options.timeout = options.timeout || 120000;
+
+  if (!self.key) {
+    throw new Error('Anthropic API key not configured (set ANTHROPIC_API_KEY)');
+  }
+
+  // Lazy-require the SDK so projects that don't use Anthropic don't need it installed
+  const SDK = require('@anthropic-ai/sdk');
+  const client = new SDK({ apiKey: self.key });
+
+  // Build messages from the OpenAI-style option shape (prompt + message) or
+  // unified messages turns (incl. ctx toolCalls + role:'tool' results)
+  const { system, messages } = format.buildMessages(options);
+
+  // JSON output via system prompt instruction (Anthropic's structured output is via prompt, not a flag)
+  let systemFinal = system;
+
+  if (options.response === 'json') {
+    systemFinal = `${systemFinal || ''}\n\nYou MUST respond with valid JSON only. No prose, no markdown fences, no explanation — just the JSON object.${options.schema ? `\n\nThe JSON must conform to this schema:\n${JSON.stringify(options.schema)}` : ''}`.trim();
+  }
+
+  const requestBody = {
+    model: options.model,
+    max_tokens: options.maxTokens,
+    messages,
+  };
+
+  if (systemFinal) {
+    requestBody.system = systemFinal;
+  }
+
+  if (options.temperature !== undefined) {
+    requestBody.temperature = options.temperature;
+  }
+
+  // Native tool calling — normalized function tools only ({ name, description,
+  // parameters }); provider-specific hosted tools throw in buildToolDefs
+  const toolDefs = format.buildToolDefs(options.tools?.list);
+
+  if (toolDefs.length) {
+    requestBody.tools = toolDefs;
+
+    const toolChoice = format.buildToolChoice(options.tools?.choice);
+
+    if (toolChoice) {
+      requestBody.tool_choice = toolChoice;
+    }
+  }
+
+  let raw;
+
+  try {
+    raw = await client.messages.create(requestBody);
+  } catch (e) {
+    ctx?.error?.(`Anthropic request failed: ${e.message}`, e);
+    throw e;
+  }
+
+  // Extract text from content blocks (concatenate text blocks) and tool calls
+  // from tool_use blocks — a tool-call turn legitimately has content: ''
+  const outputText = (raw.content || [])
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text.trim())
+    .join('\n')
+    .trim();
+
+  const toolCalls = format.extractToolCalls(raw.content);
+  const stopReason = format.mapStopReason(raw.stop_reason);
+
+  // Usage for THIS response, then rolled into the instance counter — the caller
+  // gets its own usage, never a running total
+  const modelConfig = MODEL_TABLE[options.model] || MODEL_TABLE[DEFAULT_MODEL];
+
+  const tokens = buildTokens(raw.usage?.input_tokens, raw.usage?.output_tokens, modelConfig);
+
+  addTokens(self.tokens, tokens);
+
+  // Parse JSON if requested — but never on a tool-call turn, where empty/partial
+  // text is the normal intermediate state (the caller continues the loop)
+  let parsed = outputText;
+
+  if (options.response === 'json' && !toolCalls.length) {
+    parsed = parseJsonLoose(outputText);
+  }
+
+  return {
+    output: raw.content || [],
+    content: parsed,
+    tokens: tokens,
+    raw,
+    toolCalls,
+    stopReason,
+  };
+};
+
+/**
+ * Parse JSON from Claude output. Claude usually obeys the "JSON only" instruction
+ * but occasionally wraps responses in ```json fences or adds a sentence before.
+ * Strip fences and try JSON5 for robustness.
+ */
+function parseJsonLoose(text) {
+  let cleaned = text.trim();
+
+  // Strip ```json ... ``` fences
+  cleaned = cleaned.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+
+  // Find first { or [ and last } or ] to handle preamble text
+  const firstBrace = Math.min(
+    ...[cleaned.indexOf('{'), cleaned.indexOf('[')].filter((i) => i >= 0),
+  );
+
+  if (firstBrace > 0) {
+    cleaned = cleaned.slice(firstBrace);
+  }
+
+  return JSON5.parse(cleaned);
+}
+
+module.exports = Anthropic;

package/dist/manager/libraries/ai/providers/claude-code.js

@@ -0,0 +1,183 @@
+/**
+ * Claude Code provider — calls Claude over plain HTTPS using a Claude Code /
+ * Claude Pro/Max OAuth token (NOT API credits).
+ *
+ * Unlike the Anthropic provider (which authenticates with an x-api-key and bills
+ * API credits), this provider sends the OAuth token as `Authorization: Bearer ...`
+ * plus the `anthropic-beta: oauth-2025-04-20` header, so usage bills against the
+ * Claude subscription tied to the token.
+ *
+ * Token resolution (first match wins):
+ *   1. explicit key passed to the constructor / options.apiKey
+ *   2. Manager config: config.claude_code.oauth_token
+ *   3. env.get('CLAUDE_CODE_OAUTH_TOKEN')  (from `claude setup-token`)
+ *
+ * This is pure HTTPS — no `claude` binary, no subprocess — so it runs in Cloud
+ * Functions / CI / anywhere Node runs. It is subject to the token's subscription
+ * rate limits (not API-tier limits).
+ *
+ * The OAuth token is minted with `claude setup-token` (valid ~1 year). When it
+ * expires (requests 401), re-mint and update the CLAUDE_CODE_OAUTH_TOKEN secret.
+ * NOTE: the Bearer/beta subscription path is undocumented and may change.
+ *
+ * Returns the same { content, output, tokens, raw } shape as the other providers.
+ */
+const _ = require('lodash');
+const JSON5 = require('json5');
+const format = require('./anthropic-format.js');
+const { emptyTokens, buildTokens, addTokens } = require('../tokens.js');
+const env = require('../../env.js');
+
+const DEFAULT_MODEL = 'claude-opus-4-7';
+const OAUTH_BETA = 'oauth-2025-04-20';
+
+// Pricing per 1M tokens (USD) — informational only; subscription billing is flat.
+const MODEL_TABLE = {
+  'claude-opus-4-7':   { input: 15.00, output: 75.00 },
+  'claude-opus-4-6':   { input: 15.00, output: 75.00 },
+  'claude-sonnet-4-6': { input: 3.00,  output: 15.00 },
+  'claude-haiku-4-5':  { input: 1.00,  output: 5.00  },
+};
+
+function ClaudeCode(ctx, key) {
+  const self = this;
+
+  self.ctx = ctx;
+  self.Manager = ctx?.Manager;
+  self.user = ctx?.user;
+  self.token = key
+    || self.Manager?.config?.claude_code?.oauth_token
+    || env.get('CLAUDE_CODE_OAUTH_TOKEN');
+
+  // Running counter across every call this provider instance makes. Each call
+  // reports its OWN usage — this is the instance total.
+  self.tokens = emptyTokens();
+
+  return self;
+}
+
+ClaudeCode.prototype.request = async function (options) {
+  const self = this;
+  const ctx = self.ctx;
+
+  options = _.merge({}, options);
+  options.model = options.model || DEFAULT_MODEL;
+  options.maxTokens = options.maxTokens || 2048;
+  options.temperature = typeof options.temperature === 'undefined' ? 0.7 : options.temperature;
+
+  const token = options.apiKey || self.token;
+
+  if (!token) {
+    throw new Error('claude-code provider requires a Claude OAuth token (set CLAUDE_CODE_OAUTH_TOKEN via `claude setup-token`)');
+  }
+
+  // Lazy-require the SDK so projects that don't use this provider don't need it.
+  // We use the SDK purely as an HTTP client — `authToken` makes it send
+  // `Authorization: Bearer <token>` instead of `x-api-key`, and the beta header
+  // selects the subscription (OAuth) billing path. No `claude` binary involved.
+  const SDK = require('@anthropic-ai/sdk');
+  const client = new SDK({
+    authToken: token,
+    defaultHeaders: { 'anthropic-beta': OAUTH_BETA },
+  });
+
+  const { system, messages } = format.buildMessages(options);
+
+  let systemFinal = system;
+
+  if (options.response === 'json') {
+    systemFinal = `${systemFinal || ''}\n\nYou MUST respond with valid JSON only. No prose, no markdown fences, no explanation — just the JSON object.${options.schema ? `\n\nThe JSON must conform to this schema:\n${JSON.stringify(options.schema)}` : ''}`.trim();
+  }
+
+  const requestBody = {
+    model: options.model,
+    max_tokens: options.maxTokens,
+    messages,
+  };
+
+  if (systemFinal) {
+    requestBody.system = systemFinal;
+  }
+
+  if (options.temperature !== undefined) {
+    requestBody.temperature = options.temperature;
+  }
+
+  // Native tool calling — same normalized interface as the anthropic provider
+  const toolDefs = format.buildToolDefs(options.tools?.list);
+
+  if (toolDefs.length) {
+    requestBody.tools = toolDefs;
+
+    const toolChoice = format.buildToolChoice(options.tools?.choice);
+
+    if (toolChoice) {
+      requestBody.tool_choice = toolChoice;
+    }
+  }
+
+  let raw;
+
+  try {
+    raw = await client.messages.create(requestBody);
+  } catch (e) {
+    ctx?.error?.(`claude-code request failed: ${e.message}`, e);
+    throw e;
+  }
+
+  const outputText = (raw.content || [])
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text.trim())
+    .join('\n')
+    .trim();
+
+  const toolCalls = format.extractToolCalls(raw.content);
+  const stopReason = format.mapStopReason(raw.stop_reason);
+
+  const modelConfig = MODEL_TABLE[options.model] || MODEL_TABLE[DEFAULT_MODEL];
+
+  // Usage for THIS response, then rolled into the instance counter — the caller
+  // gets its own usage, never a running total
+  const tokens = buildTokens(raw.usage?.input_tokens, raw.usage?.output_tokens, modelConfig);
+
+  addTokens(self.tokens, tokens);
+
+  let parsed = outputText;
+
+  if (options.response === 'json' && !toolCalls.length) {
+    parsed = parseJsonLoose(outputText);
+  }
+
+  return {
+    output: raw.content || [],
+    content: parsed,
+    tokens: tokens,
+    raw,
+    toolCalls,
+    stopReason,
+  };
+};
+
+function parseJsonLoose(text) {
+  let cleaned = (text || '').trim();
+
+  cleaned = cleaned.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+
+  const candidates = [cleaned.indexOf('{'), cleaned.indexOf('[')].filter((i) => i >= 0);
+
+  if (candidates.length) {
+    const firstBrace = Math.min(...candidates);
+
+    if (firstBrace > 0) {
+      cleaned = cleaned.slice(firstBrace);
+    }
+  }
+
+  try {
+    return JSON5.parse(cleaned);
+  } catch {
+    return text;
+  }
+}
+
+module.exports = ClaudeCode;