@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/src/sam/planning/goap.js

@@ -0,0 +1,177 @@
+/**
+ * Thin GOAP adapter over planAStar.
+ * Turns precondition/effect action catalogs into an A* search space.
+ */
+
+import { planAStar, ASTAR_ENGINE } from './astar.js';
+import {
+  applyEffects,
+  cloneState,
+  goalSatisfied,
+  preconditionsMet,
+  stableStateKey,
+} from './state.js';
+
+export const GOAP_ENGINE = 'sam-goap-astar-v1';
+
+/**
+ * @typedef {object} GoapAction
+ * @property {string} id
+ * @property {number} [cost]
+ * @property {Record<string, unknown>} [preconditions]
+ * @property {Record<string, unknown>} [effects]
+ */
+
+/**
+ * @param {object} opts
+ * @param {Record<string, unknown>} opts.initialState
+ * @param {Record<string, unknown>} opts.goal
+ * @param {GoapAction[]} opts.actions
+ * @param {(state: Record<string, unknown>) => number} [opts.heuristic]
+ * @param {number} [opts.maxExpansions]
+ * @param {AbortSignal} [opts.signal]
+ */
+export function planGoap(opts = {}) {
+  const {
+    initialState,
+    goal,
+    actions,
+    heuristic,
+    maxExpansions,
+    signal,
+  } = opts;
+
+  if (!initialState || typeof initialState !== 'object' || Array.isArray(initialState)) {
+    return {
+      ok: false,
+      status: 'invalid_input',
+      plan: [],
+      action_ids: [],
+      total_cost: 0,
+      expanded_states: 0,
+      generated_states: 0,
+      frontier_peak: 0,
+      elapsed_ms: 0,
+      engine: GOAP_ENGINE,
+      error: 'initialState must be a plain object',
+    };
+  }
+  if (!goal || typeof goal !== 'object' || Array.isArray(goal)) {
+    return {
+      ok: false,
+      status: 'invalid_input',
+      plan: [],
+      action_ids: [],
+      total_cost: 0,
+      expanded_states: 0,
+      generated_states: 0,
+      frontier_peak: 0,
+      elapsed_ms: 0,
+      engine: GOAP_ENGINE,
+      error: 'goal must be a plain object',
+    };
+  }
+  if (!Array.isArray(actions)) {
+    return {
+      ok: false,
+      status: 'invalid_input',
+      plan: [],
+      action_ids: [],
+      total_cost: 0,
+      expanded_states: 0,
+      generated_states: 0,
+      frontier_peak: 0,
+      elapsed_ms: 0,
+      engine: GOAP_ENGINE,
+      error: 'actions must be an array',
+    };
+  }
+
+  // Normalize once; never mutate caller arrays/objects during search.
+  const catalog = actions.map((action, index) => {
+    if (!action || typeof action !== 'object') {
+      throw new TypeError(`goap_action_invalid:${index}`);
+    }
+    const id = typeof action.id === 'string' && action.id ? action.id : `action_${index}`;
+    const cost = Number(action.cost);
+    return {
+      id,
+      cost: Number.isFinite(cost) && cost >= 0 ? cost : 1,
+      preconditions: action.preconditions && typeof action.preconditions === 'object'
+        ? { ...action.preconditions }
+        : {},
+      effects: action.effects && typeof action.effects === 'object'
+        ? { ...action.effects }
+        : {},
+    };
+  });
+
+  // Deterministic expansion order: cost asc, then id.
+  catalog.sort((a, b) => (a.cost - b.cost) || a.id.localeCompare(b.id));
+
+  const start = cloneState(initialState);
+  const goalFacts = { ...goal };
+
+  let result;
+  try {
+    result = planAStar({
+      initialState: start,
+      isGoal: (state) => goalSatisfied(/** @type {Record<string, unknown>} */ (state), goalFacts),
+      expand: (state) => {
+        const world = /** @type {Record<string, unknown>} */ (state);
+        /** @type {Array<{ action: string, nextState: Record<string, unknown>, cost: number }>} */
+        const out = [];
+        for (const action of catalog) {
+          if (!preconditionsMet(world, action.preconditions)) continue;
+          const nextState = applyEffects(world, action.effects);
+          // Skip no-ops that do not change state (avoids infinite self-loops).
+          if (stableStateKey(nextState) === stableStateKey(world)) continue;
+          out.push({
+            action: action.id,
+            nextState,
+            cost: action.cost,
+          });
+        }
+        return out;
+      },
+      heuristic: typeof heuristic === 'function'
+        ? (state) => heuristic(/** @type {Record<string, unknown>} */ (state))
+        : () => 0,
+      stateKey: stableStateKey,
+      maxExpansions,
+      signal,
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      status: 'invalid_input',
+      plan: [],
+      action_ids: [],
+      total_cost: 0,
+      expanded_states: 0,
+      generated_states: 0,
+      frontier_peak: 0,
+      elapsed_ms: 0,
+      engine: GOAP_ENGINE,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const actionIds = result.plan.map((step) => String(step.action));
+  return {
+    ok: result.ok,
+    status: result.status,
+    plan: actionIds,
+    action_ids: actionIds,
+    total_cost: result.total_cost,
+    cost: result.total_cost,
+    final_state: result.final_state,
+    expanded_states: result.expanded_states,
+    generated_states: result.generated_states,
+    frontier_peak: result.frontier_peak,
+    elapsed_ms: result.elapsed_ms,
+    engine: GOAP_ENGINE,
+    astar_engine: ASTAR_ENGINE,
+    error: result.error,
+  };
+}

package/src/sam/planning/index.js

@@ -0,0 +1,21 @@
+/**
+ * SAM planning primitives — Systematic Autonomous Machinery.
+ */
+
+export {
+  planAStar,
+  ASTAR_ENGINE,
+} from './astar.js';
+
+export {
+  planGoap,
+  GOAP_ENGINE,
+} from './goap.js';
+
+export {
+  stableStateKey,
+  cloneState,
+  applyEffects,
+  goalSatisfied,
+  preconditionsMet,
+} from './state.js';

package/src/sam/planning/state.js

@@ -0,0 +1,84 @@
+/**
+ * Deterministic state helpers for SAM planners.
+ * Pure machine utilities — no D1, model, or repository assumptions.
+ */
+
+/**
+ * Stable deterministic identity for plain object / array / primitive state.
+ * Object keys are sorted so insertion order does not affect identity.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function stableStateKey(value) {
+  return stringifyStable(value);
+}
+
+/**
+ * Shallow clone of a plain object state (GOAP worlds are flat fact maps).
+ * @param {Record<string, unknown>|null|undefined} state
+ * @returns {Record<string, unknown>}
+ */
+export function cloneState(state) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) {
+    return {};
+  }
+  return { ...state };
+}
+
+/**
+ * Merge effects onto a clone of state (never mutates input).
+ * @param {Record<string, unknown>} state
+ * @param {Record<string, unknown>|null|undefined} effects
+ * @returns {Record<string, unknown>}
+ */
+export function applyEffects(state, effects) {
+  const next = cloneState(state);
+  if (!effects || typeof effects !== 'object') return next;
+  for (const [key, value] of Object.entries(effects)) {
+    next[key] = value;
+  }
+  return next;
+}
+
+/**
+ * True when every desired goal fact matches current state (===).
+ * @param {Record<string, unknown>} state
+ * @param {Record<string, unknown>|null|undefined} goal
+ */
+export function goalSatisfied(state, goal) {
+  if (!goal || typeof goal !== 'object') return true;
+  return Object.entries(goal).every(([key, value]) => state[key] === value);
+}
+
+/**
+ * True when every precondition matches current state (===).
+ * @param {Record<string, unknown>} state
+ * @param {Record<string, unknown>|null|undefined} preconditions
+ */
+export function preconditionsMet(state, preconditions) {
+  if (!preconditions || typeof preconditions !== 'object') return true;
+  return Object.entries(preconditions).every(([key, value]) => state[key] === value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stringifyStable(value) {
+  if (value === null) return 'null';
+  const t = typeof value;
+  if (t === 'undefined') return 'undefined';
+  if (t === 'number' || t === 'boolean' || t === 'bigint') return String(value);
+  if (t === 'string') return JSON.stringify(value);
+  if (t === 'symbol') return value.toString();
+  if (typeof value === 'function') return `"fn:${value.name || 'anonymous'}"`;
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stringifyStable(item)).join(',')}]`;
+  }
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
+  if (t === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stringifyStable(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(String(value));
+}

package/src/sam/registry.js

@@ -0,0 +1,48 @@
+/** @type {Map<string, import('./types.js').SamOperationDef>} */
+const operations = new Map();
+
+/**
+ * @param {import('./types.js').SamOperationDef} def
+ */
+export function registerSamOperation(def) {
+  if (operations.has(def.id)) {
+    throw new Error(`sam_operation_already_registered:${def.id}`);
+  }
+  operations.set(def.id, def);
+  return def;
+}
+
+/**
+ * @param {string} id
+ */
+export function getSamOperation(id) {
+  return operations.get(id) || null;
+}
+
+export function listSamOperations() {
+  return [...operations.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function clearSamRegistryForTests() {
+  operations.clear();
+}
+
+/**
+ * Compact cards for discover / tool selection.
+ * @param {import('./types.js').SamOperationDef} def
+ */
+export function toSamOperationCard(def) {
+  return {
+    id: def.id,
+    module: def.module,
+    action: def.action,
+    summary: def.summary,
+    model: def.execution.model,
+    risk: def.risk,
+    network: def.execution.network,
+    side_effects: def.execution.sideEffects,
+    lanes: [...def.execution.lanes],
+    status: def.status || 'stable',
+    cli: def.cli?.command || [],
+  };
+}

package/src/sam/result.js

@@ -0,0 +1,77 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { SAM_RESULT_SCHEMA } from './types.js';
+
+/**
+ * @param {unknown} value
+ */
+export function hashJson(value) {
+  try {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.operation
+ * @param {string} [opts.module]
+ * @param {boolean} opts.ok
+ * @param {unknown} opts.data
+ * @param {string} opts.startedAt
+ * @param {import('./types.js').SamLane} [opts.lane]
+ * @param {boolean} [opts.deterministic]
+ * @param {boolean} [opts.modelUsed]
+ * @param {string[]} [opts.sideEffects]
+ * @param {unknown} [opts.input]
+ * @param {unknown} [opts.error]
+ * @param {unknown[]} [opts.warnings]
+ * @param {import('./types.js').SamReceipt['status']} [opts.status]
+ * @returns {import('./types.js').SamResult}
+ */
+export function buildSamResult({
+  operation,
+  module,
+  ok,
+  data,
+  startedAt,
+  lane = 'local',
+  deterministic = true,
+  modelUsed = false,
+  sideEffects = [],
+  input,
+  error,
+  warnings,
+  status,
+}) {
+  const completedAt = new Date().toISOString();
+  /** @type {import('./types.js').SamResult} */
+  const result = {
+    schema: SAM_RESULT_SCHEMA,
+    operation,
+    ok,
+    data: ok ? data : (data ?? null),
+    receipt: {
+      id: `samr_${randomUUID().replace(/-/g, '').slice(0, 24)}`,
+      operation,
+      module,
+      started_at: startedAt,
+      completed_at: completedAt,
+      execution: {
+        lane,
+        deterministic,
+        model_used: modelUsed,
+      },
+      side_effects: sideEffects,
+      input_hash: input === undefined ? null : hashJson(input),
+      output_hash: ok ? hashJson(data) : null,
+      status: status || (ok ? 'completed' : 'failed'),
+    },
+  };
+  if (warnings?.length) result.warnings = warnings;
+  if (error !== undefined) result.error = error;
+  if (!modelUsed) {
+    result.usage = { provider_calls: 0, cost_usd: 0 };
+  }
+  return result;
+}

package/src/sam/seed.js

@@ -0,0 +1,44 @@
+import { registerSamOperation, getSamOperation } from './registry.js';
+import { repositoryInspect } from './operations/repository-inspect.js';
+import { brandScanOp } from './operations/brand-scan.js';
+import { securityScanOp } from './operations/security-scan.js';
+import { terminalExecOp } from './operations/terminal-exec.js';
+import { cadBlenderInspectOp } from './operations/cad-blender-inspect.js';
+import { codebaseindexIngestOp } from './operations/codebaseindex-ingest.js';
+import { planningAstarOp } from './operations/planning-astar.js';
+import { planningGoapOp } from './operations/planning-goap.js';
+import { decisionEvaluateOp } from './operations/decision-evaluate.js';
+
+export const SEED_OPERATIONS = [
+  repositoryInspect,
+  brandScanOp,
+  securityScanOp,
+  terminalExecOp,
+  cadBlenderInspectOp,
+  codebaseindexIngestOp,
+  planningAstarOp,
+  planningGoapOp,
+  decisionEvaluateOp,
+];
+
+let seeded = false;
+
+/**
+ * Register seed SAM operations (idempotent).
+ * Handlers reuse existing capability implementations — no duplicate machinery.
+ */
+export function ensureSeedOperations() {
+  if (seeded) return SEED_OPERATIONS;
+  for (const op of SEED_OPERATIONS) {
+    if (!getSamOperation(op.id)) {
+      registerSamOperation(op);
+    }
+  }
+  seeded = true;
+  return SEED_OPERATIONS;
+}
+
+/** @internal */
+export function resetSeedFlagForTests() {
+  seeded = false;
+}

package/src/sam/types.js

@@ -0,0 +1,91 @@
+/**
+ * SAM — Systematic Autonomous Machinery
+ * @see docs/architecture/SAM_KERNEL.md
+ */
+
+export const SAM_RESULT_SCHEMA = 'agentsam.result.v1';
+export const SAM_EXPANSION = 'Systematic Autonomous Machinery';
+
+/** @typedef {'local'|'remote'|'sandbox'|'platform'} SamLane */
+/** @typedef {'never'|'optional'|'required'} SamModelPolicy */
+/** @typedef {'none'|'optional'|'required'} SamNetworkPolicy */
+/** @typedef {'none'|'local_write'|'remote_read'|'remote_write'|'deploy'|'billable'} SamSideEffects */
+/** @typedef {'read_only'|'write'|'privileged'} SamRisk */
+/** @typedef {'never'|'optional'|'required'} SamSpendPolicy */
+
+/**
+ * @typedef {object} SamExecutionMeta
+ * @property {SamLane[]} lanes
+ * @property {SamModelPolicy} model
+ * @property {SamNetworkPolicy} network
+ * @property {SamSideEffects} sideEffects
+ * @property {SamSpendPolicy} [embedding]
+ * @property {SamSpendPolicy} [provider_spend]
+ */
+
+/**
+ * Rich product capability contract — not just catalog cards.
+ * @typedef {object} SamOperationDef
+ * @property {string} id
+ * @property {number} version
+ * @property {string} module
+ * @property {string} action
+ * @property {string} summary
+ * @property {string} [purpose]
+ * @property {string} [outcome]
+ * @property {string} [description]
+ * @property {SamExecutionMeta} execution
+ * @property {{ account?: boolean, provider?: string[] }} [auth]
+ * @property {SamRisk} risk
+ * @property {string} [input_schema]
+ * @property {string} [output_schema]
+ * @property {string[]} [capabilities]
+ * @property {string[]} [accepts]
+ * @property {string[]} [phases]
+ * @property {string[]} [artifacts]
+ * @property {{ id?: string, help?: boolean }|string|null} [skill]
+ * @property {{ available?: boolean, operation?: string }} [preview]
+ * @property {{ command?: string[][] }} [cli]
+ * @property {{ section?: string, examples?: string[] }} [docs]
+ * @property {'stable'|'experimental'|'stub'|'deprecated'} [status]
+ * @property {(input: unknown, ctx: SamOperationContext) => Promise<unknown>|unknown} handler
+ */
+
+/**
+ * @typedef {object} SamOperationContext
+ * @property {AbortSignal} [signal]
+ * @property {Record<string, unknown>} [execution]
+ * @property {string} [cwd]
+ * @property {Record<string, string|undefined>} [env]
+ */
+
+/**
+ * @typedef {object} SamReceipt
+ * @property {string} id
+ * @property {string} operation
+ * @property {string} [module]
+ * @property {string} started_at
+ * @property {string} completed_at
+ * @property {{ lane: SamLane, deterministic: boolean, model_used: boolean }} execution
+ * @property {string[]} [side_effects]
+ * @property {string|null} [input_hash]
+ * @property {string|null} [output_hash]
+ * @property {'completed'|'failed'|'cancelled'} status
+ */
+
+/**
+ * @typedef {object} SamResult
+ * @property {'agentsam.result.v1'} schema
+ * @property {string} operation
+ * @property {number} [operation_version]
+ * @property {boolean} ok
+ * @property {unknown} data
+ * @property {SamReceipt} receipt
+ * @property {unknown[]} [evidence]
+ * @property {unknown[]} [artifacts]
+ * @property {{ provider_calls: number, model_calls?: number, embedding_calls?: number, cost_usd?: number }} [usage]
+ * @property {{ skill?: string|null }} [help]
+ * @property {unknown[]} [warnings]
+ * @property {unknown[]} [diagnostics]
+ * @property {unknown} [error]
+ */

package/src/skills/catalog.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const skillsRoot = path.resolve(moduleDir, '..', '..', 'skills');
+const catalogPath = path.join(skillsRoot, 'catalog.json');
+
+function readCatalog() {
+  return JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+}
+
+function normalizeSkillId(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function resolveSkillRecord(idOrAlias) {
+  const needle = normalizeSkillId(idOrAlias);
+  if (!needle) return null;
+  const catalog = readCatalog();
+  return catalog.skills.find((skill) => {
+    if (normalizeSkillId(skill.id) === needle) return true;
+    return (skill.aliases ?? []).some((alias) => normalizeSkillId(alias) === needle);
+  }) ?? null;
+}
+
+function safeSkillPath(relativePath) {
+  const resolved = path.resolve(skillsRoot, relativePath);
+  const rootWithSep = `${skillsRoot}${path.sep}`;
+  if (resolved !== skillsRoot && !resolved.startsWith(rootWithSep)) {
+    throw new Error('skill_path_outside_root');
+  }
+  return resolved;
+}
+
+export function listSkills() {
+  return readCatalog().skills.map((skill) => ({ ...skill }));
+}
+
+export function getSkill(idOrAlias) {
+  const skill = resolveSkillRecord(idOrAlias);
+  return skill ? { ...skill } : null;
+}
+
+export function loadSkill(idOrAlias, options = {}) {
+  const skill = resolveSkillRecord(idOrAlias);
+  if (!skill) throw new Error(`unknown_skill:${idOrAlias}`);
+
+  const result = {
+    skill: { ...skill },
+    instructions: fs.readFileSync(safeSkillPath(skill.entry), 'utf8'),
+  };
+
+  if (options.references === true) {
+    result.references = (skill.references ?? []).map((relativePath) => ({
+      path: relativePath,
+      content: fs.readFileSync(safeSkillPath(relativePath), 'utf8'),
+    }));
+  }
+
+  return result;
+}
+
+export const AGENTSAM_SKILLS_ROOT = skillsRoot;