maestro-agent-sdk 0.1.0

package/dist/session-store.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Maestro session store + rollout encoder.
+ *
+ * Unlike claude/codex (which delegate persistence to vendor SDKs whose
+ * rollouts live at `~/.claude/projects/` and `~/.codex/sessions/`), Maestro
+ * is a pure in-process loop that owns its own conversation history. We
+ * persist it ourselves at `~/.maestro/sessions/<sessionId>.jsonl`, one
+ * ProviderMessage per line, so a follow-up `maestroProvider` call with the
+ * same `opts.sessionId` can rebuild the `messages` array and continue
+ * exactly where the previous turn left off — same contract as the SDK-backed
+ * providers, just our own storage layer.
+ *
+ * The JSONL is round-tripped verbatim: tool_use / tool_result content blocks
+ * survive a save→load cycle so multi-turn tool histories don't degrade into
+ * `[Tool: ...]` text annotations (those only happen on cross-agent rollouts,
+ * which by definition came from another provider's log).
+ *
+ * Two writer paths share the same file format:
+ *   - `saveMaestroSession` — verbatim dump from the live loop.
+ *   - `writeMaestroRollout` — synthesized from a provider-agnostic
+ *     `ConversationEntry` log (used by `set_agent` cross-agent bridging and
+ *     by `forkSession`). Pairs are flattened to `{role, content: text}`.
+ */
+import { type ChatPair } from "./agents/rollout/shared.js";
+import type { ProviderMessage } from "./providers/base.js";
+import type { ConversationEntry } from "./storage/conversations.js";
+/** Root directory for maestro session/rollout files. */
+export declare function maestroSessionsDir(): string;
+/** Absolute path of the JSONL backing a given sessionId. */
+export declare function maestroSessionPath(sessionId: string): string;
+/**
+ * Load the persisted ProviderMessage[] for a sessionId, or `null` if no
+ * file exists (i.e. this is a fresh session). Malformed lines are skipped
+ * with a warning rather than crashing the loop — a corrupt entry in the
+ * middle of history is better than losing a working session entirely.
+ */
+export declare function loadMaestroSession(sessionId: string): ProviderMessage[] | null;
+/**
+ * Overwrite (or create) the persisted session file with the provided
+ * messages. Each turn's final state is written atomically — partial-history
+ * writes can leave the next resume looking at a stale prefix.
+ */
+export declare function saveMaestroSession(sessionId: string, messages: ProviderMessage[]): void;
+/**
+ * Remove a session's backing file and drop its in-memory file-state tracker.
+ * ENOENT on the unlink is silently ignored. Tracker drop is unconditional —
+ * no-op when the session never registered a tracker.
+ */
+export declare function deleteMaestroSession(sessionId: string): void;
+export interface MaestroRolloutOptions {
+    /** Working directory the resumed Maestro session will report. Validated
+     *  against the workspace roots so callers can't smuggle arbitrary cwds. */
+    cwd: string;
+    /** Optional override; default = freshly generated UUIDv4. */
+    sessionId?: string;
+    /** Pairs to encode. If omitted, derived from `entries` via extractChatPairs. */
+    pairs?: ChatPair[];
+    /** When `pairs` is omitted, the source UnifiedEvent log to digest. */
+    entries?: ConversationEntry[];
+}
+export interface MaestroRolloutResult {
+    sessionId: string;
+    rolloutPath: string;
+}
+/**
+ * Materialize a Maestro session JSONL from the provided dialogue and place it
+ * at `~/.maestro/sessions/<sessionId>.jsonl`. A subsequent `maestroProvider`
+ * call with `opts.sessionId === sessionId` will load this file and treat it
+ * as conversation history — same path the live loop persists to.
+ *
+ * Used by `set_agent` cross-agent bridging (X → maestro) and by
+ * `maestroRegistry.forkSession`.
+ */
+export declare function writeMaestroRollout(opts: MaestroRolloutOptions): MaestroRolloutResult;
+/**
+ * Validate a message read from disk has the minimum shape Maestro needs.
+ * Used by the loader to drop entries that would crash the provider call.
+ * Returns the message typed if valid, or null if it should be dropped.
+ *
+ * Kept conservative: role must be "user" or "assistant", content must be
+ * a non-empty string or a content-block array. Anything else came from a
+ * different schema version (or a corrupt write) and is safer to drop than
+ * to feed back to the model.
+ */
+export declare function isWellFormedMessage(value: unknown): value is ProviderMessage;
+/**
+ * Drop trailing entries that would make the next Anthropic resume invalid.
+ *
+ * Two failure modes the live loop can leave behind when it exits without a
+ * clean drain (abort signal, provider crash, hard fetch error):
+ *  - A final `user` whose content is the plain-text prompt that was never
+ *    answered. Resuming would feed it to the model a second time.
+ *  - A final `assistant` carrying `tool_use` blocks without a paired user
+ *    turn of `tool_result` blocks. Anthropic rejects this with
+ *    `400 messages.N: invalid_request_error` ("each `tool_use` block must
+ *    have a corresponding `tool_result`").
+ *
+ * The trim walks back from the tail, dropping orphan turns until it lands
+ * on a consistent prefix. A user turn that already contains `tool_result`
+ * blocks is a valid stopping point (the model just hasn't been asked yet to
+ * react to those results — Anthropic treats that as a fresh starting point).
+ *
+ * Returning an empty array is fine: it means the only thing the loop pushed
+ * before failing was the new user prompt, and the next resume should treat
+ * the session as starting from the previously persisted state.
+ */
+export declare function trimToSafePrefix(messages: ProviderMessage[]): ProviderMessage[];
+/**
+ * Sweep `~/.maestro/sessions/` and unlink JSONL files whose mtime is older
+ * than `maxAgeMs` (default 30 days).
+ *
+ * Why a TTL instead of `purgeTopicLogs`-style targeted cleanup: a maestro
+ * session is identified only by UUID, and that UUID can be referenced from
+ * multiple places (conversation log, fork rollouts, set_agent bridges).
+ * A definitive "is this session still in use?" check would require
+ * cross-referencing every user's conversation manifest on disk on every
+ * cleanup pass — expensive and brittle. Instead we rely on the simple
+ * "any active session writes its file every turn, so mtime tracks use"
+ * invariant. Sessions a user hasn't touched for a month are forgotten
+ * either way; deleting the file just reclaims disk and avoids a slow
+ * directory if the user accumulates thousands of UUIDs over time.
+ *
+ * Safe on first boot (directory missing → returns 0). Per-file unlink
+ * errors are logged and skipped rather than abort the sweep — one
+ * permission glitch shouldn't block the rest.
+ *
+ * Returns { scanned, removed } so the caller can log the result.
+ */
+export declare function cleanupStaleMaestroSessions(maxAgeMs?: number): {
+    scanned: number;
+    removed: number;
+};
+//# sourceMappingURL=session-store.d.ts.map

package/dist/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAwB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,GAAG,IAAI,CAa9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI,CAGvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAe5D;AAqBD,MAAM,WAAW,qBAAqB;IACpC;+EAC2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,sEAAsE;IACtE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAarF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAS5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAgC/E;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,GAAE,MAAuC,GAAG;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAgDA"}

package/dist/session-store.js

@@ -0,0 +1,277 @@
+/**
+ * Maestro session store + rollout encoder.
+ *
+ * Unlike claude/codex (which delegate persistence to vendor SDKs whose
+ * rollouts live at `~/.claude/projects/` and `~/.codex/sessions/`), Maestro
+ * is a pure in-process loop that owns its own conversation history. We
+ * persist it ourselves at `~/.maestro/sessions/<sessionId>.jsonl`, one
+ * ProviderMessage per line, so a follow-up `maestroProvider` call with the
+ * same `opts.sessionId` can rebuild the `messages` array and continue
+ * exactly where the previous turn left off — same contract as the SDK-backed
+ * providers, just our own storage layer.
+ *
+ * The JSONL is round-tripped verbatim: tool_use / tool_result content blocks
+ * survive a save→load cycle so multi-turn tool histories don't degrade into
+ * `[Tool: ...]` text annotations (those only happen on cross-agent rollouts,
+ * which by definition came from another provider's log).
+ *
+ * Two writer paths share the same file format:
+ *   - `saveMaestroSession` — verbatim dump from the live loop.
+ *   - `writeMaestroRollout` — synthesized from a provider-agnostic
+ *     `ConversationEntry` log (used by `set_agent` cross-agent bridging and
+ *     by `forkSession`). Pairs are flattened to `{role, content: text}`.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assertUuidLike, ensureCwdExists, extractChatPairs, } from "./agents/rollout/shared.js";
+import { dropTodoStore } from "./state/todos.js";
+import { dropFileStateTracker } from "./tools/file-state.js";
+import { parseJsonlText, writeJsonlFile } from "./platform/jsonl.js";
+import { logger } from "./platform/logger.js";
+/** Root directory for maestro session/rollout files. */
+export function maestroSessionsDir() {
+    return join(homedir(), ".maestro", "sessions");
+}
+/** Absolute path of the JSONL backing a given sessionId. */
+export function maestroSessionPath(sessionId) {
+    return join(maestroSessionsDir(), `${sessionId}.jsonl`);
+}
+/**
+ * Load the persisted ProviderMessage[] for a sessionId, or `null` if no
+ * file exists (i.e. this is a fresh session). Malformed lines are skipped
+ * with a warning rather than crashing the loop — a corrupt entry in the
+ * middle of history is better than losing a working session entirely.
+ */
+export function loadMaestroSession(sessionId) {
+    const path = maestroSessionPath(sessionId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        return parseJsonlText(raw);
+    }
+    catch (err) {
+        logger.warn({ err, sessionId, path }, "loadMaestroSession: read/parse failed, starting fresh session");
+        return null;
+    }
+}
+/**
+ * Overwrite (or create) the persisted session file with the provided
+ * messages. Each turn's final state is written atomically — partial-history
+ * writes can leave the next resume looking at a stale prefix.
+ */
+export function saveMaestroSession(sessionId, messages) {
+    assertUuidLike("sessionId", sessionId);
+    writeJsonlFile(maestroSessionPath(sessionId), messages);
+}
+/**
+ * Remove a session's backing file and drop its in-memory file-state tracker.
+ * ENOENT on the unlink is silently ignored. Tracker drop is unconditional —
+ * no-op when the session never registered a tracker.
+ */
+export function deleteMaestroSession(sessionId) {
+    try {
+        unlinkSync(maestroSessionPath(sessionId));
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT") {
+            logger.warn({ err: e, sessionId }, "deleteMaestroSession: unlink failed (non-ENOENT)");
+            // Still drop the in-memory caches — caller treats the session as gone.
+            dropFileStateTracker(sessionId);
+            dropTodoStore(sessionId);
+            throw e;
+        }
+    }
+    dropFileStateTracker(sessionId);
+    // Drops the in-memory store AND unlinks the on-disk `.todos.json` sidecar.
+    dropTodoStore(sessionId);
+}
+/**
+ * Flatten chat pairs (from cross-agent extractChatPairs output) into the
+ * provider message shape Maestro feeds back into `provider.complete()`.
+ *
+ * Tool annotations baked into `assistantText` by extractChatPairs remain
+ * inline — Maestro doesn't reconstruct synthetic tool_use IDs across SDKs
+ * (same trade-off as the codex rollout encoder). The model still sees what
+ * was called and what it returned, just as plain text rather than structured
+ * blocks.
+ */
+function pairsToMessages(pairs) {
+    const out = [];
+    for (const pair of pairs) {
+        out.push({ role: "user", content: pair.userText });
+        out.push({ role: "assistant", content: pair.assistantText });
+    }
+    return out;
+}
+/**
+ * Materialize a Maestro session JSONL from the provided dialogue and place it
+ * at `~/.maestro/sessions/<sessionId>.jsonl`. A subsequent `maestroProvider`
+ * call with `opts.sessionId === sessionId` will load this file and treat it
+ * as conversation history — same path the live loop persists to.
+ *
+ * Used by `set_agent` cross-agent bridging (X → maestro) and by
+ * `maestroRegistry.forkSession`.
+ */
+export function writeMaestroRollout(opts) {
+    const sessionId = opts.sessionId ?? randomUUID();
+    assertUuidLike("sessionId", sessionId);
+    ensureCwdExists(opts.cwd);
+    const pairs = opts.pairs ?? extractChatPairs(opts.entries ?? []);
+    const messages = pairsToMessages(pairs);
+    const path = maestroSessionPath(sessionId);
+    writeJsonlFile(path, messages);
+    logger.info({ sessionId, path, pairs: pairs.length }, "writeMaestroRollout: synthetic session placed");
+    return { sessionId, rolloutPath: path };
+}
+/**
+ * Validate a message read from disk has the minimum shape Maestro needs.
+ * Used by the loader to drop entries that would crash the provider call.
+ * Returns the message typed if valid, or null if it should be dropped.
+ *
+ * Kept conservative: role must be "user" or "assistant", content must be
+ * a non-empty string or a content-block array. Anything else came from a
+ * different schema version (or a corrupt write) and is safer to drop than
+ * to feed back to the model.
+ */
+export function isWellFormedMessage(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const obj = value;
+    if (obj.role !== "user" && obj.role !== "assistant")
+        return false;
+    if (typeof obj.content === "string")
+        return true;
+    if (!Array.isArray(obj.content))
+        return false;
+    return obj.content.every((b) => b && typeof b === "object" && typeof b.type === "string");
+}
+/**
+ * Drop trailing entries that would make the next Anthropic resume invalid.
+ *
+ * Two failure modes the live loop can leave behind when it exits without a
+ * clean drain (abort signal, provider crash, hard fetch error):
+ *  - A final `user` whose content is the plain-text prompt that was never
+ *    answered. Resuming would feed it to the model a second time.
+ *  - A final `assistant` carrying `tool_use` blocks without a paired user
+ *    turn of `tool_result` blocks. Anthropic rejects this with
+ *    `400 messages.N: invalid_request_error` ("each `tool_use` block must
+ *    have a corresponding `tool_result`").
+ *
+ * The trim walks back from the tail, dropping orphan turns until it lands
+ * on a consistent prefix. A user turn that already contains `tool_result`
+ * blocks is a valid stopping point (the model just hasn't been asked yet to
+ * react to those results — Anthropic treats that as a fresh starting point).
+ *
+ * Returning an empty array is fine: it means the only thing the loop pushed
+ * before failing was the new user prompt, and the next resume should treat
+ * the session as starting from the previously persisted state.
+ */
+export function trimToSafePrefix(messages) {
+    let end = messages.length;
+    while (end > 0) {
+        const last = messages[end - 1];
+        // Final user with plain-text content = unanswered prompt.
+        if (last.role === "user" && typeof last.content === "string") {
+            end--;
+            continue;
+        }
+        // Final assistant containing any tool_use block without a matching
+        // tool_result on the NEXT turn → orphan; drop it. The loop then re-
+        // evaluates whatever preceded it.
+        //
+        // A final assistant with ONLY text (no tool_use) is a valid stopping
+        // point — the model produced a final answer and no tool round is open.
+        // We correctly hit the `break` below, not the `continue` above. Only
+        // tool_use creates a dangling obligation for the next API call.
+        if (last.role === "assistant" && Array.isArray(last.content)) {
+            const hasToolUse = last.content.some((b) => b.type === "tool_use");
+            if (hasToolUse) {
+                end--;
+                continue;
+            }
+        }
+        // Final user with tool_result blocks is valid — Anthropic accepts a
+        // history that ends after the tool round and lets the next API call
+        // produce the assistant turn.
+        break;
+    }
+    return messages.slice(0, end);
+}
+/** Default retention: sessions untouched for 30 days are auto-purged. */
+const DEFAULT_MAESTRO_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Sweep `~/.maestro/sessions/` and unlink JSONL files whose mtime is older
+ * than `maxAgeMs` (default 30 days).
+ *
+ * Why a TTL instead of `purgeTopicLogs`-style targeted cleanup: a maestro
+ * session is identified only by UUID, and that UUID can be referenced from
+ * multiple places (conversation log, fork rollouts, set_agent bridges).
+ * A definitive "is this session still in use?" check would require
+ * cross-referencing every user's conversation manifest on disk on every
+ * cleanup pass — expensive and brittle. Instead we rely on the simple
+ * "any active session writes its file every turn, so mtime tracks use"
+ * invariant. Sessions a user hasn't touched for a month are forgotten
+ * either way; deleting the file just reclaims disk and avoids a slow
+ * directory if the user accumulates thousands of UUIDs over time.
+ *
+ * Safe on first boot (directory missing → returns 0). Per-file unlink
+ * errors are logged and skipped rather than abort the sweep — one
+ * permission glitch shouldn't block the rest.
+ *
+ * Returns { scanned, removed } so the caller can log the result.
+ */
+export function cleanupStaleMaestroSessions(maxAgeMs = DEFAULT_MAESTRO_SESSION_TTL_MS) {
+    const dir = maestroSessionsDir();
+    let scanned = 0;
+    let removed = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (e) {
+        // Directory doesn't exist yet (no maestro session has ever been written)
+        // → nothing to clean.
+        if (e?.code === "ENOENT") {
+            return { scanned: 0, removed: 0 };
+        }
+        logger.warn({ err: e, dir }, "cleanupStaleMaestroSessions: readdir failed");
+        return { scanned: 0, removed: 0 };
+    }
+    const cutoff = Date.now() - maxAgeMs;
+    for (const name of entries) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        scanned++;
+        const path = join(dir, name);
+        // saveMaestroSession writes `${sessionsDir}/${sessionId}.jsonl`, so the
+        // inverse is a suffix trim. Tracker drop happens after a successful
+        // unlink so partial-cleanup errors don't strand a tracker for a still-
+        // present file.
+        const sessionId = name.slice(0, -".jsonl".length);
+        try {
+            const stat = statSync(path);
+            if (stat.mtimeMs >= cutoff)
+                continue;
+            unlinkSync(path);
+            removed++;
+            dropFileStateTracker(sessionId);
+            // Also unlinks the on-disk `.todos.json` sidecar.
+            dropTodoStore(sessionId);
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT") {
+                logger.warn({ err: e, path }, "cleanupStaleMaestroSessions: per-file unlink failed (continuing)");
+            }
+            else {
+                // ENOENT mid-loop = raced. File gone → caches moot.
+                dropFileStateTracker(sessionId);
+                dropTodoStore(sessionId);
+            }
+        }
+    }
+    return { scanned, removed };
+}
+//# sourceMappingURL=session-store.js.map

package/dist/session-store.js.map

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

package/dist/skills/curator.d.ts

@@ -0,0 +1,104 @@
+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 (upstream's curator
+ * tracks this) is approximated by the SKILL.md's parent path: anything
+ * under the upstream snapshot (`/Users/maestrobot/__KEEP_MAESTRO_AGENT__/skills/`)
+ * is `bundled`, otherwise `agent-created`. Bundled skills are never
+ * archived — they're shipped intentionally and removing them would silently
+ * break the next user's expectation.
+ *
+ * The state file lives at `${DATA_DIR}/agents/maestro/skills/state.json`.
+ * Like the usage sidecar it's process-local + atomic-write — Clawgram is
+ * single-process and the curator runs once per turn at most.
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/agent/curator.py`
+ * — we ship the rule-based transitions only. The LLM-review pass (which
+ * proposes merges between near-duplicate skills) is intentionally deferred
+ * to a later phase; needs a cost budget and operator-confirmed action.
+ */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"curator.d.ts","sourceRoot":"","sources":["../../src/skills/curator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;AAoCD;;;;;;;;;;;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"}