@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/providers/contract.js

@@ -0,0 +1,153 @@
+"use strict";
+
+const CAPABILITY_KEYS = Object.freeze([
+  "resume",
+  "readOnlyMode",
+  "effort",
+  "budget",
+  "worktree",
+  "partialStreaming",
+  "maxTurns",
+  "imageFlag",
+  "persistentUtilityStream",
+  "preToolHook",
+]);
+
+const REQUIRED_METHODS = Object.freeze([
+  "isAvailable",
+  "executable",
+  "defaultModel",
+  "tierModel",
+  "modelChoices",
+  "compatibilityStatus",
+  "buildMainInvocation",
+  "buildUtilityInvocation",
+  "createEventDecoder",
+  "normalizeEvent",
+  "authStatus",
+  "authHelp",
+]);
+
+const CAPABILITY_SUPPORT = new Set(["native", "emulated", "unsupported"]);
+const COMPATIBILITY_STATES = new Set(["compatible", "incompatible", "unknown", "not_checked"]);
+const AUTH_STATES = new Set(["authenticated", "unauthenticated", "unknown", "not_checked"]);
+
+class ProviderContractError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ProviderContractError";
+    this.code = "INVALID_PROVIDER_CONTRACT";
+    this.details = details;
+  }
+}
+
+function own(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function validateCapabilities(capabilities, providerId = "provider") {
+  if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) {
+    throw new ProviderContractError(`${providerId}.capabilities must be an object`);
+  }
+  for (const key of CAPABILITY_KEYS) {
+    const capability = capabilities[key];
+    if (!capability || typeof capability !== "object" || Array.isArray(capability)) {
+      throw new ProviderContractError(`${providerId}.capabilities.${key} is required`);
+    }
+    if (!CAPABILITY_SUPPORT.has(capability.support)) {
+      throw new ProviderContractError(`${providerId}.capabilities.${key}.support must be native, emulated, or unsupported`);
+    }
+    if (!own(capability, "reason") || (capability.reason !== null && typeof capability.reason !== "string")) {
+      throw new ProviderContractError(`${providerId}.capabilities.${key}.reason must be an explicit string or null`);
+    }
+    if (capability.support !== "native" && !String(capability.reason || "").trim()) {
+      throw new ProviderContractError(`${providerId}.capabilities.${key}.reason must explain ${capability.support} support`);
+    }
+    if (key === "effort" && !Array.isArray(capability.values)) {
+      throw new ProviderContractError(`${providerId}.capabilities.effort.values must be an array`);
+    }
+  }
+  return capabilities;
+}
+
+function validateProvider(provider) {
+  if (!provider || typeof provider !== "object" || Array.isArray(provider)) {
+    throw new ProviderContractError("provider must be an object");
+  }
+  if (typeof provider.id !== "string" || !provider.id.trim()) {
+    throw new ProviderContractError("provider.id must be a non-empty string");
+  }
+  if (typeof provider.label !== "string" || !provider.label.trim()) {
+    throw new ProviderContractError(`${provider.id}.label must be a non-empty string`);
+  }
+  for (const method of REQUIRED_METHODS) {
+    if (typeof provider[method] !== "function") {
+      throw new ProviderContractError(`${provider.id}.${method}() is required`);
+    }
+  }
+  validateCapabilities(provider.capabilities, provider.id);
+  return provider;
+}
+
+function validateInvocation(invocation) {
+  if (!invocation || typeof invocation !== "object" || Array.isArray(invocation)) {
+    throw new ProviderContractError("provider invocation must be an object");
+  }
+  if (typeof invocation.binary !== "string" || !invocation.binary) {
+    throw new ProviderContractError("provider invocation binary must be a non-empty string");
+  }
+  if (!Array.isArray(invocation.args) || invocation.args.some((arg) => typeof arg !== "string")) {
+    throw new ProviderContractError("provider invocation args must be an array of strings");
+  }
+  if (!invocation.env || typeof invocation.env !== "object" || Array.isArray(invocation.env)) {
+    throw new ProviderContractError("provider invocation env must be an object");
+  }
+  if (Object.entries(invocation.env).some(([key, value]) => !key || typeof value !== "string")) {
+    throw new ProviderContractError("provider invocation env keys and values must be strings");
+  }
+  for (const key of ["stdin", "parserState"]) {
+    if (!own(invocation, key)) {
+      throw new ProviderContractError(`provider invocation ${key} is required`);
+    }
+  }
+  if (invocation.stdin !== null && typeof invocation.stdin !== "string" && !Buffer.isBuffer(invocation.stdin)) {
+    throw new ProviderContractError("provider invocation stdin must be null, a string, or a Buffer");
+  }
+  if (!invocation.parserState || typeof invocation.parserState !== "object" || Array.isArray(invocation.parserState)) {
+    throw new ProviderContractError("provider invocation parserState must be an object");
+  }
+  if (own(invocation, "warnings")) {
+    if (!Array.isArray(invocation.warnings) || invocation.warnings.some((warning) => (
+      !warning || typeof warning !== "object" || Array.isArray(warning)
+      || typeof warning.code !== "string" || !warning.code.trim()
+      || typeof warning.message !== "string" || !warning.message.trim()
+    ))) {
+      throw new ProviderContractError("provider invocation warnings must contain code/message objects");
+    }
+  }
+  return invocation;
+}
+
+function validateTypedStatus(value, kind) {
+  const states = kind === "compatibility" ? COMPATIBILITY_STATES : AUTH_STATES;
+  if (!value || typeof value !== "object" || Array.isArray(value) || !states.has(value.state)) {
+    throw new ProviderContractError(`${kind} status must contain a typed state`);
+  }
+  if (own(value, "reason") && value.reason !== null && typeof value.reason !== "string") {
+    throw new ProviderContractError(`${kind} status reason must be a string or null`);
+  }
+  return value;
+}
+
+module.exports = {
+  AUTH_STATES,
+  CAPABILITY_KEYS,
+  CAPABILITY_SUPPORT,
+  COMPATIBILITY_STATES,
+  ProviderContractError,
+  REQUIRED_METHODS,
+  validateCapabilities,
+  validateInvocation,
+  validateProvider,
+  validateTypedStatus,
+};

package/core/providers/env.js

@@ -0,0 +1,148 @@
+"use strict";
+
+// Security boundary: these builders isolate inherited environment variables
+// between native provider children. They do not sandbox the process. A native
+// same-UID child can still read files its OS user can read, including provider
+// auth stores. This is environment isolation, not filesystem isolation or a
+// containment claim.
+const NATIVE_ISOLATION_NOTICE = "Native provider execution uses environment isolation only; it is not filesystem isolation, and same-UID processes retain the operating system user's file access.";
+
+const STANDARD_PROCESS_ENV_KEYS = Object.freeze([
+  "PATH",
+  "HOME",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "LANG",
+  "LANGUAGE",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TERM",
+  "COLORTERM",
+  "NO_COLOR",
+  "FORCE_COLOR",
+  // The hook subprocess is another Open Claudia entry point. Keep its state
+  // rooted with the parent without exposing either provider's auth store.
+  "OPEN_CLAUDIA_CONFIG_DIR",
+  "SystemRoot",
+  "ComSpec",
+  "PATHEXT",
+  "WINDIR",
+]);
+
+const PROVIDER_CREDENTIAL_KEYS = Object.freeze([
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "CURSOR_API_KEY",
+]);
+
+const PROVIDER_CONFIG_ROOT_KEYS = Object.freeze([
+  "CLAUDE_CONFIG_DIR",
+  "CODEX_HOME",
+]);
+
+const CONTROL_PLANE_KEYS = Object.freeze([
+  "TELEGRAM_BOT_TOKEN",
+  "KAZEE_BOT_TOKEN",
+  "BOT_CONTROL_TOKEN",
+  "OC_SEND_TOKEN",
+  "VOICE_BRIDGE_TOKEN",
+  "ELEVENLABS_API_KEY",
+  "AGENTSPACE_POD_TOKEN",
+  "WEB_PASSWORD",
+  "OPEN_CLAUDIA_KEYRING_CANARY",
+]);
+
+const ALWAYS_STRIPPED_KEYS = new Set([
+  ...PROVIDER_CREDENTIAL_KEYS,
+  ...PROVIDER_CONFIG_ROOT_KEYS,
+  ...CONTROL_PLANE_KEYS,
+]);
+
+function copyEnvValue(target, source, key) {
+  const value = source[key];
+  if (value === undefined || value === null) return;
+  target[key] = String(value);
+}
+
+function pickStandardProcessEnv(source = process.env) {
+  const env = {};
+  for (const key of STANDARD_PROCESS_ENV_KEYS) copyEnvValue(env, source, key);
+  return env;
+}
+
+function passthroughKeys(source = process.env, configured = source.AGENT_ENV_PASSTHROUGH) {
+  const keys = String(configured || "")
+    .split(",")
+    .map((key) => key.trim())
+    .filter(Boolean);
+  for (const key of keys) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || ["__proto__", "prototype", "constructor"].includes(key)) {
+      const error = new Error(`Invalid AGENT_ENV_PASSTHROUGH key: ${key}`);
+      error.code = "INVALID_ENV_PASSTHROUGH";
+      throw error;
+    }
+  }
+  return [...new Set(keys)];
+}
+
+function addConfiguredPassthrough(target, source = process.env, configured = source.AGENT_ENV_PASSTHROUGH) {
+  for (const key of passthroughKeys(source, configured)) copyEnvValue(target, source, key);
+  return target;
+}
+
+function baseAgentEnv(source = process.env, options = {}) {
+  const env = pickStandardProcessEnv(source);
+  addConfiguredPassthrough(env, source, options.passthrough);
+  // Strip after passthrough so a broad/operator-supplied list cannot re-open a
+  // provider credential, control-plane token, or keyring canary boundary.
+  for (const key of ALWAYS_STRIPPED_KEYS) delete env[key];
+  return env;
+}
+
+function providerValue(source, overrides, key) {
+  if (Object.prototype.hasOwnProperty.call(overrides, key)) return overrides[key];
+  return source[key];
+}
+
+function copyProviderValue(env, source, overrides, key) {
+  const value = providerValue(source, overrides, key);
+  if (value === undefined || value === null || String(value) === "") return;
+  env[key] = String(value);
+}
+
+function claudeAgentEnv(source = process.env, overrides = {}) {
+  const env = baseAgentEnv(source, overrides);
+  for (const key of ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "CLAUDE_CONFIG_DIR"]) {
+    copyProviderValue(env, source, overrides, key);
+  }
+  return env;
+}
+
+function codexAgentEnv(source = process.env, overrides = {}) {
+  const env = baseAgentEnv(source, overrides);
+  for (const key of ["OPENAI_API_KEY", "CODEX_HOME"]) {
+    copyProviderValue(env, source, overrides, key);
+  }
+  return env;
+}
+
+module.exports = {
+  ALWAYS_STRIPPED_KEYS,
+  CONTROL_PLANE_KEYS,
+  NATIVE_ISOLATION_NOTICE,
+  PROVIDER_CONFIG_ROOT_KEYS,
+  PROVIDER_CREDENTIAL_KEYS,
+  STANDARD_PROCESS_ENV_KEYS,
+  addConfiguredPassthrough,
+  baseAgentEnv,
+  claudeAgentEnv,
+  codexAgentEnv,
+  passthroughKeys,
+  pickStandardProcessEnv,
+};

package/core/providers/events.js

@@ -0,0 +1,170 @@
+"use strict";
+
+const NORMALIZED_EVENT_TYPES = Object.freeze([
+  "session",
+  "text_delta",
+  "text_final",
+  "tool_start",
+  "tool_end",
+  "usage",
+  "result",
+  "error",
+]);
+
+const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
+
+function decoderError(code, message, details = {}) {
+  return { type: "decoder.error", code, message, ...details };
+}
+
+function parseCompleteLine(line) {
+  let end = line.length;
+  if (end > 0 && line[end - 1] === 0x0d) end -= 1;
+  const text = line.subarray(0, end).toString("utf8").trim();
+  if (!text) return [];
+  try {
+    return [JSON.parse(text)];
+  } catch (error) {
+    // Do not include the source line or parser detail: provider output can
+    // contain prompts, tool results, paths, or credentials.
+    return [decoderError("MALFORMED_JSON", "Malformed provider JSONL record")];
+  }
+}
+
+function createJsonlDecoder(options = {}) {
+  const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+  if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1) {
+    throw new TypeError("maxLineBytes must be a positive safe integer");
+  }
+
+  let tail = Buffer.alloc(0);
+  let discarding = false;
+  let closed = false;
+
+  const api = {
+    push(input) {
+      if (closed) {
+        const error = new Error("provider JSONL decoder is closed");
+        error.code = "DECODER_CLOSED";
+        throw error;
+      }
+      if (input === undefined || input === null) return [];
+      const chunk = Buffer.isBuffer(input)
+        ? input
+        : (input instanceof Uint8Array ? Buffer.from(input.buffer, input.byteOffset, input.byteLength) : Buffer.from(String(input), "utf8"));
+      const events = [];
+      let offset = 0;
+
+      while (offset < chunk.length) {
+        if (discarding) {
+          const newline = chunk.indexOf(0x0a, offset);
+          if (newline === -1) return events;
+          discarding = false;
+          offset = newline + 1;
+          continue;
+        }
+
+        const newline = chunk.indexOf(0x0a, offset);
+        if (newline === -1) {
+          const remaining = chunk.subarray(offset);
+          if (tail.length + remaining.length > maxLineBytes) {
+            tail = Buffer.alloc(0);
+            discarding = true;
+            events.push(decoderError(
+              "LINE_TOO_LARGE",
+              `Provider JSONL record exceeded ${maxLineBytes} bytes`,
+              { maxLineBytes },
+            ));
+          } else if (remaining.length > 0) {
+            tail = tail.length ? Buffer.concat([tail, remaining]) : Buffer.from(remaining);
+          }
+          break;
+        }
+
+        const segment = chunk.subarray(offset, newline);
+        const lineBytes = tail.length + segment.length;
+        if (lineBytes > maxLineBytes) {
+          events.push(decoderError(
+            "LINE_TOO_LARGE",
+            `Provider JSONL record exceeded ${maxLineBytes} bytes`,
+            { maxLineBytes },
+          ));
+        } else {
+          const line = tail.length ? Buffer.concat([tail, segment]) : segment;
+          events.push(...parseCompleteLine(line));
+        }
+        tail = Buffer.alloc(0);
+        offset = newline + 1;
+      }
+
+      return events;
+    },
+
+    end() {
+      if (closed) return [];
+      closed = true;
+      if (discarding) {
+        tail = Buffer.alloc(0);
+        discarding = false;
+        return [];
+      }
+      const finalLine = tail;
+      tail = Buffer.alloc(0);
+      return finalLine.length ? parseCompleteLine(finalLine) : [];
+    },
+
+    get bufferedBytes() { return tail.length; },
+    get discarding() { return discarding; },
+    get closed() { return closed; },
+    maxLineBytes,
+  };
+
+  return api;
+}
+
+function providerErrorFlags(message) {
+  const text = String(message || "").toLowerCase();
+  return {
+    authError: /unauthori[sz]ed|not (?:logged in|authenticated)|unauthenticated|login required|authentication failed|auth failed|invalid api key|no credentials|401/.test(text),
+    usageLimit: /usage limit|spend limit|monthly cycle|quota|rate limit/.test(text),
+  };
+}
+
+function normalizeDecoderError(rawEvent) {
+  if (!rawEvent || rawEvent.type !== "decoder.error") return null;
+  return {
+    type: "error",
+    message: rawEvent.message || "Provider stream decoding failed",
+    authError: false,
+    usageLimit: false,
+  };
+}
+
+function usageFingerprint(usage, scope) {
+  if (!usage || typeof usage !== "object") return null;
+  const ordered = {};
+  for (const key of Object.keys(usage).sort()) ordered[key] = usage[key];
+  return `${scope}:${JSON.stringify(ordered)}`;
+}
+
+function normalizedUsage(usage, scope, seenUsage) {
+  const fingerprint = usageFingerprint(usage, scope);
+  if (!fingerprint || seenUsage.has(fingerprint)) return null;
+  seenUsage.add(fingerprint);
+  return { type: "usage", usage, scope };
+}
+
+function selectTerminalText({ resultText = "", finalText = "", deltaText = "" } = {}) {
+  return resultText || finalText || deltaText;
+}
+
+module.exports = {
+  DEFAULT_MAX_LINE_BYTES,
+  NORMALIZED_EVENT_TYPES,
+  createJsonlDecoder,
+  normalizeDecoderError,
+  normalizedUsage,
+  providerErrorFlags,
+  selectTerminalText,
+  usageFingerprint,
+};

package/core/providers/hook-command.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const path = require("path");
+
+function denyGateCliPath() {
+  return path.resolve(__dirname, "..", "..", "bin", "cli.js");
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function buildDenyGateCommand({ nodePath = process.execPath, cliPath = denyGateCliPath() } = {}) {
+  if (!path.isAbsolute(nodePath) || !path.isAbsolute(cliPath)) {
+    const error = new Error("Tool hook executables must use absolute paths");
+    error.code = "INVALID_TOOL_HOOK_COMMAND";
+    throw error;
+  }
+  return `${shellQuote(nodePath)} ${shellQuote(cliPath)} deny-gate-hook`;
+}
+
+module.exports = { buildDenyGateCommand, denyGateCliPath, shellQuote };