@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/sam/client.js

@@ -0,0 +1,252 @@
+import { getSamOperation, listSamOperations, toSamOperationCard } from './registry.js';
+import { buildSamResult } from './result.js';
+import { ensureSeedOperations } from './seed.js';
+
+/**
+ * Resolve root/cwd from common input shapes.
+ * @param {unknown} input
+ */
+function resolveRoot(input) {
+  if (input == null) return process.cwd();
+  if (typeof input === 'string') return input;
+  if (typeof input === 'object') {
+    const o = /** @type {Record<string, unknown>} */ (input);
+    if (typeof o.root === 'string') return o.root;
+    if (typeof o.cwd === 'string') return o.cwd;
+    if (typeof o.projectRoot === 'string') return o.projectRoot;
+  }
+  return process.cwd();
+}
+
+/**
+ * AgentSamClient — public facade over Systematic Autonomous Machinery (SAM).
+ *
+ * `sam` is the conventional variable name for this client. It is machinery,
+ * not a human identity.
+ *
+ * @example
+ * import { AgentSamClient } from '@inneranimalmedia/agentsam-sdk';
+ * const sam = new AgentSamClient();
+ * const result = await sam.invoke('repository.inspect', { root: '.' });
+ */
+export class AgentSamClient {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Explicit platform credential (AGENTSAM_API_KEY). Local ops do not require it.
+   * @param {string} [options.cwd]
+   * @param {Record<string, string|undefined>} [options.env]
+   * @param {boolean} [options.autoSeed=true]
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? options.env?.AGENTSAM_API_KEY ?? process.env.AGENTSAM_API_KEY ?? null;
+    this.cwd = options.cwd ?? process.cwd();
+    this.env = options.env ?? process.env;
+    if (options.autoSeed !== false) {
+      ensureSeedOperations();
+    }
+
+    /** Domain projections → sam.invoke(canonicalId, …) */
+    this.repository = {
+      inspect: (input = {}, opts) => this.invoke('repository.inspect', normalizeRootInput(input), opts),
+    };
+    this.brand = {
+      scan: (input = {}, opts) => this.invoke('brand.scan', normalizeRootInput(input), opts),
+    };
+    this.security = {
+      scan: (input = {}, opts) => this.invoke('security.scan', normalizeRootInput(input), opts),
+    };
+    this.terminal = {
+      exec: (input = {}, opts) => this.invoke('terminal.exec', input, opts),
+    };
+    this.cad = {
+      blender: {
+        inspect: (input = {}, opts) => this.invoke('cad.blender.inspect', input, opts),
+      },
+    };
+    this.codebaseindex = {
+      ingest: (input = {}, opts) => this.invoke('codebaseindex.ingest', normalizeRootInput(input), opts),
+    };
+    this.decision = {
+      evaluate: (input = {}, opts) => this.invoke('decision.evaluate', input, opts),
+    };
+    this.planning = {
+      astar: (input = {}, opts) => this.invoke('planning.astar', input, opts),
+      goap: (input = {}, opts) => this.invoke('planning.goap', input, opts),
+    };
+  }
+
+  /**
+   * Universal SAM execution doorway.
+   * @param {string} operationId
+   * @param {unknown} [input]
+   * @param {object} [options]
+   * @param {AbortSignal} [options.signal]
+   * @param {Record<string, unknown>} [options.execution]
+   * @returns {Promise<import('./types.js').SamResult>}
+   */
+  async invoke(operationId, input = {}, options = {}) {
+    ensureSeedOperations();
+    const def = getSamOperation(operationId);
+    if (!def) {
+      return buildSamResult({
+        operation: operationId,
+        ok: false,
+        data: null,
+        startedAt: new Date().toISOString(),
+        error: { code: 'sam_operation_not_found', message: `Unknown operation: ${operationId}` },
+        status: 'failed',
+      });
+    }
+
+    const startedAt = new Date().toISOString();
+    const deterministic = def.execution.model === 'never';
+    const sideEffects = def.execution.sideEffects === 'none' ? [] : [def.execution.sideEffects];
+    /** @type {import('./types.js').SamOperationContext} */
+    const ctx = {
+      signal: options.signal,
+      execution: options.execution,
+      cwd: this.cwd,
+      env: this.env,
+    };
+
+    try {
+      const data = await def.handler(input, ctx);
+      const warnings = Array.isArray(/** @type {any} */ (data)?.warnings)
+        ? /** @type {any} */ (data).warnings
+        : undefined;
+      return buildSamResult({
+        operation: def.id,
+        module: def.module,
+        ok: true,
+        data,
+        startedAt,
+        lane: 'local',
+        deterministic,
+        modelUsed: false,
+        sideEffects,
+        input,
+        warnings,
+      });
+    } catch (err) {
+      return buildSamResult({
+        operation: def.id,
+        module: def.module,
+        ok: false,
+        data: null,
+        startedAt,
+        lane: 'local',
+        deterministic,
+        modelUsed: false,
+        sideEffects,
+        input,
+        error: {
+          code: err?.code || 'sam_operation_failed',
+          message: err?.message || String(err),
+        },
+        status: options.signal?.aborted ? 'cancelled' : 'failed',
+      });
+    }
+  }
+
+  /**
+   * Inspect operation metadata without executing.
+   * @param {string} operationId
+   * @param {{ schema?: boolean }} [options]
+   */
+  async describe(operationId, options = {}) {
+    ensureSeedOperations();
+    const def = getSamOperation(operationId);
+    if (!def) {
+      return {
+        ok: false,
+        error: { code: 'sam_operation_not_found', message: `Unknown operation: ${operationId}` },
+      };
+    }
+    const skillId = typeof def.skill === 'string' ? def.skill : def.skill?.id || null;
+    const info = {
+      ok: true,
+      id: def.id,
+      version: def.version,
+      module: def.module,
+      action: def.action,
+      summary: def.summary,
+      purpose: def.purpose || def.description,
+      outcome: def.outcome || null,
+      description: def.description,
+      execution: { ...def.execution, lanes: [...def.execution.lanes] },
+      auth: def.auth || {},
+      risk: def.risk,
+      accepts: def.accepts || [],
+      phases: def.phases || [],
+      artifacts: def.artifacts || [],
+      capabilities: def.capabilities || [],
+      skill: skillId,
+      preview: def.preview || null,
+      cli: def.cli || {},
+      docs: def.docs || {},
+      status: def.status || 'stable',
+      input_schema: def.input_schema || null,
+      output_schema: def.output_schema || null,
+    };
+    if (options.schema) {
+      info.schemas_requested = true;
+    }
+    return info;
+  }
+
+  /**
+   * Compact operation cards matching a query (substring / token match).
+   * @param {{ query?: string, module?: string, model?: string, limit?: number }} [query]
+   */
+  async discover(query = {}) {
+    ensureSeedOperations();
+    const q = String(query.query || '').trim().toLowerCase();
+    const tokens = q ? q.split(/\s+/).filter(Boolean) : [];
+    const limit = Number.isInteger(query.limit) ? query.limit : 20;
+    let cards = listSamOperations().map(toSamOperationCard);
+
+    if (query.module) {
+      cards = cards.filter((c) => c.module === query.module);
+    }
+    if (query.model) {
+      cards = cards.filter((c) => c.model === query.model);
+    }
+    if (tokens.length) {
+      cards = cards
+        .map((card) => {
+          const hay = `${card.id} ${card.summary} ${card.module} ${card.action}`.toLowerCase();
+          const score = tokens.reduce((n, t) => n + (hay.includes(t) ? 1 : 0), 0);
+          return { card, score };
+        })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score || a.card.id.localeCompare(b.card.id))
+        .map((x) => x.card);
+    }
+
+    return {
+      ok: true,
+      count: Math.min(cards.length, limit),
+      operations: cards.slice(0, limit),
+    };
+  }
+}
+
+/**
+ * @param {unknown} input
+ */
+function normalizeRootInput(input) {
+  if (typeof input === 'string') {
+    return { root: input };
+  }
+  if (input && typeof input === 'object') {
+    const o = /** @type {Record<string, unknown>} */ (input);
+    const root = resolveRoot(input);
+    return { ...o, root, cwd: o.cwd ?? root };
+  }
+  return { root: process.cwd(), cwd: process.cwd() };
+}
+
+/** Convenience factory matching docs examples. */
+export function createAgentSamClient(options) {
+  return new AgentSamClient(options);
+}

package/src/sam/decision/calibration.js

@@ -0,0 +1,109 @@
+/**
+ * Calibration metrics — fixtures/known formulas.
+ * Do NOT claim calibrated probabilities without a stored calibration_id.
+ */
+
+import { DECISION_CALIBRATION_SCHEMA } from './types.js';
+
+/**
+ * Brier score for binary forecasts.
+ * @param {Array<{ p: number, y: 0|1|boolean }>} rows
+ */
+export function brierScore(rows) {
+  if (!rows?.length) return null;
+  let sum = 0;
+  for (const row of rows) {
+    const p = Number(row.p);
+    const y = row.y === true || row.y === 1 ? 1 : 0;
+    sum += (p - y) ** 2;
+  }
+  return sum / rows.length;
+}
+
+/**
+ * Log loss for binary forecasts.
+ * @param {Array<{ p: number, y: 0|1|boolean }>} rows
+ * @param {number} [eps]
+ */
+export function logLoss(rows, eps = 1e-15) {
+  if (!rows?.length) return null;
+  let sum = 0;
+  for (const row of rows) {
+    const y = row.y === true || row.y === 1 ? 1 : 0;
+    const p = Math.min(1 - eps, Math.max(eps, Number(row.p)));
+    sum += -(y * Math.log(p) + (1 - y) * Math.log(1 - p));
+  }
+  return sum / rows.length;
+}
+
+/**
+ * Expected Calibration Error with equal-width bins.
+ * @param {Array<{ p: number, y: 0|1|boolean }>} rows
+ * @param {number} [bins]
+ */
+export function expectedCalibrationError(rows, bins = 10) {
+  if (!rows?.length) return null;
+  /** @type {Array<{ count: number, conf: number, acc: number }>} */
+  const bucket = Array.from({ length: bins }, () => ({ count: 0, conf: 0, acc: 0 }));
+  for (const row of rows) {
+    const p = Number(row.p);
+    const y = row.y === true || row.y === 1 ? 1 : 0;
+    const idx = Math.min(bins - 1, Math.max(0, Math.floor(p * bins)));
+    bucket[idx].count += 1;
+    bucket[idx].conf += p;
+    bucket[idx].acc += y;
+  }
+  let ece = 0;
+  const n = rows.length;
+  const reliability = [];
+  for (let i = 0; i < bins; i += 1) {
+    const b = bucket[i];
+    if (!b.count) {
+      reliability.push({ bin: i, count: 0, confidence: null, accuracy: null });
+      continue;
+    }
+    const conf = b.conf / b.count;
+    const acc = b.acc / b.count;
+    ece += (b.count / n) * Math.abs(acc - conf);
+    reliability.push({ bin: i, count: b.count, confidence: conf, accuracy: acc });
+  }
+  return { ece, reliability, schema: DECISION_CALIBRATION_SCHEMA };
+}
+
+/**
+ * Dataset export contract from receipts with outcomes (no auto-train).
+ * @param {object[]} receipts
+ */
+export function exportCalibrationDataset(receipts = []) {
+  const rows = [];
+  for (const receipt of receipts) {
+    if (!receipt?.outcome) continue;
+    for (const [qid, answer] of Object.entries(receipt.answers || {})) {
+      if (answer.type !== 'check') continue;
+      const p = answer.calibrated_probability
+        ?? answer.support
+        ?? answer.confidence_estimate;
+      if (p == null) continue;
+      rows.push({
+        decision_id: receipt.decision_id,
+        question_id: qid,
+        question_version: receipt.question_versions?.[qid] ?? null,
+        evaluator: answer.evaluator || receipt.evaluator,
+        p: Number(p),
+        y: receipt.outcome.success === true
+          ? (answer.value ? 1 : 0)
+          : (receipt.outcome.actual_class != null
+            ? (String(receipt.outcome.actual_class) === String(answer.value) ? 1 : 0)
+            : null),
+        human_corrected: receipt.outcome.human_corrected,
+        calibration_id: answer.calibration_id ?? null,
+      });
+    }
+  }
+  return {
+    schema: DECISION_CALIBRATION_SCHEMA,
+    kind: 'dataset_export',
+    note: 'Not automatically used for training. Requires privacy review, splits, and label quality.',
+    rows: rows.filter((r) => r.y != null),
+  };
+}

package/src/sam/decision/confidence.js

@@ -0,0 +1,126 @@
+/**
+ * Confidence / support helpers.
+ *
+ * confidence_estimate = distribution concentration (NOT P(correct))
+ * support = check proposition strength in [0,1]
+ * probabilities = only when evaluator defines a probabilistic interpretation
+ * calibrated_probability = only with calibration_id after empirical fit
+ */
+
+/**
+ * Normalized entropy concentration in [0,1].
+ * 1 = fully concentrated on one option; 0 = uniform.
+ * @param {Record<string, number>} scores  non-negative weights
+ */
+export function concentrationFromScores(scores) {
+  const entries = Object.entries(scores || {}).filter(([, v]) => Number.isFinite(v) && v >= 0);
+  if (!entries.length) return 0;
+  const sum = entries.reduce((n, [, v]) => n + v, 0);
+  if (!(sum > 0)) return 0;
+  if (entries.length === 1) return 1;
+  const probs = entries.map(([, v]) => v / sum);
+  const entropy = -probs.reduce((n, p) => (p > 0 ? n + p * Math.log(p) : n), 0);
+  const maxEntropy = Math.log(entries.length);
+  if (!(maxEntropy > 0)) return 1;
+  return clamp01(1 - entropy / maxEntropy);
+}
+
+/**
+ * Softmax → probabilities that sum to 1 (within floating tolerance).
+ * @param {Record<string, number>} scores
+ * @param {number} [temperature]
+ */
+export function softmax(scores, temperature = 1) {
+  const entries = Object.entries(scores || {});
+  if (!entries.length) return {};
+  const t = temperature > 0 ? temperature : 1;
+  const max = Math.max(...entries.map(([, v]) => Number(v) || 0));
+  const exps = entries.map(([k, v]) => [k, Math.exp(((Number(v) || 0) - max) / t)]);
+  const sum = exps.reduce((n, [, e]) => n + e, 0) || 1;
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const [k, e] of exps) out[k] = e / sum;
+  return out;
+}
+
+/**
+ * Expected score from a probability distribution over ordered levels.
+ * @param {Array<{ index: number }>} levels
+ * @param {Record<string, number>} probabilities  keyed by level index string
+ */
+export function expectedScore(levels, probabilities) {
+  let sum = 0;
+  for (const level of levels) {
+    const p = Number(probabilities[String(level.index)] ?? probabilities[level.index] ?? 0);
+    sum += level.index * (Number.isFinite(p) ? p : 0);
+  }
+  return sum;
+}
+
+/**
+ * Assert probabilities sum ≈ 1.
+ * @param {Record<string, number>} probs
+ * @param {number} [tolerance]
+ */
+export function assertProbabilitiesSumToOne(probs, tolerance = 1e-6) {
+  const sum = Object.values(probs || {}).reduce((n, v) => n + (Number(v) || 0), 0);
+  if (Math.abs(sum - 1) > tolerance) {
+    const err = new Error(`probabilities_sum=${sum}`);
+    err.code = 'probabilities_invalid';
+    throw err;
+  }
+  return true;
+}
+
+export function clamp01(n) {
+  if (!Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+/**
+ * Build answer envelope with strict raw vs calibrated labeling.
+ * @param {object} partial
+ */
+export function buildAnswer(partial) {
+  const answer = {
+    schema: 'agentsam.decision-answer.v1',
+    type: partial.type,
+    question_id: partial.question_id,
+    value: partial.value,
+    scores: partial.scores ?? null,
+    levels: partial.levels ?? null,
+    support: partial.support ?? null,
+    confidence_estimate: partial.confidence_estimate ?? null,
+    probabilities: partial.probabilities ?? null,
+    calibrated_probability: partial.calibrated_probability ?? null,
+    calibration_id: partial.calibration_id ?? null,
+    evaluator: partial.evaluator ?? null,
+    evidence: Array.isArray(partial.evidence) ? partial.evidence : [],
+    warnings: Array.isArray(partial.warnings) ? partial.warnings : [],
+  };
+
+  if (answer.probabilities) {
+    assertProbabilitiesSumToOne(answer.probabilities);
+  }
+  if (answer.calibrated_probability != null && !answer.calibration_id) {
+    const err = new Error('calibrated_probability requires calibration_id');
+    err.code = 'calibration_required';
+    throw err;
+  }
+  // Never allow callers to smuggle calibrated claims without id via alias fields
+  if ('probability' in (partial || {}) || 'probability_true' in (partial || {})) {
+    if (!answer.calibration_id && answer.probabilities == null) {
+      // Accept probability_true only when calibration_id present; otherwise map to support
+      if (partial.probability_true != null && answer.support == null) {
+        answer.support = clamp01(Number(partial.probability_true));
+        answer.warnings = [
+          ...answer.warnings,
+          'probability_true_mapped_to_support_without_calibration',
+        ];
+      }
+    }
+  }
+  return answer;
+}

package/src/sam/decision/evaluate.js

@@ -0,0 +1,157 @@
+/**
+ * Multi-question batch evaluation.
+ *
+ * Questions in one batch:
+ * - see the same original state
+ * - are logically independent
+ * - do not consume another question's answer
+ */
+
+import { buildDecisionState, hashDecisionState } from './state.js';
+import { validateQuestionBatch } from './validate.js';
+import { selectEvaluator, DEFAULT_CHAIN } from './evaluators/select.js';
+import { applyDecisionPolicy } from './policy.js';
+import { createDecisionReceipt } from './receipt.js';
+import { DECISION_EVALUATION_SCHEMA } from './types.js';
+import { getRegisteredQuestion } from './questions.js';
+import { activityFromDecision } from '../activity/index.js';
+
+/**
+ * @param {object} opts
+ * @param {object} opts.state
+ * @param {Array<object|string>} opts.questions  question objects or registry ids
+ * @param {object[]} [opts.evaluators]
+ * @param {object} [opts.policy]
+ * @param {boolean} [opts.receipt]
+ */
+export async function evaluate(opts = {}) {
+  const state = buildDecisionState(opts.state || {});
+  const stateHash = hashDecisionState(state);
+  const questions = validateQuestionBatch(
+    (opts.questions || []).map((q) => (typeof q === 'string' ? getRegisteredQuestion(q) : q)),
+  );
+  const evaluators = opts.evaluators || DEFAULT_CHAIN;
+
+  // Group by selected evaluator — each question independently routed.
+  /** @type {Map<object, object[]>} */
+  const groups = new Map();
+  /** @type {Record<string, object>} */
+  const routing = {};
+  for (const q of questions) {
+    const ev = selectEvaluator(q, evaluators);
+    routing[q.id] = { kind: ev.kind, version: ev.version };
+    if (!groups.has(ev)) groups.set(ev, []);
+    groups.get(ev).push(q);
+  }
+
+  /** @type {Record<string, object>} */
+  const answers = {};
+  /** @type {object[]} */
+  const usedEvaluators = [];
+  let modelUsed = false;
+
+  for (const [ev, qs] of groups) {
+    // Each group receives the SAME original state — never prior answers.
+    const result = await ev.evaluate(state, qs);
+    usedEvaluators.push(result.evaluator || { kind: ev.kind, version: ev.version });
+    if (result.model_used) modelUsed = true;
+    for (const [id, answer] of Object.entries(result.answers || {})) {
+      // Independence check: answer must not reference sibling answers.
+      if (answer && answer._consumed_answers) {
+        const err = new Error(`question_dependency_leak:${id}`);
+        err.code = 'question_independence_violated';
+        throw err;
+      }
+      answers[id] = answer;
+    }
+  }
+
+  // Ensure every question answered
+  for (const q of questions) {
+    if (!answers[q.id]) {
+      const err = new Error(`missing_answer:${q.id}`);
+      err.code = 'evaluation_incomplete';
+      throw err;
+    }
+  }
+
+  const policy_result = applyDecisionPolicy({
+    answers,
+    policy: opts.policy || {},
+    state,
+  });
+
+  const evaluation = {
+    schema: DECISION_EVALUATION_SCHEMA,
+    ok: true,
+    state_hash: stateHash,
+    answers,
+    routing,
+    policy_result,
+    model_used: modelUsed,
+    deterministic: !modelUsed,
+    question_versions: Object.fromEntries(questions.map((q) => [q.id, q.version])),
+  };
+
+  if (opts.receipt !== false) {
+    evaluation.receipt = createDecisionReceipt({
+      state,
+      state_hash: stateHash,
+      answers,
+      policy_result,
+      question_ids: questions.map((q) => q.id),
+      question_versions: evaluation.question_versions,
+      evaluators: usedEvaluators,
+      evaluator: usedEvaluators[0] || null,
+      action: opts.action ?? null,
+      run_id: opts.run_id ?? null,
+      step_id: opts.step_id ?? null,
+      action_id: opts.action_id ?? null,
+      evidence: opts.evidence || [],
+    });
+  }
+
+  // Optional live activity fan-out (Studio / CLI share the same events)
+  if (opts.activity && typeof opts.activity.emit === 'function' && evaluation.receipt) {
+    for (const [qid, answer] of Object.entries(answers)) {
+      opts.activity.emit(
+        activityFromDecision({
+          run_id: opts.run_id || opts.activity.run_id,
+          step_id: opts.step_id,
+          decision_id: evaluation.receipt.decision_id,
+          question_id: qid,
+          answer,
+          phase: opts.activity_phase || 'plan',
+        }),
+      );
+    }
+  }
+
+  return evaluation;
+}
+
+/**
+ * Explicit two-stage evaluation: stage2 state must be newly built by caller.
+ * @param {object} stage1  evaluate() opts
+ * @param {(stage1Result: object) => object|Promise<object>} buildStage2State
+ * @param {object} stage2  { questions, policy?, evaluators? }
+ */
+export async function evaluateDependentStages(stage1, buildStage2State, stage2) {
+  const first = await evaluate(stage1);
+  if (typeof buildStage2State !== 'function') {
+    const err = new Error('dependent_stage_requires_explicit_state_builder');
+    err.code = 'invalid_dependent_stage';
+    throw err;
+  }
+  const nextState = await buildStage2State(first);
+  if (!nextState || nextState === stage1.state) {
+    const err = new Error('dependent_stage_must_build_new_state');
+    err.code = 'invalid_dependent_stage';
+    throw err;
+  }
+  const second = await evaluate({
+    ...stage2,
+    state: nextState,
+  });
+  return { stage1: first, stage2: second };
+}