@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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,116 @@
+/**
+ * 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'|'mcp'} SamLane */
+/** @typedef {'never'|'optional'|'required'} SamModelPolicy */
+/** @typedef {'none'|'optional'|'required'} SamNetworkPolicy */
+/** @typedef {'none'|'local_write'|'remote_read'|'remote_write'|'deploy'|'billable'|'oauth'} SamSideEffects */
+/** @typedef {'read_only'|'write'|'privileged'} SamRisk */
+/** @typedef {'never'|'optional'|'required'} SamSpendPolicy */
+
+/**
+ * Provider capability / OAuth pack reference (Cloudflare, GitHub, …).
+ * Prefer pack- or capability-scoped consent — never wholesale scope catalogs.
+ * @typedef {object} SamCapabilityRef
+ * @property {string} id
+ * @property {string} [provider]
+ * @property {string[]} [oauth_scopes]
+ * @property {string[]} [feature_packs]
+ */
+
+/**
+ * MCP projection for an operation (server tool surface).
+ * @typedef {object} SamMcpProjection
+ * @property {string} [server_name]
+ * @property {string} [server_url]
+ * @property {string} [tool_name]
+ * @property {string[]} [required_scopes]
+ * @property {string[]} [feature_packs]
+ * @property {'streamable_http'|'sse'|'stdio'} [protocol]
+ */
+
+/**
+ * @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 {SamCapabilityRef[]} [capability_refs]
+ * @property {SamMcpProjection} [mcp]
+ * @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]
+ * @property {{ mcp?: SamMcpProjection, capability_refs?: SamCapabilityRef[] }} [projection]
+ */
+
+/**
+ * @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
+ * @property {SamMcpProjection} [mcp]
+ */
+
+/**
+ * @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/security/inventory.js

@@ -11,7 +11,7 @@ export function readJson(file) {
   if (!stat.isFile() || stat.size > 32 * 1024 * 1024) throw new Error('Manifest must be a regular JSON file under 32 MiB');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
-export function collectNpmDependencies(projectRoot = process.cwd()) {
+export function collectNpmDependencies(projectRoot = process.cwd(), options = {}) {
   const root = fs.realpathSync(projectRoot);
   const manifest = readJson(path.join(root, 'package.json'));
   const issues = [], dependencies = new Map(), skipped = [];
@@ -20,9 +20,19 @@ export function collectNpmDependencies(projectRoot = process.cwd()) {
   const unsupported = ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'].filter(file => fs.existsSync(path.join(root, file)));
   if (manifest.packageManager && !manifest.packageManager.startsWith('npm@')) issues.push('Selected package manager is not npm; this adapter cannot prove its dependency graph.');
   else if (unsupported.length && !manifest.packageManager) issues.push('Multiple/unsupported package-manager lockfiles; select npm explicitly with packageManager or scan in the owning manager.');
+  const releaseCandidate = options.releaseCandidate || null;
   const add = (name, pkg, location, direct) => {
     if (pkg.link) { skipped.push({ path: location, reason: 'workspace/link (dependencies scanned from lock graph)' }); return; }
-    if (!packageName(name) || !exactVersion(pkg.version) || /^(?:file:|link:|git[+:]|https?:\/\/.*\.git)/i.test(pkg.resolved || '')) {
+    const resolved = String(pkg.resolved || '');
+    const isLocalTarball = /^file:/i.test(resolved);
+    const allowedReleaseCandidate = Boolean(
+      isLocalTarball
+      && releaseCandidate
+      && releaseCandidate.name === name
+      && releaseCandidate.version === pkg.version
+      && releaseCandidate.location === location
+    );
+    if (!packageName(name) || !exactVersion(pkg.version) || (/^(?:file:|link:|git[+:]|https?:\/\/.*\.git)/i.test(resolved) && !allowedReleaseCandidate)) {
       issues.push('Unresolved or non-registry dependency at ' + location);
       return;
     }

package/src/security/local-vault.js

@@ -120,7 +120,9 @@ function osStoreWriteDarwin(provider, secret) {
   try {
     const res = spawnSync('/usr/bin/security', ['add-generic-password', '-a', `agentsam:${provider}`, '-s', 'agentsam', '-w', secret, '-U'], {
       stdio: 'ignore',
+      timeout: 12_000,
     });
+    if (res.error?.code === 'ETIMEDOUT' || res.signal === 'SIGTERM') return false;
     return res.status === 0;
   } catch { return false; }
 }

package/src/security/scan.js

@@ -4,7 +4,7 @@ import { triageLog, resolveLogFindings } from './logs.js';
 import { scanTrustBoundary } from './trust-boundary.js';
 
 export async function scanProjectSecurity(options = {}) {
-  const inventory = collectNpmDependencies(options.projectRoot);
+  const inventory = collectNpmDependencies(options.projectRoot, { releaseCandidate: options.releaseCandidate });
   const results = options.offline
     ? inventory.dependencies.map(d => ({ ...d, checked: false, advisories: [] }))
     : await queryOsv(inventory.dependencies, options);

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;

package/src/skills/content-resolver.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * SkillContentResolver — adapters only; runtime never imports R2/D1 directly.
+ *
+ * @typedef {{
+ *   get?: (key: string) => Promise<string|null>|string|null,
+ * }} ObjectStoreAdapter
+ *
+ * @typedef {{
+ *   getText?: (ref: string) => Promise<string|null>|string|null,
+ * }} DatabaseContentAdapter
+ */
+
+export class SkillContentResolver {
+  /**
+   * @param {{
+ *     objectStore?: ObjectStoreAdapter,
+ *     database?: DatabaseContentAdapter,
+ *     packageRootResolver?: (pkg: string) => string|null,
+ *   }} [adapters]
+   */
+  constructor(adapters = {}) {
+    this.objectStore = adapters.objectStore || null;
+    this.database = adapters.database || null;
+    this.packageRootResolver = adapters.packageRootResolver || null;
+  }
+
+  /**
+   * @param {import('./manifest.js').SkillManifest} manifest
+   * @param {{ baseDir?: string, packageRoot?: string }} [ctx]
+   * @returns {Promise<{ content: string, source: string, ref: string|null }>}
+   */
+  async resolve(manifest, ctx = {}) {
+    const source = manifest?.instructions?.source;
+    if (!source) throw new Error('instructions_source_required');
+
+    if (source === 'inline') {
+      const content = String(manifest.instructions.inline ?? '');
+      return { content, source, ref: null };
+    }
+
+    if (source === 'local_file') {
+      const ref = String(manifest.instructions.ref || '').trim();
+      if (!ref) throw new Error('local_file_ref_required');
+      const base = ctx.baseDir || process.cwd();
+      const filePath = path.resolve(base, ref);
+      const content = fs.readFileSync(filePath, 'utf8');
+      return { content, source, ref: filePath };
+    }
+
+    if (source === 'package_file') {
+      const ref = String(manifest.instructions.ref || '').trim();
+      if (!ref) throw new Error('package_file_ref_required');
+      const root =
+        ctx.packageRoot ||
+        (manifest.package && this.packageRootResolver
+          ? this.packageRootResolver(manifest.package)
+          : null) ||
+        ctx.baseDir;
+      if (!root) throw new Error('package_root_required');
+      const filePath = path.resolve(root, ref);
+      const content = fs.readFileSync(filePath, 'utf8');
+      return { content, source, ref: filePath };
+    }
+
+    if (source === 'database') {
+      const ref = String(manifest.instructions.ref || '').trim();
+      if (!ref) throw new Error('database_ref_required');
+      if (!this.database?.getText) {
+        throw new Error('database_content_adapter_required');
+      }
+      const content = await this.database.getText(ref);
+      if (content == null) throw new Error(`database_content_missing:${ref}`);
+      return { content: String(content), source, ref };
+    }
+
+    if (source === 'object_store') {
+      const ref = String(manifest.instructions.ref || '').trim();
+      if (!ref) throw new Error('object_store_ref_required');
+      if (!this.objectStore?.get) {
+        throw new Error('object_store_adapter_required');
+      }
+      const content = await this.objectStore.get(ref);
+      if (content == null) throw new Error(`object_store_content_missing:${ref}`);
+      return { content: String(content), source, ref };
+    }
+
+    throw new Error(`unsupported_instruction_source:${source}`);
+  }
+}
+
+/**
+ * Minimal local object-store adapter for tests (filesystem under a root).
+ * Cloudflare R2 would implement the same `.get(ref)` surface.
+ */
+export function createFilesystemObjectStore(rootDir) {
+  const root = path.resolve(rootDir);
+  return {
+    async get(key) {
+      const file = path.resolve(root, String(key).replace(/^\/+/, ''));
+      if (!file.startsWith(root + path.sep) && file !== root) {
+        throw new Error('object_store_path_escape');
+      }
+      if (!fs.existsSync(file)) return null;
+      return fs.readFileSync(file, 'utf8');
+    },
+  };
+}
+
+export function createMemoryDatabaseContent(map = new Map()) {
+  return {
+    async getText(ref) {
+      return map.has(ref) ? map.get(ref) : null;
+    },
+  };
+}
+
+/** @deprecated identity only — prefer path.resolve for package roots */
+export function fileUrlDirname(importMetaUrl) {
+  return path.dirname(fileURLToPath(importMetaUrl));
+}

package/src/skills/hosted-store.js

@@ -0,0 +1,37 @@
+/**
+ * Hosted SkillStore adapter contract — ownership lives here, not in agentsam.skill.v1.
+ * Portable runtime works with null store (local registry only).
+ *
+ * IAM migration: implement this against real account_id rows only.
+ * Never use account_id IN ('platform','system').
+ */
+
+/**
+ * @typedef {{
+ *   listForAccount: (accountId: string) => Promise<Array<{ id: string, trigger: string, manifest: object }>>,
+ *   getByTrigger: (accountId: string, trigger: string) => Promise<object|null>,
+ *   put: (accountId: string, manifest: object, trigger: string) => Promise<void>,
+ *   remove: (accountId: string, skillId: string) => Promise<void>,
+ * }} HostedSkillStore
+ */
+
+/**
+ * No-op store for local / offline. Hosts inject a real D1-backed adapter later.
+ * @returns {HostedSkillStore}
+ */
+export function createNullHostedSkillStore() {
+  return {
+    async listForAccount() {
+      return [];
+    },
+    async getByTrigger() {
+      return null;
+    },
+    async put() {
+      throw new Error('hosted_skill_store_unavailable');
+    },
+    async remove() {
+      throw new Error('hosted_skill_store_unavailable');
+    },
+  };
+}