@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/skills/index.js

@@ -1,64 +1,29 @@
-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;
+export { parseSlashInvocation, canonicalizeSlashTrigger, isExplicitSlashMessage } from './slash.js';
+export {
+  interactionReady,
+  interactionComplete,
+  interactionBlocked,
+  interactionNeedsSelect,
+  interactionUnknownSkill,
+} from './interaction.js';
+export { normalizeSkillManifest, createBlankSkillManifest } from './manifest.js';
+export { computeSkillContentMetrics } from './metrics.js';
+export {
+  SkillContentResolver,
+  createFilesystemObjectStore,
+  createMemoryDatabaseContent,
+} from './content-resolver.js';
+export { SkillRegistry } from './registry.js';
+export { SkillRuntime } from './runtime.js';
+export {
+  createUserSkill,
+  installSkillFromPath,
+  aliasSkill,
+  removeSkill,
+  readLocalRegistry,
+  skillsHome,
+} from './local-store.js';
+
+// Legacy catalog surface (agentsam skills list / load)
+export { listSkills, getSkill, loadSkill, AGENTSAM_SKILLS_ROOT } from './catalog.js';
+export { createNullHostedSkillStore } from './hosted-store.js';

package/src/skills/interaction.js

@@ -0,0 +1,102 @@
+/**
+ * AgentSamInteraction — host-agnostic next-step contract.
+ * Separate from modelInstructions (what the model sees this turn).
+ */
+
+/**
+ * @typedef {{
+ *   status: 'ready'|'needs_input'|'needs_approval'|'blocked'|'complete',
+ *   prompt?: {
+ *     kind: 'info'|'text'|'select'|'multiselect'|'confirm'|'error',
+ *     code?: string,
+ *     title?: string,
+ *     message: string,
+ *     options?: Array<{ value: string, label: string, description?: string }>,
+ *     actions?: Array<{ id: string, label: string }>,
+ *   }
+ * }} AgentSamInteraction
+ */
+
+/** @returns {AgentSamInteraction} */
+export function interactionReady() {
+  return { status: 'ready' };
+}
+
+/** @returns {AgentSamInteraction} */
+export function interactionComplete(message) {
+  return {
+    status: 'complete',
+    prompt: message
+      ? { kind: 'info', message: String(message) }
+      : undefined,
+  };
+}
+
+/**
+ * @param {{ code?: string, title?: string, message: string, actions?: Array<{id:string,label:string}> }} opts
+ * @returns {AgentSamInteraction}
+ */
+export function interactionBlocked(opts) {
+  return {
+    status: 'blocked',
+    prompt: {
+      kind: 'error',
+      code: opts.code,
+      title: opts.title,
+      message: opts.message,
+      actions: opts.actions,
+    },
+  };
+}
+
+/**
+ * @param {{ title?: string, message: string, options: Array<{value:string,label:string,description?:string}> }} opts
+ * @returns {AgentSamInteraction}
+ */
+export function interactionNeedsSelect(opts) {
+  return {
+    status: 'needs_input',
+    prompt: {
+      kind: 'select',
+      title: opts.title,
+      message: opts.message,
+      options: opts.options,
+    },
+  };
+}
+
+/**
+ * @param {string} trigger
+ * @param {string[]} suggestions
+ * @returns {AgentSamInteraction}
+ */
+export function interactionUnknownSkill(trigger, suggestions = []) {
+  const lines = [
+    `Unknown skill ${trigger}`,
+    '',
+    ...(suggestions.length
+      ? ['Did you mean?', ...suggestions.map((s) => `  ${s}`), '']
+      : [
+          'No close matches in this registry.',
+          '',
+          'Create it locally:',
+          `  agentsam skill create ${String(trigger).replace(/^\//, '') || 'my-skill'}`,
+          '',
+        ]),
+    'List installed triggers with /skills, or create/install a skill when the list is empty.',
+  ];
+  return {
+    status: 'blocked',
+    prompt: {
+      kind: 'error',
+      code: 'SKILL_NOT_FOUND',
+      title: 'Unknown skill',
+      message: lines.join('\n'),
+      actions: [
+        { id: 'create', label: 'Create skill' },
+        { id: 'list', label: 'List skills' },
+        { id: 'cancel', label: 'Cancel' },
+      ],
+    },
+  };
+}

package/src/skills/local-store.js

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalizeSlashTrigger } from './slash.js';
+import { normalizeSkillManifest, createBlankSkillManifest } from './manifest.js';
+
+/**
+ * Local install registry under ~/.agentsam/skills/
+ *
+ * {
+ *   schema: 'agentsam.skill-registry.v1',
+ *   entries: {
+ *     [skillId]: {
+ *       id, trigger, source: 'user'|'package'|'builtin'|'app',
+ *       manifestPath, installedAt, package?, version?
+ *     }
+ *   },
+ *   triggers: { '/foo': 'skill-id' }
+ * }
+ */
+
+function homeDir(options = {}) {
+  return path.resolve(
+    String(options.home || options.env?.HOME || options.env?.USERPROFILE || os.homedir()),
+  );
+}
+
+export function skillsHome(options = {}) {
+  return path.join(homeDir(options), '.agentsam', 'skills');
+}
+
+export function registryPath(options = {}) {
+  return path.join(skillsHome(options), 'registry.json');
+}
+
+function emptyRegistry() {
+  return {
+    schema: 'agentsam.skill-registry.v1',
+    entries: {},
+    triggers: {},
+  };
+}
+
+function atomicWrite(file, data, mode = 0o600) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, data, { mode });
+  fs.renameSync(tmp, file);
+  if (process.platform !== 'win32') fs.chmodSync(file, mode);
+}
+
+export function readLocalRegistry(options = {}) {
+  const file = registryPath(options);
+  if (!fs.existsSync(file)) return emptyRegistry();
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      schema: 'agentsam.skill-registry.v1',
+      entries: parsed.entries && typeof parsed.entries === 'object' ? parsed.entries : {},
+      triggers: parsed.triggers && typeof parsed.triggers === 'object' ? parsed.triggers : {},
+    };
+  } catch {
+    return emptyRegistry();
+  }
+}
+
+export function writeLocalRegistry(registry, options = {}) {
+  const file = registryPath(options);
+  atomicWrite(file, `${JSON.stringify(registry, null, 2)}\n`, 0o600);
+  return file;
+}
+
+/**
+ * @param {string} skillId
+ * @param {{ trigger?: string, home?: string }} [options]
+ */
+export function createUserSkill(skillId, options = {}) {
+  const manifest = createBlankSkillManifest(skillId);
+  const trigger = options.trigger
+    ? canonicalizeSlashTrigger(options.trigger)
+    : manifest.slash?.suggested || `/${manifest.id}`;
+
+  const root = path.join(skillsHome(options), 'user', manifest.id);
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  const skillMd = path.join(root, 'SKILL.md');
+  fs.writeFileSync(skillMd, manifest.instructions.inline || '', { mode: 0o600 });
+
+  const onDisk = {
+    ...manifest,
+    instructions: { source: 'local_file', ref: 'SKILL.md' },
+  };
+  const manifestFile = path.join(root, 'agentsam.skill.json');
+  atomicWrite(manifestFile, `${JSON.stringify(onDisk, null, 2)}\n`);
+
+  const registry = readLocalRegistry(options);
+  if (registry.entries[manifest.id]) throw new Error(`skill_exists:${manifest.id}`);
+  if (registry.triggers[trigger]) {
+    throw new Error(`slash_collision:${trigger}->${registry.triggers[trigger]}`);
+  }
+
+  registry.entries[manifest.id] = {
+    id: manifest.id,
+    trigger,
+    source: 'user',
+    manifestPath: manifestFile,
+    baseDir: root,
+    installedAt: new Date().toISOString(),
+  };
+  registry.triggers[trigger] = manifest.id;
+  writeLocalRegistry(registry, options);
+  return { manifest: onDisk, trigger, root, manifestPath: manifestFile };
+}
+
+/**
+ * Install from a directory containing agentsam.skill.json (or package root).
+ * @param {string} sourcePath
+ * @param {{ trigger?: string, aliasOnCollision?: string, home?: string }} [options]
+ */
+export function installSkillFromPath(sourcePath, options = {}) {
+  const abs = path.resolve(sourcePath);
+  const manifestFile = fs.existsSync(path.join(abs, 'agentsam.skill.json'))
+    ? path.join(abs, 'agentsam.skill.json')
+    : abs.endsWith('agentsam.skill.json')
+      ? abs
+      : null;
+  if (!manifestFile || !fs.existsSync(manifestFile)) {
+    throw new Error('agentsam.skill.json_required');
+  }
+  const baseDir = path.dirname(manifestFile);
+  const manifest = normalizeSkillManifest(JSON.parse(fs.readFileSync(manifestFile, 'utf8')));
+  const suggested = manifest.slash?.suggested || `/${manifest.id}`;
+  let trigger = options.trigger
+    ? canonicalizeSlashTrigger(options.trigger)
+    : suggested;
+
+  const registry = readLocalRegistry(options);
+  const existingOwner = registry.triggers[trigger];
+  if (existingOwner && existingOwner !== manifest.id) {
+    if (!options.aliasOnCollision) {
+      const err = new Error(`slash_collision:${trigger}`);
+      err.code = 'SLASH_COLLISION';
+      err.suggested = suggested;
+      err.owner = existingOwner;
+      err.candidates = [`${trigger}-${manifest.id}`.slice(0, 64), `/${manifest.id}`];
+      throw err;
+    }
+    trigger = canonicalizeSlashTrigger(options.aliasOnCollision);
+    if (registry.triggers[trigger] && registry.triggers[trigger] !== manifest.id) {
+      throw new Error(`slash_collision:${trigger}`);
+    }
+  }
+
+  // Copy into install root for stability
+  const installRoot = path.join(skillsHome(options), 'installed', manifest.id);
+  fs.mkdirSync(installRoot, { recursive: true, mode: 0o700 });
+  const destManifest = path.join(installRoot, 'agentsam.skill.json');
+  atomicWrite(destManifest, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  // Copy instruction file if package_file / local_file relative
+  if (
+    (manifest.instructions.source === 'local_file' ||
+      manifest.instructions.source === 'package_file') &&
+    manifest.instructions.ref
+  ) {
+    const src = path.resolve(baseDir, manifest.instructions.ref);
+    if (fs.existsSync(src)) {
+      const dest = path.join(installRoot, path.basename(src));
+      fs.copyFileSync(src, dest);
+      manifest.instructions = {
+        source: 'local_file',
+        ref: path.basename(src),
+      };
+      atomicWrite(destManifest, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+  }
+
+  // Clear old trigger for this id if reinstalling
+  for (const [t, id] of Object.entries(registry.triggers)) {
+    if (id === manifest.id) delete registry.triggers[t];
+  }
+
+  registry.entries[manifest.id] = {
+    id: manifest.id,
+    trigger,
+    source: 'package',
+    manifestPath: destManifest,
+    baseDir: installRoot,
+    package: manifest.package || null,
+    version: manifest.version || null,
+    installedAt: new Date().toISOString(),
+  };
+  registry.triggers[trigger] = manifest.id;
+  writeLocalRegistry(registry, options);
+  return { id: manifest.id, trigger, manifestPath: destManifest };
+}
+
+export function aliasSkill(skillId, triggerRaw, options = {}) {
+  const registry = readLocalRegistry(options);
+  const entry = registry.entries[skillId];
+  if (!entry) throw new Error(`unknown_skill:${skillId}`);
+  const trigger = canonicalizeSlashTrigger(triggerRaw);
+  const owner = registry.triggers[trigger];
+  if (owner && owner !== skillId) throw new Error(`slash_collision:${trigger}->${owner}`);
+  for (const [t, id] of Object.entries(registry.triggers)) {
+    if (id === skillId) delete registry.triggers[t];
+  }
+  registry.triggers[trigger] = skillId;
+  entry.trigger = trigger;
+  writeLocalRegistry(registry, options);
+  return { id: skillId, trigger };
+}
+
+export function removeSkill(skillId, options = {}) {
+  const registry = readLocalRegistry(options);
+  if (!registry.entries[skillId]) return { removed: false };
+  delete registry.entries[skillId];
+  for (const [t, id] of Object.entries(registry.triggers)) {
+    if (id === skillId) delete registry.triggers[t];
+  }
+  writeLocalRegistry(registry, options);
+  return { removed: true, id: skillId };
+}
+
+export function loadInstalledManifest(entry) {
+  const raw = JSON.parse(fs.readFileSync(entry.manifestPath, 'utf8'));
+  return normalizeSkillManifest(raw);
+}

package/src/skills/manifest.js

@@ -0,0 +1,104 @@
+import { canonicalizeSlashTrigger } from './slash.js';
+
+/**
+ * @typedef {{
+ *   schema: 'agentsam.skill.v1',
+ *   id: string,
+ *   name: string,
+ *   description?: string,
+ *   icon?: string,
+ *   version?: string,
+ *   package?: string,
+ *   slash?: { suggested?: string },
+ *   instructions: {
+ *     source: 'inline'|'local_file'|'package_file'|'database'|'object_store',
+ *     ref?: string,
+ *     inline?: string,
+ *   },
+ *   execution?: {
+ *     mode?: 'turn',
+ *     tools?: string[],
+ *     operations?: string[],
+ *     capabilities?: string[],
+ *   },
+ * }} SkillManifest
+ */
+
+/**
+ * @param {unknown} raw
+ * @returns {SkillManifest}
+ */
+export function normalizeSkillManifest(raw) {
+  if (!raw || typeof raw !== 'object') throw new Error('skill_manifest_required');
+  const input = /** @type {Record<string, unknown>} */ (raw);
+  const id = String(input.id || '')
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, '-');
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) throw new Error(`invalid_skill_id:${id}`);
+
+  const instructions = input.instructions && typeof input.instructions === 'object'
+    ? /** @type {Record<string, unknown>} */ (input.instructions)
+    : null;
+  if (!instructions?.source) throw new Error('skill_instructions_source_required');
+
+  const source = String(instructions.source);
+  const allowed = new Set(['inline', 'local_file', 'package_file', 'database', 'object_store']);
+  if (!allowed.has(source)) throw new Error(`unsupported_instruction_source:${source}`);
+
+  let suggested;
+  const slash = input.slash && typeof input.slash === 'object'
+    ? /** @type {Record<string, unknown>} */ (input.slash)
+    : null;
+  if (slash?.suggested) {
+    suggested = canonicalizeSlashTrigger(slash.suggested);
+  }
+
+  const execution = input.execution && typeof input.execution === 'object'
+    ? /** @type {Record<string, unknown>} */ (input.execution)
+    : {};
+
+  return {
+    schema: 'agentsam.skill.v1',
+    id,
+    name: String(input.name || id).trim() || id,
+    description: String(input.description || '').trim(),
+    icon: String(input.icon || 'skill').trim() || 'skill',
+    version: input.version != null ? String(input.version) : undefined,
+    package: input.package != null ? String(input.package) : undefined,
+    slash: suggested ? { suggested } : undefined,
+    instructions: {
+      source: /** @type {SkillManifest['instructions']['source']} */ (source),
+      ref: instructions.ref != null ? String(instructions.ref) : undefined,
+      inline: instructions.inline != null ? String(instructions.inline) : undefined,
+    },
+    execution: {
+      mode: 'turn',
+      tools: Array.isArray(execution.tools) ? execution.tools.map(String) : [],
+      operations: Array.isArray(execution.operations) ? execution.operations.map(String) : [],
+      capabilities: Array.isArray(execution.capabilities) ? execution.capabilities.map(String) : [],
+    },
+  };
+}
+
+/**
+ * @param {string} id
+ * @param {string} [inline]
+ * @returns {SkillManifest}
+ */
+export function createBlankSkillManifest(id, inline = '# New skill\n\nDescribe the playbook.\n') {
+  const normalized = String(id || '')
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, '-');
+  return normalizeSkillManifest({
+    schema: 'agentsam.skill.v1',
+    id: normalized,
+    name: normalized,
+    description: '',
+    icon: 'skill',
+    slash: { suggested: `/${normalized}` },
+    instructions: { source: 'inline', inline },
+    execution: { mode: 'turn', tools: [], operations: [], capabilities: [] },
+  });
+}

package/src/skills/metrics.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Metrics are computed from *resolved* content — never authoritative from empty placeholders.
+ *
+ * @param {string} content
+ * @returns {{
+ *   byte_size: number,
+ *   char_count: number,
+ *   line_count: number,
+ *   estimated_tokens: number,
+ *   estimation_method: 'chars_div_4',
+ *   checksum: string,
+ * }}
+ */
+export function computeSkillContentMetrics(content) {
+  const text = String(content ?? '');
+  const byteSize = Buffer.byteLength(text, 'utf8');
+  const charCount = text.length;
+  const lineCount = text.length === 0 ? 0 : text.split(/\r?\n/).length;
+  const estimatedTokens = Math.ceil(charCount / 4);
+  const checksum = `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}`;
+  return {
+    byte_size: byteSize,
+    char_count: charCount,
+    line_count: lineCount,
+    estimated_tokens: estimatedTokens,
+    estimation_method: 'chars_div_4',
+    checksum,
+  };
+}