@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/commands/setup.js

@@ -0,0 +1,279 @@
+/**
+ * Interactive Agent Sam setup — discover → plan → approve → execute → verify + receipt.
+ */
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { discoverEnvironment, renderEnvironment } from '../lib/setup/discover.js';
+import { buildSetupPlan, renderSetupPlan } from '../lib/setup/planner.js';
+import {
+  collectGooglePermissionInventory,
+  executeSetupPlan,
+} from '../lib/setup/execute.js';
+import { listCapabilityRecipes } from '../lib/setup/recipes.js';
+import {
+  planRuntimeSetup,
+  renderRuntimePlan,
+  writeRuntimePlanReceipt,
+  writeRuntimeInstallReceipt,
+  RUNTIME_PROFILES,
+} from '../lib/setup/runtime.js';
+import { runRuntime } from './runtime.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function printHelp(write) {
+  writeLine(write, '');
+  writeLine(write, '  Agent Sam · setup');
+  writeLine(write, '');
+  writeLine(write, '  agentsam setup                      interactive discover + plan');
+  writeLine(write, '  agentsam setup --yes                 approve plan non-interactively');
+  writeLine(write, '  agentsam setup --dry-run             plan only');
+  writeLine(write, '  agentsam setup runtime               Discover → profiles → GOAP → receipts');
+  writeLine(write, '  agentsam setup runtime --profile my_computer --yes');
+  writeLine(write, '  agentsam setup image.vectorize       specific capability');
+  writeLine(write, '  agentsam setup google.cloud');
+  writeLine(write, '  agentsam setup google.cloud --inventory');
+  writeLine(write, '  agentsam setup --list');
+  writeLine(write, '  agentsam setup --json');
+  writeLine(write, '');
+  writeLine(write, '  Stages: discover → plan → explain → approve → execute → verify + receipt');
+  writeLine(write, '  Native installers: Homebrew / apt / winget / npm — Agent Sam does not replace them.');
+  writeLine(write, '');
+}
+
+async function confirmProceed(write, { yes = false } = {}) {
+  if (yes) return true;
+  if (!input.isTTY || !output.isTTY) {
+    writeLine(write, '  Non-interactive shell — pass --yes to execute, or --dry-run to plan only.');
+    return false;
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = String(await rl.question('  Proceed? [y/N] ')).trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function runSetupRuntime(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const home = options.home;
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const dryRun = argv.includes('--dry-run');
+  const profileIdx = argv.findIndex((a) => a === '--profile' || a === '-p');
+  const profileId =
+    profileIdx >= 0 && argv[profileIdx + 1]
+      ? argv[profileIdx + 1]
+      : argv.find((a) => a.startsWith('--profile='))?.slice('--profile='.length) || null;
+
+  if (argv.includes('help') || argv.includes('--help') || argv.includes('-h')) {
+    writeLine(write, '');
+    writeLine(write, '  agentsam setup runtime');
+    writeLine(write, '  Profiles:');
+    for (const p of RUNTIME_PROFILES) {
+      writeLine(write, `    ${p.id.padEnd(18)} ${p.label} — ${p.description}`);
+    }
+    writeLine(write, '');
+    writeLine(write, '  agentsam setup runtime --dry-run');
+    writeLine(write, '  agentsam setup runtime --profile my_computer --yes');
+    writeLine(write, '  Receipts under ~/.agentsam/runtime/');
+    writeLine(write, '');
+    return 0;
+  }
+
+  if (argv.includes('--list')) {
+    if (json) {
+      write(`${JSON.stringify(RUNTIME_PROFILES, null, 2)}\n`);
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  Runtime profiles');
+      for (const p of RUNTIME_PROFILES) {
+        writeLine(write, `    ${p.id.padEnd(18)} ${p.label} — ${p.description}`);
+      }
+      writeLine(write, '');
+    }
+    return 0;
+  }
+
+  const plan = await planRuntimeSetup({ home, profileId });
+  const planPath = writeRuntimePlanReceipt(plan, home);
+  write(renderRuntimePlan(plan));
+
+  if (json && (dryRun || !yes)) {
+    write(JSON.stringify({ plan, plan_receipt: planPath, executed: false }, null, 2) + '\n');
+    return plan.recommended?.eligible ? 0 : 2;
+  }
+
+  if (dryRun || !yes) {
+    writeLine(write, `  Plan receipt  ${planPath}`);
+    if (!yes) {
+      writeLine(write, '  Pass --yes to install agentsamd (when profile needs it) and write install receipt.');
+    }
+    writeLine(write, '');
+    return 0;
+  }
+
+  const recommended = plan.recommended;
+  if (!recommended?.eligible) {
+    writeLine(write, '  ✕ No eligible profile — resolve missing tools/capabilities first.');
+    writeLine(write, '');
+    return 2;
+  }
+
+  let installResult = null;
+  if (recommended.target.runtime_adapter === 'agentsamd') {
+    const code = await runRuntime(['install', '--yes'], { write, home });
+    installResult = { code, adapter: 'agentsamd' };
+    if (code !== 0) return code;
+  }
+
+  const receiptPath = writeRuntimeInstallReceipt({
+    product: 'agentsam-setup-runtime',
+    profile_id: recommended.profile.id,
+    target: recommended.target,
+    goap: recommended.goap,
+    install: installResult,
+    plan_receipt: planPath,
+  }, home);
+
+  writeLine(write, `  ✓ Runtime setup receipt  ${receiptPath}`);
+  writeLine(write, '');
+  if (json) {
+    write(JSON.stringify({
+      plan,
+      plan_receipt: planPath,
+      install_receipt: receiptPath,
+      executed: true,
+    }, null, 2) + '\n');
+  }
+  return 0;
+}
+
+export async function runSetup(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const dryRun = argv.includes('--dry-run');
+  const inventory = argv.includes('--inventory');
+  const args = argv.filter(
+    (a) => !['--json', '--yes', '-y', '--dry-run', '--inventory', '--list', 'help', '--help', '-h', '--profile', '-p'].includes(a)
+      && !String(a).startsWith('--profile='),
+  );
+
+  if (argv.includes('help') || argv.includes('--help') || argv.includes('-h')) {
+    printHelp(write);
+    return 0;
+  }
+
+  if (args[0] === 'runtime') {
+    return runSetupRuntime(argv.filter((a) => a !== 'runtime'), options);
+  }
+
+  if (argv.includes('--list')) {
+    const recipes = listCapabilityRecipes();
+    if (json) {
+      write(JSON.stringify(recipes.map((r) => ({
+        id: r.id,
+        displayName: r.displayName,
+        description: r.description,
+        risk: r.risk,
+      })), null, 2) + '\n');
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  Installable capabilities');
+      for (const r of recipes) {
+        writeLine(write, `    ${r.id.padEnd(22)} ${r.displayName}`);
+      }
+      writeLine(write, '');
+    }
+    return 0;
+  }
+
+  if (args[0] === 'google.cloud' && inventory) {
+    const inv = await collectGooglePermissionInventory({ env });
+    if (json) write(JSON.stringify(inv, null, 2) + '\n');
+    else {
+      writeLine(write, '');
+      writeLine(write, '  Agent Sam · Google Cloud permission inventory');
+      writeLine(write, '');
+      const active = inv.config?.core?.account || '(unset)';
+      const project = inv.config?.core?.project || '(unset)';
+      writeLine(write, `  active account   ${active}`);
+      writeLine(write, `  project          ${project}`);
+      writeLine(write, `  auth accounts    ${(inv.auth_list || []).length}`);
+      const scopes = String(inv.user_token_scopes?.scope || '').split(/\s+/).filter(Boolean);
+      writeLine(write, `  token scopes     ${scopes.length ? scopes.length : 'unknown'}`);
+      for (const s of scopes.slice(0, 12)) writeLine(write, `    • ${s}`);
+      const roles = inv.iam_roles_for_active_user?.roles || [];
+      writeLine(write, `  IAM roles        ${roles.length ? roles.join(', ') : '—'}`);
+      writeLine(write, `  projects visible ${(inv.projects || []).length}`);
+      writeLine(write, `  billing accts    ${(inv.billing_accounts || []).length}`);
+      if (inv.errors?.length) {
+        writeLine(write, '');
+        writeLine(write, '  Errors');
+        for (const e of inv.errors) writeLine(write, `    ✕ ${e}`);
+      }
+      writeLine(write, '');
+      writeLine(write, '  Next');
+      writeLine(write, '    agentsam gcloud auth login');
+      writeLine(write, '    agentsam google-cloud connection set --identity EMAIL --project PROJECT');
+      writeLine(write, '    agentsam google-cloud doctor');
+      writeLine(write, '');
+    }
+    return inv.errors?.length ? 2 : 0;
+  }
+
+  const capabilityIds = args.length ? args : listCapabilityRecipes().map((r) => r.id);
+  const environment = await discoverEnvironment({ env });
+  const plan = await buildSetupPlan({ environment, capabilityIds });
+
+  if (json && dryRun) {
+    write(JSON.stringify({ environment, plan }, null, 2) + '\n');
+    return 0;
+  }
+
+  write(renderEnvironment(environment));
+  write(renderSetupPlan(plan));
+
+  if (dryRun || !plan.would_install.length) {
+    if (!plan.would_install.length) {
+      writeLine(write, '  ✓ setup complete — requested capabilities already satisfied');
+      writeLine(write, '  Next: agentsam doctor · agentsam capabilities · agentsam google-cloud doctor');
+      writeLine(write, '');
+    }
+    if (json) write(JSON.stringify({ environment, plan, executed: false }, null, 2) + '\n');
+    return 0;
+  }
+
+  const approved = await confirmProceed(write, { yes });
+  if (!approved) {
+    writeLine(write, '  Cancelled. Re-run with --yes to install, or --dry-run to plan only.');
+    writeLine(write, '');
+    return 1;
+  }
+
+  const receipt = await executeSetupPlan(plan, { env, write, home: options.home });
+  writeLine(write, '');
+  writeLine(write, receipt.ok ? '  ✓ Agent Sam setup complete' : '  ✕ Setup finished with failures');
+  writeLine(write, `  Receipt  ${receipt.path}`);
+  writeLine(write, '');
+  writeLine(write, '  Next');
+  writeLine(write, '    agentsam doctor');
+  writeLine(write, '    agentsam capabilities');
+  if (capabilityIds.includes('google.cloud')) {
+    writeLine(write, '    agentsam setup google.cloud --inventory');
+    writeLine(write, '    agentsam gcloud auth login');
+  }
+  if (capabilityIds.includes('image.vectorize')) {
+    writeLine(write, '    agentsam image optimize ./logo.png   # when image command ships');
+  }
+  writeLine(write, '');
+
+  if (json) write(JSON.stringify({ environment, plan, receipt }, null, 2) + '\n');
+  return receipt.ok ? 0 : 2;
+}

package/src/commands/shell.js

@@ -20,7 +20,7 @@ import { createInlineActivity } from '../ui/cli/activity.js';
 import { createCliRuntimePresenter } from '../ui/cli/runtime-events.js';
 import { renderCliFooter, renderDiffPreview, renderUsagePanel } from '../ui/cli/footer.js';
 import { diagnosticFromError, renderDiagnosticError } from '../errors/index.js';
-import { getModelRecord, mergeModelReference } from '../models/index.js';
+import { getModelRecord, mergeModelReference, listModelCatalog } from '../models/index.js';
 import { discoverProviderModels } from '../models/discovery.js';
 import { detectCliProject, findCliProjectRoot, readCliPreferences, updateCliPreferences } from '../lib/cli-preferences.js';
 import { buildContextEconomicsReport, renderContextEconomics } from './context-economics.js';
@@ -31,6 +31,9 @@ import { createLocalSession, saveLocalSession, localSessionElapsedMs, loadSessio
 import { runtimeDatabasePath } from '../local/runtime-store.js';
 import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '../lib/execution-approvals.js';
 import { runWhoami } from './whoami.js';
+import { runCredentials } from './credentials.js';
+import { runCheatSheet } from './cheat-sheet.js';
+import pkg from '../../package.json' with { type: 'json' };
 import { runLogin, runLogout } from './account-auth.js';
 import { runHelp } from '../ui/cli/help.js';
 import { hydrateSecureCredentials } from '../security/local-vault.js';
@@ -40,6 +43,11 @@ import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git
 import { syncWorkspaceStateToD1, readWorkspaceStateFromD1 } from '../../packages/agentsam-repository/src/workspace-state.js';
 import { syncGitCommitsToD1 } from '../../packages/agentsam-repository/src/work-tracking.js';
 import { readGoapState, listGoapTickets, createGoapGoal, switchGoapGoal, closeGoapGoal, renderGoapStatus, renderGoapList, renderGoapGoal, renderGoapWhy, renderGoapPlan } from '../../packages/agentsam-repository/src/goap.js';
+import { SkillRegistry, SkillRuntime, SkillContentResolver } from '../skills/index.js';
+import {
+  presentAgentSamInteraction,
+  handleSkillInteractionChoice,
+} from './interaction-clack.js';
 
 function writeLine(write, value = '') { write(`${value}\n`); }
 
@@ -593,7 +601,7 @@ async function runInteractiveModelTurn(prompt, state) {
   const provider = createProviderAdapter({
     modelRecord: model,
     credential,
-    endpoint: model.provider === 'ollama' ? process.env.OLLAMA_BASE_URL : undefined,
+    endpoint: model.provider === 'ollama' ? (process.env.AGENTSAM_OLLAMA_ENDPOINT || process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST) : undefined,
     fetchImpl: state.providerFetchImpl,
   });
   const capabilityAdapter = createCapabilityAdapter();
@@ -784,12 +792,14 @@ export async function dispatchShellLine(line, state = {}) {
     const commonVerbs = [
       'help', 'exit', 'quit', 'clear', 'status', 'models', 'model',
       'whoami', 'cf', 'cloudflare', 'db', 'tunnel', 'connections',
-      'connect', 'usage', 'session', 'providers', 'settings', 'logs',
+      'connect', 'usage', 'session', 'providers', 'credentials', 'cheatsheet',
+      'settings', 'logs',
       'git', 'diff', 'pwd', 'cd', 'fast', 'flex', 'standard', 'reasoning',
     ];
     if (commonVerbs.includes(bare)) {
-      tokens[0] = `/${bare}`;
+      tokens[0] = bare === 'cheatsheet' ? '/cheat-sheet' : `/${bare}`;
     }
+    if (bare === 'cheat-sheet') tokens[0] = '/cheat-sheet';
   }
 
   const [command, ...args] = tokens;
@@ -861,6 +871,14 @@ export async function dispatchShellLine(line, state = {}) {
           state.rl?.resume?.();
         }
         break;
+      case '/credentials':
+      case '/credential':
+        await runCredentials(args.length ? args : ['audit'], { write, home: state.home });
+        break;
+      case '/cheat-sheet':
+      case '/cheatsheet':
+        runCheatSheet(args, { write, version: pkg.version });
+        break;
       case '/login':
         await runLogin(args, { write, home: state.home });
         break;
@@ -1026,8 +1044,44 @@ export async function dispatchShellLine(line, state = {}) {
           await runInteractiveModelTurn(line, state);
           break;
         }
+        {
+          // Explicit slash → portable skill registry (no D1 / R2 / subagents).
+          const skillRuntime = new SkillRuntime({
+            registry: new SkillRegistry({ home: state.home }),
+            contentResolver: new SkillContentResolver(),
+          });
+          const skillResult = await skillRuntime.invoke({ input: line });
+          if (skillResult.matched) {
+            const interactiveStatuses = new Set(['needs_input', 'needs_approval', 'blocked']);
+            if (
+              state.interactive &&
+              interactiveStatuses.has(skillResult.interaction?.status) &&
+              skillResult.interaction?.prompt
+            ) {
+              const choice = await presentAgentSamInteraction(skillResult.interaction, {
+                write,
+                interactive: state.interactive,
+              });
+              if (choice.action === 'create' || String(choice.value || '').startsWith('create')) {
+                await handleSkillInteractionChoice(choice, { write, home: state.home });
+              } else if (choice.action === 'list' || choice.value === 'list') {
+                await handleSkillInteractionChoice(choice, { write, home: state.home });
+              } else if (choice.action === 'install' || choice.value === 'install') {
+                await handleSkillInteractionChoice(choice, { write, home: state.home });
+              }
+            } else if (skillResult.interaction?.prompt?.message) {
+              for (const msgLine of String(skillResult.interaction.prompt.message).split('\n')) {
+                writeLine(write, `  ${msgLine}`);
+              }
+            } else if (skillResult.modelInstructions?.content) {
+              writeLine(write, `  skill ${skillResult.skill?.id} · ${skillResult.receipt?.checksum || 'resolved'}`);
+              writeLine(write, `  (turn instructions ready · ${skillResult.tools?.length || 0} tools declared)`);
+            }
+            break;
+          }
+        }
         writeLine(write, `  Unknown Agent Sam command: ${command}`);
-        writeLine(write, '  Type / or /help for available commands.');
+        writeLine(write, '  Type / or /help for available commands. Use /skills for installable slash skills.');
         return { handled: false, exit: false, cwd: state.cwd };
     }
   } catch (error) {

package/src/commands/skill.js

@@ -0,0 +1,248 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  SkillRegistry,
+  SkillRuntime,
+  SkillContentResolver,
+  createUserSkill,
+  installSkillFromPath,
+  aliasSkill,
+  removeSkill,
+  readLocalRegistry,
+} from '../skills/index.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function help() {
+  return [
+    'AgentSam · skill',
+    '  agentsam skill list',
+    '  agentsam skill create <id>',
+    '  agentsam skill inspect <id>',
+    '  agentsam skill edit <id>          (prints path to edit)',
+    '  agentsam skill install <path|npm-package> [--alias /trigger]',
+    '  agentsam skill alias <id> </trigger>',
+    '  agentsam skill remove <id>',
+    '  agentsam skill publish <id>       (prints package checklist; no network)',
+    '  agentsam skill invoke </trigger> [args...]',
+    '',
+    'Slash triggers are local. Package manifests only suggest a trigger.',
+    'Collisions require an explicit alias — nothing is globally reserved.',
+    '',
+  ].join('\n');
+}
+
+function looksLikeNpmPackage(source) {
+  const s = String(source || '').trim();
+  if (!s) return false;
+  if (s.startsWith('.') || s.startsWith('/') || s.includes('\\')) return false;
+  if (s.startsWith('@')) return true;
+  // bare package name (no path separators)
+  return !s.includes('/') && !s.endsWith('.json');
+}
+
+/**
+ * Download an npm package tarball and return the extracted package root
+ * that contains agentsam.skill.json (or package root for relative resolve).
+ */
+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 extractDir = path.join(tmp, 'pkg');
+  fs.mkdirSync(extractDir, { recursive: true });
+  const tar = spawn('tar', ['-xzf', tgzPath, '-C', extractDir], { encoding: 'utf8' });
+  if ((tar.status ?? 1) !== 0) {
+    throw new Error(`npm_extract_failed:${String(tar.stderr || '').trim() || 'tar failed'}`);
+  }
+  const packageRoot = path.join(extractDir, 'package');
+  const candidates = [
+    path.join(packageRoot, 'agentsam.skill.json'),
+    path.join(packageRoot, 'skill', 'agentsam.skill.json'),
+    path.join(packageRoot, 'skills', 'agentsam.skill.json'),
+  ];
+  for (const file of candidates) {
+    if (fs.existsSync(file)) return path.dirname(file);
+  }
+  // walk one level
+  if (fs.existsSync(packageRoot)) {
+    for (const name of fs.readdirSync(packageRoot)) {
+      const nested = path.join(packageRoot, name, 'agentsam.skill.json');
+      if (fs.existsSync(nested)) return path.dirname(nested);
+    }
+  }
+  throw new Error(`agentsam.skill.json_not_found_in_package:${spec}`);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ write?: Function, home?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+export async function runSkill(argv = [], options = {}) {
+  const write = options.write || ((t) => process.stdout.write(t));
+  const [command = 'list', ...rest] = argv;
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    write(help());
+    return null;
+  }
+
+  const registry = new SkillRegistry({ home: options.home, env: options.env });
+  const runtime = new SkillRuntime({
+    registry,
+    contentResolver: new SkillContentResolver(),
+  });
+
+  if (command === 'list') {
+    const rows = registry.list();
+    writeLine(write, '');
+    writeLine(write, '  AgentSam · skills');
+    writeLine(write, '');
+    for (const row of rows) {
+      const trig = row.trigger ? row.trigger.padEnd(22) : '(no trigger)'.padEnd(22);
+      writeLine(write, `  ${trig} ${row.id.padEnd(28)} [${row.source}]`);
+      if (row.description) writeLine(write, `    ${row.description}`);
+    }
+    writeLine(write, '');
+    return rows;
+  }
+
+  if (command === 'create') {
+    const id = rest[0];
+    if (!id) throw new Error('skill create requires <id>');
+    const result = createUserSkill(id, { home: options.home, env: options.env });
+    writeLine(write, '');
+    writeLine(write, `  created ${result.manifest.id}`);
+    writeLine(write, `  trigger  ${result.trigger}`);
+    writeLine(write, `  path     ${result.root}`);
+    writeLine(write, '');
+    return result;
+  }
+
+  if (command === 'inspect') {
+    const id = rest[0];
+    if (!id) throw new Error('skill inspect requires <id>');
+    const skill = registry.getById(id);
+    if (!skill) throw new Error(`unknown_skill:${id}`);
+    write(`${JSON.stringify(skill, null, 2)}\n`);
+    return skill;
+  }
+
+  if (command === 'edit') {
+    const id = rest[0];
+    if (!id) throw new Error('skill edit requires <id>');
+    const local = readLocalRegistry({ home: options.home, env: options.env });
+    const entry = local.entries[id];
+    if (!entry) throw new Error(`skill_not_user_editable:${id}`);
+    writeLine(write, entry.manifestPath);
+    writeLine(write, path.join(entry.baseDir, 'SKILL.md'));
+    return entry;
+  }
+
+  if (command === 'install') {
+    const source = rest[0];
+    if (!source) throw new Error('skill install requires <path|npm-package>');
+    let aliasOnCollision;
+    for (let i = 1; i < rest.length; i += 1) {
+      if (rest[i] === '--alias' || rest[i] === '--trigger') aliasOnCollision = rest[++i];
+    }
+
+    let installPath = source;
+    if (looksLikeNpmPackage(source)) {
+      writeLine(write, `  packing ${source}…`);
+      installPath = resolveNpmSkillPackage(source, options);
+    }
+
+    try {
+      const result = installSkillFromPath(installPath, {
+        home: options.home,
+        env: options.env,
+        aliasOnCollision,
+      });
+      writeLine(write, '');
+      writeLine(write, `  installed ${result.id}`);
+      writeLine(write, `  trigger   ${result.trigger}`);
+      writeLine(write, '');
+      return result;
+    } catch (error) {
+      if (error?.code === 'SLASH_COLLISION') {
+        writeLine(write, '');
+        writeLine(write, `  Conflict: ${error.suggested} already owned by ${error.owner}`);
+        writeLine(write, '  Choose an alias:');
+        for (const c of error.candidates || []) {
+          writeLine(write, `    agentsam skill install ${source} --alias ${c}`);
+        }
+        writeLine(write, '');
+        throw error;
+      }
+      throw error;
+    }
+  }
+
+  if (command === 'alias') {
+    const id = rest[0];
+    const trigger = rest[1];
+    if (!id || !trigger) throw new Error('skill alias requires <id> </trigger>');
+    const result = aliasSkill(id, trigger, { home: options.home, env: options.env });
+    writeLine(write, `  ${result.id} → ${result.trigger}`);
+    return result;
+  }
+
+  if (command === 'remove') {
+    const id = rest[0];
+    if (!id) throw new Error('skill remove requires <id>');
+    const result = removeSkill(id, { home: options.home, env: options.env });
+    writeLine(write, result.removed ? `  removed ${id}` : `  ${id} was not installed`);
+    return result;
+  }
+
+  if (command === 'publish') {
+    const id = rest[0];
+    if (!id) throw new Error('skill publish requires <id>');
+    const skill = registry.getById(id);
+    if (!skill) throw new Error(`unknown_skill:${id}`);
+    writeLine(write, '');
+    writeLine(write, '  Publish checklist (no network from portable core):');
+    writeLine(write, '  1. Ensure agentsam.skill.json validates as agentsam.skill.v1');
+    writeLine(write, '  2. npm publish (suggested slash is not globally reserved)');
+    writeLine(write, '  3. Consumers: agentsam skill install <path|@scope/pkg>');
+    writeLine(write, `  skill  ${skill.id}`);
+    writeLine(write, `  slash  ${skill.manifest.slash?.suggested || '(none)'}`);
+    writeLine(write, '');
+    return { id: skill.id, checklist: true };
+  }
+
+  if (command === 'invoke') {
+    const input = rest.join(' ').trim();
+    if (!input.startsWith('/')) throw new Error('skill invoke requires a /trigger');
+    const result = await runtime.invoke({ input });
+    write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+
+  throw new Error(`unknown skill command: ${command}`);
+}
+
+export function skillCommandHelp() {
+  return help();
+}

package/src/commands/skills.js

@@ -1,4 +1,4 @@
-import { getSkill, listSkills, loadSkill } from '../skills/index.js';
+import { getSkill, listSkills, loadSkill } from '../skills/catalog.js';
 
 function parse(argv = []) {
   const out = { id: '', json: false, references: false };

package/src/commands/start-local.js

@@ -32,8 +32,8 @@ export async function runStartLocal(opts = {}) {
   const port = opts.port ?? config?.pty_port ?? 3099;
 
   console.log(`
-  Agent Sam — local PTY
-  No Cloudflare · no tunnel · no IAM login
+  Agent Sam — local Studio plane (PTY + FS)
+  Loopback only · no tunnel · not ExecOS enroll
   `);
   if (!config) {
     console.log(`  ⚠ No .agentsam/config.json found; using current repository/directory as the PTY root.`);
@@ -45,6 +45,9 @@ export async function runStartLocal(opts = {}) {
   console.log(`  ✓ PTY listening  ${server.url}`);
   console.log(`  ✓ Health         ${server.healthUrl}`);
   console.log(`  ✓ Project root   ${server.cwd}`);
+  console.log(`  ✓ Workspace      ${server.workspace_id}`);
+  console.log(`  ✓ Capability     ${server.capability.capability.slice(0, 12)}… (loopback bootstrap)`);
+  console.log(`  ✓ Runtime file   ${server.runtimeFile}`);
   console.log(`  ✓ Shell          ${server.shell}`);
   console.log(`
   Project services:
@@ -52,6 +55,7 @@ export async function runStartLocal(opts = {}) {
     npm run db:status    → inspect local SQLite
     npx agentsam          → enter Agent Sam
 
+  Studio: open a filesystem workspace rooted at this same directory.
   Press Ctrl+C to stop.
   `);