@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/sam/operations/repository-inspect.js

@@ -0,0 +1,72 @@
+import { defineSamOperation } from '../define.js';
+import { repositorySnapshot } from '../../capabilities/index.js';
+
+/**
+ * Ambient repository authority — not merely “look at files.”
+ */
+export const repositoryInspect = defineSamOperation({
+  id: 'repository.inspect',
+  version: 1,
+  module: 'repository',
+  action: 'inspect',
+  summary: 'Establish bounded, content-addressed repository snapshot authority.',
+  purpose:
+    'Establish a bounded, content-addressed machine understanding of the current repository/environment and expose a reusable repository snapshot authority.',
+  outcome:
+    'Return repository identity, revision, merkle/AST evidence, package inventory, systems/layers/facets, and snapshot refs other modules can consume.',
+  description:
+    'Resolve cwd/Git root, portable repository identity, revision/branch/remotes; collect merkle + intelligence; expose bounded index/facet/file views; optionally reuse or save canonical snapshots.',
+  skill: { id: 'agentsam-app-fundamentals', help: true },
+  accepts: ['cwd', 'repository', 'directory', 'snapshot_file'],
+  phases: [
+    'resolve_root',
+    'resolve_identity',
+    'resolve_revision',
+    'snapshot_or_scan',
+    'classify',
+    'project_views',
+    'emit_refs',
+  ],
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    embedding: 'never',
+    network: 'none',
+    sideEffects: 'none',
+    provider_spend: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['repository.snapshot', 'repository.ast', 'repository.merkle'],
+  artifacts: ['repository.snapshot', 'evidence.refs'],
+  cli: { command: [['inspect']] },
+  docs: { section: 'Repository', examples: ['repository-inspect-basic'] },
+  input_schema: 'protocol/capabilities/repository-snapshot-input.schema.json',
+  output_schema: 'protocol/capabilities/repository-snapshot.schema.json',
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const root = typeof input === 'string'
+      ? input
+      : (input.root || input.cwd || ctx.cwd || process.cwd());
+    const churnDays = Number.isInteger(input.churnDays) ? input.churnDays : 30;
+    const snapshot = await repositorySnapshot({ cwd: root, churnDays });
+    return {
+      summary: snapshot.intelligence?.summary || null,
+      repository: snapshot.repository || null,
+      revision: snapshot.repository?.revision_sha || null,
+      snapshot_id: snapshot.snapshot_id || null,
+      snapshot_hash: snapshot.tree?.merkle_root || null,
+      merkle_root: snapshot.tree?.merkle_root || null,
+      file_count: Array.isArray(snapshot.tree?.paths) ? snapshot.tree.paths.length : null,
+      languages: snapshot.intelligence?.languages || null,
+      packages: snapshot.packages || null,
+      systems: snapshot.intelligence?.top_level || null,
+      facets: snapshot.intelligence || null,
+      evidence_refs: {
+        snapshot_id: snapshot.snapshot_id || null,
+        merkle_root: snapshot.tree?.merkle_root || null,
+        metadata_root: snapshot.tree?.metadata_root || null,
+      },
+      snapshot,
+    };
+  },
+});

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

@@ -0,0 +1,33 @@
+import { defineSamOperation } from '../define.js';
+import { scanProjectSecurity } from '../../security/scan.js';
+
+export const securityScanOp = defineSamOperation({
+  id: 'security.scan',
+  version: 1,
+  module: 'security',
+  action: 'scan',
+  summary: 'Scan project dependencies and trust boundary (SCA).',
+  description: 'Deterministic security scan; network optional for OSV advisory lookup.',
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    network: 'optional',
+    sideEffects: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['security.scan'],
+  cli: { command: [['security', 'scan'], ['sca', 'scan']] },
+  docs: { section: 'Security' },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const root = typeof input === 'string'
+      ? input
+      : (input.root || input.cwd || input.projectRoot || ctx.cwd || process.cwd());
+    return scanProjectSecurity({
+      projectRoot: root,
+      offline: input.offline === true,
+      log: input.log,
+      signal: ctx.signal,
+    });
+  },
+});

package/src/sam/operations/terminal-exec.js

@@ -0,0 +1,29 @@
+import { defineSamOperation } from '../define.js';
+import { terminalExec } from '../../capabilities/index.js';
+
+export const terminalExecOp = defineSamOperation({
+  id: 'terminal.exec',
+  version: 1,
+  module: 'terminal',
+  action: 'exec',
+  summary: 'Execute a bounded argv process inside the project root.',
+  description: 'Model-callable terminal primitive with cwd sandboxing, timeouts, and redacted diagnostics.',
+  execution: {
+    lanes: ['local', 'sandbox'],
+    model: 'never',
+    network: 'optional',
+    sideEffects: 'local_write',
+  },
+  risk: 'write',
+  capabilities: ['terminal.exec'],
+  cli: { command: [] },
+  docs: { section: 'Tools' },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const cwd = input.projectRoot || input.cwd || ctx.cwd || process.cwd();
+    return terminalExec(
+      { ...input, cwd: input.cwd || cwd },
+      { cwd, signal: ctx.signal, env: ctx.env },
+    );
+  },
+});

package/src/sam/planning/astar.js

@@ -0,0 +1,311 @@
+/**
+ * Domain-independent A* planner for Systematic Autonomous Machinery.
+ *
+ * f(n) = g(n) + h(n)
+ * Default heuristic is 0 (Dijkstra) — preserve optimality when h is admissible.
+ *
+ * No model / D1 / repository assumptions.
+ */
+
+import { stableStateKey } from './state.js';
+
+export const ASTAR_ENGINE = 'sam-astar-v1';
+
+/** @typedef {'found'|'no_plan'|'budget_exhausted'|'cancelled'|'invalid_input'} AStarStatus */
+
+/**
+ * @typedef {object} AStarStep
+ * @property {unknown} action
+ * @property {unknown} [state]
+ * @property {number} [cost]
+ */
+
+/**
+ * @typedef {object} AStarResult
+ * @property {boolean} ok
+ * @property {AStarStatus} status
+ * @property {AStarStep[]} plan
+ * @property {number} total_cost
+ * @property {unknown} [final_state]
+ * @property {number} expanded_states
+ * @property {number} generated_states
+ * @property {number} frontier_peak
+ * @property {number} elapsed_ms
+ * @property {string} engine
+ * @property {string} [error]
+ */
+
+/**
+ * Binary min-heap keyed by f, then g (prefer deeper when f ties), then order, then stateKey.
+ * Deterministic tie-breaking for reproducible plans.
+ */
+class Frontier {
+  constructor() {
+    /** @type {{ f: number, g: number, order: number, key: string, state: unknown, action: unknown, parentKey: string|null }[]} */
+    this.heap = [];
+  }
+
+  get size() {
+    return this.heap.length;
+  }
+
+  /**
+   * @param {{ f: number, g: number, order: number, key: string, state: unknown, action: unknown, parentKey: string|null }} node
+   */
+  push(node) {
+    this.heap.push(node);
+    this.#siftUp(this.heap.length - 1);
+  }
+
+  pop() {
+    const heap = this.heap;
+    if (!heap.length) return null;
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length && last) {
+      heap[0] = last;
+      this.#siftDown(0);
+    }
+    return top;
+  }
+
+  /**
+   * @param {number} i
+   */
+  #siftUp(i) {
+    const heap = this.heap;
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (compareNodes(heap[i], heap[p]) >= 0) break;
+      [heap[i], heap[p]] = [heap[p], heap[i]];
+      i = p;
+    }
+  }
+
+  /**
+   * @param {number} i
+   */
+  #siftDown(i) {
+    const heap = this.heap;
+    const n = heap.length;
+    while (true) {
+      let best = i;
+      const l = i * 2 + 1;
+      const r = l + 1;
+      if (l < n && compareNodes(heap[l], heap[best]) < 0) best = l;
+      if (r < n && compareNodes(heap[r], heap[best]) < 0) best = r;
+      if (best === i) break;
+      [heap[i], heap[best]] = [heap[best], heap[i]];
+      i = best;
+    }
+  }
+}
+
+/**
+ * @param {{ f: number, g: number, order: number, key: string }} a
+ * @param {{ f: number, g: number, order: number, key: string }} b
+ */
+function compareNodes(a, b) {
+  if (a.f !== b.f) return a.f - b.f;
+  // Prefer higher g when f ties (deeper / more committed path) — classic A* tie-break.
+  if (a.g !== b.g) return b.g - a.g;
+  if (a.order !== b.order) return a.order - b.order;
+  if (a.key < b.key) return -1;
+  if (a.key > b.key) return 1;
+  return 0;
+}
+
+/**
+ * @param {object} opts
+ * @param {unknown} opts.initialState
+ * @param {(state: unknown) => boolean} opts.isGoal
+ * @param {(state: unknown) => Array<{ action: unknown, nextState: unknown, cost?: number }>} opts.expand
+ * @param {(state: unknown) => number} [opts.heuristic]
+ * @param {(state: unknown) => string} [opts.stateKey]
+ * @param {number} [opts.maxExpansions]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {AStarResult}
+ */
+export function planAStar(opts = {}) {
+  const started = Date.now();
+  const {
+    initialState,
+    isGoal,
+    expand,
+    heuristic = () => 0,
+    stateKey = stableStateKey,
+    maxExpansions = Number.POSITIVE_INFINITY,
+    signal,
+  } = opts;
+
+  /** @type {AStarResult} */
+  const base = {
+    ok: false,
+    status: 'invalid_input',
+    plan: [],
+    total_cost: 0,
+    expanded_states: 0,
+    generated_states: 0,
+    frontier_peak: 0,
+    elapsed_ms: 0,
+    engine: ASTAR_ENGINE,
+  };
+
+  if (typeof isGoal !== 'function' || typeof expand !== 'function') {
+    return finish(base, 'invalid_input', { error: 'isGoal and expand are required functions' }, started);
+  }
+  if (typeof heuristic !== 'function' || typeof stateKey !== 'function') {
+    return finish(base, 'invalid_input', { error: 'heuristic and stateKey must be functions' }, started);
+  }
+  if (!(typeof maxExpansions === 'number' && maxExpansions >= 0)) {
+    return finish(base, 'invalid_input', { error: 'maxExpansions must be a non-negative number' }, started);
+  }
+
+  if (signal?.aborted) {
+    return finish(base, 'cancelled', { error: 'aborted_before_start' }, started);
+  }
+
+  const startKey = stateKey(initialState);
+  const open = new Frontier();
+  /** @type {Map<string, number>} */
+  const bestG = new Map();
+  /** @type {Map<string, { parentKey: string|null, action: unknown, state: unknown, g: number }>} */
+  const cameFrom = new Map();
+
+  let order = 0;
+  const h0 = Math.max(0, Number(heuristic(initialState)) || 0);
+  open.push({
+    f: h0,
+    g: 0,
+    order: order++,
+    key: startKey,
+    state: initialState,
+    action: null,
+    parentKey: null,
+  });
+  bestG.set(startKey, 0);
+  cameFrom.set(startKey, { parentKey: null, action: null, state: initialState, g: 0 });
+  base.generated_states = 1;
+  base.frontier_peak = 1;
+
+  while (open.size > 0) {
+    if (signal?.aborted) {
+      return finish(base, 'cancelled', { error: 'aborted' }, started);
+    }
+
+    const current = open.pop();
+    if (!current) break;
+
+    const knownG = bestG.get(current.key);
+    // Superseded entry still in heap — skip.
+    if (knownG !== undefined && current.g > knownG) continue;
+
+    if (isGoal(current.state)) {
+      const plan = reconstructPlan(cameFrom, current.key);
+      return finish(base, 'found', {
+        ok: true,
+        plan,
+        total_cost: current.g,
+        final_state: current.state,
+      }, started);
+    }
+
+    if (base.expanded_states >= maxExpansions) {
+      return finish(base, 'budget_exhausted', {
+        error: `maxExpansions=${maxExpansions}`,
+        final_state: current.state,
+      }, started);
+    }
+
+    base.expanded_states += 1;
+
+    let successors;
+    try {
+      successors = expand(current.state);
+    } catch (err) {
+      return finish(base, 'invalid_input', {
+        error: err instanceof Error ? err.message : String(err),
+      }, started);
+    }
+
+    if (!Array.isArray(successors)) {
+      return finish(base, 'invalid_input', { error: 'expand must return an array' }, started);
+    }
+
+    for (const step of successors) {
+      if (!step || typeof step !== 'object') continue;
+      const cost = Number(step.cost);
+      const stepCost = Number.isFinite(cost) && cost >= 0 ? cost : 1;
+      const nextState = step.nextState;
+      const nextKey = stateKey(nextState);
+      const tentativeG = current.g + stepCost;
+      const prior = bestG.get(nextKey);
+      if (prior !== undefined && tentativeG >= prior) continue;
+
+      bestG.set(nextKey, tentativeG);
+      cameFrom.set(nextKey, {
+        parentKey: current.key,
+        action: step.action,
+        state: nextState,
+        g: tentativeG,
+      });
+      const h = Math.max(0, Number(heuristic(nextState)) || 0);
+      open.push({
+        f: tentativeG + h,
+        g: tentativeG,
+        order: order++,
+        key: nextKey,
+        state: nextState,
+        action: step.action,
+        parentKey: current.key,
+      });
+      base.generated_states += 1;
+      if (open.size > base.frontier_peak) base.frontier_peak = open.size;
+    }
+  }
+
+  return finish(base, 'no_plan', { error: 'frontier_empty' }, started);
+}
+
+/**
+ * @param {Map<string, { parentKey: string|null, action: unknown, state: unknown, g: number }>} cameFrom
+ * @param {string} goalKey
+ * @returns {AStarStep[]}
+ */
+function reconstructPlan(cameFrom, goalKey) {
+  /** @type {AStarStep[]} */
+  const steps = [];
+  let key = goalKey;
+  while (true) {
+    const node = cameFrom.get(key);
+    if (!node || node.parentKey === null) break;
+    const parent = cameFrom.get(node.parentKey);
+    const stepCost = parent ? node.g - parent.g : node.g;
+    steps.push({
+      action: node.action,
+      state: node.state,
+      cost: stepCost,
+    });
+    key = node.parentKey;
+  }
+  steps.reverse();
+  return steps;
+}
+
+/**
+ * @param {AStarResult} base
+ * @param {AStarStatus} status
+ * @param {Partial<AStarResult>} extra
+ * @param {number} started
+ * @returns {AStarResult}
+ */
+function finish(base, status, extra, started) {
+  return {
+    ...base,
+    ...extra,
+    status,
+    ok: status === 'found',
+    elapsed_ms: Date.now() - started,
+    engine: ASTAR_ENGINE,
+  };
+}

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';