@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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

package/src/sam/operations/planning-astar.js

@@ -0,0 +1,77 @@
+import { defineSamOperation } from '../define.js';
+import { planAStar, ASTAR_ENGINE } from '../planning/astar.js';
+import { hashJson } from '../result.js';
+import { stableStateKey } from '../planning/state.js';
+
+/**
+ * Pure A* search — domain-independent machine primitive.
+ * Input supplies expand/isGoal; handler does not call models or D1.
+ */
+export const planningAstarOp = defineSamOperation({
+  id: 'planning.astar',
+  version: 1,
+  module: 'planning',
+  action: 'astar',
+  summary: 'Run domain-independent A* search over an explicit expand graph.',
+  purpose:
+    'Find a lowest-cost path through an explicit state graph using f(n)=g(n)+h(n).',
+  outcome:
+    'Return a typed plan with cost, expansion stats, and deterministic receipt evidence.',
+  description:
+    'Systematic Autonomous Machinery planner. Default heuristic is 0 (Dijkstra). No model spend.',
+  skill: { id: 'agentsam-app-fundamentals', help: true },
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    embedding: 'never',
+    network: 'none',
+    sideEffects: 'none',
+    provider_spend: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['planning.astar'],
+  artifacts: ['planning.plan', 'planning.receipt'],
+  cli: { command: [] },
+  docs: { section: 'Planning', examples: ['planning-astar-basic'] },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const {
+      initialState,
+      isGoal,
+      expand,
+      heuristic,
+      stateKey,
+      maxExpansions,
+    } = input || {};
+
+    if (typeof isGoal !== 'function' || typeof expand !== 'function') {
+      const err = new Error('planning.astar requires isGoal and expand functions in input');
+      err.code = 'invalid_input';
+      throw err;
+    }
+
+    const result = planAStar({
+      initialState,
+      isGoal,
+      expand,
+      heuristic: typeof heuristic === 'function' ? heuristic : undefined,
+      stateKey: typeof stateKey === 'function' ? stateKey : stableStateKey,
+      maxExpansions,
+      signal: ctx.signal,
+    });
+
+    return {
+      ...result,
+      engine: ASTAR_ENGINE,
+      evidence: {
+        initial_state_hash: hashJson(initialState),
+        selected_actions: result.plan.map((step) => step.action),
+        total_cost: result.total_cost,
+        expanded_states: result.expanded_states,
+        max_expansions: maxExpansions ?? null,
+        engine: ASTAR_ENGINE,
+        deterministic: true,
+      },
+    };
+  },
+});

package/src/sam/operations/planning-goap.js

@@ -0,0 +1,60 @@
+import { defineSamOperation } from '../define.js';
+import { planGoap, GOAP_ENGINE } from '../planning/goap.js';
+import { hashJson } from '../result.js';
+
+/**
+ * GOAP planning via A* — precondition/effect actions over flat world state.
+ */
+export const planningGoapOp = defineSamOperation({
+  id: 'planning.goap',
+  version: 1,
+  module: 'planning',
+  action: 'goap',
+  summary: 'Plan a GOAP action sequence with A* (sam-goap-astar-v1).',
+  purpose:
+    'Select a lowest-cost sequence of precondition/effect actions that satisfies a goal.',
+  outcome:
+    'Return action ids, total cost, expansion stats, and deterministic receipt evidence.',
+  description:
+    'Thin GOAP adapter over planning.astar. Replaces greedy cheapest-applicable loops.',
+  skill: { id: 'agentsam-app-fundamentals', help: true },
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    embedding: 'never',
+    network: 'none',
+    sideEffects: 'none',
+    provider_spend: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['planning.goap', 'planning.astar'],
+  artifacts: ['planning.goap.plan', 'planning.receipt'],
+  cli: { command: [['plan', 'brand', '--goap']] },
+  docs: { section: 'Planning', examples: ['planning-goap-basic'] },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const { initialState, goal, actions, heuristic, maxExpansions } = input || {};
+    const result = planGoap({
+      initialState,
+      goal,
+      actions,
+      heuristic: typeof heuristic === 'function' ? heuristic : undefined,
+      maxExpansions,
+      signal: ctx.signal,
+    });
+
+    return {
+      ...result,
+      evidence: {
+        initial_state_hash: hashJson(initialState),
+        goal_hash: hashJson(goal),
+        selected_actions: result.action_ids || result.plan || [],
+        total_cost: result.total_cost ?? result.cost,
+        expanded_states: result.expanded_states,
+        max_expansions: maxExpansions ?? null,
+        engine: GOAP_ENGINE,
+        deterministic: true,
+      },
+    };
+  },
+});