@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

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

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