maestro-agent-sdk 0.1.32 → 0.1.34

package/dist/skills/curator.d.ts

@@ -1,106 +0,0 @@
-import type { SkillEntry } from "../skills/loader.js";
-import { type SkillCounters } from "../skills/usage.js";
-/**
- * Skill Curator — assigns lifecycle states (active / stale / archived) to
- * every loaded skill based on the usage sidecar, then filters the catalog
- * fed to the system prompt so attention isn't shredded by 100 dormant
- * entries.
- *
- * Lifecycle:
- *
- *   - active   — recently viewed OR brand-new. Surface in the index.
- *   - stale    — has been viewed at least once but hasn't been touched in
- *                a long time. Still in the index, but at the bottom (and
- *                marked) so the model can recognize "this exists" without
- *                being nudged toward it.
- *   - archived — old + never viewed. Dropped from the index entirely.
- *                The skill file stays on disk; the model can still reach
- *                it via skill_view if the user explicitly names it, but
- *                it stops costing tokens on every turn.
- *
- * The `bundled` vs `agent-created` provenance bit is no longer derivable
- * from path under the `(cwd, skillKey)` model — every skill lives under
- * `<cwd>/.skills/<skillKey>/` regardless of origin. `isBundled` returns
- * true for everything, which protects project-shipped skills from
- * archival; the side effect is that agent-created skills also persist
- * indefinitely. If accumulation becomes a problem, a future release can
- * re-introduce provenance via a frontmatter marker (e.g.
- * `provenance: agent`).
- *
- * The state file lives at `${DATA_DIR}/agents/maestro/skills/state.json`.
- * Like the usage sidecar it's process-local + atomic-write — a host loop
- * is single-process and the curator runs at most once per turn.
- *
- * The SDK ships the rule-based lifecycle transitions only. The LLM-review
- * pass that upstream uses to propose merges between near-duplicate skills
- * is intentionally deferred — it needs a cost budget and operator-confirmed
- * action, both of which are host-side concerns.
- */
-export type SkillLifecycle = "active" | "stale" | "archived";
-export interface SkillState {
-    lifecycle: SkillLifecycle;
-    /** ISO timestamp of the last transition (any direction). */
-    changedTs: string;
-    /** Provenance hint — bundled skills are protected from archival. */
-    bundled: boolean;
-}
-export interface SkillStateFile {
-    schemaVersion: 1;
-    states: Record<string, SkillState>;
-}
-/** How many days since `lastTouchedTs` before a previously-viewed skill is
- *  marked `stale`. Default 30. */
-export declare const STALE_AFTER_DAYS = 30;
-/** How many days since `firstSeenTs` (and never viewed) before an unused
- *  agent-created skill is archived. Default 60. Bundled skills are exempt. */
-export declare const ARCHIVE_AFTER_DAYS = 60;
-/** Default state file path. Overridable via `MAESTRO_SKILL_STATE_PATH`. */
-export declare function defaultStatePath(): string;
-/** Read the state file synchronously, or return an empty one on
- *  ENOENT / schema mismatch / parse error. Cached in-process. */
-export declare function loadState(path?: string): SkillStateFile;
-/**
- * Decide the lifecycle for one skill given its counters + provenance + a
- * reference `now`. Pure function — no I/O. Drives both the in-memory
- * filter and the state-file persistence.
- *
- * Rules:
- *   - bundled + never viewed     → "active"  (operator shipped it for a reason)
- *   - viewCount > 0 + recent     → "active"
- *   - viewCount > 0 + N days old → "stale"
- *   - agent-created + never viewed + M days old → "archived"
- *   - default (just-loaded, no record yet)      → "active"
- */
-export declare function decideLifecycle(counters: SkillCounters | undefined, bundled: boolean, now?: Date): SkillLifecycle;
-export interface CurateOptions {
-    /** Use a fixed `now` for reproducible tests. */
-    now?: Date;
-    /** Override the state path for tests. */
-    statePath?: string;
-    /** Override the usage path for tests. */
-    usagePath?: string;
-    /** Skip writing the state file (read-only inspection). */
-    readOnly?: boolean;
-}
-export interface CuratedSkill {
-    skill: SkillEntry;
-    state: SkillState;
-}
-/**
- * Walk the loaded catalog, compute each skill's lifecycle from the usage
- * sidecar, persist the assignments, and return only the `active` + `stale`
- * entries (callers feed these into the system prompt index builder).
- *
- * Archived skills are kept on disk but dropped from the returned list so
- * the per-turn system prompt stays slim. `skill_view(name=...)` for an
- * archived skill still works — the model just won't be prompted with it.
- *
- * The state-file update is idempotent: skills that didn't change lifecycle
- * since the last call get a no-op write (still atomic).
- */
-export declare function curateSkills(skills: SkillEntry[], opts?: CurateOptions): CuratedSkill[];
-/** Test-only: drop the in-process state cache. Disk file is NOT erased —
- *  tests that need filesystem isolation should point
- *  `MAESTRO_SKILL_STATE_PATH` at a tmp file and remove it themselves. */
-export declare function __resetForTests(): void;
-//# sourceMappingURL=curator.d.ts.map

package/dist/skills/curator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"curator.d.ts","sourceRoot":"","sources":["../../src/skills/curator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAID;kCACkC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC;8EAC8E;AAC9E,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAIrC,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAWD;iEACiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAA2B,GAAG,cAAc,CAM3E;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,OAAO,EAAE,OAAO,EAChB,GAAG,GAAE,IAAiB,GACrB,cAAc,CAYhB;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,YAAY,EAAE,CAoD3F;AAED;;yEAEyE;AACzE,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/skills/curator.js

@@ -1,168 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { DATA_DIR } from "../platform/config.js";
-import { logger } from "../platform/logger.js";
-import { loadUsage } from "../skills/usage.js";
-const SCHEMA_VERSION = 1;
-/** How many days since `lastTouchedTs` before a previously-viewed skill is
- *  marked `stale`. Default 30. */
-export const STALE_AFTER_DAYS = 30;
-/** How many days since `firstSeenTs` (and never viewed) before an unused
- *  agent-created skill is archived. Default 60. Bundled skills are exempt. */
-export const ARCHIVE_AFTER_DAYS = 60;
-const DAY_MS = 24 * 60 * 60 * 1000;
-/** Default state file path. Overridable via `MAESTRO_SKILL_STATE_PATH`. */
-export function defaultStatePath() {
-    return (process.env.MAESTRO_SKILL_STATE_PATH ??
-        join(DATA_DIR, "agents", "maestro", "skills", "state.json"));
-}
-function emptyFile() {
-    return { schemaVersion: SCHEMA_VERSION, states: {} };
-}
-// Write-through cache: curateSkills is the sole writer, runs once per turn
-// at most, and produces an explicit `next` object that we install into the
-// cache after writeAtomic. Eliminates the per-turn state.json readFileSync.
-const stateCacheByPath = new Map();
-/** Read the state file synchronously, or return an empty one on
- *  ENOENT / schema mismatch / parse error. Cached in-process. */
-export function loadState(path = defaultStatePath()) {
-    const cached = stateCacheByPath.get(path);
-    if (cached)
-        return cached;
-    const fresh = readStateFromDisk(path);
-    stateCacheByPath.set(path, fresh);
-    return fresh;
-}
-function readStateFromDisk(path) {
-    if (!existsSync(path))
-        return emptyFile();
-    try {
-        const raw = readFileSync(path, "utf8");
-        const parsed = JSON.parse(raw);
-        if (parsed.schemaVersion !== SCHEMA_VERSION || typeof parsed.states !== "object") {
-            logger.warn({ path }, "skill curator: state schema mismatch, resetting");
-            return emptyFile();
-        }
-        return parsed;
-    }
-    catch (err) {
-        logger.warn({ err, path }, "skill curator: state read/parse failed, resetting");
-        return emptyFile();
-    }
-}
-/** Atomic tmp + rename write. */
-function writeAtomic(path, contents) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(contents, null, 2));
-    renameSync(tmp, path);
-}
-/** A skill is `bundled` if the operator (or project) shipped it deliberately,
- *  vs `agent-created` if it was synthesized at runtime by the model.
- *
- *  In the `(cwd, skillKey)` model every skill lives under
- *  `<cwd>/.skills/<skillKey>/`, so path alone can't tell the two apart —
- *  both end up in the same directory. We treat everything as bundled so
- *  the curator never archives a project-shipped skill. Agent-created
- *  skills also stop archiving as a side effect; if accumulation becomes
- *  a problem, a future release can re-introduce provenance via a marker
- *  in SKILL.md frontmatter (`provenance: agent` etc.) rather than by
- *  path heuristics that the new layout doesn't support. */
-function isBundled(_skill) {
-    return true;
-}
-/**
- * Decide the lifecycle for one skill given its counters + provenance + a
- * reference `now`. Pure function — no I/O. Drives both the in-memory
- * filter and the state-file persistence.
- *
- * Rules:
- *   - bundled + never viewed     → "active"  (operator shipped it for a reason)
- *   - viewCount > 0 + recent     → "active"
- *   - viewCount > 0 + N days old → "stale"
- *   - agent-created + never viewed + M days old → "archived"
- *   - default (just-loaded, no record yet)      → "active"
- */
-export function decideLifecycle(counters, bundled, now = new Date()) {
-    if (!counters)
-        return "active";
-    const lastTouched = Date.parse(counters.lastTouchedTs);
-    const firstSeen = Date.parse(counters.firstSeenTs);
-    const nowMs = now.getTime();
-    if (counters.viewCount > 0) {
-        const idleDays = (nowMs - lastTouched) / DAY_MS;
-        return idleDays >= STALE_AFTER_DAYS ? "stale" : "active";
-    }
-    if (bundled)
-        return "active";
-    const ageDays = (nowMs - firstSeen) / DAY_MS;
-    return ageDays >= ARCHIVE_AFTER_DAYS ? "archived" : "active";
-}
-/**
- * Walk the loaded catalog, compute each skill's lifecycle from the usage
- * sidecar, persist the assignments, and return only the `active` + `stale`
- * entries (callers feed these into the system prompt index builder).
- *
- * Archived skills are kept on disk but dropped from the returned list so
- * the per-turn system prompt stays slim. `skill_view(name=...)` for an
- * archived skill still works — the model just won't be prompted with it.
- *
- * The state-file update is idempotent: skills that didn't change lifecycle
- * since the last call get a no-op write (still atomic).
- */
-export function curateSkills(skills, opts = {}) {
-    const usage = loadUsage(opts.usagePath).skills;
-    const prior = loadState(opts.statePath);
-    const now = opts.now ?? new Date();
-    const next = { schemaVersion: SCHEMA_VERSION, states: {} };
-    const out = [];
-    let changed = false;
-    for (const skill of skills) {
-        const bundled = isBundled(skill);
-        const counters = usage[skill.name];
-        const lifecycle = decideLifecycle(counters, bundled, now);
-        const priorState = prior.states[skill.name];
-        let changedTs;
-        if (priorState && priorState.lifecycle === lifecycle && priorState.bundled === bundled) {
-            // Stable — preserve the existing change timestamp.
-            changedTs = priorState.changedTs;
-        }
-        else {
-            changedTs = now.toISOString();
-            changed = true;
-        }
-        const state = { lifecycle, changedTs, bundled };
-        next.states[skill.name] = state;
-        if (lifecycle !== "archived")
-            out.push({ skill, state });
-    }
-    // Skills that were in `prior` but no longer in the catalog (renamed /
-    // deleted) get implicitly dropped — `next.states` only carries the
-    // current catalog. Treat that as a change so the file shrinks too.
-    for (const oldName of Object.keys(prior.states)) {
-        if (!next.states[oldName]) {
-            changed = true;
-            break;
-        }
-    }
-    if (changed && !opts.readOnly) {
-        const path = opts.statePath ?? defaultStatePath();
-        try {
-            writeAtomic(path, next);
-            // Install post-write file as the new cache reference so the next
-            // loadState call sees the freshly-persisted state without re-reading.
-            stateCacheByPath.set(path, next);
-        }
-        catch (err) {
-            logger.warn({ err, path }, "skill curator: state write failed (continuing with in-memory result)");
-        }
-    }
-    return out;
-}
-/** Test-only: drop the in-process state cache. Disk file is NOT erased —
- *  tests that need filesystem isolation should point
- *  `MAESTRO_SKILL_STATE_PATH` at a tmp file and remove it themselves. */
-export function __resetForTests() {
-    stateCacheByPath.clear();
-}
-//# sourceMappingURL=curator.js.map

package/dist/skills/curator.js.map

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

package/dist/skills/index-builder.d.ts

@@ -1,41 +0,0 @@
-import { type SkillEntry } from "../skills/loader.js";
-/**
- * Render the `## Skills (mandatory)` block that gets appended to the Maestro
- * system prompt.
- *
- * Ported from upstream `agent/prompt_builder.py::build_skills_prompt` with
- * two changes:
- *   1. CLI-installer-specific guidance from the upstream tree is dropped —
- *      the SDK ships no bundled SKILL.md catalog, so suggesting a tool that
- *      isn't there would just produce `unknown tool` noise.
- *   2. The `skill_manage(action='patch')` invitation is dropped — the
- *      Curator's mutation path is intentionally deferred; surfacing the
- *      tool before then would invite a `unknown tool` error.
- *
- * Everything else is preserved word-for-word because it's the "MUST load /
- * err on the side of loading" framing that actually raises the skill-call
- * rate. Empty / softer phrasings tested by upstream regressed activation by
- * ~30%.
- *
- * Why system-prompt placement (not user message): upstream caches this block
- * (`_SKILLS_PROMPT_CACHE`) and embeds it in the system prompt so Anthropic's
- * prefix cache covers it across every turn. Putting it in a user message
- * would invalidate the cache the moment the user sends a follow-up. The
- * trade-off: skill_view output is large enough that we always want it in a
- * fresh user/tool message (cache-busting it once per skill load is fine —
- * it's the index that needs the rolling hit).
- *
- * Returns the empty string when there are no skills — the caller can then
- * skip the append entirely instead of injecting an empty header.
- */
-export declare function buildSkillsIndex(skills: SkillEntry[]): string;
-/**
- * Cap a skill description to the index limit (`SKILL_INDEX_DESCRIPTION_CAP`).
- * Trims trailing whitespace + ellipsis-truncates so the index stays at one
- * line per skill. The full description still ships with `skill_view`, so the
- * model can read it in full once it decides to load.
- *
- * Empty input returns "" so the caller can suppress the trailing `: …`.
- */
-export declare function capDescription(desc: string): string;
-//# sourceMappingURL=index-builder.d.ts.map

package/dist/skills/index-builder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../src/skills/index-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CA6C7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/skills/index-builder.js

@@ -1,93 +0,0 @@
-import { SKILL_INDEX_DESCRIPTION_CAP } from "../skills/loader.js";
-/**
- * Render the `## Skills (mandatory)` block that gets appended to the Maestro
- * system prompt.
- *
- * Ported from upstream `agent/prompt_builder.py::build_skills_prompt` with
- * two changes:
- *   1. CLI-installer-specific guidance from the upstream tree is dropped —
- *      the SDK ships no bundled SKILL.md catalog, so suggesting a tool that
- *      isn't there would just produce `unknown tool` noise.
- *   2. The `skill_manage(action='patch')` invitation is dropped — the
- *      Curator's mutation path is intentionally deferred; surfacing the
- *      tool before then would invite a `unknown tool` error.
- *
- * Everything else is preserved word-for-word because it's the "MUST load /
- * err on the side of loading" framing that actually raises the skill-call
- * rate. Empty / softer phrasings tested by upstream regressed activation by
- * ~30%.
- *
- * Why system-prompt placement (not user message): upstream caches this block
- * (`_SKILLS_PROMPT_CACHE`) and embeds it in the system prompt so Anthropic's
- * prefix cache covers it across every turn. Putting it in a user message
- * would invalidate the cache the moment the user sends a follow-up. The
- * trade-off: skill_view output is large enough that we always want it in a
- * fresh user/tool message (cache-busting it once per skill load is fine —
- * it's the index that needs the rolling hit).
- *
- * Returns the empty string when there are no skills — the caller can then
- * skip the append entirely instead of injecting an empty header.
- */
-export function buildSkillsIndex(skills) {
-    if (skills.length === 0)
-        return "";
-    const byCategory = new Map();
-    for (const s of skills) {
-        const bucket = byCategory.get(s.category) ?? [];
-        bucket.push(s);
-        byCategory.set(s.category, bucket);
-    }
-    const lines = [];
-    const sortedCategories = [...byCategory.keys()].sort((a, b) => a.localeCompare(b));
-    for (const category of sortedCategories) {
-        lines.push(`  ${category}:`);
-        const inCat = byCategory.get(category) ?? [];
-        inCat.sort((a, b) => a.name.localeCompare(b.name));
-        for (const s of inCat) {
-            const trimmed = capDescription(s.description);
-            if (trimmed) {
-                lines.push(`    - ${s.name}: ${trimmed}`);
-            }
-            else {
-                lines.push(`    - ${s.name}`);
-            }
-        }
-    }
-    return [
-        "## Skills (mandatory)",
-        "Before replying, scan the skills below. If a skill matches or is even partially relevant " +
-            "to your task, you MUST load it with skill_view(name) and follow its instructions. " +
-            "Err on the side of loading — it is always better to have context you don't need " +
-            "than to miss critical steps, pitfalls, or established workflows. " +
-            "Skills contain specialized knowledge — API endpoints, tool-specific commands, " +
-            "and proven workflows that outperform general-purpose approaches. Load the skill " +
-            "even if you think you could handle the task with basic tools. " +
-            "Skills also encode the user's preferred approach, conventions, and quality standards " +
-            "for tasks like code review, planning, and testing — load them even for tasks you " +
-            "already know how to do, because the skill defines how it should be done here.",
-        "",
-        "<available_skills>",
-        ...lines,
-        "</available_skills>",
-        "",
-        "Only proceed without loading a skill if genuinely none are relevant to the task.",
-    ].join("\n");
-}
-/**
- * Cap a skill description to the index limit (`SKILL_INDEX_DESCRIPTION_CAP`).
- * Trims trailing whitespace + ellipsis-truncates so the index stays at one
- * line per skill. The full description still ships with `skill_view`, so the
- * model can read it in full once it decides to load.
- *
- * Empty input returns "" so the caller can suppress the trailing `: …`.
- */
-export function capDescription(desc) {
-    const collapsed = desc.replace(/\s+/g, " ").trim();
-    if (!collapsed)
-        return "";
-    if (collapsed.length <= SKILL_INDEX_DESCRIPTION_CAP)
-        return collapsed;
-    // -1 for the ellipsis.
-    return `${collapsed.slice(0, SKILL_INDEX_DESCRIPTION_CAP - 1)}…`;
-}
-//# sourceMappingURL=index-builder.js.map

package/dist/skills/index-builder.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-builder.js","sourceRoot":"","sources":["../../src/skills/index-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAmB,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,gBAAgB,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,KAAK,MAAM,QAAQ,IAAI,gBAAgB,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,GAAG,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;YAC9C,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,uBAAuB;QACvB,2FAA2F;YACzF,oFAAoF;YACpF,kFAAkF;YAClF,mEAAmE;YACnE,gFAAgF;YAChF,kFAAkF;YAClF,gEAAgE;YAChE,uFAAuF;YACvF,mFAAmF;YACnF,+EAA+E;QACjF,EAAE;QACF,oBAAoB;QACpB,GAAG,KAAK;QACR,qBAAqB;QACrB,EAAE;QACF,kFAAkF;KACnF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,SAAS,CAAC,MAAM,IAAI,2BAA2B;QAAE,OAAO,SAAS,CAAC;IACtE,uBAAuB;IACvB,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,2BAA2B,GAAG,CAAC,CAAC,GAAG,CAAC;AACnE,CAAC"}

package/dist/skills/loader.d.ts

@@ -1,132 +0,0 @@
-/**
- * Skill loader for the Maestro TS port — accepts two on-disk conventions:
- *
- *   1. **Upstream v0.13.0** — `SKILL.md` (UPPERCASE) with a leading
- *      `---\nYAML\n---\n` frontmatter block carrying `name` + `description`
- *      and an optional `platforms` filter.
- *
- *   2. **Clawgram body-based** — `skill.md` (lowercase) with no YAML
- *      block; the first `# Heading` is treated as the display title and
- *      a `> **Description**: ...` blockquote on a single line carries the
- *      trigger keywords / summary. Canonical `name` falls back to the
- *      parent directory's kebab-case identifier so the rest of the
- *      pipeline (index, skill_view, usage counters) is convention-agnostic.
- *
- * Both filename casings and both metadata sources are merged transparently
- * — a SKILL.md with frontmatter wins on conflicting fields, and a project
- * can mix the two styles in the same `.skills/<key>/` tree without
- * configuration. The full YAML parser is still avoided; the minimal
- * fallback parser (top-level scalars + flat `platforms: [...]` list)
- * covers every real-world frontmatter we've seen.
- *
- * Directory layout (both styles):
- *     <root>/<category>/<skill-name>/{SKILL.md|skill.md}
- * The penultimate path segment is treated as `category` (used for the
- * Skills index grouping); a skill file at the root level is bucketed
- * under "general".
- *
- * Filters:
- *   - Hidden / build dirs (`.git`, `.github`, `.archive`, `.hub`) are
- *     skipped recursively (same skip set as upstream).
- *   - Platform mismatch (`platforms: [macos]` on Linux) drops the skill so
- *     the index doesn't suggest tools that won't run.
- */
-/** One loaded SKILL.md entry, ready for index rendering or full-load via skill_view. */
-export interface SkillEntry {
-    /** `name:` from frontmatter, falling back to the parent directory name. */
-    name: string;
-    /** Short summary surfaced in the index. Empty string if missing. */
-    description: string;
-    /** Directory bucket = the parent of the skill's own directory. "general" at root. */
-    category: string;
-    /** Absolute path to the directory containing SKILL.md. Used for
-     *  `${MAESTRO_SKILL_DIR}` template substitution and for resolving
-     *  relative paths inside the skill body. */
-    skillDir: string;
-    /** Absolute path to SKILL.md itself. */
-    mdPath: string;
-    /** Raw file contents (frontmatter + body). Kept so skill_view can return
-     *  the body without a second disk read. */
-    raw: string;
-    /** Parsed frontmatter as a flat string map. Multi-value entries (e.g.
-     *  `platforms: [macos, linux]`) are joined with `,`. */
-    frontmatter: Record<string, string>;
-}
-/** Description length cap for the rendered index. Raised from 60 → 300 in
- *  v0.1.5 because the original 60-char ceiling truncated the "trigger
- *  keywords" line that clawgram-style skills rely on for activation —
- *  hosts intentionally pack a comma-separated list of search terms into
- *  the description, and chopping it at 60 chars regularly lost half the
- *  keywords. 300 is generous enough that every real-world description we
- *  audited fits intact, while still keeping the per-skill system-prompt
- *  footprint bounded if a runaway author writes a 5KB description. The
- *  full description still ships with `skill_view` for the body view. */
-export declare const SKILL_INDEX_DESCRIPTION_CAP = 300;
-/**
- * Walk `rootDir` recursively and return one `SkillEntry` per SKILL.md found,
- * subject to platform compatibility + the skip-dir filter.
- *
- * Errors per-file (unreadable, malformed) are logged at debug and the file
- * is dropped — one bad SKILL.md never aborts the whole scan, same stance as
- * upstream `scan_skill_commands`.
- */
-export declare function loadSkills(rootDir: string): SkillEntry[];
-/**
- * Pull a `> **Description**: ...` (or `> Description: ...`) blockquote out
- * of a markdown body. Matches the clawgram convention where a single-line
- * blockquote near the top of the file carries the trigger keywords.
- *
- * Case-insensitive on the label, tolerant of either `**Description**` or
- * plain `Description`. Only the first match is returned — multi-line
- * blockquotes get joined into one line by trimming trailing whitespace and
- * collapsing inner newlines.
- *
- * Returns "" when no blockquote matches, so the caller can decide whether
- * to fall back to a different source.
- */
-export declare function extractBlockquoteDescription(body: string): string;
-/**
- * Parse a `---\n...\n---\n` YAML frontmatter block into a flat string map.
- *
- * Supports the SKILL.md surface that matters in v0.13.0:
- *   - `key: value` scalars (with optional surrounding quotes)
- *   - `key: [a, b, c]` flow-list literals (joined with "," for storage)
- *   - Nested blocks (`metadata:\n  maestro:\n    tags: [...]`) are flattened
- *     by ignoring indented lines — we only need top-level keys for the
- *     index + platform filter.
- *
- * Lines that don't fit the `key: value` shape are dropped silently. This
- * matches the upstream "fallback" parser; the full YAML parser is omitted
- * because every real-world SKILL.md in v0.13.0 round-trips cleanly through
- * this subset.
- *
- * Returns `body` as the post-frontmatter text. If no frontmatter is
- * present, `frontmatter` is empty and `body` is the original input.
- */
-export declare function parseFrontmatter(content: string): {
-    frontmatter: Record<string, string>;
-    body: string;
-};
-/**
- * Return true if the skill's `platforms:` list contains the current OS, or
- * if the field is missing/empty (skill claims cross-platform).
- *
- * Match logic is upstream-compatible: any listed platform whose mapped
- * runtime prefix is a prefix of `process.platform` counts as a hit (so
- * `darwin` matches `darwin23.6.0`).
- */
-export declare function matchesPlatform(frontmatter: Record<string, string>, platform?: string): boolean;
-/**
- * Cached variant of `loadSkills` — same return shape, but memoizes on the
- * (rootDir, rootDir-mtime) pair with a TTL backstop. Use this from any hot
- * path (per-turn callers, per-iteration callers). Tests or operators that
- * need a guaranteed fresh load can call `invalidateSkillsCache()` first.
- */
-export declare function loadSkillsCached(rootDir: string): SkillEntry[];
-/** Drop the in-memory cache so the next `loadSkillsCached` call rebuilds.
- *  Call after writing a new SKILL.md to disk, or between tests. */
-export declare function invalidateSkillsCache(): void;
-/** Find a single skill by name. Used by `skill_view`. Returns null if the
- *  name doesn't resolve to a loaded entry. */
-export declare function findSkillByName(skills: SkillEntry[], name: string): SkillEntry | null;
-//# sourceMappingURL=loader.d.ts.map

package/dist/skills/loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/skills/loader.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;gDAE4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf;+CAC2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;4DACwD;IACxD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAMD;;;;;;;;wEAQwE;AACxE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAgBxD;AAsGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAkCA;AAaD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,QAAQ,GAAE,MAAyB,GAClC,OAAO,CAaT;AA8CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAoB9D;AAED;mEACmE;AACnE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;8CAC8C;AAC9C,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAYrF"}