@causyne/agent 1.10.21 → 1.11.0

package/src/modelRouter.ts

@@ -0,0 +1,134 @@
+import { UTILITY_MODEL_BY_PROVIDER } from './modelCatalogue.js';
+
+// Hybrid model routing.
+//
+// Not every call an agent makes is reasoning. Condensing a dropped transcript,
+// classifying an intent, filtering a log, extracting keywords — these are
+// utility work, and paying a flagship rate for them is pure waste. The research
+// spec puts the saving at the difference between the two rate cards, which for
+// OpenAI is $5/$30 against $0.75/$4.50: roughly 6x on work that never needed
+// the better model.
+//
+// THREE RULES THIS MODULE EXISTS TO ENFORCE, all of them things a naive router
+// gets wrong:
+//
+//   1. NEVER CHANGE PROVIDER. Causyne is BYOK. The user holds one key. A router
+//      that sends utility work to "whatever is cheapest on the market" calls an
+//      endpoint there is no credential for and the task fails — having spent
+//      the tokens that got it there.
+//
+//   2. NEVER CHANGE THE PRIVACY POSTURE. Muse's cheap tier is `-contributor`,
+//      discounted because the vendor trains on the content. Routing into it to
+//      save money would opt the user into training silently. Cost is not a
+//      reason to make that choice for someone.
+//
+//   3. NEVER GUESS. A provider with no published second tier routes to nothing
+//      and pays full rate. An invented model id becomes a 404 mid-task, or
+//      worse, a real model at a price nobody predicted.
+//
+// The router returns a DESCRIPTION of where a call should go. It never
+// constructs a provider and never performs a call, so it stays trivially
+// testable and cannot become a second place where credentials are handled.
+
+export type RouteClass = 'reasoning' | 'utility';
+
+export interface Route {
+  provider: string;
+  model: string;
+  routed: boolean;
+  reason: string;
+}
+
+export interface RouterConfig {
+  provider?: string | undefined;
+  model?: string | undefined;
+  modelRouting?: Record<string, string> | undefined;
+  disableModelRouting?: boolean | undefined;
+  [key: string]: unknown;
+}
+
+/**
+ * Utility work that is cheap to get wrong and expensive to run on a flagship.
+ * Anything not listed is treated as reasoning — the safe default is to spend
+ * more, never to silently downgrade work the user is judging.
+ */
+export const UTILITY_KINDS: ReadonlySet<string> = new Set([
+  'condense',        // cortex/autoCondenser semantic pass
+  'keywords',        // plan-cache intent extraction
+  'classify',        // intent / archetype disambiguation
+  'filter',          // log and output filtering
+  'summarise'        // non-decision summaries
+]);
+
+/**
+ * Decide where a call of a given kind should go.
+ *
+ * @param config The live agent config, as loaded from `~/.causyne/config.json`.
+ * @param kind Either a RouteClass or one of UTILITY_KINDS.
+ * @returns The resolved route description.
+ */
+export function resolveRoute(config: RouterConfig | undefined | null, kind: RouteClass | string): Route {
+  const provider = String(config?.provider || '').toLowerCase();
+  const configured = String(config?.model || '');
+
+  const stay: Route = {
+    provider,
+    model: configured,
+    routed: false,
+    reason: 'reasoning work runs on the configured model'
+  };
+
+  if (!provider || !configured) {
+    return { ...stay, reason: 'no provider or model configured' };
+  }
+
+  const isUtility = kind === 'utility' || UTILITY_KINDS.has(String(kind));
+  if (!isUtility) return stay;
+
+  if (config?.disableModelRouting === true) {
+    return { ...stay, reason: 'model routing disabled by config' };
+  }
+
+  // An explicit choice by the user outranks the table, including a deliberate
+  // choice of a training tier — they made it, we did not make it for them.
+  const override = config?.modelRouting?.['utility'];
+  if (override) {
+    return {
+      provider,
+      model: String(override),
+      routed: String(override) !== configured,
+      reason: 'utility route set explicitly in config'
+    };
+  }
+
+  const cheap = UTILITY_MODEL_BY_PROVIDER[provider];
+  if (!cheap) {
+    return { ...stay, reason: `no published utility tier for ${provider}; paying full rate` };
+  }
+  if (cheap === configured) {
+    return { ...stay, reason: 'already on this provider\'s utility tier' };
+  }
+
+  // Rule 2. The configured model already carries a privacy posture; a route may
+  // not alter it in either direction.
+  if (/-contributor$/.test(configured) !== /-contributor$/.test(cheap)) {
+    return { ...stay, reason: 'a route may not change the training-data posture' };
+  }
+
+  return {
+    provider,
+    model: cheap,
+    routed: true,
+    reason: `utility work routed to ${provider}'s cheaper tier`
+  };
+}
+
+/**
+ * A config object for the routed call, leaving everything except the model
+ * untouched — same provider, same key, same base URL.
+ */
+export function routedConfig<T extends RouterConfig>(config: T, kind: RouteClass | string): { config: T; route: Route } {
+  const route = resolveRoute(config, kind);
+  if (!route.routed) return { config, route };
+  return { config: { ...config, model: route.model }, route };
+}

package/src/observer/advisory.js

@@ -0,0 +1,164 @@
+const MAX_PAYLOAD_CHARS = 5000;
+export function isLoopbackEndpoint(value) {
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return false;
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return false;
+        const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    }
+    catch {
+        return false;
+    }
+}
+function completionUrl(endpoint) {
+    const trimmed = endpoint.replace(/\/+$/, '');
+    if (/\/chat\/completions$/.test(trimmed))
+        return trimmed;
+    return `${trimmed}/chat/completions`;
+}
+function redact(value) {
+    return value
+        .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 [redacted]')
+        .replace(/\b(api[-_]?key|token|secret|password|passwd)\b\s*[:=]\s*["']?[^"'\s,}]+/gi, '$1=[redacted]')
+        .slice(0, MAX_PAYLOAD_CHARS);
+}
+function compactArguments(args) {
+    const allowed = {};
+    for (const key of ['command', 'cmd', 'path', 'file_path', 'source', 'destination', 'action', 'url']) {
+        const value = args[key];
+        if (typeof value === 'string')
+            allowed[key] = value;
+    }
+    if (typeof args.content === 'string') {
+        allowed.contentExcerpt = args.content.slice(0, 800);
+        allowed.contentBytes = Buffer.byteLength(args.content, 'utf8');
+    }
+    if (Array.isArray(args.edits)) {
+        allowed.edits = args.edits.slice(0, 8).map((edit) => {
+            if (edit === null || typeof edit !== 'object' || Array.isArray(edit))
+                return {};
+            const record = edit;
+            return {
+                before: typeof record.old_string === 'string'
+                    ? record.old_string.slice(0, 200)
+                    : typeof record.searchContent === 'string' ? record.searchContent.slice(0, 200) : '',
+                after: typeof record.new_string === 'string'
+                    ? record.new_string.slice(0, 200)
+                    : typeof record.replaceContent === 'string' ? record.replaceContent.slice(0, 200) : ''
+            };
+        });
+    }
+    return redact(JSON.stringify(allowed));
+}
+function parseVerdict(content) {
+    const match = content.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        const risk = record.risk;
+        const confidence = record.confidence;
+        if (typeof risk !== 'number' || !Number.isFinite(risk))
+            return null;
+        if (typeof confidence !== 'number' || !Number.isFinite(confidence))
+            return null;
+        return {
+            risk: Math.max(0, Math.min(1, risk)),
+            confidence: Math.max(0, Math.min(1, confidence)),
+            observation: typeof record.observation === 'string' ? record.observation.slice(0, 400) : ''
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function queryAdvisory(input, options) {
+    if (!isLoopbackEndpoint(options.endpoint))
+        return null;
+    if (!options.model.trim())
+        return null;
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 200)
+        return null;
+    const payload = {
+        model: options.model,
+        temperature: 0,
+        max_tokens: 160,
+        messages: [
+            {
+                role: 'system',
+                content: 'You are an evidence reviewer for a software agent. Judge only the supplied action and deterministic findings. Do not invent facts. Return one JSON object with keys risk (0..1), confidence (0..1), and observation (one sentence). High risk means the action could destroy work, escape the workspace, expose credentials, or publish state. Low risk means the action is reversible and scoped.'
+            },
+            {
+                role: 'user',
+                content: `Tool: ${input.tool}\nWorkspace: ${input.workspaceRoot}\nFindings: ${input.findings.slice(0, 6).join(' | ') || 'none'}\nArguments: ${compactArguments(input.args)}`
+            }
+        ]
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetch(completionUrl(options.endpoint), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: controller.signal
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (body === null || typeof body !== 'object' || Array.isArray(body))
+            return null;
+        const choices = body.choices;
+        if (!Array.isArray(choices) || choices.length === 0)
+            return null;
+        const first = choices[0];
+        if (first === null || typeof first !== 'object' || Array.isArray(first))
+            return null;
+        const message = first.message;
+        if (message === null || typeof message !== 'object' || Array.isArray(message))
+            return null;
+        const content = message.content;
+        if (typeof content !== 'string')
+            return null;
+        return parseVerdict(content);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function probeAdvisory(options) {
+    if (!isLoopbackEndpoint(options.endpoint)) {
+        return { healthy: false, latencyMs: 0, detail: 'endpoint must be a loopback HTTP URL' };
+    }
+    const start = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(500, options.timeoutMs));
+    try {
+        const base = options.endpoint.replace(/\/+$/, '').replace(/\/chat\/completions$/, '');
+        const response = await fetch(`${base}/models`, { signal: controller.signal });
+        return {
+            healthy: response.ok,
+            latencyMs: Date.now() - start,
+            detail: response.ok ? 'endpoint responded' : `endpoint returned HTTP ${response.status}`
+        };
+    }
+    catch (error) {
+        return {
+            healthy: false,
+            latencyMs: Date.now() - start,
+            detail: error instanceof Error ? error.message : 'endpoint did not respond'
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/src/observer/advisory.ts

@@ -0,0 +1,171 @@
+export interface AdvisoryInput {
+  tool: string;
+  args: Record<string, unknown>;
+  findings: string[];
+  workspaceRoot: string;
+}
+
+export interface AdvisoryVerdict {
+  risk: number;
+  confidence: number;
+  observation: string;
+}
+
+export interface AdvisoryOptions {
+  endpoint: string;
+  model: string;
+  timeoutMs: number;
+}
+
+const MAX_PAYLOAD_CHARS = 5000;
+
+export function isLoopbackEndpoint(value: string): boolean {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return false;
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+  } catch {
+    return false;
+  }
+}
+
+function completionUrl(endpoint: string): string {
+  const trimmed = endpoint.replace(/\/+$/, '');
+  if (/\/chat\/completions$/.test(trimmed)) return trimmed;
+  return `${trimmed}/chat/completions`;
+}
+
+function redact(value: string): string {
+  return value
+    .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 [redacted]')
+    .replace(/\b(api[-_]?key|token|secret|password|passwd)\b\s*[:=]\s*["']?[^"'\s,}]+/gi, '$1=[redacted]')
+    .slice(0, MAX_PAYLOAD_CHARS);
+}
+
+function compactArguments(args: Record<string, unknown>): string {
+  const allowed: Record<string, unknown> = {};
+  for (const key of ['command', 'cmd', 'path', 'file_path', 'source', 'destination', 'action', 'url']) {
+    const value = args[key];
+    if (typeof value === 'string') allowed[key] = value;
+  }
+  if (typeof args.content === 'string') {
+    allowed.contentExcerpt = args.content.slice(0, 800);
+    allowed.contentBytes = Buffer.byteLength(args.content, 'utf8');
+  }
+  if (Array.isArray(args.edits)) {
+    allowed.edits = args.edits.slice(0, 8).map((edit) => {
+      if (edit === null || typeof edit !== 'object' || Array.isArray(edit)) return {};
+      const record = edit as Record<string, unknown>;
+      return {
+        before: typeof record.old_string === 'string'
+          ? record.old_string.slice(0, 200)
+          : typeof record.searchContent === 'string' ? record.searchContent.slice(0, 200) : '',
+        after: typeof record.new_string === 'string'
+          ? record.new_string.slice(0, 200)
+          : typeof record.replaceContent === 'string' ? record.replaceContent.slice(0, 200) : ''
+      };
+    });
+  }
+  return redact(JSON.stringify(allowed));
+}
+
+function parseVerdict(content: string): AdvisoryVerdict | null {
+  const match = content.match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  try {
+    const parsed: unknown = JSON.parse(match[0]);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    const record = parsed as Record<string, unknown>;
+    const risk = record.risk;
+    const confidence = record.confidence;
+    if (typeof risk !== 'number' || !Number.isFinite(risk)) return null;
+    if (typeof confidence !== 'number' || !Number.isFinite(confidence)) return null;
+    return {
+      risk: Math.max(0, Math.min(1, risk)),
+      confidence: Math.max(0, Math.min(1, confidence)),
+      observation: typeof record.observation === 'string' ? record.observation.slice(0, 400) : ''
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function queryAdvisory(
+  input: AdvisoryInput,
+  options: AdvisoryOptions
+): Promise<AdvisoryVerdict | null> {
+  if (!isLoopbackEndpoint(options.endpoint)) return null;
+  if (!options.model.trim()) return null;
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 200) return null;
+
+  const payload = {
+    model: options.model,
+    temperature: 0,
+    max_tokens: 160,
+    messages: [
+      {
+        role: 'system',
+        content: 'You are an evidence reviewer for a software agent. Judge only the supplied action and deterministic findings. Do not invent facts. Return one JSON object with keys risk (0..1), confidence (0..1), and observation (one sentence). High risk means the action could destroy work, escape the workspace, expose credentials, or publish state. Low risk means the action is reversible and scoped.'
+      },
+      {
+        role: 'user',
+        content: `Tool: ${input.tool}\nWorkspace: ${input.workspaceRoot}\nFindings: ${input.findings.slice(0, 6).join(' | ') || 'none'}\nArguments: ${compactArguments(input.args)}`
+      }
+    ]
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const response = await fetch(completionUrl(options.endpoint), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    if (!response.ok) return null;
+    const body: unknown = await response.json();
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) return null;
+    const choices = (body as Record<string, unknown>).choices;
+    if (!Array.isArray(choices) || choices.length === 0) return null;
+    const first = choices[0];
+    if (first === null || typeof first !== 'object' || Array.isArray(first)) return null;
+    const message = (first as Record<string, unknown>).message;
+    if (message === null || typeof message !== 'object' || Array.isArray(message)) return null;
+    const content = (message as Record<string, unknown>).content;
+    if (typeof content !== 'string') return null;
+    return parseVerdict(content);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function probeAdvisory(options: AdvisoryOptions): Promise<{ healthy: boolean; latencyMs: number; detail: string }> {
+  if (!isLoopbackEndpoint(options.endpoint)) {
+    return { healthy: false, latencyMs: 0, detail: 'endpoint must be a loopback HTTP URL' };
+  }
+  const start = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(500, options.timeoutMs));
+  try {
+    const base = options.endpoint.replace(/\/+$/, '').replace(/\/chat\/completions$/, '');
+    const response = await fetch(`${base}/models`, { signal: controller.signal });
+    return {
+      healthy: response.ok,
+      latencyMs: Date.now() - start,
+      detail: response.ok ? 'endpoint responded' : `endpoint returned HTTP ${response.status}`
+    };
+  } catch (error) {
+    return {
+      healthy: false,
+      latencyMs: Date.now() - start,
+      detail: error instanceof Error ? error.message : 'endpoint did not respond'
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}