maestro-agent-sdk 0.1.0

package/dist/skills/loader.js

@@ -0,0 +1,286 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { logger } from "../platform/logger.js";
+/** Sub-directory names we never descend into. Mirrors upstream
+ *  `scan_skill_commands` skip set. */
+const SKIP_DIRS = new Set([".git", ".github", ".hub", ".archive", "node_modules"]);
+/** Description length cap for the rendered index. Upstream uses 80, but the
+ *  Clawgram routing review settled on 60 to keep the system-prompt block
+ *  tight (~6K tokens hard ceiling once the catalog has 60+ skills). The
+ *  full description survives in `frontmatter.description` for skill_view. */
+export const SKILL_INDEX_DESCRIPTION_CAP = 60;
+/**
+ * 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 function loadSkills(rootDir) {
+    if (!existsSync(rootDir)) {
+        logger.debug({ rootDir }, "maestro skills: rootDir missing — returning empty");
+        return [];
+    }
+    const out = [];
+    const seenNames = new Set();
+    walk(rootDir, rootDir, out, seenNames);
+    // Deterministic ordering for cache-friendly system-prompt rendering: by
+    // category then by name. Without this, readdir's filesystem-dependent
+    // ordering would shuffle entries between runs and break prefix caching.
+    out.sort((a, b) => {
+        if (a.category !== b.category)
+            return a.category.localeCompare(b.category);
+        return a.name.localeCompare(b.name);
+    });
+    return out;
+}
+function walk(root, dir, out, seenNames) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        logger.debug({ err, dir }, "maestro skills: readdir failed, skipping subtree");
+        return;
+    }
+    for (const name of entries) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const path = join(dir, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            walk(root, path, out, seenNames);
+            continue;
+        }
+        if (!stat.isFile() || basename(path) !== "SKILL.md")
+            continue;
+        const entry = parseSkillFile(root, path);
+        if (!entry)
+            continue;
+        // De-duplicate by skill name. Upstream scans local dir first, then
+        // external dirs; we follow the same precedence by walking in readdir
+        // order from a single root — the first occurrence wins.
+        if (seenNames.has(entry.name))
+            continue;
+        if (!matchesPlatform(entry.frontmatter))
+            continue;
+        seenNames.add(entry.name);
+        out.push(entry);
+    }
+}
+function parseSkillFile(root, mdPath) {
+    let raw;
+    try {
+        raw = readFileSync(mdPath, "utf8");
+    }
+    catch (err) {
+        logger.debug({ err, mdPath }, "maestro skills: read failed, skipping");
+        return null;
+    }
+    const { frontmatter, body } = parseFrontmatter(raw);
+    const skillDir = mdPath.slice(0, -"/SKILL.md".length);
+    const dirName = basename(skillDir);
+    const name = (frontmatter.name ?? dirName).trim();
+    if (!name)
+        return null;
+    // Category = directory bucket relative to root.  e.g. root/apple/foo/SKILL.md → "apple".
+    // Root-level skills get "general" to match upstream behavior.
+    const rel = skillDir.slice(root.length).replace(/^[/\\]+/, "");
+    const parts = rel.split(sep).filter(Boolean);
+    const category = parts.length > 1 ? parts.slice(0, -1).join("/") : "general";
+    // Description: prefer frontmatter, fall back to the first non-blank,
+    // non-heading line of the body (upstream same fallback). Empty string is
+    // valid — index-builder renders it without the `: ...` suffix.
+    let description = (frontmatter.description ?? "").trim();
+    if (!description) {
+        for (const line of body.split("\n")) {
+            const t = line.trim();
+            if (!t || t.startsWith("#"))
+                continue;
+            description = t;
+            break;
+        }
+    }
+    // Strip surrounding quotes (YAML scalars are often written as quoted strings).
+    description = description.replace(/^["']|["']$/g, "");
+    return {
+        name,
+        description,
+        category,
+        skillDir,
+        mdPath,
+        raw,
+        frontmatter,
+    };
+}
+/**
+ * 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 function parseFrontmatter(content) {
+    const frontmatter = {};
+    if (!content.startsWith("---"))
+        return { frontmatter, body: content };
+    // Find the closing `---` (must be on its own line, after the opening).
+    const closeMatch = /\n---[ \t]*(?:\n|$)/.exec(content.slice(3));
+    if (!closeMatch)
+        return { frontmatter, body: content };
+    const yamlBlock = content.slice(3, closeMatch.index + 3);
+    const body = content.slice(closeMatch.index + 3 + closeMatch[0].length);
+    for (const rawLine of yamlBlock.split("\n")) {
+        // Skip blanks, comments, and indented (nested) entries.
+        const line = rawLine.replace(/[\r]+$/, "");
+        if (!line.trim() || line.trim().startsWith("#"))
+            continue;
+        if (/^\s/.test(line))
+            continue;
+        const idx = line.indexOf(":");
+        if (idx < 0)
+            continue;
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        if (!key)
+            continue;
+        // Flow-list literal → CSV of unwrapped scalars.
+        if (value.startsWith("[") && value.endsWith("]")) {
+            value = value
+                .slice(1, -1)
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean)
+                .join(",");
+        }
+        else {
+            // Strip surrounding quotes if present.
+            value = value.replace(/^["']|["']$/g, "");
+        }
+        frontmatter[key] = value;
+    }
+    return { frontmatter, body };
+}
+/** Map `process.platform` to the upstream platform tokens used in SKILL.md
+ *  `platforms:` lists. */
+const PLATFORM_ALIASES = {
+    macos: "darwin",
+    osx: "darwin",
+    mac: "darwin",
+    linux: "linux",
+    win: "win32",
+    windows: "win32",
+};
+/**
+ * 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 function matchesPlatform(frontmatter, platform = process.platform) {
+    const raw = frontmatter.platforms;
+    if (!raw)
+        return true;
+    const list = raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (list.length === 0)
+        return true;
+    for (const p of list) {
+        const mapped = PLATFORM_ALIASES[p] ?? p;
+        if (platform.startsWith(mapped))
+            return true;
+    }
+    return false;
+}
+let cachedSkills = null;
+const DEFAULT_CACHE_TTL_MS = 30_000;
+function cacheTtlMs() {
+    const raw = process.env.MAESTRO_SKILL_CACHE_TTL_MS;
+    if (raw === undefined)
+        return DEFAULT_CACHE_TTL_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_CACHE_TTL_MS;
+    return n;
+}
+function safeRootMtime(rootDir) {
+    try {
+        return statSync(rootDir).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 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 function loadSkillsCached(rootDir) {
+    const ttl = cacheTtlMs();
+    if (ttl === 0)
+        return loadSkills(rootDir);
+    const now = Date.now();
+    if (cachedSkills && cachedSkills.rootDir === rootDir) {
+        const rootMtimeMs = safeRootMtime(rootDir);
+        const fresh = now - cachedSkills.builtAtMs < ttl;
+        const sameRoot = rootMtimeMs === cachedSkills.rootMtimeMs;
+        if (fresh && sameRoot)
+            return cachedSkills.entries;
+    }
+    const entries = loadSkills(rootDir);
+    cachedSkills = {
+        rootDir,
+        entries,
+        builtAtMs: now,
+        rootMtimeMs: safeRootMtime(rootDir),
+    };
+    return entries;
+}
+/** Drop the in-memory cache so the next `loadSkillsCached` call rebuilds.
+ *  Call after writing a new SKILL.md to disk, or between tests. */
+export function invalidateSkillsCache() {
+    cachedSkills = null;
+}
+/** Find a single skill by name. Used by `skill_view`. Returns null if the
+ *  name doesn't resolve to a loaded entry. */
+export function findSkillByName(skills, name) {
+    const wanted = name.trim();
+    if (!wanted)
+        return null;
+    for (const s of skills) {
+        if (s.name === wanted)
+            return s;
+    }
+    // Case-insensitive fallback — model occasionally lowercases identifiers.
+    const lower = wanted.toLowerCase();
+    for (const s of skills) {
+        if (s.name.toLowerCase() === lower)
+            return s;
+    }
+    return null;
+}
+//# sourceMappingURL=loader.js.map

package/dist/skills/loader.js.map

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

package/dist/skills/preprocess.d.ts

@@ -0,0 +1,45 @@
+export interface PreprocessOptions {
+    /** Absolute path passed to `${MAESTRO_SKILL_DIR}` (`null` keeps the token literal). */
+    skillDir?: string | null;
+    /** Maestro session UUID for `${MAESTRO_SESSION_ID}` (`null` keeps the token literal). */
+    sessionId?: string | null;
+    /** Run `!`cmd`` snippets at preprocess time. Default `false` (matches upstream). */
+    inlineShell?: boolean;
+    /** Per-snippet timeout in seconds when `inlineShell: true`. */
+    inlineShellTimeoutS?: number;
+}
+/**
+ * Replace `${MAESTRO_SKILL_DIR}` / `${MAESTRO_SESSION_ID}` in `content`.
+ *
+ * Tokens for which the corresponding option value is missing are left in
+ * place — the author can then see "oh, this skill was loaded without a
+ * session id" instead of getting silent empty strings.
+ */
+export declare function substituteTemplateVars(content: string, opts: {
+    skillDir?: string | null;
+    sessionId?: string | null;
+}): string;
+/**
+ * Run one inline-shell snippet. Failures return a short `[inline-shell ...]`
+ * marker rather than throwing so a single bad snippet can't break the whole
+ * skill load.
+ *
+ * `cwd` is set to the skill directory so relative paths in the snippet
+ * resolve where the author expected them to.
+ */
+export declare function runInlineShell(command: string, cwd: string | null | undefined, timeoutS: number): string;
+/** Expand every `` !`cmd` `` snippet in `content` with its stdout. No-op
+ *  when the content has no `!`` marker (cheap fast path). */
+export declare function expandInlineShell(content: string, cwd: string | null | undefined, timeoutS: number): string;
+/**
+ * Single-call entry point used by `skill_view`. Applies template-var
+ * substitution unconditionally and inline-shell only when explicitly
+ * opted in.
+ *
+ * Returns the input unchanged when it's empty (defensive — upstream's
+ * `preprocess_skill_content` returns `""` for empty inputs).
+ */
+export declare function preprocessSkillContent(content: string, opts: PreprocessOptions): string;
+export declare const __INLINE_SHELL_MAX_OUTPUT = 4000;
+export declare const __INLINE_SHELL_DEFAULT_TIMEOUT_S = 10;
+//# sourceMappingURL=preprocess.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preprocess.d.ts","sourceRoot":"","sources":["../../src/skills/preprocess.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oFAAoF;IACpF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC5D,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAyBR;AAED;6DAC6D;AAC7D,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAQvF;AAGD,eAAO,MAAM,yBAAyB,OAA0B,CAAC;AACjE,eAAO,MAAM,gCAAgC,KAAiC,CAAC"}

package/dist/skills/preprocess.js

@@ -0,0 +1,126 @@
+import { spawnSync } from "node:child_process";
+/**
+ * SKILL.md content preprocessing for the Maestro TS port.
+ *
+ * Two transforms, both lifted from upstream `agent/skill_preprocessing.py`:
+ *
+ *   1. Template variable substitution — `${MAESTRO_SKILL_DIR}` and
+ *      `${MAESTRO_SESSION_ID}` get replaced with the active skill's absolute
+ *      directory and the current Maestro session id, respectively. Skill
+ *      authors rely on this to reference bundled scripts:
+ *
+ *          Run `bash ${MAESTRO_SKILL_DIR}/scripts/setup.sh` before continuing.
+ *
+ *      Tokens whose value isn't supplied stay literal — the author can spot
+ *      the unresolved placeholder when reading the model's output.
+ *
+ *   2. Inline shell snippets — `` !`<cmd>` `` runs the command at load time
+ *      and is replaced with its stdout (capped). Off by default (matches
+ *      upstream's `skills.inline_shell: false` default) because it runs
+ *      arbitrary code at preprocessing time; opt-in via the `inlineShell`
+ *      flag for trusted skills that need dynamic state (e.g. current
+ *      git branch).
+ *
+ * Both are applied at `skill_view`-time, **after** the SKILL.md body has been
+ * loaded and **before** the body is handed to the model. The model sees a
+ * fully-resolved skill, never a raw template token.
+ */
+/** Matches `${MAESTRO_SKILL_DIR}` / `${MAESTRO_SESSION_ID}`. Unknown tokens are
+ *  left intact for debugability. */
+const TEMPLATE_TOKEN_RE = /\$\{(MAESTRO_SKILL_DIR|MAESTRO_SESSION_ID)\}/g;
+/** Inline shell shape: `` !`single-line-cmd` ``. No newlines inside the
+ *  backticks (matches upstream — multi-line shell goes in a code fence). */
+const INLINE_SHELL_RE = /!`([^`\n]+)`/g;
+/** Hard cap on stdout from a single inline-shell snippet so a runaway
+ *  command can't blow out the model's context window. */
+const INLINE_SHELL_MAX_OUTPUT = 4000;
+/** Default per-snippet timeout (seconds). Upstream uses 10s. */
+const INLINE_SHELL_DEFAULT_TIMEOUT_S = 10;
+/**
+ * Replace `${MAESTRO_SKILL_DIR}` / `${MAESTRO_SESSION_ID}` in `content`.
+ *
+ * Tokens for which the corresponding option value is missing are left in
+ * place — the author can then see "oh, this skill was loaded without a
+ * session id" instead of getting silent empty strings.
+ */
+export function substituteTemplateVars(content, opts) {
+    if (!content)
+        return content;
+    return content.replace(TEMPLATE_TOKEN_RE, (full, token) => {
+        if (token === "MAESTRO_SKILL_DIR" && opts.skillDir)
+            return opts.skillDir;
+        if (token === "MAESTRO_SESSION_ID" && opts.sessionId)
+            return opts.sessionId;
+        return full;
+    });
+}
+/**
+ * Run one inline-shell snippet. Failures return a short `[inline-shell ...]`
+ * marker rather than throwing so a single bad snippet can't break the whole
+ * skill load.
+ *
+ * `cwd` is set to the skill directory so relative paths in the snippet
+ * resolve where the author expected them to.
+ */
+export function runInlineShell(command, cwd, timeoutS) {
+    const cleanedTimeout = Number.isFinite(timeoutS) && timeoutS > 0 ? Math.floor(timeoutS) : 1;
+    try {
+        const result = spawnSync("bash", ["-c", command], {
+            cwd: cwd ?? undefined,
+            encoding: "utf-8",
+            timeout: cleanedTimeout * 1000,
+            maxBuffer: INLINE_SHELL_MAX_OUTPUT * 4,
+        });
+        if (result.error) {
+            const err = result.error;
+            if (err.code === "ETIMEDOUT") {
+                return `[inline-shell timeout after ${cleanedTimeout}s: ${command}]`;
+            }
+            return `[inline-shell error: ${err.message}]`;
+        }
+        let output = (result.stdout ?? "").replace(/\n+$/, "");
+        if (!output && result.stderr)
+            output = result.stderr.replace(/\n+$/, "");
+        if (output.length > INLINE_SHELL_MAX_OUTPUT) {
+            output = `${output.slice(0, INLINE_SHELL_MAX_OUTPUT)}...[truncated]`;
+        }
+        return output;
+    }
+    catch (err) {
+        return `[inline-shell error: ${err.message}]`;
+    }
+}
+/** Expand every `` !`cmd` `` snippet in `content` with its stdout. No-op
+ *  when the content has no `!`` marker (cheap fast path). */
+export function expandInlineShell(content, cwd, timeoutS) {
+    if (!content.includes("!`"))
+        return content;
+    return content.replace(INLINE_SHELL_RE, (_full, cmd) => {
+        const trimmed = String(cmd).trim();
+        if (!trimmed)
+            return "";
+        return runInlineShell(trimmed, cwd, timeoutS);
+    });
+}
+/**
+ * Single-call entry point used by `skill_view`. Applies template-var
+ * substitution unconditionally and inline-shell only when explicitly
+ * opted in.
+ *
+ * Returns the input unchanged when it's empty (defensive — upstream's
+ * `preprocess_skill_content` returns `""` for empty inputs).
+ */
+export function preprocessSkillContent(content, opts) {
+    if (!content)
+        return content;
+    let out = substituteTemplateVars(content, { skillDir: opts.skillDir, sessionId: opts.sessionId });
+    if (opts.inlineShell) {
+        const timeout = opts.inlineShellTimeoutS ?? INLINE_SHELL_DEFAULT_TIMEOUT_S;
+        out = expandInlineShell(out, opts.skillDir, timeout);
+    }
+    return out;
+}
+// Expose internal constants for tests.
+export const __INLINE_SHELL_MAX_OUTPUT = INLINE_SHELL_MAX_OUTPUT;
+export const __INLINE_SHELL_DEFAULT_TIMEOUT_S = INLINE_SHELL_DEFAULT_TIMEOUT_S;
+//# sourceMappingURL=preprocess.js.map

package/dist/skills/preprocess.js.map

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

package/dist/skills/usage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Skill usage sidecar — process-local persistent counters.
+ *
+ * Each skill the catalog ever surfaces accumulates three counters:
+ *
+ *   - viewCount:   bumped when `skill_view(name)` returns its body. Direct
+ *                  signal that the model thought this skill was worth pulling
+ *                  the full SKILL.md for.
+ *   - useCount:    bumped by callers when one of the skill's recommended
+ *                  commands actually ran. Optional today (no auto-detector
+ *                  for "did the bash call use a skill-suggested invocation");
+ *                  kept in the schema so future instrumentation can land
+ *                  without a migration.
+ *   - patchCount:  bumped on skill edits (future `skill_edit` builtin).
+ *
+ * Storage: a single JSON file at `${DATA_DIR}/agents/maestro/skills/usage.json`.
+ * Process-local — Clawgram is single-process in production, so a per-skill
+ * sidecar would over-shard the disk for no gain. Atomic-write via tmp +
+ * rename guards against the rare `writeFileSync` interrupted-write race.
+ *
+ * Concurrency: serialized via an in-process mutex chain (Promises). Two
+ * `bumpView` calls during the same tick (e.g. a model that views two skills
+ * in one assistant turn) queue cleanly instead of one clobbering the other.
+ * Inter-process locking is intentionally NOT implemented — production has
+ * one bun process; tests use `__resetForTests` to avoid cross-test leak.
+ *
+ * Read path is non-blocking (synchronous read of the at-rest JSON). Write
+ * path is async (await the mutex, then sync-write the tmp + rename). Both
+ * tolerate ENOENT — first-ever bump creates the file fresh.
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/tools/skill_usage.py`
+ * (similar schema; we collapse their per-skill `.usage.json` directory
+ * pattern into one central JSON to avoid polluting the upstream snapshot's
+ * skills/ directory with mutated files).
+ */
+export interface SkillCounters {
+    viewCount: number;
+    useCount: number;
+    patchCount: number;
+    /** ISO timestamp of the most recent bump on any counter. */
+    lastTouchedTs: string;
+    /** ISO timestamp of the first time this skill appeared in the file.
+     *  Used by the Curator to weight new vs long-stale skills. */
+    firstSeenTs: string;
+}
+export interface SkillUsageFile {
+    schemaVersion: 1;
+    skills: Record<string, SkillCounters>;
+}
+/** Default sidecar path. Overridable via `MAESTRO_SKILL_USAGE_PATH` for tests
+ *  and operators that prefer a different on-disk location. */
+export declare function defaultUsagePath(): string;
+/**
+ * Read the usage file synchronously. Returns an empty (in-memory) file on
+ * ENOENT / parse failure — callers that need to disambiguate can call
+ * `existsSync(defaultUsagePath())` themselves. Logged at debug so a missing
+ * file is not noise on every read.
+ */
+export declare function loadUsage(path?: string): SkillUsageFile;
+/** Get counters for a single skill. Never returns undefined — synthesizes
+ *  zeroed counters for unseen skills so callers can compute deltas without
+ *  null-checks. */
+export declare function getCounters(name: string, path?: string): SkillCounters;
+/** Bump `viewCount` for `name`. Called from `skill_view` after a successful body load. */
+export declare function bumpView(name: string, path?: string): Promise<SkillCounters>;
+/** Bump `useCount` for `name`. Reserved for future call-site instrumentation. */
+export declare function bumpUse(name: string, path?: string): Promise<SkillCounters>;
+/** Bump `patchCount` for `name`. Reserved for the future `skill_edit` builtin. */
+export declare function bumpPatch(name: string, path?: string): Promise<SkillCounters>;
+/** Test-only: drop the in-memory mutex queue + write-through cache. Disk
+ *  file is NOT erased — tests that need filesystem isolation should point
+ *  `MAESTRO_SKILL_USAGE_PATH` at a tmp file via `process.env` and remove it
+ *  themselves. */
+export declare function __resetForTests(): void;
+//# sourceMappingURL=usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/skills/usage.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB;kEAC8D;IAC9D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAID;8DAC8D;AAC9D,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAmCD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAA2B,GAAG,cAAc,CAM3E;AA2BD;;mBAEmB;AACnB,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAA2B,GAAG,aAAa,CAG1F;AAmDD,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAE5E;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAE3E;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAE7E;AAED;;;kBAGkB;AAClB,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}