@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/src/sam/activity/index.js

@@ -0,0 +1,183 @@
+/**
+ * AgentSam activity event stream — one run, many surfaces (Studio / CLI / desktop).
+ * Scene/status/progress come ONLY from these events — never demo timers.
+ */
+
+export const ACTIVITY_SCHEMA = 'agentsam.activity.v1';
+
+export const ACTIVITY_PHASES = Object.freeze([
+  'boot',
+  'observe',
+  'context',
+  'plan',
+  'execute',
+  'verify',
+  'compact',
+  'waiting',
+  'recover',
+  'complete',
+]);
+
+export const ACTIVITY_EVENTS = Object.freeze([
+  'run.started',
+  'phase.changed',
+  'step.started',
+  'step.progress',
+  'step.completed',
+  'decision.made',
+  'tool.started',
+  'tool.completed',
+  'artifact.created',
+  'file.changed',
+  'approval.required',
+  'input.required',
+  'verification.completed',
+  'run.failed',
+  'run.completed',
+]);
+
+/** User-facing labels — never expose choose/score/check as primary copy. */
+export const DECISION_ACTIVITY_LABELS = Object.freeze({
+  terminal_lane: 'Selecting execution path',
+  retrieval_mode: 'Choosing retrieval path',
+  change_risk: 'Assessing change risk',
+  requires_approval: 'Checking approval requirements',
+  security_review_required: 'Checking security review requirements',
+  verification_scope: 'Selecting verification scope',
+  skill_candidate: 'Selecting skill',
+});
+
+/**
+ * @param {object} partial
+ */
+export function createActivityEvent(partial = {}) {
+  const phase = partial.phase || 'execute';
+  const event = partial.event || 'step.progress';
+  if (!ACTIVITY_PHASES.includes(phase)) {
+    const err = new Error(`invalid_activity_phase:${phase}`);
+    err.code = 'invalid_activity_phase';
+    throw err;
+  }
+  if (!ACTIVITY_EVENTS.includes(event)) {
+    const err = new Error(`invalid_activity_event:${event}`);
+    err.code = 'invalid_activity_event';
+    throw err;
+  }
+  return Object.freeze({
+    schema: ACTIVITY_SCHEMA,
+    run_id: String(partial.run_id || ''),
+    seq: Number.isInteger(partial.seq) ? partial.seq : 0,
+    timestamp: partial.timestamp || new Date().toISOString(),
+    phase,
+    event,
+    step_id: partial.step_id ?? null,
+    parent_id: partial.parent_id ?? null,
+    label: String(partial.label || ''),
+    detail: partial.detail ?? null,
+    progress: normalizeProgress(partial.progress),
+    source: partial.source
+      ? {
+          kind: partial.source.kind || 'sam',
+          name: partial.source.name ?? null,
+        }
+      : { kind: 'sam', name: null },
+    evidence: partial.evidence && typeof partial.evidence === 'object'
+      ? { ...partial.evidence }
+      : null,
+  });
+}
+
+function normalizeProgress(progress) {
+  if (progress == null) return null;
+  if (typeof progress !== 'object') return null;
+  const current = Number(progress.current);
+  const total = Number(progress.total);
+  if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0) return null;
+  return { current, total };
+}
+
+/**
+ * Map a decision answer to a user-visible activity event (primitives stay in evidence).
+ * @param {object} opts
+ */
+export function activityFromDecision(opts = {}) {
+  const questionId = opts.question_id || opts.answer?.question_id;
+  const answer = opts.answer || {};
+  const label = DECISION_ACTIVITY_LABELS[questionId]
+    || opts.label
+    || 'Making a structured decision';
+  const valueText = formatAnswerValue(answer);
+  return createActivityEvent({
+    run_id: opts.run_id,
+    seq: opts.seq,
+    phase: opts.phase || 'plan',
+    event: 'decision.made',
+    step_id: opts.step_id ?? null,
+    label,
+    detail: valueText,
+    source: { kind: 'sam', name: answer.evaluator?.kind || 'decision' },
+    evidence: {
+      decision_id: opts.decision_id ?? null,
+      question_id: questionId,
+      question_type: answer.type ?? null,
+      value: answer.value ?? null,
+      confidence_estimate: answer.confidence_estimate ?? null,
+      support: answer.support ?? null,
+      receipt_id: opts.decision_id ?? null,
+    },
+  });
+}
+
+function formatAnswerValue(answer) {
+  if (!answer || answer.value == null) return null;
+  if (answer.type === 'check') return answer.value ? 'Required' : 'Not required';
+  if (answer.type === 'score') {
+    const n = Number(answer.value);
+    return Number.isFinite(n) ? (n < 2 ? 'Bounded' : n < 3.5 ? 'Elevated' : 'High') : String(answer.value);
+  }
+  return String(answer.value);
+}
+
+/**
+ * In-memory run activity store — Studio SideStage and CLI subscribe to the same seq stream.
+ */
+export function createActivityStore(runId) {
+  const id = String(runId || `run_${Date.now().toString(36)}`);
+  /** @type {object[]} */
+  const events = [];
+  /** @type {Set<(e: object) => void>} */
+  const listeners = new Set();
+  let seq = 0;
+
+  function emit(partial) {
+    const event = createActivityEvent({
+      ...partial,
+      run_id: id,
+      seq: ++seq,
+    });
+    events.push(event);
+    for (const fn of listeners) {
+      try {
+        fn(event);
+      } catch {
+        /* subscriber errors must not break the run */
+      }
+    }
+    return event;
+  }
+
+  return {
+    run_id: id,
+    emit,
+    on(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    snapshot() {
+      return [...events];
+    },
+    latest() {
+      return events[events.length - 1] || null;
+    },
+  };
+}

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;
+}