@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

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,
+  };
+}

package/src/skills/registry.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeSkillManifest } from './manifest.js';
+import { canonicalizeSlashTrigger } from './slash.js';
+import {
+  readLocalRegistry,
+  loadInstalledManifest,
+  skillsHome,
+} from './local-store.js';
+import { listSkills as listBuiltinCatalog } from './catalog.js';
+
+/**
+ * SkillRegistry — resolve from layered sources without fake accounts.
+ *
+ * Layers (later does not override earlier trigger unless aliased explicitly):
+ *   1. user / installed local registry (authoritative triggers)
+ *   2. app-provided (optional)
+ *   3. SDK builtins (suggested triggers only if free)
+ */
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   name: string,
+ *   description: string,
+ *   icon: string,
+ *   trigger: string|null,
+ *   source: 'user'|'package'|'builtin'|'app',
+ *   manifest: import('./manifest.js').SkillManifest,
+ *   baseDir?: string,
+ *   version?: string|null,
+ *   package?: string|null,
+ * }} ResolvedSkill
+ */
+
+function builtinSuggestedTrigger(skill) {
+  const id = String(skill.id || '')
+    .replace(/^agentsam-/, '')
+    .replace(/_/g, '-');
+  try {
+    return canonicalizeSlashTrigger(`/${id}`);
+  } catch {
+    return null;
+  }
+}
+
+function builtinToManifest(skill, skillsRoot) {
+  return normalizeSkillManifest({
+    schema: 'agentsam.skill.v1',
+    id: skill.id,
+    name: skill.title || skill.id,
+    description: skill.description || '',
+    icon: 'skill',
+    slash: { suggested: builtinSuggestedTrigger(skill) || undefined },
+    instructions: {
+      source: 'package_file',
+      ref: skill.entry,
+    },
+    execution: {
+      mode: 'turn',
+      tools: [],
+      operations: [],
+      capabilities: [],
+    },
+    package: '@inneranimalmedia/agentsam-sdk',
+  });
+}
+
+export class SkillRegistry {
+  /**
+   * @param {{
+ *     home?: string,
+ *     builtins?: boolean,
+ *     appSkills?: ResolvedSkill[],
+ *     skillsRoot?: string,
+ *   }} [options]
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.includeBuiltins = options.builtins !== false;
+    this.appSkills = Array.isArray(options.appSkills) ? options.appSkills : [];
+    this.skillsRoot =
+      options.skillsRoot ||
+      path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+  }
+
+  /** @returns {ResolvedSkill[]} */
+  list() {
+    /** @type {Map<string, ResolvedSkill>} */
+    const byId = new Map();
+
+    if (this.includeBuiltins) {
+      for (const row of listBuiltinCatalog()) {
+        const manifest = builtinToManifest(row, this.skillsRoot);
+        byId.set(manifest.id, {
+          id: manifest.id,
+          name: manifest.name,
+          description: manifest.description || '',
+          icon: manifest.icon || 'skill',
+          trigger: null, // assigned only when free / aliased
+          source: 'builtin',
+          manifest,
+          baseDir: this.skillsRoot,
+          package: manifest.package || null,
+          version: null,
+        });
+      }
+    }
+
+    for (const app of this.appSkills) {
+      byId.set(app.id, { ...app, source: 'app' });
+    }
+
+    const local = readLocalRegistry(this.options);
+    for (const entry of Object.values(local.entries)) {
+      try {
+        const manifest = loadInstalledManifest(entry);
+        byId.set(entry.id, {
+          id: entry.id,
+          name: manifest.name,
+          description: manifest.description || '',
+          icon: manifest.icon || 'skill',
+          trigger: entry.trigger,
+          source: entry.source === 'user' ? 'user' : 'package',
+          manifest,
+          baseDir: entry.baseDir,
+          package: entry.package || null,
+          version: entry.version || null,
+        });
+      } catch {
+        /* skip corrupt */
+      }
+    }
+
+    // Assign builtin suggested triggers only when not claimed
+    const claimed = new Set(
+      Object.keys(local.triggers || {}).concat(
+        [...byId.values()].map((s) => s.trigger).filter(Boolean),
+      ),
+    );
+    for (const skill of byId.values()) {
+      if (skill.trigger) continue;
+      if (skill.source !== 'builtin') continue;
+      const suggested = skill.manifest.slash?.suggested;
+      if (suggested && !claimed.has(suggested)) {
+        skill.trigger = suggested;
+        claimed.add(suggested);
+      }
+    }
+
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  /** @returns {Map<string, ResolvedSkill>} */
+  triggerMap() {
+    const map = new Map();
+    for (const skill of this.list()) {
+      if (skill.trigger) map.set(skill.trigger, skill);
+    }
+    return map;
+  }
+
+  getById(id) {
+    const needle = String(id || '').trim().toLowerCase();
+    return this.list().find((s) => s.id === needle) || null;
+  }
+
+  getByTrigger(triggerRaw) {
+    let trigger;
+    try {
+      trigger = canonicalizeSlashTrigger(triggerRaw);
+    } catch {
+      return null;
+    }
+    return this.triggerMap().get(trigger) || null;
+  }
+
+  vocabulary() {
+    return [...this.triggerMap().keys()].sort();
+  }
+}
+
+export { skillsHome };

package/src/skills/runtime.js

@@ -0,0 +1,287 @@
+import { parseSlashInvocation } from './slash.js';
+import { SkillContentResolver } from './content-resolver.js';
+import { computeSkillContentMetrics } from './metrics.js';
+import {
+  interactionReady,
+  interactionUnknownSkill,
+  interactionBlocked,
+} from './interaction.js';
+
+/**
+ * @typedef {{
+ *   matched: boolean,
+ *   invocation?: { trigger: string, args: string, skillId: string|null },
+ *   skill?: { id: string, trigger: string, name: string, source: string },
+ *   modelInstructions?: { content: string },
+ *   tools?: string[],
+ *   operations?: string[],
+ *   capabilities?: string[],
+ *   interaction: import('./interaction.js').AgentSamInteraction,
+ *   receipt?: {
+ *     skillId: string,
+ *     source: string,
+ *     version: string|null,
+ *     checksum: string,
+ *     contentSource: string,
+ *   },
+ * }} SkillInvocationResult
+ */
+
+function suggestTriggers(trigger, vocabulary = []) {
+  const needle = String(trigger || '').replace(/^\//, '');
+  return vocabulary
+    .map((t) => ({ t, score: distance(needle, t.replace(/^\//, '')) }))
+    .filter((row) => row.score <= 3)
+    .sort((a, b) => a.score - b.score)
+    .slice(0, 5)
+    .map((row) => row.t);
+}
+
+function distance(a, b) {
+  // cheap Levenshtein for short triggers
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i += 1) dp[i][0] = i;
+  for (let j = 0; j <= n; j += 1) dp[0][j] = j;
+  for (let i = 1; i <= m; i += 1) {
+    for (let j = 1; j <= n; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[m][n];
+}
+
+function tipArgs(args) {
+  const raw = String(args || '').trim();
+  if (!raw) {
+    return 'Tip: `/skills release-check` pre-fills a suggested id from your args.';
+  }
+  return `Using “${raw}” as the suggested skill id.`;
+}
+
+export class SkillRuntime {
+  /**
+   * @param {{
+ *     registry: import('./registry.js').SkillRegistry,
+ *     contentResolver?: SkillContentResolver,
+ *     toolRegistry?: { has?: (id: string) => boolean },
+ *     operationRegistry?: { has?: (id: string) => boolean },
+ *   }} deps
+   */
+  constructor(deps) {
+    this.registry = deps.registry;
+    this.contentResolver = deps.contentResolver || new SkillContentResolver();
+    this.toolRegistry = deps.toolRegistry || null;
+    this.operationRegistry = deps.operationRegistry || null;
+  }
+
+  /**
+   * Explicit slash only. Normal prose → matched:false, no lookup.
+   * @param {{ input: unknown, context?: Record<string, unknown> }} opts
+   * @returns {Promise<SkillInvocationResult>}
+   */
+  async invoke(opts) {
+    const parsed = parseSlashInvocation(opts?.input);
+    if (!parsed) {
+      return {
+        matched: false,
+        interaction: interactionReady(),
+      };
+    }
+
+    if (parsed.trigger === '/skills') {
+      const vocab = this.registry.vocabulary();
+      if (vocab.length) {
+        return {
+          matched: true,
+          invocation: { trigger: '/skills', args: parsed.args, skillId: null },
+          interaction: {
+            status: 'complete',
+            prompt: {
+              kind: 'info',
+              title: 'Skills',
+              message: ['Installed slash vocabulary:', ...vocab.map((t) => `  ${t}`)].join('\n'),
+            },
+          },
+        };
+      }
+
+      // Empty registry: help create the first skill — don't bounce to list again.
+      const hintName = String(parsed.args || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+      const exampleId = hintName || 'my-first-skill';
+      return {
+        matched: true,
+        invocation: { trigger: '/skills', args: parsed.args, skillId: null },
+        interaction: {
+          status: 'needs_input',
+          prompt: {
+            kind: 'select',
+            code: 'NO_SKILLS',
+            title: 'No slash skills yet',
+            message: [
+              'Nothing is installed in this registry yet.',
+              '',
+              'A skill is a named playbook with an explicit /trigger — create one locally, then invoke it:',
+              '',
+              `  agentsam skill create ${exampleId}`,
+              `  # edit ~/.agentsam/skills/user/${exampleId}/SKILL.md`,
+              `  /${exampleId} your args here`,
+              '',
+              'Or install from a folder that has agentsam.skill.json:',
+              '  agentsam skill install ./path/to/skill',
+              '',
+              tipArgs(parsed.args),
+            ]
+              .filter(Boolean)
+              .join('\n'),
+            options: [
+              {
+                value: `create:${exampleId}`,
+                label: `Create /${exampleId}`,
+                description: `agentsam skill create ${exampleId}`,
+              },
+              {
+                value: 'install',
+                label: 'Install from path or npm',
+                description: 'agentsam skill install ./my-skill | @scope/pkg',
+              },
+              {
+                value: 'docs',
+                label: 'What is a skill?',
+                description: 'Portable playbook: instructions + tools/operations — no workspace/R2 required',
+              },
+            ],
+            actions: [
+              { id: `create:${exampleId}`, label: 'Create skill' },
+              { id: 'install', label: 'Install skill' },
+              { id: 'cancel', label: 'Cancel' },
+            ],
+          },
+        },
+      };
+    }
+
+    const skill = this.registry.getByTrigger(parsed.trigger);
+    if (!skill) {
+      const suggestions = suggestTriggers(parsed.trigger, this.registry.vocabulary());
+      return {
+        matched: true,
+        invocation: { trigger: parsed.trigger, args: parsed.args, skillId: null },
+        interaction: interactionUnknownSkill(parsed.trigger, suggestions),
+      };
+    }
+
+    let resolved;
+    try {
+      resolved = await this.contentResolver.resolve(skill.manifest, {
+        baseDir: skill.baseDir,
+        packageRoot: skill.baseDir,
+      });
+    } catch (error) {
+      return {
+        matched: true,
+        invocation: {
+          trigger: parsed.trigger,
+          args: parsed.args,
+          skillId: skill.id,
+        },
+        skill: {
+          id: skill.id,
+          trigger: skill.trigger,
+          name: skill.name,
+          source: skill.source,
+        },
+        interaction: interactionBlocked({
+          code: 'CONTENT_RESOLVE_FAILED',
+          title: 'Skill content unavailable',
+          message: error?.message || String(error),
+          actions: [
+            { id: 'inspect', label: 'Inspect skill' },
+            { id: 'cancel', label: 'Cancel' },
+          ],
+        }),
+      };
+    }
+
+    const metrics = computeSkillContentMetrics(resolved.content);
+    const tools = skill.manifest.execution?.tools || [];
+    const operations = skill.manifest.execution?.operations || [];
+    const capabilities = skill.manifest.execution?.capabilities || [];
+
+    // Missing required tools → blocked interaction (no subagent fallback)
+    if (this.toolRegistry?.has) {
+      const missing = tools.filter((id) => !this.toolRegistry.has(id));
+      if (missing.length) {
+        return {
+          matched: true,
+          invocation: {
+            trigger: parsed.trigger,
+            args: parsed.args,
+            skillId: skill.id,
+          },
+          skill: {
+            id: skill.id,
+            trigger: skill.trigger,
+            name: skill.name,
+            source: skill.source,
+          },
+          tools,
+          operations,
+          capabilities,
+          interaction: interactionBlocked({
+            code: 'TOOL_REQUIRED',
+            title: 'Required tools unavailable',
+            message: `This skill needs: ${missing.join(', ')}`,
+            actions: [
+              { id: 'connect', label: 'Review tools' },
+              { id: 'cancel', label: 'Cancel' },
+            ],
+          }),
+          receipt: {
+            skillId: skill.id,
+            source: skill.source,
+            version: skill.version || skill.manifest.version || null,
+            checksum: metrics.checksum,
+            contentSource: resolved.source,
+          },
+        };
+      }
+    }
+
+    return {
+      matched: true,
+      invocation: {
+        trigger: parsed.trigger,
+        args: parsed.args,
+        skillId: skill.id,
+      },
+      skill: {
+        id: skill.id,
+        trigger: skill.trigger,
+        name: skill.name,
+        source: skill.source,
+      },
+      modelInstructions: {
+        content: resolved.content,
+      },
+      tools,
+      operations,
+      capabilities,
+      interaction: interactionReady(),
+      receipt: {
+        skillId: skill.id,
+        source: skill.source,
+        version: skill.version || skill.manifest.version || null,
+        checksum: metrics.checksum,
+        contentSource: resolved.source,
+      },
+    };
+  }
+}

package/src/skills/slash.js

@@ -0,0 +1,44 @@
+/**
+ * Canonical slash invocation parser.
+ * Normalize to lowercase kebab at write/parse time; never LOWER() DB columns on lookup.
+ */
+
+/**
+ * @param {unknown} message
+ * @returns {{ trigger: string, args: string } | null}
+ */
+export function parseSlashInvocation(message) {
+  const raw = String(message ?? '').trim();
+  if (!raw.startsWith('/')) return null;
+
+  const match = raw.match(/^\/([a-zA-Z0-9][a-zA-Z0-9-]{0,63})(?:\s+([\s\S]*))?$/);
+  if (!match) return null;
+
+  return {
+    trigger: `/${match[1].toLowerCase()}`,
+    args: String(match[2] ?? '').trim(),
+  };
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function canonicalizeSlashTrigger(raw) {
+  let value = String(raw ?? '').trim().toLowerCase();
+  if (!value) throw new Error('slash_trigger_required');
+  if (!value.startsWith('/')) value = `/${value}`;
+  value = value.replace(/_/g, '-');
+  if (!/^\/[a-z0-9][a-z0-9-]{0,63}$/.test(value)) {
+    throw new Error(`invalid_slash_trigger:${value}`);
+  }
+  return value;
+}
+
+/**
+ * Prose must never trigger skill lookup.
+ * @param {unknown} message
+ */
+export function isExplicitSlashMessage(message) {
+  return parseSlashInvocation(message) != null;
+}