@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/sam/decision/index.js

@@ -0,0 +1,53 @@
+/**
+ * SAM decision module — choose / score / check + batch evaluate.
+ */
+
+export {
+  DECISION_STATE_SCHEMA,
+  DECISION_QUESTION_SCHEMA,
+  DECISION_ANSWER_SCHEMA,
+  DECISION_EVALUATION_SCHEMA,
+  DECISION_RECEIPT_SCHEMA,
+  DECISION_OUTCOME_SCHEMA,
+  DECISION_CALIBRATION_SCHEMA,
+} from './types.js';
+
+export { buildDecisionState, hashDecisionState, projectState } from './state.js';
+export {
+  defineChoose,
+  defineScore,
+  defineCheck,
+  validateQuestion,
+  validateQuestionBatch,
+} from './validate.js';
+export {
+  concentrationFromScores,
+  softmax,
+  expectedScore,
+  assertProbabilitiesSumToOne,
+  buildAnswer,
+  clamp01,
+} from './confidence.js';
+export { evaluate, evaluateDependentStages } from './evaluate.js';
+export { applyDecisionPolicy, composeUtility } from './policy.js';
+export { createDecisionReceipt, appendOutcome, attachAction, OUTCOME_DISPOSITIONS } from './receipt.js';
+export {
+  brierScore,
+  logLoss,
+  expectedCalibrationError,
+  exportCalibrationDataset,
+} from './calibration.js';
+export {
+  QUESTION_REGISTRY,
+  getRegisteredQuestion,
+  listRegisteredQuestions,
+} from './questions.js';
+export {
+  selectEvaluator,
+  DETERMINISTIC_EVALUATOR,
+  HEURISTIC_EVALUATOR,
+  SEMANTIC_EVALUATOR,
+  DEFAULT_CHAIN,
+} from './evaluators/select.js';
+export { createSemanticEvaluator } from './evaluators/semantic.js';
+export { hierarchicalChoose, beamRetain } from './hierarchical.js';

package/src/sam/decision/policy.js

@@ -0,0 +1,86 @@
+/**
+ * Policy owns permission — scores/confidence never grant authority alone.
+ */
+
+/**
+ * @param {object} opts
+ * @param {Record<string, object>} opts.answers
+ * @param {object} [opts.policy]
+ * @param {object} [opts.state]
+ */
+export function applyDecisionPolicy(opts = {}) {
+  const answers = opts.answers || {};
+  const policy = opts.policy || {};
+  const state = opts.state || {};
+  const required = [];
+  const denied = [];
+  const notes = [];
+
+  // Hard policy: production writes always require approval regardless of check support.
+  if (
+    policy.production_database_write === 'ALWAYS_REQUIRE_APPROVAL'
+    || state.constraints?.production_write
+    || state.facts?.production_write
+  ) {
+    required.push('user_approval');
+    notes.push('policy:production_write_always_requires_approval');
+  }
+
+  const approvalAnswer = answers.requires_approval;
+  if (approvalAnswer?.type === 'check' && approvalAnswer.value === true) {
+    required.push('user_approval');
+  }
+
+  // High confidence NEVER authorizes by itself.
+  for (const [id, answer] of Object.entries(answers)) {
+    if (
+      answer?.confidence_estimate != null
+      && answer.confidence_estimate >= 0.95
+      && policy.confidence_grants_authority
+    ) {
+      notes.push(`ignored_confidence_authority_claim:${id}`);
+    }
+  }
+
+  if (policy.deny_sandbox && answers.terminal_lane?.value === 'sandbox') {
+    denied.push('terminal_lane:sandbox');
+  }
+
+  const allowed = denied.length === 0;
+  return {
+    allowed,
+    require_approval: required.includes('user_approval'),
+    required: [...new Set(required)],
+    denied,
+    notes,
+    // Explicit: confidence is not permission
+    authorization_source: 'policy',
+  };
+}
+
+/**
+ * Composite utility from separate score/check answers — weights live in code.
+ * @param {object} parts
+ * @param {object} [weights]
+ */
+export function composeUtility(parts = {}, weights = {}) {
+  const w = {
+    goal_progress: weights.goal_progress ?? 0.4,
+    reversibility: weights.reversibility ?? 0.15,
+    risk: weights.risk ?? 0.25,
+    cost: weights.cost ?? 0.1,
+    confidence: weights.confidence ?? 0.1,
+  };
+  const goal = Number(parts.goal_progress ?? 0);
+  const rev = Number(parts.reversibility ?? 0);
+  const risk = Number(parts.risk ?? 0);
+  const cost = Number(parts.cost ?? 0);
+  const conf = Number(parts.confidence ?? 0);
+  return (
+    goal * w.goal_progress
+    + rev * w.reversibility
+    + conf * w.confidence
+    - risk * w.risk
+    - cost * w.cost
+  );
+}

package/src/sam/decision/questions.js

@@ -0,0 +1,120 @@
+/**
+ * Initial AgentSam decision question registry.
+ */
+
+import { defineChoose, defineScore, defineCheck } from './validate.js';
+
+export const QUESTION_REGISTRY = Object.freeze({
+  terminal_lane: defineChoose({
+    id: 'terminal_lane',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: {
+      question: 'Which execution lane best fits this task?',
+      focus: 'Use isolation, repository locality, availability and cost.',
+    },
+    criteria: {
+      local: {
+        use_when: ['task requires unsynced local files', 'local terminal healthy'],
+        avoid_when: ['strong isolation required'],
+      },
+      remote: {
+        use_when: ['shared remote environment needed'],
+        avoid_when: ['requires local-only paths'],
+      },
+      sandbox: {
+        use_when: ['code is untrusted', 'strong isolation is required'],
+        avoid_when: ['task requires direct access to unsynced local files'],
+      },
+    },
+    options: ['local', 'remote', 'sandbox'],
+  }),
+
+  retrieval_mode: defineChoose({
+    id: 'retrieval_mode',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: 'Which retrieval corpus should SAM query first?',
+    options: ['ast', 'lexical', 'semantic', 'memory', 'web', 'none'],
+    criteria: {
+      ast: { use_when: ['symbol / import / call-graph questions'] },
+      lexical: { use_when: ['exact string / path lookup'] },
+      semantic: { use_when: ['architectural concept questions'] },
+      memory: { use_when: ['historical decisions'] },
+      web: { use_when: ['fresh provider docs'] },
+      none: { use_when: ['no retrieval needed'] },
+    },
+  }),
+
+  change_risk: defineScore({
+    id: 'change_risk',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: 'How much operational risk does this proposed change carry?',
+    levels: [
+      { index: 0, label: 'Local, reversible change with no runtime impact' },
+      { index: 1, label: 'Bounded implementation change with focused verification' },
+      { index: 2, label: 'Cross-package change with known consumers' },
+      { index: 3, label: 'Runtime/schema/security boundary change' },
+      { index: 4, label: 'High-blast-radius or production-sensitive change' },
+    ],
+  }),
+
+  requires_approval: defineCheck({
+    id: 'requires_approval',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: {
+      question: 'Does this action require explicit user approval?',
+      inspect: ['action.reversibility', 'action.production_effect', 'policy'],
+    },
+  }),
+
+  security_review_required: defineCheck({
+    id: 'security_review_required',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: {
+      question: 'Does this change require a security review before merge?',
+      inspect: ['security_boundary', 'auth_change', 'secret_handling'],
+    },
+  }),
+
+  verification_scope: defineChoose({
+    id: 'verification_scope',
+    version: 1,
+    evaluator_hint: 'deterministic',
+    instructions: 'How broad should verification be for this change?',
+    options: ['focused', 'package', 'workspace', 'repository'],
+  }),
+});
+
+/**
+ * @param {string} id
+ * @param {object} [overrides] e.g. dynamic options for skill_candidate
+ */
+export function getRegisteredQuestion(id, overrides = {}) {
+  if (id === 'skill_candidate') {
+    const options = Array.isArray(overrides.options) ? overrides.options : [];
+    return defineChoose({
+      id: 'skill_candidate',
+      version: 1,
+      evaluator_hint: overrides.evaluator_hint || 'deterministic',
+      instructions: overrides.instructions || 'Which skill best fits this task from the retrieved candidates?',
+      options,
+      criteria: overrides.criteria || null,
+    });
+  }
+  const base = QUESTION_REGISTRY[id];
+  if (!base) {
+    const err = new Error(`unknown_question:${id}`);
+    err.code = 'unknown_question';
+    throw err;
+  }
+  if (!Object.keys(overrides).length) return base;
+  return { ...base, ...overrides, id: base.id, type: base.type };
+}
+
+export function listRegisteredQuestions() {
+  return Object.keys(QUESTION_REGISTRY);
+}

package/src/sam/decision/receipt.js

@@ -0,0 +1,148 @@
+/**
+ * Decision receipts + outcome reconciliation + run/step/action linkage.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { DECISION_RECEIPT_SCHEMA, DECISION_OUTCOME_SCHEMA } from './types.js';
+import { hashDecisionState } from './state.js';
+
+export const OUTCOME_DISPOSITIONS = Object.freeze([
+  'accepted',
+  'rejected',
+  'overridden',
+  'corrected_to',
+  'retry_required',
+  'verification_failed',
+  'user_intervened',
+  'success',
+  'failure',
+]);
+
+/**
+ * @param {object} opts
+ */
+export function createDecisionReceipt(opts = {}) {
+  const decision_id = opts.decision_id || `dec_${randomUUID().replace(/-/g, '').slice(0, 20)}`;
+  return {
+    schema: DECISION_RECEIPT_SCHEMA,
+    decision_id,
+    run_id: opts.run_id ?? null,
+    step_id: opts.step_id ?? null,
+    action_id: opts.action_id ?? null,
+    outcome_id: null,
+    question_contract: opts.question_contract || null,
+    question_ids: Array.isArray(opts.question_ids) ? opts.question_ids : [],
+    question_versions: opts.question_versions || {},
+    evaluator: opts.evaluator || null,
+    evaluators: opts.evaluators || [],
+    state_hash: opts.state_hash || (opts.state ? hashDecisionState(opts.state) : null),
+    answers: opts.answers || {},
+    policy_result: opts.policy_result || null,
+    evidence: Array.isArray(opts.evidence) ? opts.evidence : [],
+    action: opts.action ?? null,
+    outcome: null,
+    created_at: new Date().toISOString(),
+    why: opts.why || buildWhy(opts.answers, opts.policy_result),
+  };
+}
+
+/**
+ * Attach a consequential outcome to a receipt (pass/fail + human corrections).
+ * Passive /why with no correction is NOT treated as a strong correctness label.
+ *
+ * @param {object} receipt
+ * @param {object} outcome
+ */
+export function appendOutcome(receipt, outcome) {
+  if (!receipt || receipt.schema !== DECISION_RECEIPT_SCHEMA) {
+    const err = new Error('invalid_receipt');
+    err.code = 'invalid_receipt';
+    throw err;
+  }
+  const disposition = normalizeDisposition(outcome);
+  const outcome_id = outcome.outcome_id || `out_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+  const normalized = {
+    schema: DECISION_OUTCOME_SCHEMA,
+    outcome_id,
+    success: outcome.success != null ? Boolean(outcome.success) : disposition === 'accepted' || disposition === 'success',
+    disposition,
+    human_corrected: Boolean(outcome.human_corrected || disposition === 'overridden' || disposition === 'corrected_to' || disposition === 'user_intervened'),
+    corrected_to: outcome.corrected_to ?? null,
+    user_override: Boolean(outcome.user_override),
+    actual_class: outcome.actual_class ?? null,
+    duration_ms: Number.isFinite(Number(outcome.duration_ms)) ? Number(outcome.duration_ms) : null,
+    retries: Number.isInteger(outcome.retries) ? outcome.retries : null,
+    verification: Array.isArray(outcome.verification) ? outcome.verification : [],
+    // Passive acceptance is weak evidence — do not treat as calibrated label
+    label_strength: outcome.label_strength
+      || (outcome.human_corrected || disposition === 'corrected_to' || disposition === 'overridden'
+        ? 'supervised'
+        : disposition === 'accepted' && outcome.explicit_accept
+          ? 'explicit_accept'
+          : 'weak_passive'),
+    recorded_at: new Date().toISOString(),
+  };
+  return {
+    ...receipt,
+    action_id: outcome.action_id ?? receipt.action_id,
+    outcome_id,
+    outcome: normalized,
+    updated_at: normalized.recorded_at,
+  };
+}
+
+/**
+ * Link an executed action onto a receipt before outcome is known.
+ */
+export function attachAction(receipt, action = {}) {
+  if (!receipt || receipt.schema !== DECISION_RECEIPT_SCHEMA) {
+    const err = new Error('invalid_receipt');
+    err.code = 'invalid_receipt';
+    throw err;
+  }
+  const action_id = action.action_id || `act_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+  return {
+    ...receipt,
+    action_id,
+    action: {
+      action_id,
+      kind: action.kind || null,
+      summary: action.summary || null,
+      started_at: action.started_at || new Date().toISOString(),
+      ...action,
+    },
+    updated_at: new Date().toISOString(),
+  };
+}
+
+function normalizeDisposition(outcome = {}) {
+  if (outcome.disposition && OUTCOME_DISPOSITIONS.includes(outcome.disposition)) {
+    return outcome.disposition;
+  }
+  if (outcome.human_corrected && outcome.corrected_to != null) return 'corrected_to';
+  if (outcome.user_override) return 'overridden';
+  if (outcome.success === true) return 'accepted';
+  if (outcome.success === false) return 'failure';
+  return 'accepted';
+}
+
+function buildWhy(answers = {}, policy = null) {
+  const decisions = Object.entries(answers).map(([id, a]) => ({
+    id,
+    type: a.type,
+    value: a.value,
+    support: a.support ?? null,
+    confidence_estimate: a.confidence_estimate ?? null,
+  }));
+  return {
+    surface: 'agentsam.why.v1',
+    decisions,
+    policy: policy
+      ? {
+          allowed: policy.allowed,
+          require_approval: policy.require_approval,
+          authorization_source: policy.authorization_source,
+        }
+      : null,
+  };
+}

package/src/sam/decision/state.js

@@ -0,0 +1,117 @@
+/**
+ * Shared SAM decision state — minimal projection for a question set.
+ */
+
+import { createHash } from 'node:crypto';
+import { DECISION_STATE_SCHEMA } from './types.js';
+
+/**
+ * @param {object} [partial]
+ * @returns {object}
+ */
+export function buildDecisionState(partial = {}) {
+  const state = {
+    schema: DECISION_STATE_SCHEMA,
+    intent: partial.intent ?? null,
+    goal: partial.goal ?? null,
+    repository: partial.repository
+      ? {
+          repository_id: partial.repository.repository_id ?? null,
+          root: partial.repository.root ?? null,
+          branch: partial.repository.branch ?? null,
+          dirty: partial.repository.dirty ?? null,
+          merkle_root: partial.repository.merkle_root ?? null,
+        }
+      : null,
+    code: partial.code
+      ? {
+          relevant_nodes: Array.isArray(partial.code.relevant_nodes) ? [...partial.code.relevant_nodes] : [],
+          dependency_nodes: Array.isArray(partial.code.dependency_nodes) ? [...partial.code.dependency_nodes] : [],
+          affected_packages: Array.isArray(partial.code.affected_packages) ? [...partial.code.affected_packages] : [],
+        }
+      : null,
+    runtime: partial.runtime
+      ? {
+          terminal_lanes: partial.runtime.terminal_lanes ?? null,
+          connection_health: partial.runtime.connection_health ?? null,
+          capabilities: Array.isArray(partial.runtime.capabilities) ? [...partial.runtime.capabilities] : [],
+        }
+      : null,
+    tools: partial.tools ?? null,
+    skills: partial.skills ?? null,
+    models: partial.models ?? null,
+    constraints: partial.constraints
+      ? {
+          budget: partial.constraints.budget ?? null,
+          latency: partial.constraints.latency ?? null,
+          approval: partial.constraints.approval ?? null,
+          security: partial.constraints.security ?? null,
+          production_write: partial.constraints.production_write ?? null,
+          isolation_required: partial.constraints.isolation_required ?? null,
+          requires_local_files: partial.constraints.requires_local_files ?? null,
+        }
+      : null,
+    evidence: Array.isArray(partial.evidence) ? [...partial.evidence] : [],
+    history: partial.history ?? null,
+    metadata: partial.metadata && typeof partial.metadata === 'object' ? { ...partial.metadata } : {},
+    facts: partial.facts && typeof partial.facts === 'object' ? { ...partial.facts } : {},
+  };
+  return Object.freeze(deepFreezeShallow(state));
+}
+
+/**
+ * Stable hash of decision state for receipts.
+ * @param {object} state
+ */
+export function hashDecisionState(state) {
+  return createHash('sha256').update(stableStringify(state)).digest('hex');
+}
+
+/**
+ * Project only the keys needed for a question set (does not mutate input).
+ * @param {object} state
+ * @param {string[]} paths
+ */
+export function projectState(state, paths = []) {
+  if (!paths.length) return buildDecisionState(state);
+  const out = { schema: DECISION_STATE_SCHEMA, facts: {}, evidence: [], metadata: {} };
+  for (const p of paths) {
+    const value = getPath(state, p);
+    if (value !== undefined) setPath(out, p, value);
+  }
+  if (state.evidence) out.evidence = [...state.evidence];
+  return buildDecisionState({ ...state, ...out });
+}
+
+function getPath(obj, dotted) {
+  const parts = String(dotted).split('.');
+  let cur = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function setPath(obj, dotted, value) {
+  const parts = String(dotted).split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const p = parts[i];
+    if (cur[p] == null || typeof cur[p] !== 'object') cur[p] = {};
+    cur = cur[p];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function deepFreezeShallow(value) {
+  if (!value || typeof value !== 'object') return value;
+  return value;
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}

package/src/sam/decision/types.js

@@ -0,0 +1,22 @@
+/**
+ * SAM decision contracts — Systematic Autonomous Machinery.
+ * choose / score / check — AgentSam-native, no vendor terminology.
+ */
+
+export const DECISION_STATE_SCHEMA = 'agentsam.decision-state.v1';
+export const DECISION_QUESTION_SCHEMA = 'agentsam.decision-question.v1';
+export const DECISION_ANSWER_SCHEMA = 'agentsam.decision-answer.v1';
+export const DECISION_EVALUATION_SCHEMA = 'agentsam.decision-evaluation.v1';
+export const DECISION_RECEIPT_SCHEMA = 'agentsam.decision-receipt.v1';
+export const DECISION_OUTCOME_SCHEMA = 'agentsam.decision-outcome.v1';
+export const DECISION_CALIBRATION_SCHEMA = 'agentsam.decision-calibration.v1';
+
+/** @typedef {'choose'|'score'|'check'} QuestionType */
+/** @typedef {'deterministic'|'heuristic'|'graph'|'semantic'|'calibrated-statistical'} EvaluatorKind */
+
+/**
+ * Confidence semantics:
+ * - confidence_estimate / support: raw evaluator concentration or proposition support
+ * - probabilities: ONLY when evaluator has a defined probabilistic interpretation
+ * - calibrated_probability: ONLY after empirical calibration with calibration_id
+ */