@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

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
+ */

package/src/sam/decision/validate.js

@@ -0,0 +1,200 @@
+/**
+ * Question builders + validation for choose / score / check.
+ */
+
+import { DECISION_QUESTION_SCHEMA } from './types.js';
+
+/**
+ * @param {object} def
+ */
+export function defineChoose(def) {
+  return validateQuestion({
+    schema: DECISION_QUESTION_SCHEMA,
+    id: def.id,
+    type: 'choose',
+    version: def.version ?? 1,
+    instructions: def.instructions ?? null,
+    criteria: def.criteria ?? null,
+    options: def.options,
+    evaluator_hint: def.evaluator_hint ?? null,
+  });
+}
+
+/**
+ * @param {object} def
+ */
+export function defineScore(def) {
+  return validateQuestion({
+    schema: DECISION_QUESTION_SCHEMA,
+    id: def.id,
+    type: 'score',
+    version: def.version ?? 1,
+    instructions: def.instructions ?? null,
+    criteria: def.criteria ?? null,
+    levels: def.levels,
+    evaluator_hint: def.evaluator_hint ?? null,
+  });
+}
+
+/**
+ * @param {object} def
+ */
+export function defineCheck(def) {
+  return validateQuestion({
+    schema: DECISION_QUESTION_SCHEMA,
+    id: def.id,
+    type: 'check',
+    version: def.version ?? 1,
+    instructions: def.instructions ?? null,
+    criteria: def.criteria ?? null,
+    evaluator_hint: def.evaluator_hint ?? null,
+  });
+}
+
+/**
+ * Fail-closed validation.
+ * @param {object} question
+ */
+export function validateQuestion(question) {
+  if (!question || typeof question !== 'object') {
+    throw fail('invalid_question', 'question must be an object');
+  }
+  if (typeof question.id !== 'string' || !question.id.trim()) {
+    throw fail('invalid_question_id', 'question.id is required');
+  }
+  if (!['choose', 'score', 'check'].includes(question.type)) {
+    throw fail('invalid_question_type', `unsupported type: ${question.type}`);
+  }
+  if (question.instructions != null && !isAllowedInstructions(question.instructions)) {
+    throw fail('invalid_instructions', 'instructions must be string|object|array|null');
+  }
+  if (question.criteria != null && !isAllowedCriteria(question.criteria)) {
+    throw fail('invalid_criteria', 'criteria must be string|object|array|null');
+  }
+
+  if (question.type === 'choose') {
+    const options = normalizeOptions(question.options, question.criteria);
+    if (!options.length) {
+      throw fail('choose_options_required', 'choose requires a finite options set');
+    }
+    return Object.freeze({
+      ...question,
+      schema: DECISION_QUESTION_SCHEMA,
+      options,
+      version: question.version ?? 1,
+    });
+  }
+
+  if (question.type === 'score') {
+    const levels = normalizeLevels(question.levels ?? question.criteria);
+    if (levels.length < 2) {
+      throw fail('score_levels_required', 'score requires an ordered levels list (>=2)');
+    }
+    // Ensure strictly ordered by numeric index (and unique)
+    const seen = new Set();
+    for (let i = 0; i < levels.length; i += 1) {
+      if (seen.has(levels[i].index)) {
+        throw fail('score_levels_unordered', 'score levels must have unique strictly increasing indexes');
+      }
+      seen.add(levels[i].index);
+      if (i > 0 && !(levels[i].index > levels[i - 1].index)) {
+        throw fail('score_levels_unordered', 'score levels must be strictly increasing');
+      }
+    }
+    return Object.freeze({
+      ...question,
+      schema: DECISION_QUESTION_SCHEMA,
+      levels,
+      version: question.version ?? 1,
+    });
+  }
+
+  // check — single proposition; do not smuggle multi-dimensional scoring
+  return Object.freeze({
+    ...question,
+    schema: DECISION_QUESTION_SCHEMA,
+    version: question.version ?? 1,
+  });
+}
+
+/**
+ * @param {object[]} questions
+ */
+export function validateQuestionBatch(questions) {
+  if (!Array.isArray(questions) || !questions.length) {
+    throw fail('empty_batch', 'questions must be a non-empty array');
+  }
+  const ids = new Set();
+  const validated = questions.map((q) => validateQuestion(q));
+  for (const q of validated) {
+    if (ids.has(q.id)) throw fail('duplicate_question_id', `duplicate question id: ${q.id}`);
+    ids.add(q.id);
+  }
+  return validated;
+}
+
+function normalizeOptions(options, criteria) {
+  if (Array.isArray(options)) {
+    return options.map((o) => {
+      if (typeof o === 'string') return o;
+      if (o && typeof o === 'object' && typeof o.id === 'string') return o.id;
+      throw fail('invalid_option', 'choose options must be strings or {id}');
+    });
+  }
+  if (criteria && typeof criteria === 'object' && !Array.isArray(criteria)) {
+    return Object.keys(criteria);
+  }
+  return [];
+}
+
+function normalizeLevels(levels) {
+  if (Array.isArray(levels)) {
+    return levels.map((level, i) => {
+      if (typeof level === 'string') return { index: i, label: level };
+      if (level && typeof level === 'object') {
+        const index = Number(level.index ?? level.value ?? i);
+        if (!Number.isFinite(index)) throw fail('invalid_level_index', 'level index must be numeric');
+        return {
+          index,
+          label: String(level.label ?? level.description ?? `level_${index}`),
+          description: level.description ?? null,
+        };
+      }
+      throw fail('invalid_level', 'score level must be string or object');
+    }).sort((a, b) => a.index - b.index);
+  }
+  if (levels && typeof levels === 'object') {
+    return Object.keys(levels)
+      .map((k) => {
+        const index = Number(k);
+        if (!Number.isFinite(index)) throw fail('invalid_level_key', 'object level keys must be numeric');
+        const v = levels[k];
+        return {
+          index,
+          label: typeof v === 'string' ? v : String(v?.label ?? k),
+          description: typeof v === 'object' ? v.description ?? null : null,
+        };
+      })
+      .sort((a, b) => a.index - b.index);
+  }
+  return [];
+}
+
+function isAllowedInstructions(value) {
+  return (
+    value === null
+    || typeof value === 'string'
+    || Array.isArray(value)
+    || (typeof value === 'object')
+  );
+}
+
+function isAllowedCriteria(value) {
+  return isAllowedInstructions(value);
+}
+
+function fail(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}

package/src/sam/define.js

@@ -0,0 +1,51 @@
+/**
+ * @param {import('./types.js').SamOperationDef} def
+ * @returns {import('./types.js').SamOperationDef}
+ */
+export function defineSamOperation(def) {
+  if (!def || typeof def !== 'object') {
+    throw new TypeError('defineSamOperation requires an operation definition object');
+  }
+  if (typeof def.id !== 'string' || !def.id.includes('.')) {
+    throw new TypeError('defineSamOperation: id must be a dotted operation id (e.g. brand.scan)');
+  }
+  if (typeof def.handler !== 'function') {
+    throw new TypeError(`defineSamOperation(${def.id}): handler must be a function`);
+  }
+  if (!def.module || !def.action) {
+    throw new TypeError(`defineSamOperation(${def.id}): module and action are required`);
+  }
+  if (!def.execution?.lanes?.length || !def.execution.model || !def.execution.network || !def.execution.sideEffects) {
+    throw new TypeError(`defineSamOperation(${def.id}): execution.{lanes,model,network,sideEffects} required`);
+  }
+  if (!def.risk) {
+    throw new TypeError(`defineSamOperation(${def.id}): risk is required`);
+  }
+  if (!def.summary) {
+    throw new TypeError(`defineSamOperation(${def.id}): summary is required`);
+  }
+
+  const skill = typeof def.skill === 'string'
+    ? { id: def.skill, help: true }
+    : def.skill === null
+      ? null
+      : (def.skill || undefined);
+
+  return {
+    ...def,
+    version: def.version ?? 1,
+    status: def.status ?? 'stable',
+    purpose: def.purpose || def.description || def.summary,
+    outcome: def.outcome || undefined,
+    accepts: Array.isArray(def.accepts) ? [...def.accepts] : [],
+    phases: Array.isArray(def.phases) ? [...def.phases] : [],
+    artifacts: Array.isArray(def.artifacts) ? [...def.artifacts] : [],
+    skill,
+    execution: {
+      embedding: 'never',
+      provider_spend: def.execution.model === 'never' ? 'none' : 'possible',
+      ...def.execution,
+      lanes: [...def.execution.lanes],
+    },
+  };
+}

package/src/sam/index.js

@@ -0,0 +1,65 @@
+/**
+ * SAM — Systematic Autonomous Machinery
+ *
+ * AgentSam = product / SDK / CLI
+ * SAM = execution architecture underneath AgentSam
+ * sam = conventional AgentSamClient variable (machinery, not a person)
+ *
+ * @see docs/architecture/SAM_KERNEL.md
+ */
+
+export { SAM_RESULT_SCHEMA, SAM_EXPANSION } from './types.js';
+export { defineSamOperation } from './define.js';
+export {
+  registerSamOperation,
+  getSamOperation,
+  listSamOperations,
+  toSamOperationCard,
+  clearSamRegistryForTests,
+} from './registry.js';
+export { buildSamResult, hashJson } from './result.js';
+export { AgentSamClient, createAgentSamClient } from './client.js';
+export { ensureSeedOperations, SEED_OPERATIONS, resetSeedFlagForTests } from './seed.js';
+export {
+  planAStar,
+  planGoap,
+  ASTAR_ENGINE,
+  GOAP_ENGINE,
+  stableStateKey,
+  cloneState,
+  applyEffects,
+  goalSatisfied,
+  preconditionsMet,
+} from './planning/index.js';
+export {
+  evaluate as evaluateDecisions,
+  evaluateDependentStages,
+  buildDecisionState,
+  defineChoose,
+  defineScore,
+  defineCheck,
+  applyDecisionPolicy,
+  composeUtility,
+  createDecisionReceipt,
+  appendOutcome,
+  attachAction,
+  QUESTION_REGISTRY,
+  getRegisteredQuestion,
+  brierScore,
+  logLoss,
+  expectedCalibrationError,
+  hierarchicalChoose,
+  beamRetain,
+  createSemanticEvaluator,
+  DECISION_STATE_SCHEMA,
+  DECISION_RECEIPT_SCHEMA,
+} from './decision/index.js';
+export {
+  createActivityEvent,
+  createActivityStore,
+  activityFromDecision,
+  ACTIVITY_SCHEMA,
+  ACTIVITY_PHASES,
+  ACTIVITY_EVENTS,
+  DECISION_ACTIVITY_LABELS,
+} from './activity/index.js';

package/src/sam/operations/brand-scan.js

@@ -0,0 +1,62 @@
+import { defineSamOperation } from '../define.js';
+import { repositorySnapshot } from '../../capabilities/index.js';
+import { brandScan } from '../../../packages/agentsam-brand/src/index.js';
+
+/**
+ * Brand intelligence — evidence-backed BrandPack candidate chain (scan remains read-only).
+ * Preview/export are separate operations with local_write side effects.
+ */
+export const brandScanOp = defineSamOperation({
+  id: 'brand.scan',
+  version: 1,
+  module: 'brand',
+  action: 'scan',
+  summary: 'Audit materials into evidence-backed brand intelligence.',
+  purpose:
+    'Audit a repository and supplied materials into evidence-backed brand intelligence.',
+  outcome:
+    'Produce a BrandPack candidate describing observed brand assets, tokens, typography, themes, components, layouts, URLs, content references, conflicts and normalization opportunities.',
+  description:
+    'Deterministic evidence extraction over repository.snapshot authority — tokens, assets, typography, components, conflicts. Does not mutate the source tree.',
+  skill: { id: 'agentsam-app-fundamentals', help: true },
+  accepts: [
+    'repository', 'directory', 'html', 'css', 'javascript', 'typescript',
+    'image', 'svg', 'archive', 'glb', 'gltf', 'text',
+  ],
+  phases: [
+    'inventory',
+    'evidence',
+    'brand-observation',
+    'normalization',
+    'theme-proposal',
+    'brandpack',
+  ],
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'optional',
+    embedding: 'never',
+    network: 'optional',
+    sideEffects: 'none',
+    provider_spend: 'possible',
+  },
+  risk: 'read_only',
+  capabilities: ['brand.scan', 'repository.snapshot'],
+  artifacts: ['brandpack.candidate', 'brand.evidence', 'theme.proposal'],
+  preview: { available: true, operation: 'brand.preview' },
+  cli: { command: [['brand', 'scan']] },
+  docs: { section: 'Brand', examples: ['brand-scan-basic'] },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const root = typeof input === 'string'
+      ? input
+      : (input.root || input.cwd || ctx.cwd || process.cwd());
+    const snapshot = input.snapshot
+      || await repositorySnapshot({ cwd: root, churnDays: 30 });
+    return brandScan({
+      cwd: root,
+      snapshot,
+      maxFiles: input.maxFiles,
+      onEvent: input.onEvent,
+    });
+  },
+});

package/src/sam/operations/cad-blender-inspect.js

@@ -0,0 +1,36 @@
+import { defineSamOperation } from '../define.js';
+import { blenderInspect } from '../../lib/cad/blender.js';
+
+export const cadBlenderInspectOp = defineSamOperation({
+  id: 'cad.blender.inspect',
+  version: 1,
+  module: 'cad',
+  action: 'blender.inspect',
+  summary: 'Inspect an existing Blender source (.blend).',
+  description: 'Host-tool inspect via Blender binary; no model spend. Requires blender on PATH or blenderBin.',
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    network: 'none',
+    sideEffects: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['cad.blender.inspect'],
+  cli: { command: [['cad', 'blender', 'inspect']] },
+  docs: { section: 'CAD' },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const source = input.source || input.input || input.path;
+    if (!source) {
+      throw Object.assign(new Error('cad.blender.inspect requires source/input'), {
+        code: 'sam_invalid_input',
+      });
+    }
+    return blenderInspect({
+      input: source,
+      blenderBin: input.blenderBin,
+      timeoutSeconds: input.timeoutSeconds,
+      cwd: input.cwd || input.root || ctx.cwd || process.cwd(),
+    });
+  },
+});

package/src/sam/operations/codebaseindex-ingest.js

@@ -0,0 +1,49 @@
+import { defineSamOperation } from '../define.js';
+import { runCodebaseindexIngest } from '../../commands/codebaseindex.js';
+
+export const codebaseindexIngestOp = defineSamOperation({
+  id: 'codebaseindex.ingest',
+  version: 1,
+  module: 'codebaseindex',
+  action: 'ingest',
+  summary: 'Inventory-first ingest into the knowledge / code-intelligence spine.',
+  purpose:
+    'Acquire materials, inventory the environment, confirm scope, resolve embed/storage lanes, dry-run, then index.',
+  outcome:
+    'A verified knowledge generation (and optional vectors) with job graph, inventory, and receipt — usable by search/agents without re-learning the product for cloud later.',
+  skill: { id: 'agentsam-codebaseindex', help: true },
+  accepts: [
+    'directory', 'archive', 'html', 'image', 'glb', 'code', 'document', 'repository',
+  ],
+  phases: [
+    'material.stage',
+    'inventory.classify',
+    'scope.resolve',
+    'profile.resolve',
+    'lane.resolve',
+    'plan.dry_run',
+    'index.execute',
+    'generation.verify',
+  ],
+  execution: {
+    lanes: ['local', 'remote', 'platform'],
+    model: 'optional',
+    embedding: 'optional',
+    network: 'optional',
+    sideEffects: 'local_write',
+    provider_spend: 'possible',
+  },
+  risk: 'write',
+  capabilities: ['knowledge.index', 'knowledge.search', 'repository.snapshot'],
+  artifacts: [
+    'inventory.v1',
+    'codebaseindex.job.graph.v1',
+    'knowledge.generation',
+  ],
+  cli: { command: [['codebaseindex'], ['ingest']] },
+  docs: { section: 'Codebaseindex', examples: ['codebaseindex-ingest-wizard'] },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    return runCodebaseindexIngest(input, ctx);
+  },
+});

package/src/sam/operations/decision-evaluate.js

@@ -0,0 +1,59 @@
+import { defineSamOperation } from '../define.js';
+import { evaluate } from '../decision/evaluate.js';
+import { getRegisteredQuestion, listRegisteredQuestions } from '../decision/questions.js';
+
+export const decisionEvaluateOp = defineSamOperation({
+  id: 'decision.evaluate',
+  version: 1,
+  module: 'decision',
+  action: 'evaluate',
+  summary: 'Evaluate choose/score/check questions against a SAM decision state.',
+  purpose:
+    'Run a batch of independent typed decision questions against one explicit state.',
+  outcome:
+    'Return answers, routing, policy result, and an optional decision receipt (/why-compatible).',
+  description:
+    'Systematic Autonomous Machinery decision layer. Prefer deterministic evaluators; semantic evaluators never invent calibrated probabilities.',
+  skill: { id: 'agentsam-app-fundamentals', help: true },
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'optional',
+    embedding: 'never',
+    network: 'optional',
+    sideEffects: 'none',
+    provider_spend: 'possible',
+  },
+  risk: 'read_only',
+  capabilities: ['decision.evaluate', 'planning.goap'],
+  artifacts: ['decision.evaluation', 'decision.receipt'],
+  cli: { command: [] },
+  docs: { section: 'Decision', examples: ['decision-evaluate-terminal'] },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const questions = Array.isArray(input.questions)
+      ? input.questions.map((q) => {
+          if (typeof q === 'string') return getRegisteredQuestion(q, input.overrides?.[q] || {});
+          if (q && typeof q === 'object' && typeof q.id === 'string' && !q.type) {
+            return getRegisteredQuestion(q.id, q);
+          }
+          return q;
+        })
+      : listRegisteredQuestions().slice(0, 0);
+
+    if (!questions.length) {
+      const err = new Error('decision.evaluate requires questions[]');
+      err.code = 'invalid_input';
+      throw err;
+    }
+
+    return evaluate({
+      state: input.state || {},
+      questions,
+      policy: input.policy || {},
+      receipt: input.receipt !== false,
+      action: input.action,
+      evaluators: input.evaluators,
+      signal: ctx.signal,
+    });
+  },
+});