@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

package/src/commands/plan-ledger.js

@@ -0,0 +1,370 @@
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createLocalSqliteDatabaseSync } from '../local/sqlite.js';
+import { applyRuntimeMigrationsSync } from '../local/migrations.js';
+import { getLocalDatabasePath, readProjectConfig } from '../lib/project-config.js';
+import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
+
+function id(prefix) {
+  return prefix + '_' + Date.now().toString(36) + '_' + randomBytes(4).toString('hex');
+}
+
+function parseJson(value, fallback) {
+  try { return JSON.parse(String(value || '')); }
+  catch { return fallback; }
+}
+
+function repositoryIdFor(root, git, config) {
+  return config?.repository?.id
+    || (git?.repoFullName ? 'github:' + git.repoFullName.toLowerCase() : null)
+    || 'local:' + root;
+}
+
+export function openPlanLedger(cwd = process.cwd()) {
+  const git = tryResolveGitContext({ cwd });
+  const root = git?.root || path.resolve(cwd);
+  const config = readProjectConfig(root);
+  const dbPath = path.resolve(root, getLocalDatabasePath(config));
+  const db = createLocalSqliteDatabaseSync(dbPath);
+  applyRuntimeMigrationsSync(db);
+  db.exec('PRAGMA foreign_keys = ON;');
+  return {
+    db, dbPath, root, git,
+    repositoryId: repositoryIdFor(root, git, config),
+    close() { db.close(); },
+  };
+}
+
+function planMetadata(ctx, input = {}) {
+  return {
+    schema: 'agentsam.plan.v1',
+    repository_id: ctx.repositoryId,
+    repository_root: ctx.root,
+    branch: ctx.git?.branch || null,
+    revision: ctx.git?.revisionSha || null,
+    dirty: Boolean(ctx.git?.dirty),
+    goal: input.goal || input.title || '',
+    acceptance: input.acceptance || [],
+    evidence: input.evidence || [],
+    scope: input.scope || {},
+    created_by: input.createdBy || 'cli',
+  };
+}
+
+function taskMetadata(ctx, input = {}) {
+  return {
+    schema: 'agentsam.todo.v1',
+    repository_id: ctx.repositoryId,
+    kind: input.kind || 'work',
+    depends_on: input.dependsOn || [],
+    acceptance: input.acceptance || [],
+    evidence: input.evidence || [],
+    blocker_reason: input.blockerReason || null,
+  };
+}
+
+function hydratePlan(row) {
+  return row ? { ...row, metadata: parseJson(row.metadata_json, {}) } : null;
+}
+
+function hydrateTask(row) {
+  return row ? { ...row, metadata: parseJson(row.metadata_json, {}) } : null;
+}
+
+function refreshPlanCounts(ctx, planId) {
+  const counts = ctx.db.prepare(
+    "SELECT COUNT(*) AS total, " +
+    "SUM(CASE WHEN status = 'complete' THEN 1 ELSE 0 END) AS done, " +
+    "SUM(CASE WHEN status = 'blocked' THEN 1 ELSE 0 END) AS blocked " +
+    "FROM agentsam_todo WHERE plan_id = ?"
+  ).get(planId);
+  ctx.db.prepare(
+    'UPDATE agentsam_plans SET tasks_total = ?, tasks_done = ?, tasks_blocked = ?, updated_at_unix = unixepoch() WHERE id = ?'
+  ).run(Number(counts?.total || 0), Number(counts?.done || 0), Number(counts?.blocked || 0), planId);
+}
+
+export function createPlan(ctx, input) {
+  const title = String(input?.title || '').trim();
+  if (!title) throw new Error('plan_title_required');
+  const goal = String(input?.goal || title).trim();
+  const planId = id('plan');
+  const metadata = planMetadata(ctx, { ...input, title, goal });
+  ctx.db.prepare(
+    "INSERT INTO agentsam_plans (" +
+    "id, account_id, session_id, agent_run_id, plan_type, title, status, summary_text, token_budget, metadata_json" +
+    ") VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)"
+  ).run(
+    planId,
+    input?.accountId || null,
+    input?.sessionId || null,
+    input?.agentRunId || null,
+    input?.planType || 'feature',
+    title,
+    goal,
+    input?.tokenBudget ?? null,
+    JSON.stringify(metadata),
+  );
+  return getPlan(ctx, planId);
+}
+
+export function listPlans(ctx, { all = false } = {}) {
+  const sql =
+    "SELECT * FROM agentsam_plans " +
+    "WHERE json_extract(metadata_json, '$.repository_id') = ? " +
+    (all ? '' : "AND status IN ('draft','active') ") +
+    "ORDER BY updated_at_unix DESC, created_at_unix DESC";
+  return ctx.db.prepare(sql).all(ctx.repositoryId).map(hydratePlan);
+}
+
+export function getCurrentPlan(ctx) {
+  const row = ctx.db.prepare(
+    "SELECT p.* FROM agentsam_plans p " +
+    "WHERE json_extract(p.metadata_json, '$.repository_id') = ? " +
+    "AND p.status IN ('active','draft') " +
+    "ORDER BY " +
+    "EXISTS(SELECT 1 FROM agentsam_todo t WHERE t.plan_id = p.id AND t.status = 'running') DESC, " +
+    "CASE p.status WHEN 'active' THEN 0 ELSE 1 END, p.updated_at_unix DESC, p.created_at_unix DESC LIMIT 1"
+  ).get(ctx.repositoryId);
+  return hydratePlan(row);
+}
+
+export function getPlan(ctx, planId = 'current') {
+  const plan = planId === 'current'
+    ? getCurrentPlan(ctx)
+    : hydratePlan(ctx.db.prepare('SELECT * FROM agentsam_plans WHERE id = ? LIMIT 1').get(planId));
+  if (!plan) return null;
+  const tasks = ctx.db.prepare(
+    'SELECT * FROM agentsam_todo WHERE plan_id = ? ORDER BY sort_order ASC, created_at_unix ASC'
+  ).all(plan.id).map(hydrateTask);
+  return { ...plan, tasks };
+}
+
+export function addPlanStep(ctx, input) {
+  const plan = getPlan(ctx, input?.planId || 'current');
+  if (!plan) throw new Error('active_plan_required');
+  const title = String(input?.title || '').trim();
+  if (!title) throw new Error('step_title_required');
+  const taskId = id('todo');
+  const order = ctx.db.prepare(
+    'SELECT COALESCE(MAX(sort_order), 0) + 10 AS next_order FROM agentsam_todo WHERE plan_id = ?'
+  ).get(plan.id)?.next_order || 10;
+  ctx.db.prepare(
+    "INSERT INTO agentsam_todo (" +
+    "id, account_id, plan_id, agent_run_id, title, description, status, priority, sort_order, token_budget, requires_approval, metadata_json" +
+    ") VALUES (?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?)"
+  ).run(
+    taskId,
+    input?.accountId || plan.account_id || null,
+    plan.id,
+    input?.agentRunId || null,
+    title,
+    input?.description || null,
+    input?.priority || 'medium',
+    Number(order),
+    input?.tokenBudget ?? null,
+    input?.requiresApproval ? 1 : 0,
+    JSON.stringify(taskMetadata(ctx, input)),
+  );
+  refreshPlanCounts(ctx, plan.id);
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ?').get(taskId));
+}
+
+const PRIORITY_ORDER = Object.freeze({ critical: 0, high: 1, medium: 2, low: 3 });
+
+function getTask(ctx, taskId) {
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ? LIMIT 1').get(taskId));
+}
+
+function dependencyBlockers(ctx, task) {
+  const ids = Array.isArray(task?.metadata?.depends_on) ? task.metadata.depends_on : [];
+  if (!ids.length) return [];
+  const blockers = [];
+  for (const dependencyId of ids) {
+    const dependency = getTask(ctx, dependencyId);
+    if (!dependency || dependency.status !== 'complete') {
+      blockers.push({
+        id: dependencyId,
+        status: dependency?.status || 'missing',
+        title: dependency?.title || null,
+      });
+    }
+  }
+  return blockers;
+}
+
+function pendingAcceptance(task) {
+  const entries = Array.isArray(task?.metadata?.acceptance) ? task.metadata.acceptance : [];
+  return entries.filter((entry) => {
+    if (typeof entry === 'string') return true;
+    if (!entry || typeof entry !== 'object') return false;
+    return entry.required !== false && entry.status !== 'accepted';
+  });
+}
+
+export function getNextPlanStep(ctx, { planId = 'current', start = false } = {}) {
+  const plan = getPlan(ctx, planId);
+  if (!plan) throw new Error('plan_not_found');
+  const rank = (a, b) => {
+    const priority = (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99);
+    if (priority !== 0) return priority;
+    if (Number(a.sort_order) !== Number(b.sort_order)) return Number(a.sort_order) - Number(b.sort_order);
+    return Number(a.created_at_unix) - Number(b.created_at_unix);
+  };
+  const running = (plan.tasks || []).filter((task) => task.status === 'running').sort(rank);
+  if (running.length) {
+    const selected = running[0];
+    return {
+      plan: { id: plan.id, title: plan.title, status: plan.status },
+      step: selected,
+      selection: 'running',
+      blocked: [],
+      evidence: selected?.metadata?.evidence || [],
+      acceptance: selected?.metadata?.acceptance || [],
+      depends_on: selected?.metadata?.depends_on || [],
+      recommended_action: 'agentsam plan show ' + plan.id,
+    };
+  }
+
+  const candidates = (plan.tasks || [])
+    .filter((task) => task.status === 'open')
+    .sort(rank);
+
+  const blocked = [];
+  let selected = null;
+  for (const task of candidates) {
+    const blockers = dependencyBlockers(ctx, task);
+    if (!blockers.length) {
+      selected = task;
+      break;
+    }
+    blocked.push({ task_id: task.id, blockers });
+  }
+
+  if (selected && start) selected = setPlanStepStatus(ctx, selected.id, 'running');
+  return {
+    plan: { id: plan.id, title: plan.title, status: plan.status },
+    step: selected,
+    selection: selected ? (start ? 'started' : 'open') : 'none',
+    blocked,
+    evidence: selected?.metadata?.evidence || [],
+    acceptance: selected?.metadata?.acceptance || [],
+    depends_on: selected?.metadata?.depends_on || [],
+    recommended_action: selected ? ('agentsam plan ' + (start ? 'show ' : 'start ') + selected.id) : null,
+  };
+}
+
+export function addPlanStepEvidence(ctx, taskId, input = {}) {
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  const type = String(input.type || 'evidence').trim();
+  const ref = String(input.ref || '').trim();
+  if (!ref) throw new Error('evidence_ref_required');
+  const metadata = { ...task.metadata };
+  const evidence = Array.isArray(metadata.evidence) ? [...metadata.evidence] : [];
+  const duplicate = evidence.some((entry) => entry && typeof entry === 'object' && entry.type === type && entry.ref === ref);
+  if (!duplicate) {
+    evidence.push({
+      type,
+      ref,
+      hash: input.hash ? String(input.hash) : null,
+      note: input.note ? String(input.note) : null,
+      added_at_unix: Math.floor(Date.now() / 1000),
+    });
+  }
+  metadata.evidence = evidence;
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function acceptPlanStep(ctx, taskId, criterion, { evidenceRef = null } = {}) {
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  const text = String(criterion || '').trim();
+  if (!text) throw new Error('acceptance_criterion_required');
+  const metadata = { ...task.metadata };
+  const entries = Array.isArray(metadata.acceptance) ? [...metadata.acceptance] : [];
+  const now = Math.floor(Date.now() / 1000);
+  let matched = false;
+  metadata.acceptance = entries.map((entry) => {
+    const entryText = typeof entry === 'string' ? entry : String(entry?.criterion || '');
+    if (entryText !== text) return entry;
+    matched = true;
+    return {
+      criterion: text,
+      required: typeof entry === 'object' ? entry.required !== false : true,
+      status: 'accepted',
+      accepted_at_unix: now,
+      evidence_ref: evidenceRef || (typeof entry === 'object' ? entry.evidence_ref || null : null),
+    };
+  });
+  if (!matched) {
+    metadata.acceptance.push({
+      criterion: text,
+      required: true,
+      status: 'accepted',
+      accepted_at_unix: now,
+      evidence_ref: evidenceRef || null,
+    });
+  }
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function addPlanDependency(ctx, taskId, dependencyId) {
+  const task = getTask(ctx, taskId);
+  const dependency = getTask(ctx, dependencyId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  if (!dependency) throw new Error('dependency_not_found:' + dependencyId);
+  if (task.plan_id !== dependency.plan_id) throw new Error('dependency_cross_plan_not_allowed');
+  if (task.id === dependency.id) throw new Error('dependency_self_reference');
+  const metadata = { ...task.metadata };
+  const dependsOn = new Set(Array.isArray(metadata.depends_on) ? metadata.depends_on : []);
+  dependsOn.add(dependency.id);
+  metadata.depends_on = [...dependsOn];
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function setPlanStepStatus(ctx, taskId, status, { reason = null } = {}) {
+  const allowed = new Set(['open', 'running', 'blocked', 'complete', 'cancelled']);
+  if (!allowed.has(status)) throw new Error('invalid_step_status:' + status);
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  if (status === 'complete') {
+    const blockers = dependencyBlockers(ctx, task);
+    if (blockers.length) throw new Error('step_dependencies_incomplete:' + blockers.map((row) => row.id).join(','));
+    const acceptance = pendingAcceptance(task);
+    if (acceptance.length) {
+      const labels = acceptance.map((entry) => typeof entry === 'string' ? entry : entry.criterion).filter(Boolean);
+      throw new Error('step_acceptance_incomplete:' + labels.join(' | '));
+    }
+  }
+  const metadata = { ...task.metadata };
+  if (status === 'blocked') metadata.blocker_reason = reason || metadata.blocker_reason || 'blocked';
+  else metadata.blocker_reason = null;
+
+  let startedSql = 'started_at_unix';
+  let completedSql = 'NULL';
+  if (status === 'running') startedSql = 'COALESCE(started_at_unix, unixepoch())';
+  if (status === 'complete') completedSql = 'unixepoch()';
+  if (status === 'cancelled') completedSql = 'COALESCE(completed_at_unix, unixepoch())';
+
+  ctx.db.prepare(
+    'UPDATE agentsam_todo SET status = ?, metadata_json = ?, started_at_unix = ' + startedSql +
+    ', completed_at_unix = ' + completedSql + ', updated_at_unix = unixepoch() WHERE id = ?'
+  ).run(status, JSON.stringify(metadata), taskId);
+  refreshPlanCounts(ctx, task.plan_id);
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ?').get(taskId));
+}
+
+export function setPlanStatus(ctx, planId, status) {
+  const allowed = new Set(['draft', 'active', 'complete', 'abandoned']);
+  if (!allowed.has(status)) throw new Error('invalid_plan_status:' + status);
+  const plan = getPlan(ctx, planId || 'current');
+  if (!plan) throw new Error('plan_not_found');
+  ctx.db.prepare('UPDATE agentsam_plans SET status = ?, updated_at_unix = unixepoch() WHERE id = ?').run(status, plan.id);
+  return getPlan(ctx, plan.id);
+}

package/src/commands/plan.js

@@ -0,0 +1,183 @@
+import { runBrand } from './brand.js';
+import {
+  acceptPlanStep,
+  addPlanDependency,
+  addPlanStep,
+  addPlanStepEvidence,
+  createPlan,
+  getNextPlanStep,
+  getPlan,
+  listPlans,
+  openPlanLedger,
+  setPlanStatus,
+  setPlanStepStatus,
+} from './plan-ledger.js';
+
+function parse(argv = []) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (!value.startsWith('--')) {
+      opts._.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      opts[key] = next;
+      i += 1;
+    } else {
+      opts[key] = true;
+    }
+  }
+  return opts;
+}
+
+function renderPlan(plan) {
+  if (!plan) return 'No active local plan.\n';
+  const lines = [
+    '',
+    'AgentSam plan',
+    '',
+    '  id        ' + plan.id,
+    '  title     ' + plan.title,
+    '  type      ' + plan.plan_type,
+    '  status    ' + plan.status,
+    '  goal      ' + (plan.metadata?.goal || plan.summary_text || ''),
+    '  repo      ' + (plan.metadata?.repository_id || 'unknown'),
+    '  revision  ' + (plan.metadata?.revision || 'uncommitted/unknown'),
+    '  progress  ' + plan.tasks_done + '/' + plan.tasks_total + ' complete - ' + plan.tasks_blocked + ' blocked',
+  ];
+  if (plan.tasks?.length) {
+    lines.push('', '  steps');
+    for (const step of plan.tasks) {
+      const marker = step.status === 'complete' ? '[x]' : step.status === 'blocked' ? '[!]' : step.status === 'running' ? '[>]' : '[ ]';
+      lines.push('    ' + marker + ' ' + step.id + '  [' + step.status + '] ' + step.title);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function help() {
+  console.log([
+    '',
+    'agentsam plan - durable project-local work plans',
+    '',
+    '  agentsam plan new "<title>" [--goal "..."] [--type feature|sprint|refactor|incident|daily|run]',
+    '  agentsam plan list [--all] [--json]',
+    '  agentsam plan show [current|PLAN_ID] [--json]',
+    '  agentsam plan next [--plan PLAN_ID] [--start] [--json]',
+    '  agentsam plan add "<step>" [--plan PLAN_ID] [--kind inspect|implement|verify|deploy|decision] [--acceptance "..."]',
+    '  agentsam plan evidence TODO_ID --type TYPE --ref REF [--note "..."]',
+    '  agentsam plan accept TODO_ID "<criterion>" [--evidence REF]',
+    '  agentsam plan depends TODO_ID DEPENDENCY_ID',
+    '  agentsam plan start TODO_ID',
+    '  agentsam plan done TODO_ID',
+    '  agentsam plan block TODO_ID [--reason "..."]',
+    '  agentsam plan cancel TODO_ID',
+    '  agentsam plan complete [PLAN_ID]',
+    '  agentsam plan abandon [PLAN_ID]',
+    '',
+    'Existing domain plan:',
+    '  agentsam plan brand [--goap] [--json] [--write]',
+    '',
+  ].join('\n'));
+}
+
+export async function runPlan(argv = []) {
+  const opts = parse(argv);
+  const [sub, ...rest] = opts._;
+  if (!sub || sub === 'help' || opts.help) return help();
+  if (sub === 'brand') {
+    return runBrand(['plan', ...rest, ...(opts.json ? ['--json'] : []), ...(opts.goap ? ['--goap'] : []), ...(opts.write ? ['--write'] : [])]);
+  }
+
+  const ctx = openPlanLedger(process.cwd());
+  try {
+    let result;
+    if (sub === 'new') {
+      result = createPlan(ctx, {
+        title: rest.join(' '),
+        goal: opts.goal,
+        planType: opts.type || 'feature',
+        tokenBudget: opts.budget ? Number(opts.budget) : null,
+      });
+    } else if (sub === 'list') {
+      result = listPlans(ctx, { all: Boolean(opts.all) });
+    } else if (sub === 'show') {
+      result = getPlan(ctx, rest[0] || 'current');
+    } else if (sub === 'next') {
+      result = getNextPlanStep(ctx, { planId: opts.plan || 'current', start: Boolean(opts.start) });
+    } else if (sub === 'add') {
+      result = addPlanStep(ctx, {
+        planId: opts.plan || 'current',
+        title: rest.join(' '),
+        description: opts.description || null,
+        priority: opts.priority || 'medium',
+        kind: opts.kind || 'work',
+        tokenBudget: opts.budget ? Number(opts.budget) : null,
+        requiresApproval: Boolean(opts.approval),
+        acceptance: opts.acceptance ? [{ criterion: String(opts.acceptance), required: true, status: 'pending' }] : [],
+      });
+    } else if (sub === 'evidence') {
+      if (!rest[0]) throw new Error('TODO_ID is required');
+      result = addPlanStepEvidence(ctx, rest[0], { type: opts.type, ref: opts.ref, note: opts.note, hash: opts.hash });
+    } else if (sub === 'accept') {
+      if (!rest[0]) throw new Error('TODO_ID is required');
+      result = acceptPlanStep(ctx, rest[0], rest.slice(1).join(' '), { evidenceRef: opts.evidence || null });
+    } else if (sub === 'depends') {
+      if (!rest[0] || !rest[1]) throw new Error('TODO_ID and DEPENDENCY_ID are required');
+      result = addPlanDependency(ctx, rest[0], rest[1]);
+    } else if (['start', 'done', 'block', 'cancel'].includes(sub)) {
+      const taskId = rest[0];
+      if (!taskId) throw new Error('TODO_ID is required');
+      const status = { start: 'running', done: 'complete', block: 'blocked', cancel: 'cancelled' }[sub];
+      result = setPlanStepStatus(ctx, taskId, status, { reason: opts.reason || null });
+    } else if (sub === 'complete' || sub === 'abandon') {
+      result = setPlanStatus(ctx, rest[0] || 'current', sub === 'complete' ? 'complete' : 'abandoned');
+    } else {
+      return help();
+    }
+
+    if (opts.json) console.log(JSON.stringify(result, null, 2));
+    else if (sub === 'list') {
+      if (!result.length) console.log('\nNo local plans for this repository.\n');
+      else {
+        console.log('\nAgentSam plans\n');
+        for (const plan of result) console.log('  ' + plan.id + '  [' + plan.status + '] ' + plan.title + '  ' + plan.tasks_done + '/' + plan.tasks_total);
+        console.log('');
+      }
+    } else if (sub === 'next') {
+      if (!result.step) {
+        console.log('\nNo executable open step. Check dependencies or plan completion.\n');
+      } else {
+        console.log([
+          '',
+          'Next executable step',
+          '',
+          '  ' + result.step.id,
+          '  ' + result.step.title,
+          '',
+          '  kind       ' + (result.step.metadata?.kind || 'work'),
+          '  priority   ' + result.step.priority,
+          '  plan       ' + result.plan.title,
+          '  depends    ' + (result.depends_on.length ? result.depends_on.join(', ') : 'none'),
+          '  status     ' + result.step.status,
+          '  evidence   ' + result.evidence.length,
+          '  acceptance ' + result.acceptance.length,
+          '',
+          '  Recommended',
+          '    ' + result.recommended_action,
+          '',
+        ].join('\n'));
+      }
+    } else if (['add','evidence','accept','depends'].includes(sub) || ['start', 'done', 'block', 'cancel'].includes(sub)) {
+      console.log('\n  ' + result.id + '  [' + result.status + '] ' + result.title + '\n');
+    } else {
+      console.log(renderPlan(result));
+    }
+    return result;
+  } finally {
+    ctx.close();
+  }
+}

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/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/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' },