@agnt5/sdk 0.4.1 → 0.5.0

package/dist/skills.js

@@ -0,0 +1,281 @@
+/**
+ * Skills - on-demand capability loading for agents.
+ *
+ * A *skill* is a folder containing a `SKILL.md` file (Claude's open format):
+ * YAML-style frontmatter with `name` and `description`, followed by a markdown
+ * body of instructions. Optional sibling files (scripts, reference docs) are the
+ * skill's bundled resources.
+ *
+ * Skills follow progressive disclosure: only `name` + `description` sit in the
+ * agent's context (the *catalog*); the full body is loaded on demand when the
+ * agent decides the skill is relevant. This keeps prompts small while giving the
+ * agent access to many capabilities.
+ *
+ * @example
+ * ```typescript
+ * // Curated subset by name, resolved against a shared pool directory
+ * new Agent({ ..., skillsDir: './skills', skills: ['pdf-extraction', 'sql-reporting'] });
+ *
+ * // Load every skill in the pool (single-agent convenience)
+ * new Agent({ ..., skillsDir: './skills' });
+ *
+ * // Self-contained Skill objects, no pool directory needed
+ * new Agent({ ..., skills: [Skill.fromPath('./skills/pdf-extraction')] });
+ * ```
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { randomUUID } from 'crypto';
+import { Tool } from './tool.js';
+import { skillLoaded } from './events.js';
+const SKILL_FILE = 'SKILL.md';
+/**
+ * A loadable agent capability parsed from a `SKILL.md` folder.
+ */
+export class Skill {
+    constructor(name, description, instructions, resourcesDir) {
+        this.name = name;
+        this.description = description;
+        this.instructions = instructions;
+        this.resourcesDir = resourcesDir;
+    }
+    /**
+     * Parse a skill from a folder containing `SKILL.md` (or the file itself).
+     *
+     * @throws if no `SKILL.md` exists, or frontmatter is missing `name`/`description`.
+     */
+    static fromPath(path) {
+        const skillFile = existsSync(path) && statSync(path).isDirectory() ? join(path, SKILL_FILE) : path;
+        if (!existsSync(skillFile) || !statSync(skillFile).isFile()) {
+            throw new Error(`No ${SKILL_FILE} found at ${path}`);
+        }
+        const text = readFileSync(skillFile, 'utf-8');
+        const { meta, body } = parseFrontmatter(text);
+        if (!meta.name) {
+            throw new Error(`${skillFile}: frontmatter is missing required 'name'`);
+        }
+        if (!meta.description) {
+            throw new Error(`${skillFile}: frontmatter is missing required 'description'`);
+        }
+        return new Skill(meta.name, meta.description, body.trim(), join(skillFile, '..'));
+    }
+}
+/**
+ * Split `SKILL.md` text into a frontmatter map and the markdown body.
+ *
+ * Supports the minimal subset skills need: a leading `---` fenced block of
+ * single-line `key: value` pairs (values may be single- or double-quoted). No
+ * YAML dependency. Text without a frontmatter block yields an empty map and the
+ * full text as body.
+ */
+function parseFrontmatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines.length === 0 || lines[0].trim() !== '---') {
+        return { meta: {}, body: text };
+    }
+    const meta = {};
+    let bodyStart = lines.length;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            bodyStart = i + 1;
+            break;
+        }
+        const line = lines[i].trim();
+        const colon = line.indexOf(':');
+        if (!line || line.startsWith('#') || colon === -1) {
+            continue;
+        }
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim().replace(/^['"]|['"]$/g, '');
+        meta[key] = value;
+    }
+    return { meta, body: lines.slice(bodyStart).join('\n') };
+}
+/**
+ * Parse every skill in a pool directory, keyed by skill name.
+ *
+ * A skill is any immediate subfolder containing a `SKILL.md`. Malformed skills
+ * are skipped with a warning rather than failing discovery.
+ */
+export function discoverSkills(skillsDir) {
+    if (!existsSync(skillsDir) || !statSync(skillsDir).isDirectory()) {
+        throw new Error(`skillsDir does not exist: ${skillsDir}`);
+    }
+    const found = new Map();
+    for (const entry of readdirSync(skillsDir).sort()) {
+        const child = join(skillsDir, entry);
+        if (!statSync(child).isDirectory() || !existsSync(join(child, SKILL_FILE))) {
+            continue;
+        }
+        try {
+            const skill = Skill.fromPath(child);
+            found.set(skill.name, skill);
+        }
+        catch (err) {
+            console.warn(`Skipping malformed skill at ${child}: ${err.message}`);
+        }
+    }
+    return found;
+}
+/**
+ * Resolve an agent's skill selection into a `name -> Skill` map.
+ *
+ * - Items may be names (resolved against `skillsDir`) or `Skill` objects.
+ * - `skills` omitted with a `skillsDir` loads every skill in the pool.
+ * - Neither provided yields an empty map (skills disabled — no behavior change).
+ *
+ * @throws if a named skill is not found (lists available names), or a name is
+ *   given without a pool.
+ */
+export function resolveSkills(skills, skillsDir) {
+    if (skills === undefined) {
+        return skillsDir !== undefined ? discoverSkills(skillsDir) : new Map();
+    }
+    let available;
+    const resolved = new Map();
+    for (const item of skills) {
+        if (item instanceof Skill) {
+            resolved.set(item.name, item);
+            continue;
+        }
+        if (skillsDir === undefined) {
+            throw new Error(`Skill '${item}' given by name but no skillsDir was provided to resolve it against`);
+        }
+        if (available === undefined) {
+            available = discoverSkills(skillsDir);
+        }
+        let skill = available.get(item);
+        if (skill === undefined) {
+            // Fall back to a direct folder match (folder name != frontmatter name)
+            const folder = join(skillsDir, item);
+            if (existsSync(join(folder, SKILL_FILE))) {
+                skill = Skill.fromPath(folder);
+            }
+            else {
+                const names = [...available.keys()].sort().join(', ') || '(none)';
+                throw new Error(`Skill '${item}' not found in ${skillsDir}. Available: ${names}`);
+            }
+        }
+        resolved.set(skill.name, skill);
+    }
+    return resolved;
+}
+/**
+ * Render the always-present `<skills>` catalog block for the system prompt.
+ *
+ * Only `name` + `description` are included — the progressive-disclosure
+ * contract. Returns an empty string when there are no skills.
+ */
+export function renderCatalog(skills) {
+    if (skills.size === 0) {
+        return '';
+    }
+    const lines = [
+        '<skills>',
+        "You have access to the following skills. When a task matches a skill's " +
+            'purpose, call load_skill(skill_name) to load its full instructions before ' +
+            'proceeding.',
+        '',
+    ];
+    for (const skill of skills.values()) {
+        lines.push(`- ${skill.name}: ${skill.description}`);
+    }
+    lines.push('</skills>');
+    return lines.join('\n');
+}
+/** Recursively list every file path under `dir`. */
+function walkFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir).sort()) {
+        const full = join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory()) {
+            out.push(...walkFiles(full));
+        }
+        else if (st.isFile()) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * Copy a skill's bundled files into the sandbox so its scripts can run.
+ *
+ * Files are written under `skills/<name>/` preserving their relative layout,
+ * excluding `SKILL.md` itself. Writes are idempotent. Returns `[base, paths]`,
+ * or `undefined` when there is no sandbox or no resources to copy.
+ */
+async function materializeResources(ctx, skill, sandbox) {
+    const active = sandbox ?? ctx.sandbox;
+    if (!active || !skill.resourcesDir) {
+        return undefined;
+    }
+    const base = `skills/${skill.name}`;
+    const written = [];
+    for (const file of walkFiles(skill.resourcesDir)) {
+        if (basename(file) === SKILL_FILE) {
+            continue;
+        }
+        const rel = relative(skill.resourcesDir, file).split(/[\\/]/).join('/');
+        const dest = `${base}/${rel}`;
+        await active.writeFile(dest, readFileSync(file));
+        written.push(dest);
+    }
+    return written.length > 0 ? [base, written] : undefined;
+}
+/**
+ * Emit a `skill.loaded` event if the context supports emission. Guarded so the
+ * tool handler stays callable with a minimal context (e.g. in unit tests).
+ */
+async function emitSkillLoaded(ctx, skill, resourceCount) {
+    const emit = ctx.emit;
+    if (typeof emit !== 'function') {
+        return;
+    }
+    await emit.call(ctx, skillLoaded(randomUUID(), ctx.correlationId ?? null, {
+        skillName: skill.name,
+        instructionsLength: skill.instructions.length,
+        resourcesMaterialized: resourceCount,
+    }));
+}
+/**
+ * Build the `load_skill` tool that loads a skill's body on demand.
+ *
+ * The returned tool closes over the agent's resolved `skills` map and its
+ * sandbox. Invoking it returns the skill's instructions (progressive-disclosure
+ * level 2) and, when a sandbox is present, materializes bundled resources.
+ */
+export function makeLoadSkillTool(skills, sandbox) {
+    const handler = async (ctx, args) => {
+        const skillName = args.skill_name;
+        const skill = skills.get(skillName);
+        if (skill === undefined) {
+            const names = [...skills.keys()].sort().join(', ') || '(none)';
+            return `Unknown skill '${skillName}'. Available skills: ${names}`;
+        }
+        const materialized = await materializeResources(ctx, skill, sandbox);
+        const resourceCount = materialized ? materialized[1].length : 0;
+        await emitSkillLoaded(ctx, skill, resourceCount);
+        if (!materialized) {
+            return skill.instructions;
+        }
+        const [base, paths] = materialized;
+        const files = paths.map((p) => `- ${p}`).join('\n');
+        return (`${skill.instructions}\n\n---\n` +
+            `Bundled resources are available in the sandbox under '${base}':\n${files}`);
+    };
+    return new Tool('load_skill', 'Load the full instructions for a skill by name. Call this when a task ' +
+        'matches a skill listed in the <skills> catalog before proceeding.', handler, {
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skill_name: {
+                    type: 'string',
+                    description: 'Name of the skill to load (as shown in the catalog).',
+                },
+            },
+            required: ['skill_name'],
+        },
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { RuntimeContext } from './runtime-context.js';
+import type { Sandbox } from './sandbox.js';
 /**
  * Retry policy configuration for functions
  */
@@ -54,6 +55,8 @@ export interface Context {
     readonly serviceName: string;
     /** Runtime-provided execution options for this invocation */
     readonly runtime: RuntimeContext;
+    /** Sandbox workspace attached by Agent when configured. */
+    readonly sandbox?: Sandbox;
     /**
      * Cancellation signal for this invocation. Aborted when the run is
      * cancelled (a CancelExecution arrives). Thread it into fetch/LLM SDK

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agnt5/sdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "AGNT5 TypeScript SDK - Durable AI workflows and agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,10 +53,10 @@
     ]
   },
   "optionalDependencies": {
-    "@agnt5/sdk-darwin-arm64": "0.4.1",
-    "@agnt5/sdk-darwin-x64": "0.4.1",
-    "@agnt5/sdk-linux-arm64-gnu": "0.4.1",
-    "@agnt5/sdk-linux-x64-gnu": "0.4.1"
+    "@agnt5/sdk-darwin-arm64": "0.5.0",
+    "@agnt5/sdk-darwin-x64": "0.5.0",
+    "@agnt5/sdk-linux-arm64-gnu": "0.5.0",
+    "@agnt5/sdk-linux-x64-gnu": "0.5.0"
   },
   "engines": {
     "node": ">=18.0.0"