@shomra/agent 0.3.16 → 0.3.18

package/src/guard/tool-guard.mjs

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveAgentIdentityHandle } from '../commands/agent-identity.mjs';
+import { isMemoryPath, reportMemoryWrite } from '../commands/memory-scan.mjs';
+import { breakerOpen, breakerReset, breakerTrip, guardTimeoutMs } from '../core/circuit-breaker.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { downrankCodeContext, grade, localScan } from '../detect/guard-signals.mjs';
+import { WRITE_TOOLS, guardNeedsServer, guardTargetPath, guardText } from './classify.mjs';
+import { emitGuardAsk, emitGuardDeny } from './emit.mjs';
+import { guardPathAllowlisted } from './ignore.mjs';
+import { screenModelLoad } from './model-load.mjs';
+import { normalizeGuardInput } from './normalize.mjs';
+import { envFlag, resolveAgentFlag } from './options.mjs';
+import { buildGuardBody, reportGuardDecision } from './report.mjs';
+
+const ALLOW_VERDICT = { verdict: 'ALLOW', top: null, findings: [] };
+
+function readHookPayload() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return process.exit(0);
+  }
+}
+
+function localTierDisabled() {
+  return process.env.SHOMRA_GUARD_LOCAL === '0'
+    || String(process.env.SHOMRA_GUARD_LOCAL).toLowerCase() === 'false';
+}
+
+function screenLocally(normalized, tool, input) {
+  const scan = localScan(guardText(tool, input));
+  const isWrite = WRITE_TOOLS.has(tool);
+  const allowlisted = isWrite && guardPathAllowlisted(normalized.cwd, guardTargetPath(normalized));
+
+  let findings = scan.findings;
+  if (allowlisted) findings = [];
+  else if (isWrite) findings = downrankCodeContext(scan.findings);
+
+  const top = findings.find((finding) => finding.severity === 'CRITICAL') || findings[0] || null;
+  return { ...grade(findings), top, findings };
+}
+
+function memoryWriteContent(input) {
+  if (typeof input.content === 'string') return input.content;
+  if (typeof input.new_string === 'string') return input.new_string;
+  return null;
+}
+
+async function recordMemoryWrite({ url, apiKey, input, normalized }) {
+  const memoryPath = input.file_path || input.path;
+  if (!memoryPath || !isMemoryPath(memoryPath) || breakerOpen()) return;
+
+  const content = memoryWriteContent(input);
+  if (content == null) return;
+
+  await reportMemoryWrite(url, apiKey, {
+    path: String(memoryPath).split(path.sep).join('/'),
+    name: path.basename(String(memoryPath)),
+    content,
+    writer: 'AGENT',
+    source: os.hostname(),
+    actor: os.userInfo().username,
+    sessionId: normalized.session_id,
+  });
+}
+
+function reportUnauthenticated(agent, status, strict) {
+  process.stderr.write(
+    `[shomra] guard NOT enforced: the backend rejected this API key (HTTP ${status}). `
+    + 'Local Tier-0 screening still ran; org policy, agent identity and flow control did not. '
+    + 'Re-enroll with `shomra init --key <key>`.\n',
+  );
+  if (strict) {
+    emitGuardDeny(agent, `Shomra guard could not authenticate (HTTP ${status}); blocked by fail-closed policy.`);
+  }
+  process.exit(0);
+}
+
+async function requestServerDecision({ url, apiKey, agentId, body, agent, strict }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), guardTimeoutMs());
+  try {
+    const response = await fetch(`${url}/gate/tool-call`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shomra-Key': apiKey,
+        ...(agentId ? { 'X-Shomra-Agent': agentId } : {}),
+        Connection: 'close',
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) reportUnauthenticated(agent, response.status, strict);
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const decision = await response.json();
+    breakerReset();
+    return decision;
+  } catch (error) {
+    clearTimeout(timer);
+    breakerTrip();
+    if (strict) emitGuardDeny(agent, `Shomra guard could not be reached (${error.message}); blocked by fail-closed policy.`);
+    return process.exit(0);
+  }
+}
+
+function enforceServerDecision(agent, decision) {
+  if (decision?.hold) {
+    emitGuardAsk(agent, decision.reason || 'Held for approval by Shomra - waiting on a reviewer. Retry once it’s approved.');
+  }
+  if (decision?.decision === 'BLOCK') {
+    emitGuardDeny(agent, decision.reason || 'Blocked by Shomra security policy.');
+  }
+}
+
+export async function cmdToolGuard(flags) {
+  const agent = resolveAgentFlag(flags);
+  const agentId = resolveAgentIdentityHandle(flags);
+  const strict = envFlag('SHOMRA_GUARD_STRICT');
+  const alwaysEscalate = envFlag('SHOMRA_GUARD_ALWAYS_ESCALATE');
+  const { apiKey, url } = resolveSettings(loadConfig());
+
+  const normalized = normalizeGuardInput(agent, readHookPayload());
+  const tool = (normalized.tool_name ?? '').trim();
+  const input = normalized.tool_input ?? {};
+
+  const local = localTierDisabled() ? ALLOW_VERDICT : screenLocally(normalized, tool, input);
+  if (local.verdict === 'BLOCK') {
+    await reportGuardDecision(url, apiKey, agentId, buildGuardBody(normalized, agent, 'BLOCK', local.top?.label));
+    emitGuardDeny(agent, `Blocked on-machine by Shomra: ${local.top?.label || 'dangerous tool call'}.`);
+  }
+
+  await screenModelLoad(agent, tool, input, url);
+
+  if (!apiKey) {
+    if (strict) {
+      emitGuardDeny(agent, 'Shomra is not configured on this machine (SHOMRA_GUARD_STRICT). Run: shomra init --key shm_…');
+    }
+    process.exit(0);
+  }
+
+  await recordMemoryWrite({ url, apiKey, input, normalized });
+
+  const escalate = alwaysEscalate || local.verdict === 'FLAG' || guardNeedsServer(tool, input, !!agentId);
+  if (!escalate) process.exit(0);
+  if (!strict && breakerOpen()) process.exit(0);
+
+  const flagged = local.verdict === 'FLAG';
+  const decision = await requestServerDecision({
+    url,
+    apiKey,
+    agentId,
+    agent,
+    strict,
+    body: buildGuardBody(normalized, agent, flagged ? 'FLAG' : undefined, flagged ? local.top?.label : undefined),
+  });
+
+  enforceServerDecision(agent, decision);
+  process.exit(0);
+}

package/src/inventory/agent-artifacts.mjs

@@ -0,0 +1,5 @@
+export { discoverAgentArtifacts, rollupArtifacts } from './artifacts/discover.mjs';
+export { canonicalHooks } from './artifacts/hooks.mjs';
+export { ARTIFACT_KINDS } from './artifacts/limits.mjs';
+export { installedMarketplaces } from './artifacts/marketplaces.mjs';
+export { artifactRoots } from './artifacts/roots.mjs';

package/src/inventory/agent-posture.mjs

@@ -0,0 +1,249 @@
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const HOME = os.homedir();
+const PLAT = process.platform;
+const MAX_SETTINGS_BYTES = 512 * 1024;
+
+export const POSTURE_TIERS = ['declared', 'flag', 'none'];
+
+export const TIER_MEANING = {
+  declared: 'The vendor documents a permission grant schema; grants are parsed and reasoned about.',
+  flag: 'No grant schema. Auto-approval switches are recognised by name; a grant list cannot be enumerated.',
+  none: 'No machine-readable permission surface. This agent appears in inventory only.',
+};
+
+function readJsonc(file) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size > MAX_SETTINGS_BYTES) return { state: 'unreadable', reason: st.isFile() ? 'oversized' : 'not-a-file' };
+    const raw = fs.readFileSync(file, 'utf8');
+
+    const stripped = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:"])\/\/.*$/gm, '$1');
+    return { state: 'read', json: JSON.parse(stripped) };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: 'absent' };
+
+    return { state: 'unreadable', reason: err?.code === 'EACCES' ? 'permission-denied' : 'parse-failed' };
+  }
+}
+
+export const VENDOR_POSTURE = {
+  'claude-code': {
+    tier: 'declared',
+    label: 'Claude Code',
+    sources: [
+      { rel: ['.claude', 'settings.json'], base: 'home', scope: 'user' },
+      { rel: ['.claude.json'], base: 'home', scope: 'user' },
+      { rel: ['.claude', 'settings.local.json'], base: 'home', scope: 'user' },
+      { rel: ['.claude', 'settings.json'], base: 'cwd', scope: 'project' },
+      { rel: ['.claude', 'settings.local.json'], base: 'cwd', scope: 'project' },
+    ],
+  },
+  gemini: {
+    tier: 'declared',
+    label: 'Gemini CLI',
+    sources: [
+      { rel: ['.gemini', 'settings.json'], base: 'home', scope: 'user' },
+      { rel: ['.gemini', 'settings.json'], base: 'cwd', scope: 'project' },
+    ],
+  },
+  codex: {
+    tier: 'declared',
+    label: 'OpenAI Codex CLI',
+    sources: [
+      { rel: ['.codex', 'config.json'], base: 'home', scope: 'user' },
+      { rel: ['.codex', 'settings.json'], base: 'home', scope: 'user' },
+    ],
+  },
+  cursor: {
+    tier: 'flag',
+    label: 'Cursor',
+    sources: [
+      { rel: ['.cursor', 'settings.json'], base: 'home', scope: 'user' },
+      { rel: ['.cursor', 'mcp.json'], base: 'home', scope: 'user' },
+      { rel: ['.cursor', 'mcp.json'], base: 'cwd', scope: 'project' },
+      { rel: ['.cursor', 'settings.json'], base: 'cwd', scope: 'project' },
+      { rel: ['User', 'settings.json'], base: 'cursor-user', scope: 'user' },
+    ],
+  },
+  windsurf: {
+    tier: 'flag',
+    label: 'Windsurf',
+    sources: [
+      { rel: ['.codeium', 'windsurf', 'settings.json'], base: 'home', scope: 'user' },
+      { rel: ['.codeium', 'windsurf', 'mcp_config.json'], base: 'home', scope: 'user' },
+      { rel: ['.windsurf', 'mcp.json'], base: 'cwd', scope: 'project' },
+    ],
+  },
+  cline: {
+    tier: 'flag',
+    label: 'Cline',
+    sources: [
+      { rel: ['settings', 'cline_mcp_settings.json'], base: 'cline-storage', scope: 'user' },
+      { rel: ['.cline', 'settings.json'], base: 'home', scope: 'user' },
+    ],
+  },
+  roo: {
+    tier: 'flag',
+    label: 'Roo Code',
+    sources: [
+      { rel: ['settings', 'mcp_settings.json'], base: 'roo-storage', scope: 'user' },
+      { rel: ['.roo', 'settings.json'], base: 'cwd', scope: 'project' },
+    ],
+  },
+  copilot: {
+    tier: 'flag',
+    label: 'GitHub Copilot CLI',
+    sources: [{ rel: ['.copilot', 'config.json'], base: 'home', scope: 'user' }],
+  },
+
+  aider: { tier: 'none', label: 'Aider', sources: [] },
+};
+
+function vscodeUserDir(variant) {
+  if (PLAT === 'win32') return path.join(process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming'), variant, 'User');
+  if (PLAT === 'darwin') return path.join(HOME, 'Library', 'Application Support', variant, 'User');
+  return path.join(HOME, '.config', variant, 'User');
+}
+
+function resolveBase(base, cwd) {
+  switch (base) {
+    case 'home': return HOME;
+    case 'cwd': return cwd;
+    case 'cursor-user': return path.dirname(vscodeUserDir('Cursor'));
+    case 'cline-storage': return path.join(vscodeUserDir('Code'), 'globalStorage', 'saoudrizwan.claude-dev');
+    case 'roo-storage': return path.join(vscodeUserDir('Code'), 'globalStorage', 'rooveterinaryinc.roo-cline');
+    default: return cwd;
+  }
+}
+
+const AUTO_APPROVE_KEYS = [
+  { re: /^(yolo|yolomode|enableyolo)$/i, label: 'YOLO mode', severity: 'CRITICAL' },
+  { re: /^(autoapprove|alwaysallow|autoallow|autoaccept|autoconfirm)$/i, label: 'auto-approve', severity: 'HIGH' },
+  { re: /^(autorun|autoexecute|autoexec|runwithoutasking|executewithoutconfirmation)$/i, label: 'auto-run commands', severity: 'CRITICAL' },
+  { re: /^(skippermissions|bypasspermissions|disableapproval|noconfirm)$/i, label: 'approval disabled', severity: 'CRITICAL' },
+  { re: /^(autoapprovemcp|alwaysallowmcp|autotrustmcp|enableallprojectmcpservers)$/i, label: 'MCP auto-trust', severity: 'HIGH' },
+  { re: /^(alwaysallowreadonly|autoapproveread)$/i, label: 'read auto-approve', severity: 'MEDIUM' },
+  { re: /^(alwaysallowwrite|autoapprovewrite|autoacceptedits)$/i, label: 'write auto-approve', severity: 'HIGH' },
+];
+
+function collectSwitches(node, out, depth = 0, trail = '') {
+  if (!node || typeof node !== 'object' || depth > 6 || out.length >= 40) return;
+  for (const [rawKey, value] of Object.entries(node)) {
+
+    const leaf = String(rawKey).split('.').pop() ?? rawKey;
+    const normal = leaf.replace(/[_\-\s]/g, '');
+    const where = trail ? `${trail}.${rawKey}` : rawKey;
+    const rule = AUTO_APPROVE_KEYS.find((r) => r.re.test(normal));
+    if (rule) {
+
+      const on = value === true || value === 'true' || value === 'always' || (Array.isArray(value) && value.length > 0);
+      if (on) out.push({ key: where, label: rule.label, severity: rule.severity, value: Array.isArray(value) ? `${value.length} entries` : String(value) });
+    }
+    if (value && typeof value === 'object') collectSwitches(value, out, depth + 1, where);
+  }
+}
+
+function collectMcpServers(json) {
+  const servers = json?.mcpServers ?? json?.servers ?? json?.mcp?.servers ?? null;
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return [];
+  return Object.entries(servers)
+    .slice(0, 60)
+    .map(([name, def]) => ({
+      name,
+      transport: def?.url ? 'http' : 'stdio',
+
+      autoApprove: Array.isArray(def?.autoApprove) ? def.autoApprove.slice(0, 20) : Array.isArray(def?.alwaysAllow) ? def.alwaysAllow.slice(0, 20) : [],
+      disabled: def?.disabled === true,
+    }));
+}
+
+export function readVendorPosture(vendor, cwd = process.cwd()) {
+  const def = VENDOR_POSTURE[vendor];
+  if (!def) return null;
+
+  const sources = [];
+  const switches = [];
+  const mcpServers = [];
+  let mode = null;
+  const allow = [];
+  const deny = [];
+  const ask = [];
+  let enableAllProjectMcpServers = null;
+
+  for (const src of def.sources) {
+    const file = path.join(resolveBase(src.base, cwd), ...src.rel);
+    const res = readJsonc(file);
+    sources.push({ path: file, scope: src.scope, state: res.state, reason: res.reason ?? null });
+    if (res.state !== 'read') continue;
+
+    const json = res.json ?? {};
+    const perms = json.permissions ?? {};
+
+    const m = perms.defaultMode ?? json.defaultMode ?? null;
+    if (m && (!mode || String(m).toLowerCase() === 'bypasspermissions')) mode = String(m);
+    for (const [key, sink] of [['allow', allow], ['deny', deny], ['ask', ask]]) {
+      const list = Array.isArray(perms[key]) ? perms[key] : key === 'allow' && Array.isArray(json.allowedTools) ? json.allowedTools : [];
+      for (const g of list) if (typeof g === 'string' && !sink.includes(g)) sink.push(g);
+    }
+    if (json.enableAllProjectMcpServers === true) enableAllProjectMcpServers = true;
+    else if (enableAllProjectMcpServers === null && json.enableAllProjectMcpServers === false) enableAllProjectMcpServers = false;
+
+    if (def.tier === 'flag') collectSwitches(json, switches);
+    for (const s of collectMcpServers(json)) if (!mcpServers.some((x) => x.name === s.name)) mcpServers.push(s);
+  }
+
+  const read = sources.filter((s) => s.state === 'read');
+  const holes = sources.filter((s) => s.state === 'unreadable');
+
+  return {
+    vendor,
+    tier: def.tier,
+    label: def.label,
+
+    readable: read.length > 0,
+    sources,
+    unreadableCount: holes.length,
+    mode,
+    allow: allow.slice(0, 60),
+    deny: deny.slice(0, 60),
+    ask: ask.slice(0, 60),
+    enableAllProjectMcpServers,
+    switches: switches.slice(0, 20),
+    mcpServers,
+
+    autoApprovedMcp: mcpServers.filter((s) => s.autoApprove.length > 0 && !s.disabled).map((s) => s.name),
+
+    claim: def.tier === 'declared' && read.length > 0 && holes.length === 0 ? 'complete' : 'floor',
+  };
+}
+
+export function canonicalGrant(posture) {
+  if (!posture) return null;
+  const doc = {};
+  const perms = {};
+  if (posture.mode) perms.defaultMode = posture.mode;
+  if (posture.allow.length) perms.allow = posture.allow;
+  if (posture.deny.length) perms.deny = posture.deny;
+  if (posture.ask.length) perms.ask = posture.ask;
+  if (Object.keys(perms).length) doc.permissions = perms;
+  if (posture.enableAllProjectMcpServers === true) doc.enableAllProjectMcpServers = true;
+  return Object.keys(doc).length ? JSON.stringify(doc, null, 2) : null;
+}
+
+export function readPostures(vendors, cwd = process.cwd()) {
+  const out = {};
+  for (const v of vendors) {
+    try {
+      const p = readVendorPosture(v, cwd);
+      if (p) out[v] = p;
+    } catch {
+
+      out[v] = { vendor: v, tier: VENDOR_POSTURE[v]?.tier ?? 'none', readable: false, sources: [], claim: 'floor', allow: [], deny: [], ask: [], switches: [], mcpServers: [], autoApprovedMcp: [], mode: null, enableAllProjectMcpServers: null, unreadableCount: 1 };
+    }
+  }
+  return out;
+}

package/src/inventory/artifacts/classify.mjs

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { extOf } from './limits.mjs';
+import { SETTINGS_BASENAMES } from './marketplaces.mjs';
+
+export function classify(rel, vendor) {
+  const lower = rel.toLowerCase().replace(/\\/g, '/');
+  const base = path.basename(lower);
+  const ext = extOf(lower);
+
+  if (base === 'skill.md') return 'skill';
+  if (SETTINGS_BASENAMES.has(base)) return 'hook';
+  if (/(^|\/)(sub)?agents?\//.test(lower) && ext === 'md') return 'subagent';
+  if (/(^|\/)(commands?|prompts?|workflows?)\//.test(lower) && (ext === 'md' || ext === 'toml')) {
+
+    if (vendor === 'copilot' && !/(^|\/)(prompts|chatmodes)\//.test(lower)) return null;
+    return 'command';
+  }
+  if (vendor === 'copilot' && /(^|\/)chatmodes\//.test(lower) && ext === 'md') return 'subagent';
+  return null;
+}
+
+export function declaredName(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return null;
+  const n = /^name:\s*(.+)$/m.exec(m[1]);
+  return n ? n[1].trim().replace(/^["']|["']$/g, '').slice(0, 120) || null : null;
+}

package/src/inventory/artifacts/discover.mjs

@@ -0,0 +1,187 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { clampArtifact } from '../../core/wire-limits.mjs';
+import { classify, declaredName } from './classify.mjs';
+import { readText } from './file-read.mjs';
+import { canonicalHooks } from './hooks.mjs';
+import { MAX_ARTIFACTS, MAX_BUNDLED, MAX_DIRS, MAX_TOTAL_BYTES, TEXT_EXTS, extOf } from './limits.mjs';
+import { CATALOGUE_DIR_RE, PLUGIN_PATH_RE, installedMarketplaces } from './marketplaces.mjs';
+import { artifactRoots } from './roots.mjs';
+import { walkRoot } from './walk.mjs';
+
+const MAX_NAME_LENGTH = 200;
+
+function relativeToSite(site, absolutePath) {
+  return path.relative(path.dirname(site.dir), absolutePath).replace(/\\/g, '/');
+}
+
+function artifactName(kind, content, absolutePath) {
+  const declared = declaredName(content);
+  if (declared) return declared;
+  if (kind === 'skill') return path.basename(path.dirname(absolutePath));
+  if (kind === 'hook') return `${path.basename(absolutePath)} · hooks`;
+  return path.basename(absolutePath).replace(/\.(md|toml)$/i, '');
+}
+
+function resolveActivation(marketplace, installed) {
+  if (!marketplace) return 'active';
+  if (installed === null) return 'unknown';
+  return installed.has(marketplace) ? 'active' : 'not-installed';
+}
+
+function readArtifactContent(kind, absolutePath) {
+  const read = readText(absolutePath);
+  if (!read) return null;
+  if (kind !== 'hook') return { ...read, content: read.text };
+  const content = canonicalHooks(read.text);
+  return content ? { ...read, content } : null;
+}
+
+function buildArtifact({ kind, content, read, relativePath, site, project, marketplace, activation, absolutePath }) {
+  return {
+    kind,
+    name: String(artifactName(kind, content, absolutePath)).slice(0, MAX_NAME_LENGTH),
+    path: relativePath,
+    scope: site.scope,
+    vendor: site.vendor,
+    content,
+    files: [],
+    metadata: {
+      bytes: read.bytes,
+      truncated: read.truncated,
+      project: site.scope === 'project' ? project : null,
+      activation,
+      marketplace,
+    },
+  };
+}
+
+function collectFromSite({ site, files, state, project }) {
+  const { artifacts, capped, consumed, skills, availableBy, budget } = state;
+  const installed = installedMarketplaces(site.dir);
+
+  for (const absolutePath of files) {
+    if (artifacts.length >= MAX_ARTIFACTS) {
+      capped.push({ reason: 'artifact-cap', path: absolutePath });
+      return;
+    }
+    const relativePath = relativeToSite(site, absolutePath);
+    const kind = classify(relativePath, site.vendor);
+    if (!kind) continue;
+
+    const catalogue = CATALOGUE_DIR_RE.exec(relativePath);
+    if (catalogue) {
+      const label = `${site.vendor}:${catalogue[2].toLowerCase()}`;
+      availableBy.set(label, (availableBy.get(label) ?? 0) + 1);
+      continue;
+    }
+
+    const marketplace = PLUGIN_PATH_RE.exec(relativePath)?.[2] ?? null;
+    const activation = resolveActivation(marketplace, installed);
+    if (activation === 'not-installed') {
+      availableBy.set(marketplace, (availableBy.get(marketplace) ?? 0) + 1);
+      continue;
+    }
+
+    const read = readArtifactContent(kind, absolutePath);
+    if (!read) continue;
+    if (read.bytes > budget.bytes) {
+      capped.push({ reason: 'byte-budget', path: relativePath });
+      continue;
+    }
+
+    budget.bytes -= Buffer.byteLength(read.content);
+    const artifact = buildArtifact({
+      kind, content: read.content, read, relativePath, site, project, marketplace, activation, absolutePath,
+    });
+    consumed.add(absolutePath);
+    artifacts.push(artifact);
+    if (kind === 'skill') skills.push({ artifact, dir: path.dirname(absolutePath), site });
+  }
+}
+
+function bundleSkillFiles({ skills, walked, state }) {
+  const { capped, consumed, budget } = state;
+
+  for (const { artifact, dir, site } of skills) {
+    const prefix = dir.endsWith(path.sep) ? dir : dir + path.sep;
+    const siteFiles = walked.find((entry) => entry.site === site)?.files ?? [];
+
+    for (const absolutePath of siteFiles.filter((file) => file.startsWith(prefix))) {
+      if (consumed.has(absolutePath)) continue;
+      if (artifact.files.length >= MAX_BUNDLED) {
+        capped.push({ reason: 'bundle-cap', path: artifact.path });
+        break;
+      }
+      const relativePath = relativeToSite(site, absolutePath);
+      const read = TEXT_EXTS.has(extOf(absolutePath)) ? readText(absolutePath) : null;
+      if (!read) {
+        artifact.files.push({ path: relativePath, content: null, binary: true });
+        consumed.add(absolutePath);
+        continue;
+      }
+      if (read.bytes > budget.bytes) {
+        capped.push({ reason: 'byte-budget', path: relativePath });
+        continue;
+      }
+      budget.bytes -= Buffer.byteLength(read.text);
+      artifact.files.push({ path: relativePath, content: read.text, binary: false });
+      consumed.add(absolutePath);
+    }
+    artifact.metadata.bundledCount = artifact.files.length;
+  }
+}
+
+function walkSites(sites, budget) {
+  const walked = [];
+  const seenRoot = new Set();
+  for (const site of sites) {
+    let realRoot;
+    try {
+      realRoot = fs.realpathSync(site.dir);
+    } catch {
+      continue;
+    }
+    if (seenRoot.has(realRoot)) continue;
+    seenRoot.add(realRoot);
+    walked.push({ site, files: walkRoot(site.dir, budget) });
+  }
+  return walked;
+}
+
+function availableCatalogue(availableBy) {
+  return [...availableBy.entries()]
+    .map(([marketplace, count]) => ({ marketplace, count, installed: false }))
+    .sort((a, b) => b.count - a.count);
+}
+
+export function discoverAgentArtifacts(cwd = process.cwd(), roots = null) {
+  const sites = roots || artifactRoots(cwd);
+  const project = path.basename(path.resolve(cwd)) || null;
+  const state = {
+    budget: { dirs: MAX_DIRS, bytes: MAX_TOTAL_BYTES },
+    artifacts: [],
+    capped: [],
+    consumed: new Set(),
+    skills: [],
+    availableBy: new Map(),
+  };
+
+  const walked = walkSites(sites, state.budget);
+  for (const { site, files } of walked) collectFromSite({ site, files, state, project });
+  bundleSkillFiles({ skills: state.skills, walked, state });
+
+  if (state.budget.dirs <= 0) state.capped.push({ reason: 'walk-budget', path: null });
+
+  return {
+    artifacts: state.artifacts.map(clampArtifact),
+    capped: state.capped,
+    available: availableCatalogue(state.availableBy),
+  };
+}
+
+export function rollupArtifacts(artifacts) {
+  const counts = {};
+  for (const artifact of artifacts) counts[artifact.kind] = (counts[artifact.kind] ?? 0) + 1;
+  return counts;
+}

package/src/inventory/artifacts/file-read.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import { MAX_FILE_BYTES } from './limits.mjs';
+
+export function readJsonAt(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(stripJsonComments(raw));
+  } catch {
+    return undefined;
+  }
+}
+
+export function readText(file, cap = MAX_FILE_BYTES) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile()) return null;
+    const fd = fs.openSync(file, 'r');
+    try {
+      const len = Math.min(st.size, cap);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, 0);
+
+      if (buf.includes(0)) return null;
+      return { text: buf.toString('utf8'), truncated: st.size > cap, bytes: st.size };
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+export function stripJsonComments(s) {
+  return String(s)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}