@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/src/lib/project-config.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { tryResolveGitContext } from './git-context.js';
+
+export const PROJECT_CONFIG_PATH = '.agentsam/config.json';
+export const PROJECT_CONFIG_SCHEMA_VERSION = 2;
+
+function providerForHost(host) {
+  const value = String(host || '').toLowerCase();
+  if (value === 'github.com') return 'github';
+  if (value === 'gitlab.com') return 'gitlab';
+  if (value === 'bitbucket.org') return 'bitbucket';
+  return value ? 'git' : null;
+}
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function portableRepositoryIdFromGit(cwd = process.cwd()) {
+  const git = tryResolveGitContext({ cwd });
+  if (!git) return null;
+  const provider = providerForHost(git.remoteHost);
+  if (!provider || !git.repoFullName) return null;
+  const fullName = provider === 'github' ? git.repoFullName.toLowerCase() : git.repoFullName;
+  return `${provider}:${fullName}`;
+}
+
+export function newLocalRepositoryId() {
+  return `local:${randomUUID()}`;
+}
+
+export function createProjectManifest({
+  projectName,
+  preset = null,
+  profile = 'default',
+  runTarget = 'local',
+  sdkVersion = null,
+  repositoryId = null,
+  repositoryRemote = 'origin',
+} = {}) {
+  const name = clean(projectName);
+  if (!name) throw new Error('project_name_required');
+  const repoId = clean(repositoryId) || newLocalRepositoryId();
+  const target = clean(runTarget) || 'local';
+  return {
+    schema_version: PROJECT_CONFIG_SCHEMA_VERSION,
+    project: {
+      name,
+    },
+    repository: {
+      id: repoId,
+      remote: clean(repositoryRemote) || 'origin',
+    },
+    product: {
+      preset: preset ? clean(preset) : null,
+      features: [],
+      capabilities: [],
+    },
+    defaults: {
+      mode: 'agent',
+      profile: clean(profile) || 'default',
+      runtime: 'local',
+      model: 'auto',
+      deploy_target: target === 'local' ? null : target,
+    },
+    merkle: {
+      enabled: true,
+      semantic: true,
+      persistence: 'auto',
+    },
+    rules: {
+      file: '.agentsamrules',
+    },
+    knowledge: {
+      config: '.agentsam/knowledge.json',
+    },
+    local: {
+      database: '.agentsam/data/agentsam.sqlite',
+      schema: 'db/schema.sql',
+    },
+    sdk: {
+      created_with: sdkVersion || null,
+    },
+  };
+}
+
+export function projectConfigPath(root) {
+  return path.join(path.resolve(root), PROJECT_CONFIG_PATH);
+}
+
+export function readProjectConfig(root) {
+  return JSON.parse(fs.readFileSync(projectConfigPath(root), 'utf8'));
+}
+
+export function tryReadProjectConfig(root) {
+  try {
+    return readProjectConfig(root);
+  } catch {
+    return null;
+  }
+}
+
+export function writeProjectConfig(root, config) {
+  const filename = projectConfigPath(root);
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  fs.writeFileSync(filename, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return filename;
+}
+
+export function isProjectManifestV2(config) {
+  return Number(config?.schema_version) === PROJECT_CONFIG_SCHEMA_VERSION && Boolean(config?.project?.name);
+}
+
+// Accessors deliberately understand the old flat scaffold so existing projects keep working
+// while new projects use the committed portable v2 manifest.
+export function getProjectName(config, fallback = '') {
+  return clean(config?.project?.name || config?.project || fallback);
+}
+
+export function getProjectPreset(config) {
+  return clean(config?.product?.preset || config?.preset || config?.lane) || null;
+}
+
+export function getDefaultProfile(config) {
+  return clean(config?.defaults?.profile || config?.agent) || 'default';
+}
+
+export function getDefaultRuntime(config) {
+  return clean(config?.defaults?.runtime || config?.run_target) || 'local';
+}
+
+export function getDefaultModel(config) {
+  return clean(config?.defaults?.model) || 'auto';
+}
+
+export function getDeployTarget(config) {
+  return clean(config?.defaults?.deploy_target || config?.deploy_target) || null;
+}
+
+export function getRepositoryId(config) {
+  return clean(config?.repository?.id) || null;
+}
+
+export function getProjectRulesPath(config) {
+  return clean(config?.rules?.file) || '.agentsamrules';
+}
+
+export function getKnowledgeConfigPath(config) {
+  return clean(config?.knowledge?.config) || '.agentsam/knowledge.json';
+}
+
+export function getLocalDatabasePath(config) {
+  return clean(config?.local?.database || config?.db_path) || '.agentsam/data/agentsam.sqlite';
+}
+
+export function getLocalSchemaPath(config) {
+  return clean(config?.local?.schema || config?.db_schema) || 'db/schema.sql';
+}
+
+export function getCreatedWithVersion(config) {
+  return clean(config?.sdk?.created_with || config?.scaffold_version) || null;
+}
+
+export function setDeployTarget(config, target) {
+  const value = clean(target) || null;
+  if (isProjectManifestV2(config)) {
+    config.defaults ||= {};
+    config.defaults.deploy_target = value;
+  } else {
+    config.deploy_target = value;
+  }
+  return config;
+}
+
+export function setProductPreset(config, preset) {
+  if (isProjectManifestV2(config)) {
+    config.product ||= { preset: null, features: [], capabilities: [] };
+    config.product.preset = clean(preset?.id) || null;
+    config.product.features = [...(preset?.features || [])];
+    config.product.capabilities = [...(preset?.capabilities || [])];
+  } else {
+    config.preset = clean(preset?.id) || null;
+    config.features = [...(preset?.features || [])];
+    config.capabilities = [...(preset?.capabilities || [])];
+  }
+  return config;
+}
+
+export function setLocalModelCapability(config, provider = 'ollama') {
+  if (isProjectManifestV2(config)) {
+    config.models ||= { default: getDefaultModel(config) };
+    config.models.local = {
+      provider,
+      base_url_env: 'OLLAMA_BASE_URL',
+      model_env: 'OLLAMA_MODEL',
+      embed_model_env: 'OLLAMA_EMBED_MODEL',
+    };
+  } else {
+    config.local_model = {
+      provider,
+      local_only: true,
+      base_url_env: 'OLLAMA_BASE_URL',
+      model_env: 'OLLAMA_MODEL',
+      embed_model_env: 'OLLAMA_EMBED_MODEL',
+    };
+  }
+  return config;
+}
+
+export function ensureProjectManifest(root, options = {}) {
+  const existing = tryReadProjectConfig(root);
+  if (existing) return existing;
+  const gitId = portableRepositoryIdFromGit(root);
+  const manifest = createProjectManifest({
+    projectName: options.projectName || path.basename(path.resolve(root)),
+    preset: options.preset ?? null,
+    profile: options.profile || 'default',
+    runTarget: options.runTarget || 'local',
+    sdkVersion: options.sdkVersion || null,
+    repositoryId: options.repositoryId || gitId || newLocalRepositoryId(),
+    repositoryRemote: options.repositoryRemote || 'origin',
+  });
+  writeProjectConfig(root, manifest);
+  return manifest;
+}

package/src/lib/project-rules.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const PROJECT_RULES_FILENAME = '.agentsamrules';
+export const DEFAULT_PROJECT_RULES_MAX_CHARS = 24_000;
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function defaultProjectRules(projectName = 'this project') {
+  return `# Agent Sam project rules
+
+These instructions are committed with ${projectName} and apply when Agent Sam works in this repository.
+
+- Prefer repository evidence over assumptions.
+- Prefer structural lookup before semantic retrieval when an exact symbol or relationship can answer the question.
+- Keep retrieval bounded: metadata -> cards -> excerpt -> range -> full object only when required.
+- Keep secrets, account/runtime state, active runs, and machine-local preferences out of committed project configuration.
+- Treat Git as source-control authority and Merkle snapshots as filesystem evidence.
+- Run the smallest relevant validation before reporting a code change as complete.
+
+## Project-specific rules
+
+Add repository-specific conventions, commands, constraints, or architecture notes below this line.
+`;
+}
+
+export function ensureProjectRules(root, projectName = path.basename(path.resolve(root))) {
+  const filename = path.join(path.resolve(root), PROJECT_RULES_FILENAME);
+  if (fs.existsSync(filename)) return filename;
+  fs.writeFileSync(filename, defaultProjectRules(projectName), { encoding: 'utf8', flag: 'wx' });
+  return filename;
+}
+
+export function findProjectRules(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 16; i += 1) {
+    const filename = path.join(dir, PROJECT_RULES_FILENAME);
+    if (fs.existsSync(filename)) return filename;
+    const projectBoundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json'));
+    if (projectBoundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function loadProjectRules(startDir = process.cwd(), options = {}) {
+  const maxChars = Number(options.maxChars ?? DEFAULT_PROJECT_RULES_MAX_CHARS);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('project rules maxChars must be a positive integer');
+  const filename = options.filename ? path.resolve(options.filename) : findProjectRules(startDir);
+  if (!filename) return Object.freeze({ found: false, path: null, content: '', chars: 0, truncated: false, hash: null });
+  const source = fs.readFileSync(filename, 'utf8');
+  const truncated = source.length > maxChars;
+  const content = truncated ? `${source.slice(0, Math.max(0, maxChars - 1))}…` : source;
+  return Object.freeze({
+    found: true,
+    path: filename,
+    content,
+    chars: content.length,
+    source_chars: source.length,
+    truncated,
+    hash: sha256(source),
+  });
+}

package/src/lib/save-sdk-token.js

@@ -11,7 +11,7 @@ export function saveSdkTokenHint(cwd, token) {
   fs.mkdirSync(dir, { recursive: true });
   const hintPath = path.join(dir, 'credentials.env.example');
   const content = `# Agent Sam SDK — add to your shell profile (optional)
-export AGENTSAM_SDK_TOKEN=${t}
+export AGENTSAM_SDK_KEY=${t}
 export USER_GCP_PROJECT=YOUR_GCP_PROJECT_ID
 `;
   fs.writeFileSync(hintPath, content, 'utf8');

package/src/lib/slash-commands.js

@@ -15,8 +15,9 @@ export const SLASH_COMMANDS = [
   { cmd: '/git', description: 'Git status, diff, branch, commit, and remote', lane: 'git' },
   { cmd: '/db', description: 'Local SQLite status and query helpers', lane: 'data' },
   { cmd: '/agent', description: 'Send a goal to the configured Agent Sam', lane: 'agent' },
+  { cmd: '/models', description: 'Show available model providers and local models' },
+  { cmd: '/settings', description: 'Choose project, runtime, terminal, and model preference' },
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
-  { cmd: '/tui', description: 'Switch or preview terminal presentation', lane: 'terminal' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
   { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];

package/src/lib/tools.js

@@ -1,3 +1,5 @@
+import { DEFAULT_RESULT_POLICY } from '../context/result-policy.js';
+
 const CATALOG = {
   fullstack: [
     { name: 'plan', description: 'Break a goal into implementation steps.' },
@@ -30,9 +32,13 @@ export function normalizeLane(lane = 'fullstack') {
 
 export function getToolCatalog(lane = 'fullstack') {
   const key = normalizeLane(lane);
-  if (key.includes('cms')) return CATALOG.cms;
-  if (key.includes('data')) return CATALOG.data;
-  if (key.includes('customer') || key.includes('crm')) return CATALOG.crm;
-  if (key.includes('creative') || key.includes('design')) return CATALOG.creative;
-  return CATALOG.fullstack;
+  const rows = key.includes('cms') ? CATALOG.cms
+    : key.includes('data') ? CATALOG.data
+      : (key.includes('customer') || key.includes('crm')) ? CATALOG.crm
+        : (key.includes('creative') || key.includes('design')) ? CATALOG.creative
+          : CATALOG.fullstack;
+  return rows.map((tool) => ({
+    ...tool,
+    result_policy: { ...DEFAULT_RESULT_POLICY },
+  }));
 }

package/src/security/index.js

@@ -4,3 +4,4 @@ export { triageLog, resolveLogFindings } from './logs.js';
 export { scanProjectSecurity, remediationPlan, reportExitCode } from './scan.js';
 export { repairProject } from './repair.js';
 export { formatSecurityReport } from './render.js';
+export { scanTrustBoundary } from './trust-boundary.js';

package/src/security/inventory.js

@@ -76,7 +76,10 @@ export function collectNpmDependencies(projectRoot = process.cwd()) {
         if (location) {
           const workspacePath = path.resolve(root, location);
           const relative = path.relative(root, fs.realpathSync(workspacePath));
-          if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Workspace escapes project root');
+          if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            issues.push('Linked package escapes project root and cannot be fully verified here: ' + location);
+            continue;
+          }
           const workspace = readJson(path.join(workspacePath, 'package.json'));
           for (const field of fields) {
             if (JSON.stringify(Object.entries(workspace[field] || {}).sort()) !== JSON.stringify(Object.entries(pkg[field] || {}).sort())) issues.push('Workspace manifest and lockfile disagree: ' + location + ':' + field);

package/src/security/render.js

@@ -1,15 +1,26 @@
 import { stripVTControlCharacters } from 'node:util';
 
 export const safeText = value => stripVTControlCharacters(String(value ?? '')).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/[\u202a-\u202e\u2066-\u2069]/g, '');
+
+function renderBoundaryFinding(item, lines) {
+  const evidence = [item.kind, item.source, item.target ? `→ ${item.target}` : null, item.specifier, item.env].filter(Boolean).join(' · ');
+  lines.push('  ! ' + safeText(evidence));
+  lines.push('    Next: ' + safeText(item.action || item.repair?.action || 'review-trust-boundary'));
+  if (item.repair?.summary) lines.push('    ' + safeText(item.repair.summary));
+}
+
 export function formatSecurityReport(report, { color = false } = {}) {
   const scan = report.after || report.scan || report.before || report;
   const label = safeText(report.status || scan.status).toUpperCase();
-  const title = 'Agent Sam · dependency health · ' + label;
+  const title = 'Agent Sam · security · ' + label;
+  const boundary = scan.trust_boundary;
   const lines = [color ? '\x1b[1;36m' + title + '\x1b[0m' : title,
+    '',
+    'Dependencies',
     '  Checked: ' + scan.checked_count + '/' + scan.dependency_count + ' packages',
-    '  Coverage: ' + (scan.complete ? 'complete' : 'INCOMPLETE — not a clean bill of health')];
+    '  Coverage: ' + (scan.dependency_complete ? 'complete' : 'INCOMPLETE — dependency graph not fully verified')];
   for (const issue of scan.issues || []) lines.push('  ! ' + safeText(issue));
-  for (const item of scan.findings || []) {
+  for (const item of (scan.findings || []).filter((finding) => finding.section !== 'trust-boundary')) {
     lines.push('  ! ' + safeText([item.kind, item.package, item.version, item.advisory?.id, item.advisory?.severity].filter(Boolean).join(' · ')));
     lines.push('    Next: ' + safeText(item.action));
     if (item.advisory?.url) lines.push('    ' + safeText(item.advisory.url));
@@ -17,8 +28,19 @@ export function formatSecurityReport(report, { color = false } = {}) {
   }
   const informational = (scan.log_findings || []).filter(f => f.resolution === 'informational').length;
   if (informational) lines.push('  Informational log notices: ' + informational);
-  if (report.worktree) lines.push('  Candidate: ' + safeText(report.worktree), '  Branch: ' + safeText(report.branch));
+
+  if (boundary) {
+    lines.push('', 'Trust boundary',
+      '  AST files: ' + safeText(boundary.ast_files),
+      '  Browser graph: ' + safeText(boundary.browser_reachable_files) + ' reachable files from ' + safeText(boundary.browser_roots) + ' browser roots',
+      '  Evidence: merkle=' + safeText(boundary.merkle_root) + ' metadata=' + safeText(boundary.metadata_root),
+      '  Coverage: ' + (boundary.complete ? 'complete for indexed JS/TS syntax' : 'INCOMPLETE — parse errors prevent a clean boundary result'));
+    for (const item of boundary.findings || []) renderBoundaryFinding(item, lines);
+    if (!boundary.findings?.length) lines.push('  ✓ no indexed client/server boundary contradictions detected');
+  }
+
+  if (report.worktree) lines.push('', '  Candidate: ' + safeText(report.worktree), '  Branch: ' + safeText(report.branch));
   if (report.reason) lines.push('  Reason: ' + safeText(report.reason));
-  if (report.mode === 'plan') lines.push('  Apply in an isolated worktree: agentsam security repair --apply');
+  if (report.mode === 'plan') lines.push('  Apply dependency-only automatic repair in an isolated worktree: agentsam security repair --apply');
   return lines.join('\n') + '\n';
 }

package/src/security/scan.js

@@ -1,38 +1,53 @@
 import { collectNpmDependencies } from './inventory.js';
 import { queryOsv } from './osv.js';
 import { triageLog, resolveLogFindings } from './logs.js';
+import { scanTrustBoundary } from './trust-boundary.js';
 
 export async function scanProjectSecurity(options = {}) {
   const inventory = collectNpmDependencies(options.projectRoot);
   const results = options.offline
     ? inventory.dependencies.map(d => ({ ...d, checked: false, advisories: [] }))
     : await queryOsv(inventory.dependencies, options);
-  const complete = !options.offline && !options.signal?.aborted && !inventory.issues.length && results.every(r => r.checked);
-  const logFindings = resolveLogFindings(triageLog(options.log || ''), { complete, results });
-  const findings = [
-    ...results.flatMap(r => r.advisories.map(a => ({ kind: 'vulnerability', package: r.name, version: r.version, advisory: a, action: 'audit-fix-within-ranges' }))),
-    ...results.filter(r => r.deprecated).map(r => ({ kind: 'deprecated', package: r.name, version: r.version, action: 'update-within-ranges' })),
-    ...logFindings.filter(f => f.resolution === 'action-required'),
+  const dependencyComplete = !options.offline && !options.signal?.aborted && !inventory.issues.length && results.every(r => r.checked);
+  const scanBoundary = options.scanBoundary || scanTrustBoundary;
+  const trustBoundary = await scanBoundary(inventory.root, options);
+  const complete = dependencyComplete && trustBoundary.complete;
+  const logFindings = resolveLogFindings(triageLog(options.log || ''), { complete: dependencyComplete, results });
+  const dependencyFindings = [
+    ...results.flatMap(r => r.advisories.map(a => ({ kind: 'vulnerability', section: 'dependencies', package: r.name, version: r.version, advisory: a, action: 'audit-fix-within-ranges' }))),
+    ...results.filter(r => r.deprecated).map(r => ({ kind: 'deprecated', section: 'dependencies', package: r.name, version: r.version, action: 'update-within-ranges' })),
+    ...logFindings.filter(f => f.resolution === 'action-required').map((f) => ({ ...f, section: 'logs' })),
   ];
+  const boundaryFindings = (trustBoundary.findings || []).map((item) => ({
+    ...item,
+    section: 'trust-boundary',
+    action: item.repair?.action || 'review-trust-boundary',
+  }));
+  const findings = [...dependencyFindings, ...boundaryFindings];
   return {
     schema_version: 1, scanner: 'agentsam-sca', checked_at: new Date().toISOString(),
     project_root: inventory.root, lockfile: inventory.lockfile, lock_fingerprint: inventory.fingerprint,
     complete, status: !complete ? 'incomplete' : findings.length ? 'action-required' : 'clean',
     ok: complete && findings.length === 0,
     dependency_count: results.length, checked_count: results.filter(r => r.checked).length,
+    dependency_complete: dependencyComplete,
     issues: inventory.issues, skipped: inventory.skipped, results, findings, log_findings: logFindings,
+    trust_boundary: trustBoundary,
   };
 }
 export const reportExitCode = report => report.complete === false ? 2 : report.ok ? 0 : 1;
 export function remediationPlan(report) {
+  const boundaryRepairs = report.trust_boundary?.repair_suggestions || [];
   return {
     mode: 'plan', ok: report.ok, complete: report.complete, status: report.status,
     scan: report,
     steps: [
-      { action: 'npm-audit-fix', automatic: report.complete, constraints: 'Existing manifest ranges; no force; no lifecycle scripts during resolution.' },
-      ...(report.findings.some(f => f.kind === 'deprecated') ? [{ action: 'npm-update', automatic: report.complete, constraints: 'Existing ranges; package manifests unchanged.' }] : []),
-      { action: 'verify', automatic: report.complete, constraints: 'Fresh install, configured project verification script, advisory rescan and warning triage.' },
+      { action: 'npm-audit-fix', automatic: report.dependency_complete !== false, constraints: 'Existing manifest ranges; no force; no lifecycle scripts during resolution.' },
+      ...(report.findings.some(f => f.kind === 'deprecated') ? [{ action: 'npm-update', automatic: report.dependency_complete !== false, constraints: 'Existing ranges; package manifests unchanged.' }] : []),
+      ...boundaryRepairs.map((repair) => ({ ...repair, constraints: 'Preserve the existing public contract where possible; verify the repaired import graph against a fresh Merkle/filemeta snapshot.' })),
+      { action: 'verify', automatic: report.complete, constraints: 'Fresh install, configured project verification script, advisory rescan, warning triage, and trust-boundary rescan.' },
     ],
+    boundary_repairs: boundaryRepairs,
     manual: report.findings.filter(f => !['vulnerability', 'deprecated', 'audit'].includes(f.kind)),
   };
 }

package/src/security/trust-boundary.js

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import { buildMerkleTree } from '../lib/merkle/index.js';
+import { gitIgnoredPaths } from '../lib/merkle/git-ignore.js';
+import { analyzeExecutionBoundaries } from '../indexing/execution-boundary.js';
+
+export async function scanTrustBoundary(projectRoot = process.cwd(), options = {}) {
+  const root = fs.realpathSync(projectRoot);
+  const ignored = options.exclude || await gitIgnoredPaths(root);
+  const snapshot = options.snapshot || await buildMerkleTree(root, { semantic: true, exclude: ignored });
+  if (!snapshot.semantic) throw new Error('Semantic Merkle metadata is required for trust-boundary scanning');
+  const analysis = analyzeExecutionBoundaries(snapshot.semantic);
+  return {
+    ...analysis,
+    project_root: root,
+    merkle_root: snapshot.rootHash,
+    metadata_root: snapshot.semantic.rootHash,
+    evidence: {
+      authority: 'agentsam-merkle+agentsam-filemeta',
+      merkle_root: snapshot.rootHash,
+      metadata_root: snapshot.semantic.rootHash,
+      policy_hash: snapshot.policyHash || null,
+    },
+  };
+}

package/src/skills/index.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/tools/index.js

@@ -0,0 +1 @@
+export { searchToolCards, toToolCard } from './search.js';

package/src/tools/search.js

@@ -0,0 +1,70 @@
+import { DEFAULT_RESULT_POLICY, normalizeResultPolicy } from '../context/result-policy.js';
+
+function text(value) { return value == null ? '' : String(value).trim(); }
+
+export function toToolCard(tool = {}) {
+  const required = Array.isArray(tool.required)
+    ? tool.required
+    : Array.isArray(tool.input_schema?.required)
+      ? tool.input_schema.required
+      : [];
+  return Object.freeze({
+    tool: text(tool.tool || tool.name),
+    summary: text(tool.summary || tool.description),
+    category: text(tool.category) || undefined,
+    risk: text(tool.risk) || 'read',
+    required: Object.freeze([...required]),
+    result_class: text(tool.result_class) || 'bounded_evidence',
+  });
+}
+
+function score(card, query) {
+  if (!query) return 1;
+  const q = query.toLowerCase();
+  const terms = q.split(/\s+/).filter(Boolean);
+  const haystack = `${card.tool} ${card.summary} ${card.category || ''}`.toLowerCase();
+  let total = 0;
+  if (card.tool.toLowerCase() === q) total += 100;
+  if (card.tool.toLowerCase().includes(q)) total += 30;
+  if (card.summary.toLowerCase().includes(q)) total += 15;
+  for (const term of terms) {
+    if (card.tool.toLowerCase().includes(term)) total += 8;
+    if (card.summary.toLowerCase().includes(term)) total += 4;
+    if ((card.category || '').toLowerCase().includes(term)) total += 2;
+  }
+  return total;
+}
+
+export function searchToolCards(catalog = [], query = '', options = {}) {
+  if (!Array.isArray(catalog)) throw new TypeError('catalog must be an array');
+  const policy = normalizeResultPolicy({
+    max_items: options.maxItems ?? DEFAULT_RESULT_POLICY.max_items,
+    max_chars: options.maxChars ?? DEFAULT_RESULT_POLICY.max_chars,
+    detail: 'card',
+  }, { ceiling: DEFAULT_RESULT_POLICY });
+  const cards = catalog.map(toToolCard)
+    .map((card, index) => ({ card, score: score(card, text(query)), index }))
+    .filter((row) => row.card.tool && row.score > 0)
+    .sort((a, b) => (b.score - a.score) || (a.index - b.index))
+    .slice(0, policy.max_items)
+    .map((row) => row.card);
+
+  let chars = 0;
+  const bounded = [];
+  for (const card of cards) {
+    const size = JSON.stringify(card).length;
+    if (chars + size > policy.max_chars) break;
+    bounded.push(card);
+    chars += size;
+  }
+  return Object.freeze({
+    query: text(query),
+    cards: Object.freeze(bounded),
+    receipt: Object.freeze({
+      catalog_items: catalog.length,
+      returned_items: bounded.length,
+      chars,
+      result_policy: policy,
+    }),
+  });
+}

package/src/ui/ansi.js

@@ -40,7 +40,7 @@ export function renderLocalStatus(status) {
     return lines.join('\n');
   }
 
-  lines.push(row('lane', `${status.lane} · ${status.agent}`, width));
+  lines.push(row('profile', `${status.lane || 'custom'} · ${status.agent || 'default'}`, width));
   lines.push(
     row(
       'git',