@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/src/commands/skill.js

@@ -49,25 +49,86 @@ function looksLikeNpmPackage(source) {
  * Download an npm package tarball and return the extracted package root
  * that contains agentsam.skill.json (or package root for relative resolve).
  */
+
+function buildNpmPackEnv(baseEnv = process.env) {
+  const env = { ...baseEnv };
+
+  // resolveNpmSkillPackage requires a physical tarball.
+  // Parent npm lifecycle flags such as `npm publish --dry-run`
+  // must not change the semantics of this nested npm invocation.
+  for (const key of Object.keys(env)) {
+    if (/^npm_config_dry[_-]?run$/i.test(key)) {
+      delete env[key];
+    }
+  }
+
+  return env;
+}
+
 export function resolveNpmSkillPackage(spec, options = {}) {
   const spawn = options.spawnSyncImpl || spawnSync;
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-skill-npm-'));
-  const pack = spawn('npm', ['pack', spec, '--pack-destination', tmp], {
-    encoding: 'utf8',
-    cwd: options.cwd || process.cwd(),
-    env: options.env || process.env,
-  });
-  if ((pack.status ?? 1) !== 0) {
-    throw new Error(`npm_pack_failed:${spec}:${String(pack.stderr || pack.stdout || '').trim() || 'unknown'}`);
-  }
-  const tgzName = String(pack.stdout || '')
-    .trim()
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .pop();
-  if (!tgzName) throw new Error(`npm_pack_empty:${spec}`);
-  const tgzPath = path.join(tmp, path.basename(tgzName));
-  if (!fs.existsSync(tgzPath)) throw new Error(`npm_pack_missing:${tgzPath}`);
+  const maxPackAttempts = 2;
+
+  let tmp = null;
+  let tgzPath = null;
+  let lastExpectedPath = null;
+
+  for (let attempt = 1; attempt <= maxPackAttempts; attempt += 1) {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-skill-npm-'));
+
+    const pack = spawn('npm', ['pack', spec, '--json', '--pack-destination', tmp], {
+      encoding: 'utf8',
+      cwd: options.cwd || process.cwd(),
+      env: buildNpmPackEnv(options.env || process.env),
+    });
+
+    if ((pack.status ?? 1) !== 0) {
+      throw new Error(
+        `npm_pack_failed:${spec}:${String(pack.stderr || pack.stdout || '').trim() || 'unknown'}`,
+      );
+    }
+
+    let tgzName = null;
+
+    try {
+      const payload = JSON.parse(String(pack.stdout || ''));
+      const entry = Array.isArray(payload) ? payload[0] : payload;
+      if (entry?.filename) tgzName = path.basename(String(entry.filename));
+    } catch {
+      // Fall through to filesystem discovery.
+    }
+
+    const packed = fs.readdirSync(tmp)
+      .filter((name) => name.endsWith('.tgz'))
+      .sort();
+
+    if (!tgzName && packed.length === 1) {
+      tgzName = packed[0];
+    }
+
+    if (tgzName) {
+      const expected = path.join(tmp, tgzName);
+      lastExpectedPath = expected;
+
+      if (fs.existsSync(expected)) {
+        tgzPath = expected;
+        break;
+      }
+    }
+
+    // npm occasionally reports success before producing no artifact.
+    // Treat only that narrow condition as transient and retry once.
+    if (attempt < maxPackAttempts) {
+      fs.rmSync(tmp, { recursive: true, force: true });
+      tmp = null;
+    }
+  }
+
+  if (!tmp || !tgzPath || !fs.existsSync(tgzPath)) {
+    throw new Error(
+      `npm_pack_missing:${lastExpectedPath || spec}:attempts=${maxPackAttempts}`,
+    );
+  }
 
   const extractDir = path.join(tmp, 'pkg');
   fs.mkdirSync(extractDir, { recursive: true });

package/src/commands/terminal.js

@@ -30,6 +30,21 @@ function printIdentity(identity, write) {
   write(`hw_model:  ${identity.model || 'unknown'}`);
 }
 
+function terminalUsage() {
+  return [
+    'agentsam terminal — device identity and ExecOS enrollment',
+    '',
+    'Usage:',
+    '  agentsam terminal identity [--json]',
+    '  agentsam terminal enroll --instance <id> [--endpoint <url>] [--pair] [--json]',
+    '  agentsam terminal --help',
+    '',
+    'Identity lanes:',
+    '  AGENTSAM_API_KEY      account/CLI identity used to mint enrollment',
+    '  AGENTSAM_BRIDGE_KEY   one terminal_connection credential written by --pair',
+  ].join('\n');
+}
+
 function defaultExecosEnrollBin() {
   return path.join(homedir(), 'ExecOS', 'bin', 'enroll.mjs');
 }
@@ -52,6 +67,10 @@ function pairWithExecos(enrollmentToken, options = {}) {
 
 export async function runTerminal(argv = [], options = {}) {
   const write = options.write || ((line) => console.log(line));
+  if (argv.includes('--help') || argv.includes('-h') || argv.includes('help')) {
+    write(terminalUsage());
+    return { ok: true, help: true };
+  }
   const sub = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'identity';
   const json = argv.includes('--json') || options.json === true;
   const pair = argv.includes('--pair') || options.pair === true;
@@ -70,14 +89,7 @@ export async function runTerminal(argv = [], options = {}) {
   }
 
   if (sub !== 'enroll') {
-    write([
-      'Usage: agentsam terminal identity [--json]',
-      '       agentsam terminal enroll --instance <id> [--endpoint <url>] [--pair] [--json]',
-      '',
-      'Lanes:',
-      '  AGENTSAM_API_KEY      account (CLI / whoami / mint enrollment) — required for this command',
-      '  AGENTSAM_BRIDGE_KEY   one terminal_connection secret (written by --pair into ExecOS profile)',
-    ].join('\n'));
+    write(terminalUsage());
     return { ok: false, error: 'terminal_usage' };
   }
 

package/src/errors/contract.js

@@ -2,8 +2,8 @@
 import {
   ERROR_CODE,
   ERROR_REASON,
-} from '../../packages/agentsam-errors/src/vocabulary.js';
-import { canonicalCodeFromHttpStatus } from '../../packages/agentsam-errors/src/envelope.js';
+} from '@inneranimalmedia/agentsam-errors';
+import { canonicalCodeFromHttpStatus } from '@inneranimalmedia/agentsam-errors';
 
 export {
   ERROR_SCHEMA_VERSION,
@@ -15,7 +15,7 @@ export {
   ERROR_DOMAIN,
   REMEDIATION_ACTION,
   GRPC_STATUS,
-} from '../../packages/agentsam-errors/src/vocabulary.js';
+} from '@inneranimalmedia/agentsam-errors';
 
 export {
   canonicalCodeFromHttpStatus,
@@ -27,7 +27,7 @@ export {
   assertErrorEnvelope,
   serializeError,
   parseError,
-} from '../../packages/agentsam-errors/src/envelope.js';
+} from '@inneranimalmedia/agentsam-errors';
 
 // Legacy compact classifier shapes remain public here; richer envelope classifiers
 // live in packages/agentsam-errors and are available via the other adapter exports.

package/src/errors/diagnostic.js

@@ -6,7 +6,7 @@ import {
   normalizeError,
   redactErrorValue,
   redactString,
-} from '../../packages/agentsam-errors/src/index.js';
+} from '@inneranimalmedia/agentsam-errors';
 
 const DEFAULT_MAX_DETAIL_CHARS = 12_000;
 function clean(value) { return value == null ? '' : String(value).trim(); }

package/src/errors/index.js

@@ -1,4 +1,4 @@
-export * from '../../packages/agentsam-errors/src/index.js';
+export * from '@inneranimalmedia/agentsam-errors';
 
 export {
   AgentSamDiagnosticError,

package/src/index.js

@@ -77,6 +77,26 @@ export {
   terminalExec,
 } from './capabilities/index.js';
 export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
+export {
+  LOCAL_ENGINE_SCHEMA,
+  LOCAL_ENGINE_BENCHMARK_SCHEMA,
+  ENGINE_CAPABILITIES,
+  LocalEngineRegistry,
+  createLocalEngineRegistry,
+  createOllamaEngine,
+  createMlxLmEngine,
+  createLlamaCppEngine,
+  auditLocalCompute,
+  auditHost,
+  auditAppleHost,
+  auditTools,
+  auditAssets,
+  adoptAsset,
+  readAssetManifest,
+  assetManifestPath,
+  benchmarkEngine,
+  validateStructuredOutput,
+} from './local-engine/index.js';
 export {
   COMPANY_REPOSITORY_GRAPH_SCHEMA_VERSION,
   REPOSITORY_STATUSES,

package/src/indexing/ingest/materials.js

@@ -1,6 +1,6 @@
 /**
  * Material intake for codebaseindex.ingest — paths pasted/dropped into the CLI.
- * Handles archives (tar/zip), sites/builds, HTML, images, GLB, and mixed trees.
+ * Archives are inspected first and selectively mined instead of blindly unpacked.
  */
 
 import fs from 'node:fs';
@@ -12,6 +12,20 @@ import { isCodeSourceExtension, isDocumentSourceExtension } from '../../../packa
 const ARCHIVE_EXT = new Set(['.zip', '.tar', '.tgz', '.gz', '.tar.gz', '.tbz2', '.tar.bz2']);
 const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
 const MODEL_3D_EXT = new Set(['.glb', '.gltf', '.obj', '.fbx', '.stl', '.usdz']);
+const VIDEO_EXT = new Set(['.mp4', '.mov', '.m4v', '.webm', '.mkv', '.avi', '.mpeg', '.mpg']);
+const AUDIO_EXT = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.flac']);
+const TEXT_BASENAMES = new Set([
+  'readme', 'license', 'licence', 'dockerfile', 'makefile', 'procfile', 'gemfile', 'rakefile',
+  'cargo.lock', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', '.gitignore', '.npmrc', '.editorconfig',
+]);
+const DEFAULT_ARCHIVE_POLICY = Object.freeze({
+  maxEntries: 10_000,
+  maxFiles: 2_000,
+  maxEntryBytes: 8 * 1024 * 1024,
+  maxTotalBytes: 128 * 1024 * 1024,
+  includeAssets: false,
+});
+
 function clean(value) {
   return value == null ? '' : String(value).trim();
 }
@@ -43,9 +57,7 @@ export function parsePastedPaths(text) {
   return [...new Set(paths)];
 }
 
-/**
- * @param {string} filePath
- */
+/** @param {string} filePath */
 export function classifyMaterial(filePath) {
   const resolved = path.resolve(filePath);
   const ext = extOf(resolved);
@@ -79,37 +91,237 @@ function hashFile(filePath) {
 
 function hasBin(name) {
   const result = spawnSync(name, ['--help'], { stdio: 'ignore' });
-  // Some tools exit non-zero on --help; presence of spawn failure matters more.
   return result.error == null;
 }
 
+function archiveFormat(archivePath) {
+  const lower = archivePath.toLowerCase();
+  if (lower.endsWith('.zip')) return 'zip';
+  if (lower.endsWith('.tar') || lower.endsWith('.tar.gz') || lower.endsWith('.tgz')
+    || lower.endsWith('.tar.bz2') || lower.endsWith('.tbz2')) return 'tar';
+  if (lower.endsWith('.gz')) return 'gzip';
+  return null;
+}
+
+function archiveEntryKind(entryPath) {
+  const normalized = String(entryPath || '').replace(/\\/g, '/');
+  const ext = path.posix.extname(normalized.toLowerCase());
+  const base = path.posix.basename(normalized).toLowerCase();
+  if (IMAGE_EXT.has(ext)) return 'image';
+  if (MODEL_3D_EXT.has(ext)) return 'model3d';
+  if (VIDEO_EXT.has(ext)) return 'video';
+  if (AUDIO_EXT.has(ext)) return 'audio';
+  if (isDocumentSourceExtension(ext) || TEXT_BASENAMES.has(base)) return 'document';
+  if (isCodeSourceExtension(ext)) return 'code';
+  return 'file';
+}
+
+function isSafeArchivePath(entryPath) {
+  const raw = String(entryPath || '').replace(/\\/g, '/');
+  if (!raw || raw.includes('\0') || raw.startsWith('/') || /^[a-zA-Z]:\//.test(raw)) return false;
+  const parts = raw.split('/').filter((part) => part && part !== '.');
+  return !parts.includes('..');
+}
+
+function shouldMineArchiveEntry(entry, policy) {
+  if (!entry.safe) return { selected: false, reason: 'unsafe_path' };
+  if (entry.link) return { selected: false, reason: 'link_entry' };
+  if (entry.directory) return { selected: false, reason: 'directory' };
+  if (Number.isFinite(entry.bytes) && entry.bytes > policy.maxEntryBytes) {
+    return { selected: false, reason: 'entry_too_large' };
+  }
+  if (entry.kind === 'code' || entry.kind === 'document') return { selected: true, reason: 'indexable_text' };
+  if (policy.includeAssets && ['image', 'model3d'].includes(entry.kind)) return { selected: true, reason: 'requested_asset' };
+  return { selected: false, reason: ['image', 'model3d', 'video', 'audio'].includes(entry.kind) ? 'asset_inventory_only' : 'non_indexable' };
+}
+
+function commandText(command, args, maxBuffer = 16 * 1024 * 1024) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    maxBuffer,
+    env: { ...process.env, LC_ALL: 'C' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function zipSizeMap(archivePath) {
+  if (!hasBin('zipinfo')) return new Map();
+  const map = new Map();
+  const lines = commandText('zipinfo', ['-l', archivePath], 32 * 1024 * 1024).split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^(\S+)\s+\S+\s+\S+\s+(\d+)\s+\S+\s+\d+\s+\S+\s+\S+\s+\S+\s+(.*)$/);
+    if (!match) continue;
+    map.set(match[3], { bytes: Number(match[2]), link: match[1].startsWith('l') });
+  }
+  return map;
+}
+
 /**
- * Extract archive into destDir. Uses host tar/unzip (no extra npm deps).
+ * Inspect an archive without expanding it to disk.
+ * @param {string} archivePath
+ * @param {Partial<typeof DEFAULT_ARCHIVE_POLICY>} [options]
+ */
+export function inspectArchive(archivePath, options = {}) {
+  const resolved = path.resolve(archivePath);
+  const policy = { ...DEFAULT_ARCHIVE_POLICY, ...options };
+  const format = archiveFormat(resolved);
+  if (!format) throw new Error(`unsupported_archive:${path.basename(resolved)}`);
+  if (!fs.existsSync(resolved)) throw new Error(`archive_missing:${resolved}`);
+
+  let names = [];
+  let zipMeta = new Map();
+  let tarLinks = new Set();
+  if (format === 'zip') {
+    if (!hasBin('unzip')) throw new Error('unzip_unavailable: install unzip to inspect .zip materials');
+    names = commandText('unzip', ['-Z1', resolved], 32 * 1024 * 1024).split(/\r?\n/).filter(Boolean);
+    zipMeta = zipSizeMap(resolved);
+  } else if (format === 'tar') {
+    if (!hasBin('tar')) throw new Error('tar_unavailable: install tar to inspect tar materials');
+    names = commandText('tar', ['-tf', resolved], 32 * 1024 * 1024).split(/\r?\n/).filter(Boolean);
+    const verbose = commandText('tar', ['-tvf', resolved], 32 * 1024 * 1024).split(/\r?\n/);
+    for (const line of verbose) {
+      if (!(line.startsWith('l') || line.startsWith('h'))) continue;
+      const marker = line.includes(' -> ') ? line.split(' -> ')[0] : line;
+      const name = names.find((candidate) => marker.endsWith(candidate));
+      if (name) tarLinks.add(name);
+    }
+  } else {
+    if (!hasBin('gzip')) throw new Error('gzip_unavailable: install gzip to inspect .gz materials');
+    names = [path.basename(resolved, '.gz') || 'payload'];
+  }
+
+  if (names.length > policy.maxEntries) {
+    const error = new Error(`archive_entry_limit_exceeded:${names.length}>${policy.maxEntries}`);
+    error.code = 'AGENTSAM_ARCHIVE_ENTRY_LIMIT';
+    throw error;
+  }
+
+  const entries = names.map((name) => {
+    const meta = zipMeta.get(name) || {};
+    const directory = name.endsWith('/');
+    const entry = {
+      path: name,
+      bytes: Number.isFinite(meta.bytes) ? meta.bytes : null,
+      kind: directory ? 'directory' : archiveEntryKind(name),
+      directory,
+      link: Boolean(meta.link || tarLinks.has(name)),
+      safe: isSafeArchivePath(name),
+    };
+    return { ...entry, ...shouldMineArchiveEntry(entry, policy) };
+  });
+
+  const unsafe = entries.filter((entry) => !entry.safe);
+  if (unsafe.length) {
+    const error = new Error(`archive_unsafe_paths:${unsafe.slice(0, 5).map((entry) => entry.path).join(',')}`);
+    error.code = 'AGENTSAM_ARCHIVE_UNSAFE_PATH';
+    throw error;
+  }
+
+  const selected = entries.filter((entry) => entry.selected);
+  const selectedKnownBytes = selected.reduce((sum, entry) => sum + (entry.bytes || 0), 0);
+  const byKind = {};
+  for (const entry of entries) byKind[entry.kind] = (byKind[entry.kind] || 0) + 1;
+
+  return {
+    schema: 'agentsam.archive.inspect.v1',
+    archive: resolved,
+    format,
+    compressed_bytes: fs.statSync(resolved).size,
+    entries_total: entries.length,
+    selected_total: selected.length,
+    selected_known_bytes: selectedKnownBytes,
+    by_kind: byKind,
+    policy,
+    entries,
+  };
+}
+
+function readArchiveEntry(archivePath, format, entry, maxBytes) {
+  const maxBuffer = Math.max(1024 * 1024, maxBytes + 1);
+  if (format === 'zip') {
+    return execFileSync('unzip', ['-p', archivePath, entry], { encoding: null, maxBuffer, stdio: ['ignore', 'pipe', 'pipe'] });
+  }
+  if (format === 'tar') {
+    return execFileSync('tar', ['-xOf', archivePath, entry], { encoding: null, maxBuffer, stdio: ['ignore', 'pipe', 'pipe'] });
+  }
+  return execFileSync('gzip', ['-dc', archivePath], { encoding: null, maxBuffer, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * Selectively mine indexable content from an archive into destDir.
+ * Large/binary/media members remain represented in the receipt but are not copied.
  * @param {string} archivePath
  * @param {string} destDir
+ * @param {Partial<typeof DEFAULT_ARCHIVE_POLICY>} [options]
  */
-export function extractArchive(archivePath, destDir) {
+export function extractArchive(archivePath, destDir, options = {}) {
+  const policy = { ...DEFAULT_ARCHIVE_POLICY, ...options };
+  const inspection = inspectArchive(archivePath, policy);
+  fs.rmSync(destDir, { recursive: true, force: true });
   fs.mkdirSync(destDir, { recursive: true });
-  const lower = archivePath.toLowerCase();
-  if (lower.endsWith('.zip')) {
-    if (!hasBin('unzip')) throw new Error('unzip_unavailable: install unzip to extract .zip materials');
-    execFileSync('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
-    return { tool: 'unzip', dest: destDir };
-  }
-  if (lower.endsWith('.tar') || lower.endsWith('.tar.gz') || lower.endsWith('.tgz')
-    || lower.endsWith('.tar.bz2') || lower.endsWith('.tbz2') || lower.endsWith('.gz')) {
-    if (!hasBin('tar')) throw new Error('tar_unavailable: install tar to extract archive materials');
-    execFileSync('tar', ['-xf', archivePath, '-C', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
-    return { tool: 'tar', dest: destDir };
+
+  const selected = inspection.entries.filter((entry) => entry.selected);
+  const mined = [];
+  const skipped = inspection.entries.filter((entry) => !entry.selected).map((entry) => ({
+    path: entry.path, kind: entry.kind, bytes: entry.bytes, reason: entry.reason,
+  }));
+  let totalBytes = 0;
+
+  for (const entry of selected) {
+    if (mined.length >= policy.maxFiles) {
+      skipped.push({ path: entry.path, kind: entry.kind, bytes: entry.bytes, reason: 'file_limit' });
+      continue;
+    }
+    if (Number.isFinite(entry.bytes) && totalBytes + entry.bytes > policy.maxTotalBytes) {
+      skipped.push({ path: entry.path, kind: entry.kind, bytes: entry.bytes, reason: 'total_byte_limit' });
+      continue;
+    }
+
+    let payload;
+    try {
+      payload = readArchiveEntry(inspection.archive, inspection.format, entry.path, policy.maxEntryBytes);
+    } catch (cause) {
+      skipped.push({ path: entry.path, kind: entry.kind, bytes: entry.bytes, reason: 'extract_error', error: String(cause?.message || cause).slice(0, 240) });
+      continue;
+    }
+    if (payload.length > policy.maxEntryBytes || totalBytes + payload.length > policy.maxTotalBytes) {
+      skipped.push({ path: entry.path, kind: entry.kind, bytes: payload.length, reason: payload.length > policy.maxEntryBytes ? 'entry_too_large' : 'total_byte_limit' });
+      continue;
+    }
+
+    const normalized = entry.path.replace(/\\/g, '/').replace(/^\.\//, '');
+    const output = path.resolve(destDir, ...normalized.split('/'));
+    const root = path.resolve(destDir);
+    if (!(output === root || output.startsWith(`${root}${path.sep}`))) {
+      throw new Error(`archive_unsafe_output:${entry.path}`);
+    }
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, payload);
+    totalBytes += payload.length;
+    mined.push({ path: entry.path, kind: entry.kind, bytes: payload.length });
   }
-  throw new Error(`unsupported_archive:${path.basename(archivePath)}`);
+
+  return {
+    schema: 'agentsam.archive.mine.v1',
+    format: inspection.format,
+    dest: destDir,
+    entries_total: inspection.entries_total,
+    mined_files: mined.length,
+    mined_bytes: totalBytes,
+    skipped_files: skipped.length,
+    by_kind: inspection.by_kind,
+    policy,
+    mined,
+    skipped: skipped.slice(0, 200),
+    skipped_truncated: skipped.length > 200,
+  };
 }
 
 /**
  * Stage pasted/dropped materials under `.agentsam/ingest/<id>/`.
- * Archives are extracted; files/dirs are copied or linked by relative include paths.
+ * Archives are inspected + selectively mined; files/dirs are copied or linked by relative include paths.
  *
- * @param {{ root: string, materials: string[], ingestId?: string }} opts
+ * @param {{ root: string, materials: string[], ingestId?: string, archivePolicy?: object }} opts
  */
 export function stageMaterials(opts) {
   const root = path.resolve(opts.root);
@@ -117,11 +329,8 @@ export function stageMaterials(opts) {
   const stageRoot = path.join(root, '.agentsam', 'ingest', ingestId);
   fs.mkdirSync(stageRoot, { recursive: true });
 
-  /** @type {object[]} */
   const items = [];
-  /** @type {string[]} */
   const include = [];
-  /** @type {object[]} */
   const assets = [];
 
   for (const raw of opts.materials) {
@@ -133,11 +342,10 @@ export function stageMaterials(opts) {
 
     if (classified.kind === 'archive') {
       const dest = path.join(stageRoot, 'archives', path.basename(classified.path, classified.ext) || 'archive');
-      fs.mkdirSync(dest, { recursive: true });
-      const extracted = extractArchive(classified.path, dest);
+      const extracted = extractArchive(classified.path, dest, opts.archivePolicy || {});
       const rel = path.relative(root, dest);
-      include.push(rel);
-      items.push({ ...classified, status: 'extracted', stage: dest, extract: extracted });
+      if (extracted.mined_files > 0) include.push(rel);
+      items.push({ ...classified, status: 'mined', stage: dest, extract: extracted });
       continue;
     }
 
@@ -158,7 +366,6 @@ export function stageMaterials(opts) {
       continue;
     }
 
-    // Single file
     const destDir = path.join(stageRoot, classified.kind === 'image' ? 'images'
       : classified.kind === 'model3d' ? 'models3d'
         : classified.kind === 'document' ? 'documents'
@@ -180,7 +387,7 @@ export function stageMaterials(opts) {
 
   const uniqueInclude = [...new Set(include.map((p) => p.replace(/\\/g, '/').replace(/\/$/, '') || '.'))].sort();
   const manifest = {
-    schema: 'agentsam.ingest.materials.v1',
+    schema: 'agentsam.ingest.materials.v2',
     ingest_id: ingestId,
     staged_at: new Date().toISOString(),
     stage_root: path.relative(root, stageRoot),

package/src/knowledge/source.js

@@ -7,7 +7,7 @@ import { isKnowledgeSourcePath } from '../../packages/agentsam-repository/src/so
 import { fingerprint } from './config.js';
 
 export const PARSER = `typescript:${ts.version}:agentsam-1`;
-const OMIT = /(^|\/)(?:\.git|\.agentsam|node_modules|dist|build|coverage|vendor|\.next|\.wrangler|\.venv|__pycache__)(\/|$)|(^|\/)(?:\.env[^/]*|\.dev\.vars[^/]*|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Cargo\.lock|poetry\.lock|uv\.lock|[^/]*\.(?:pem|key|p12|pfx|min\.js|map))$/i;
+const OMIT = /(^|\/)(?:\.git|\.agentsam|node_modules|python_modules|dist|build|target|coverage|vendor|\.next|\.wrangler|\.venv|__pycache__)(\/|$)|(^|\/)(?:\.env[^/]*|\.dev\.vars[^/]*|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Cargo\.lock|poetry\.lock|uv\.lock|[^/]*\.(?:pem|key|p12|pfx|min\.js|bundle\.js|map))$/i;
 const under = (file, scope) => scope === '.' || file === scope || file.startsWith(scope + '/');
 export function inventory(root, scope) {
   let files;

package/src/lib/setup/runtime.js

@@ -380,14 +380,16 @@ export function renderRuntimePlan(plan) {
         lines.push(`      missing tools: ${c.constraints.missing_tools.join(', ')}`);
       }
     } else if (c.goap.action_ids.length) {
-      lines.push(`      plan: ${c.goap.action_ids.join(' → ')}`);
+      lines.push(`      target plan: ${c.goap.action_ids.join(' → ')}`);
     }
   }
   lines.push('');
   if (plan.recommended) {
     lines.push(`  Recommended  ${plan.recommended.profile.label} (${plan.recommended.profile.id})`);
     lines.push(`  Next         agentsam setup runtime --profile ${plan.recommended.profile.id} --yes`);
-    lines.push(`               agentsam runtime install`);
+    lines.push(plan.facts.agentsamd.installed
+      ? '               agentsam runtime status'
+      : '               agentsam runtime install');
   }
   lines.push('');
   return `${lines.join('\n')}\n`;

package/src/lib/slash-commands.js

@@ -32,7 +32,7 @@ export const SLASH_COMMANDS = [
   { cmd: '/agent', description: 'Send a goal to the configured local Agent Sam runtime', lane: 'agent' },
   { cmd: '/goap', description: 'Inspect and manage GOAP blackboard: /goap [status|goal|why|plan|list|new|switch|close]', lane: 'agent' },
   { cmd: '/brand', description: 'Brand intelligence: /brand [scan|resolve|plan|inspect]', lane: 'product' },
-  { cmd: '/plan', description: 'Composable plans: /plan brand', lane: 'product' },
+  { cmd: '/plan', description: 'Durable local plans: /plan [new|list|show|add|start|done|block|complete|brand]', lane: 'product' },
   { cmd: '/next', description: 'Suggested next actions from session progression', lane: 'product' },
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },

package/src/local/runtime-store.js

@@ -43,14 +43,36 @@ export function createRuntimeRunId() {
 export async function startRuntimeRun(value = {}) {
   const id = clean(value.id) || createRuntimeRunId();
   await withStore(value.projectRoot || value.cwd, async (db) => {
+    const activeStep = (!clean(value.plan_id) || !clean(value.todo_id))
+      ? await db.prepare(`
+          SELECT t.id AS todo_id, t.plan_id
+          FROM agentsam_todo t
+          JOIN agentsam_plans p ON p.id = t.plan_id
+          WHERE t.status = 'running' AND p.status = 'active'
+          ORDER BY t.updated_at_unix DESC, t.created_at_unix DESC
+          LIMIT 1
+        `).first()
+      : null;
+    const activePlan = !clean(value.plan_id) && !activeStep?.plan_id
+      ? await db.prepare(`
+          SELECT id AS plan_id FROM agentsam_plans
+          WHERE status = 'active'
+          ORDER BY updated_at_unix DESC, created_at_unix DESC
+          LIMIT 1
+        `).first()
+      : null;
+    const planId = clean(value.plan_id) || clean(activeStep?.plan_id) || clean(activePlan?.plan_id) || null;
+    const todoId = clean(value.todo_id) || clean(activeStep?.todo_id) || null;
     await db.prepare(`
       INSERT INTO agentsam_agent_run (
-        id, account_id, source_client, surface, mode, model_key,
+        id, account_id, plan_id, todo_id, source_client, surface, mode, model_key,
         reasoning_effort, requested_service_tier, status, started_at_unix, updated_at_unix
-      ) VALUES (?, ?, 'agentsam-cli', 'cli', ?, ?, ?, ?, 'running', unixepoch(), unixepoch())
+      ) VALUES (?, ?, ?, ?, 'agentsam-cli', 'cli', ?, ?, ?, ?, 'running', unixepoch(), unixepoch())
     `).bind(
       id,
       clean(value.account_id) || null,
+      planId,
+      todoId,
       clean(value.mode) || 'agent',
       clean(value.model_key) || null,
       clean(value.reasoning_effort) || null,