loopengine 0.1.15 → 0.1.22

package/dist/core/sessionknit.d.ts

@@ -0,0 +1,87 @@
+/** One node in the session's parent-linked tree. Multiple entries can
+ * share the same parentId — that's exactly what a turn with parallel
+ * tool calls produces (siblings), not an error case. */
+export interface SessionEntry<TMessage> {
+    id: string;
+    parentId: string | null;
+    message: TMessage;
+}
+export interface ResumeResult<TMessage> {
+    messages: TMessage[];
+    /** True if the session ended mid-turn (an unresolved tool call with
+     * no result) rather than cleanly. */
+    resumedAfterInterruption: boolean;
+    /** id of the last *durably stored* entry in the reconstructed chain —
+     * null for a brand-new session. Excludes any synthetic continuation
+     * (that message was never appended), so a caller resuming a session and
+     * then appending new entries should parent the first one on this, not
+     * on the last entry of `messages`. */
+    leafId: string | null;
+}
+export interface SessionKnitOptions<TMessage> {
+    /** Does this message contain a tool call with no result yet? Used to
+     * detect a session that ended mid-turn. No default — a format SessionKnit
+     * doesn't recognize is treated as clean rather than guessed at. */
+    hasUnresolvedToolCall?: (message: TMessage) => boolean;
+    /** Given the unresolved message, build a synthetic continuation to
+     * append so the reconstructed chain is valid to resend to a model. */
+    buildContinuation?: (message: TMessage) => TMessage;
+}
+export interface Storage<TMessage> {
+    append(sessionId: string, entry: SessionEntry<TMessage>): Promise<void>;
+    /** Force any pending writes to be durable. */
+    flush(sessionId: string): Promise<void>;
+    readAll(sessionId: string): Promise<SessionEntry<TMessage>[]>;
+}
+/** Append-only JSONL storage with a debounced, batched write-behind
+ * queue — append() never blocks the caller. flush() (called
+ * automatically before every resume) forces pending lines to disk. */
+export declare class FileStorage<TMessage> implements Storage<TMessage> {
+    private readonly dir;
+    private readonly debounceMs;
+    private readonly pending;
+    private readonly timers;
+    constructor(dir: string, debounceMs?: number);
+    private pathFor;
+    append(sessionId: string, entry: SessionEntry<TMessage>): Promise<void>;
+    flush(sessionId: string): Promise<void>;
+    private drain;
+    readAll(sessionId: string): Promise<SessionEntry<TMessage>[]>;
+}
+/** Same debounce/flush contract as FileStorage, backed by memory instead
+ * of disk — useful for tests, and a second real example proving the
+ * Storage interface is genuinely swappable for a host that wants a
+ * database or S3 backend instead. */
+export declare class MemoryStorage<TMessage> implements Storage<TMessage> {
+    private readonly debounceMs;
+    private readonly committed;
+    private readonly pending;
+    private readonly timers;
+    constructor(debounceMs?: number);
+    append(sessionId: string, entry: SessionEntry<TMessage>): Promise<void>;
+    flush(sessionId: string): Promise<void>;
+    private drain;
+    readAll(sessionId: string): Promise<SessionEntry<TMessage>[]>;
+}
+export interface ReconstructResult<TMessage> {
+    messages: TMessage[];
+    entries: SessionEntry<TMessage>[];
+}
+/** Pure reconstruction — no I/O, so it's testable without a storage
+ * backend. Walks parentId from the target leaf back to the root, then
+ * runs topology repair: at each node on that path, any *other* children
+ * (siblings of the node that continues the path) are reattached too —
+ * exactly what a turn with parallel tool calls produces, and exactly
+ * what a naive single-parent walk would silently drop. */
+export declare function reconstructChain<TMessage>(entries: SessionEntry<TMessage>[], leafId?: string): ReconstructResult<TMessage>;
+/** Durable, parent-linked session persistence: append never blocks,
+ * resume runs topology repair for parallel tool-call siblings, and
+ * detects a session that ended mid-turn rather than cleanly. */
+export declare class SessionKnit<TMessage> {
+    private readonly storage;
+    private readonly options;
+    constructor(storage: Storage<TMessage>, options?: SessionKnitOptions<TMessage>);
+    append(sessionId: string, entry: SessionEntry<TMessage>): Promise<void>;
+    flush(sessionId: string): Promise<void>;
+    resume(sessionId: string, leafId?: string): Promise<ResumeResult<TMessage>>;
+}

package/dist/core/sessionknit.js

@@ -0,0 +1,189 @@
+// Formerly the standalone `sessionknit` package — folded in here for the
+// same reason mcpplug.ts and toollane.ts were: no consumer besides
+// loopengine itself (core/session-store.ts) ever actually materialized,
+// so the separate-package/portable-to-any-host framing was aspirational
+// rather than realized. Durable, parent-linked session persistence:
+// append never blocks, resume runs topology repair for parallel
+// tool-call siblings, and detects a session that ended mid-turn rather
+// than cleanly — see session-store.ts's own header comment for why this
+// matters for a real agent loop specifically.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Append-only JSONL storage with a debounced, batched write-behind
+ * queue — append() never blocks the caller. flush() (called
+ * automatically before every resume) forces pending lines to disk. */
+export class FileStorage {
+    dir;
+    debounceMs;
+    pending = new Map();
+    timers = new Map();
+    constructor(dir, debounceMs = 100) {
+        this.dir = dir;
+        this.debounceMs = debounceMs;
+    }
+    pathFor(sessionId) {
+        // sessionId is caller-controlled and often comes straight from
+        // untrusted input (a CLI flag, an HTTP body) — strip path separators so
+        // it can't escape `dir` via `../` traversal.
+        const safeId = sessionId.replace(/[/\\]/g, '_');
+        return join(this.dir, `${safeId}.jsonl`);
+    }
+    async append(sessionId, entry) {
+        const lines = this.pending.get(sessionId) ?? [];
+        lines.push(JSON.stringify(entry));
+        this.pending.set(sessionId, lines);
+        if (!this.timers.has(sessionId)) {
+            const timer = setTimeout(() => {
+                this.timers.delete(sessionId);
+                void this.drain(sessionId);
+            }, this.debounceMs);
+            this.timers.set(sessionId, timer);
+        }
+    }
+    async flush(sessionId) {
+        const timer = this.timers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(sessionId);
+        }
+        await this.drain(sessionId);
+    }
+    async drain(sessionId) {
+        const lines = this.pending.get(sessionId);
+        if (!lines || lines.length === 0)
+            return;
+        this.pending.delete(sessionId);
+        const path = this.pathFor(sessionId);
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, `${lines.join('\n')}\n`);
+    }
+    async readAll(sessionId) {
+        try {
+            const content = await readFile(this.pathFor(sessionId), 'utf8');
+            return content
+                .split('\n')
+                .filter((line) => line.length > 0)
+                .map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+}
+/** Same debounce/flush contract as FileStorage, backed by memory instead
+ * of disk — useful for tests, and a second real example proving the
+ * Storage interface is genuinely swappable for a host that wants a
+ * database or S3 backend instead. */
+export class MemoryStorage {
+    debounceMs;
+    committed = new Map();
+    pending = new Map();
+    timers = new Map();
+    constructor(debounceMs = 100) {
+        this.debounceMs = debounceMs;
+    }
+    async append(sessionId, entry) {
+        const items = this.pending.get(sessionId) ?? [];
+        items.push(entry);
+        this.pending.set(sessionId, items);
+        if (!this.timers.has(sessionId)) {
+            const timer = setTimeout(() => {
+                this.timers.delete(sessionId);
+                this.drain(sessionId);
+            }, this.debounceMs);
+            this.timers.set(sessionId, timer);
+        }
+    }
+    async flush(sessionId) {
+        const timer = this.timers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(sessionId);
+        }
+        this.drain(sessionId);
+    }
+    drain(sessionId) {
+        const items = this.pending.get(sessionId);
+        if (!items || items.length === 0)
+            return;
+        this.pending.delete(sessionId);
+        const existing = this.committed.get(sessionId) ?? [];
+        this.committed.set(sessionId, [...existing, ...items]);
+    }
+    async readAll(sessionId) {
+        return this.committed.get(sessionId) ?? [];
+    }
+}
+/** Pure reconstruction — no I/O, so it's testable without a storage
+ * backend. Walks parentId from the target leaf back to the root, then
+ * runs topology repair: at each node on that path, any *other* children
+ * (siblings of the node that continues the path) are reattached too —
+ * exactly what a turn with parallel tool calls produces, and exactly
+ * what a naive single-parent walk would silently drop. */
+export function reconstructChain(entries, leafId) {
+    if (entries.length === 0)
+        return { messages: [], entries: [] };
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    const childrenOf = new Map();
+    for (const entry of entries) {
+        const list = childrenOf.get(entry.parentId) ?? [];
+        list.push(entry);
+        childrenOf.set(entry.parentId, list);
+    }
+    const target = leafId !== undefined ? byId.get(leafId) : entries[entries.length - 1];
+    if (!target) {
+        throw new Error(`Unknown entry '${leafId}'`);
+    }
+    // Walk parentId back to the root, collecting root-to-leaf order.
+    const path = [];
+    let current = target;
+    while (current) {
+        path.unshift(current);
+        current = current.parentId !== null ? byId.get(current.parentId) : undefined;
+    }
+    // Topology repair.
+    const repaired = [];
+    for (let i = 0; i < path.length; i++) {
+        const node = path[i];
+        repaired.push(node);
+        const nextOnPath = path[i + 1]?.id;
+        const siblings = childrenOf.get(node.id) ?? [];
+        for (const sibling of siblings) {
+            if (sibling.id !== nextOnPath) {
+                repaired.push(sibling);
+            }
+        }
+    }
+    return { messages: repaired.map((entry) => entry.message), entries: repaired };
+}
+/** Durable, parent-linked session persistence: append never blocks,
+ * resume runs topology repair for parallel tool-call siblings, and
+ * detects a session that ended mid-turn rather than cleanly. */
+export class SessionKnit {
+    storage;
+    options;
+    constructor(storage, options = {}) {
+        this.storage = storage;
+        this.options = options;
+    }
+    async append(sessionId, entry) {
+        await this.storage.append(sessionId, entry);
+    }
+    async flush(sessionId) {
+        await this.storage.flush(sessionId);
+    }
+    async resume(sessionId, leafId) {
+        await this.storage.flush(sessionId);
+        const entries = await this.storage.readAll(sessionId);
+        const { messages, entries: repaired } = reconstructChain(entries, leafId);
+        const lastEntry = repaired[repaired.length - 1];
+        const interrupted = lastEntry !== undefined && (this.options.hasUnresolvedToolCall?.(lastEntry.message) ?? false);
+        let finalMessages = messages;
+        if (interrupted && this.options.buildContinuation) {
+            finalMessages = [...messages, this.options.buildContinuation(lastEntry.message)];
+        }
+        return { messages: finalMessages, resumedAfterInterruption: interrupted, leafId: lastEntry?.id ?? null };
+    }
+}

package/dist/core/skillgarden/activation.d.ts

@@ -0,0 +1,4 @@
+/** A skill with no `paths` restriction is always eligible. One with a
+ * restriction only activates once a touched file matches one of its
+ * glob patterns — mirrors Claude Code's conditional-activation skills. */
+export declare function matchesActivationPaths(paths: string[] | undefined, touchedPath: string): boolean;

package/dist/core/skillgarden/activation.js

@@ -0,0 +1,16 @@
+/** Same matching semantics used in ActAuth's scope patterns: '*' matches
+ * any run of characters, '?' matches exactly one. Kept independent of any
+ * glob library on purpose — this is the whole matcher this module needs. */
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const withWildcards = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+    return new RegExp(`^${withWildcards}$`);
+}
+/** A skill with no `paths` restriction is always eligible. One with a
+ * restriction only activates once a touched file matches one of its
+ * glob patterns — mirrors Claude Code's conditional-activation skills. */
+export function matchesActivationPaths(paths, touchedPath) {
+    if (!paths || paths.length === 0)
+        return true;
+    return paths.some((pattern) => globToRegExp(pattern).test(touchedPath));
+}

package/dist/core/skillgarden/budget.d.ts

@@ -0,0 +1,20 @@
+import type { SkillIndexEntry } from './types.js';
+/** ~4 chars/token — a common rough heuristic, good enough for budgeting
+ * an index of short description lines. Deliberately its own copy, not a
+ * shared import from core/budget.ts's own estimateTokens — that one
+ * budgets a model's full conversation context; this one budgets a
+ * skill-index listing, a different unit at a different layer, even
+ * though the heuristic they both land on happens to be identical. */
+export declare function estimateTokens(text: string): number;
+export interface BuildIndexOptions {
+    maxTokens: number;
+}
+export interface BudgetedIndex {
+    included: SkillIndexEntry[];
+    truncated: SkillIndexEntry[];
+}
+/** Fills the index in order until the token budget is spent, then drops
+ * the rest. Order matters — callers that want priority (e.g. skills
+ * matching recently-touched files first) should sort entries before
+ * calling this. */
+export declare function buildBudgetedIndex(entries: SkillIndexEntry[], options: BuildIndexOptions): BudgetedIndex;

package/dist/core/skillgarden/budget.js

@@ -0,0 +1,28 @@
+/** ~4 chars/token — a common rough heuristic, good enough for budgeting
+ * an index of short description lines. Deliberately its own copy, not a
+ * shared import from core/budget.ts's own estimateTokens — that one
+ * budgets a model's full conversation context; this one budgets a
+ * skill-index listing, a different unit at a different layer, even
+ * though the heuristic they both land on happens to be identical. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Fills the index in order until the token budget is spent, then drops
+ * the rest. Order matters — callers that want priority (e.g. skills
+ * matching recently-touched files first) should sort entries before
+ * calling this. */
+export function buildBudgetedIndex(entries, options) {
+    const included = [];
+    const truncated = [];
+    let used = 0;
+    for (const entry of entries) {
+        if (used + entry.estimatedTokens <= options.maxTokens) {
+            included.push(entry);
+            used += entry.estimatedTokens;
+        }
+        else {
+            truncated.push(entry);
+        }
+    }
+    return { included, truncated };
+}

package/dist/core/skillgarden/discovery.d.ts

@@ -0,0 +1,11 @@
+export interface DiscoveredSkillFile {
+    /** Namespaced name — nested dirs join with ':', e.g. "deploy:web". */
+    namespacedName: string;
+    filePath: string;
+}
+/** Walks a root directory for nested `SKILL.md` files. A directory containing
+ * SKILL.md is treated as one skill and not walked further — supporting
+ * files live alongside it, not nested skills. Nesting depth becomes the
+ * namespace: `deploy/web/SKILL.md` under root `skills/` becomes
+ * `deploy:web`, matching Claude Code's own namespacing convention. */
+export declare function discoverSkillFiles(rootDir: string): DiscoveredSkillFile[];

package/dist/core/skillgarden/discovery.js

@@ -0,0 +1,40 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/** Walks a root directory for nested `SKILL.md` files. A directory containing
+ * SKILL.md is treated as one skill and not walked further — supporting
+ * files live alongside it, not nested skills. Nesting depth becomes the
+ * namespace: `deploy/web/SKILL.md` under root `skills/` becomes
+ * `deploy:web`, matching Claude Code's own namespacing convention. */
+export function discoverSkillFiles(rootDir) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const full = join(dir, entry.name);
+            const skillFile = join(full, 'SKILL.md');
+            let hasSkillFile = false;
+            try {
+                hasSkillFile = statSync(skillFile).isFile();
+            }
+            catch {
+                hasSkillFile = false;
+            }
+            if (hasSkillFile) {
+                const namespacedName = relative(rootDir, full).split(sep).join(':');
+                results.push({ namespacedName, filePath: skillFile });
+                continue;
+            }
+            walk(full);
+        }
+    }
+    walk(rootDir);
+    return results;
+}

package/dist/core/skillgarden/frontmatter.d.ts

@@ -0,0 +1,10 @@
+import type { SkillFrontmatter } from './types.js';
+/** Parses a SKILL.md file. Frontmatter is optional and malformed YAML
+ * doesn't throw — a bad skill file should never break discovery of every
+ * other skill. Missing `name`/`description` fall back to the directory
+ * name and the first markdown heading, matching how authors actually
+ * write these files in practice. */
+export declare function parseSkillFile(raw: string, fallbackName: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};

package/dist/core/skillgarden/frontmatter.js

@@ -0,0 +1,35 @@
+import { parse as parseYaml } from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Parses a SKILL.md file. Frontmatter is optional and malformed YAML
+ * doesn't throw — a bad skill file should never break discovery of every
+ * other skill. Missing `name`/`description` fall back to the directory
+ * name and the first markdown heading, matching how authors actually
+ * write these files in practice. */
+export function parseSkillFile(raw, fallbackName) {
+    const match = raw.match(FRONTMATTER_RE);
+    let frontmatterRaw = '';
+    let body = raw;
+    if (match) {
+        frontmatterRaw = match[1] ?? '';
+        body = match[2] ?? '';
+    }
+    let parsed = {};
+    if (frontmatterRaw.trim()) {
+        try {
+            parsed = parseYaml(frontmatterRaw) ?? {};
+        }
+        catch {
+            parsed = {};
+        }
+    }
+    const name = typeof parsed.name === 'string' ? parsed.name : fallbackName;
+    const description = typeof parsed.description === 'string' ? parsed.description : (extractFirstHeading(body) ?? name);
+    return {
+        frontmatter: { ...parsed, name, description },
+        body: body.trim(),
+    };
+}
+function extractFirstHeading(markdown) {
+    const match = markdown.match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim();
+}

package/dist/core/skillgarden/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './frontmatter.js';
+export * from './discovery.js';
+export * from './budget.js';
+export * from './substitute.js';
+export * from './activation.js';
+export { SkillGarden } from './loader.js';
+export type { SkillGardenOptions } from './loader.js';

package/dist/core/skillgarden/index.js

@@ -0,0 +1,12 @@
+// Formerly the standalone `skillgarden` package — folded into loopengine
+// core since it had no consumer besides loopengine itself.
+// `SKILL.md` discovery/loading/budgeting: a lightweight name+description
+// index loads at startup capped to a token budget, and the full body
+// loads lazily only when a skill is actually invoked.
+export * from './types.js';
+export * from './frontmatter.js';
+export * from './discovery.js';
+export * from './budget.js';
+export * from './substitute.js';
+export * from './activation.js';
+export { SkillGarden } from './loader.js';

package/dist/core/skillgarden/loader.d.ts

@@ -0,0 +1,31 @@
+import { type BudgetedIndex } from './budget.js';
+import type { LoadedSkill, SkillIndexEntry } from './types.js';
+export interface SkillGardenOptions {
+    /** Roots to scan for nested `SKILL.md` files. */
+    dirs: string[];
+    /** Token budget for the always-loaded name+description index. Real
+     * agent context windows are large (~100k-200k tokens); Claude Code
+     * itself caps this index around 1% of the window, so ~2000 is a
+     * reasonable default rather than an arbitrary round number. */
+    indexBudgetTokens?: number;
+}
+/** Phase 1: scan + parse frontmatter only, budget-capped — this is what
+ * stays loaded in context at all times. Phase 2 (`load`/`invoke`) reads
+ * the full body lazily, only for a skill actually being invoked. */
+export declare class SkillGarden {
+    private readonly dirs;
+    private readonly indexBudgetTokens;
+    private indexed;
+    constructor(options: SkillGardenOptions);
+    buildIndex(): BudgetedIndex;
+    /** Full body, read only now — call after buildIndex() has discovered
+     * the skill. */
+    load(name: string): LoadedSkill;
+    /** Load + substitute placeholders, ready to inject into a running
+     * conversation. */
+    invoke(name: string, args?: string): string;
+    /** Filters index entries down to skills eligible given files touched
+     * so far in the session. Skills with no `paths` restriction are always
+     * eligible. */
+    eligibleFor(entries: SkillIndexEntry[], touchedPaths: string[]): SkillIndexEntry[];
+}

package/dist/core/skillgarden/loader.js

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { matchesActivationPaths } from './activation.js';
+import { buildBudgetedIndex, estimateTokens } from './budget.js';
+import { discoverSkillFiles } from './discovery.js';
+import { parseSkillFile } from './frontmatter.js';
+import { substituteArguments } from './substitute.js';
+/** Phase 1: scan + parse frontmatter only, budget-capped — this is what
+ * stays loaded in context at all times. Phase 2 (`load`/`invoke`) reads
+ * the full body lazily, only for a skill actually being invoked. */
+export class SkillGarden {
+    dirs;
+    indexBudgetTokens;
+    indexed = new Map();
+    constructor(options) {
+        this.dirs = options.dirs;
+        this.indexBudgetTokens = options.indexBudgetTokens ?? 2000;
+    }
+    buildIndex() {
+        this.indexed.clear();
+        const entries = [];
+        for (const dir of this.dirs) {
+            for (const { namespacedName, filePath } of discoverSkillFiles(dir)) {
+                const raw = readFileSync(filePath, 'utf8');
+                const { frontmatter } = parseSkillFile(raw, namespacedName);
+                this.indexed.set(namespacedName, { filePath, frontmatter });
+                entries.push({
+                    name: namespacedName,
+                    description: String(frontmatter.description),
+                    filePath,
+                    estimatedTokens: estimateTokens(`${namespacedName}: ${frontmatter.description}`),
+                });
+            }
+        }
+        return buildBudgetedIndex(entries, { maxTokens: this.indexBudgetTokens });
+    }
+    /** Full body, read only now — call after buildIndex() has discovered
+     * the skill. */
+    load(name) {
+        const indexed = this.indexed.get(name);
+        if (!indexed) {
+            throw new Error(`Unknown skill '${name}' — call buildIndex() first, or it wasn't discovered`);
+        }
+        const raw = readFileSync(indexed.filePath, 'utf8');
+        const { frontmatter, body } = parseSkillFile(raw, name);
+        return {
+            name,
+            description: String(frontmatter.description),
+            body,
+            frontmatter,
+            filePath: indexed.filePath,
+        };
+    }
+    /** Load + substitute placeholders, ready to inject into a running
+     * conversation. */
+    invoke(name, args) {
+        const skill = this.load(name);
+        return substituteArguments(skill.body, args);
+    }
+    /** Filters index entries down to skills eligible given files touched
+     * so far in the session. Skills with no `paths` restriction are always
+     * eligible. */
+    eligibleFor(entries, touchedPaths) {
+        return entries.filter((entry) => {
+            const paths = this.indexed.get(entry.name)?.frontmatter.paths;
+            if (!paths || paths.length === 0)
+                return true;
+            return touchedPaths.some((touched) => matchesActivationPaths(paths, touched));
+        });
+    }
+}

package/dist/core/skillgarden/substitute.d.ts

@@ -0,0 +1,4 @@
+/** Replaces `$ARGUMENTS` with the raw args string, and `$1`/`$2`/... with
+ * whitespace-split positional args — the same placeholder convention
+ * skill authors already expect from Claude Code's own Skill tool. */
+export declare function substituteArguments(body: string, args?: string): string;

package/dist/core/skillgarden/substitute.js

@@ -0,0 +1,13 @@
+/** Replaces `$ARGUMENTS` with the raw args string, and `$1`/`$2`/... with
+ * whitespace-split positional args — the same placeholder convention
+ * skill authors already expect from Claude Code's own Skill tool. */
+export function substituteArguments(body, args) {
+    const argString = args ?? '';
+    let result = body.replaceAll('$ARGUMENTS', argString);
+    const positional = argString.split(/\s+/).filter(Boolean);
+    result = result.replace(/\$(\d+)/g, (_match, indexStr) => {
+        const index = Number(indexStr);
+        return positional[index - 1] ?? '';
+    });
+    return result;
+}

package/dist/core/skillgarden/types.d.ts

@@ -0,0 +1,23 @@
+/** Deliberately loose — real skill authors' frontmatter always has fields
+ * we haven't modeled yet, so the parser must not reject unknown keys. */
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    paths?: string[];
+    [key: string]: unknown;
+}
+export interface SkillIndexEntry {
+    /** Namespaced name — nested dirs join with ':', e.g. "deploy:web". */
+    name: string;
+    description: string;
+    filePath: string;
+    estimatedTokens: number;
+}
+export interface LoadedSkill {
+    name: string;
+    description: string;
+    /** Markdown body with the frontmatter block stripped. */
+    body: string;
+    frontmatter: SkillFrontmatter;
+    filePath: string;
+}

package/dist/core/skillgarden/types.js

@@ -0,0 +1 @@
+export {};