maestro-agent-sdk 0.1.0

package/dist/skills/usage.js

@@ -0,0 +1,147 @@
+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";
+const SCHEMA_VERSION = 1;
+/** Default sidecar path. Overridable via `MAESTRO_SKILL_USAGE_PATH` for tests
+ *  and operators that prefer a different on-disk location. */
+export function defaultUsagePath() {
+    return (process.env.MAESTRO_SKILL_USAGE_PATH ??
+        join(DATA_DIR, "agents", "maestro", "skills", "usage.json"));
+}
+/** Mutex queue — each enqueued action awaits the previous one. */
+const queuesByPath = new Map();
+// Write-through cache: every `bump` is serialized through `enqueue`, so the
+// in-process cache is the authoritative state between writes. Eliminates the
+// per-turn readFileSync that curator + skill_view used to incur for every
+// `loadUsage` call. Tests reset via `__resetForTests`.
+const usageCacheByPath = new Map();
+function enqueue(path, fn) {
+    const prev = queuesByPath.get(path) ?? Promise.resolve();
+    let resolver;
+    let rejecter;
+    const result = new Promise((res, rej) => {
+        resolver = res;
+        rejecter = rej;
+    });
+    const next = prev.then(async () => {
+        try {
+            const v = await fn();
+            resolver(v);
+        }
+        catch (err) {
+            rejecter(err);
+        }
+    });
+    queuesByPath.set(path, next);
+    return result;
+}
+function emptyFile() {
+    return { schemaVersion: SCHEMA_VERSION, skills: {} };
+}
+/**
+ * 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 function loadUsage(path = defaultUsagePath()) {
+    const cached = usageCacheByPath.get(path);
+    if (cached)
+        return cached;
+    const fresh = readUsageFromDisk(path);
+    usageCacheByPath.set(path, fresh);
+    return fresh;
+}
+function readUsageFromDisk(path) {
+    if (!existsSync(path))
+        return emptyFile();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        logger.debug({ err, path }, "skill usage: read failed, returning empty");
+        return emptyFile();
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== SCHEMA_VERSION || typeof parsed.skills !== "object") {
+            logger.warn({ path, schemaVersion: parsed.schemaVersion }, "skill usage: schema mismatch — resetting");
+            return emptyFile();
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger.warn({ err, path }, "skill usage: JSON parse failed — resetting");
+        return emptyFile();
+    }
+}
+/** Get counters for a single skill. Never returns undefined — synthesizes
+ *  zeroed counters for unseen skills so callers can compute deltas without
+ *  null-checks. */
+export function getCounters(name, path = defaultUsagePath()) {
+    const file = loadUsage(path);
+    return file.skills[name] ?? zeroedCounters();
+}
+function zeroedCounters() {
+    const ts = new Date().toISOString();
+    return {
+        viewCount: 0,
+        useCount: 0,
+        patchCount: 0,
+        lastTouchedTs: ts,
+        firstSeenTs: ts,
+    };
+}
+/** Atomic write: tmp → rename. Survives a process kill mid-write because
+ *  the destination either has the old bytes or the new bytes, never half. */
+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);
+}
+/** Internal: increment one counter by one for `name`, persisting. */
+async function bump(name, key, path = defaultUsagePath()) {
+    if (!name) {
+        throw new Error("skill usage bump: empty name");
+    }
+    return enqueue(path, () => {
+        const file = loadUsage(path);
+        const ts = new Date().toISOString();
+        const existing = file.skills[name];
+        const next = existing
+            ? { ...existing, [key]: existing[key] + 1, lastTouchedTs: ts }
+            : { ...zeroedCounters(), firstSeenTs: ts, [key]: 1, lastTouchedTs: ts };
+        file.skills[name] = next;
+        writeAtomic(path, file);
+        // `file` is the cached reference — mutation above already updated the
+        // cache. Reassert here in case `loadUsage` had returned a fresh disk read
+        // (cold cache miss) so a subsequent loadUsage call gets the post-write
+        // state without going through disk again.
+        usageCacheByPath.set(path, file);
+        return next;
+    });
+}
+/** Bump `viewCount` for `name`. Called from `skill_view` after a successful body load. */
+export function bumpView(name, path) {
+    return bump(name, "viewCount", path);
+}
+/** Bump `useCount` for `name`. Reserved for future call-site instrumentation. */
+export function bumpUse(name, path) {
+    return bump(name, "useCount", path);
+}
+/** Bump `patchCount` for `name`. Reserved for the future `skill_edit` builtin. */
+export function bumpPatch(name, path) {
+    return bump(name, "patchCount", path);
+}
+/** 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 function __resetForTests() {
+    queuesByPath.clear();
+    usageCacheByPath.clear();
+}
+//# sourceMappingURL=usage.js.map

package/dist/skills/usage.js.map

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

package/dist/state/todos.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-session todo list backing TodoWrite.
+ *
+ * The model gets a single `todo_write` tool to upsert / mutate the list. There
+ * is no `todo_list` tool — read-side surfaces via the per-turn system
+ * reminder, which keeps the model from juggling two near-identical tools
+ * (and saves a per-turn round-trip for what is fundamentally a snapshot view).
+ *
+ * Persistence: one JSON file at `~/.maestro/sessions/<sid>.todos.json` — a
+ * snapshot of the current list, atomically written. Not JSONL: `todo_write`
+ * semantically OVERWRITES the list each call, so an append-only stream
+ * would accumulate dead entries the loader has to filter. A single JSON
+ * snapshot matches the actual semantics and is cheaper to read.
+ *
+ * Lifecycle:
+ *   - `getTodoStore(sid)` lazy-creates the store and hydrates from disk if
+ *     a prior turn wrote one.
+ *   - `dropTodoStore(sid)` is called from `deleteMaestroSession` and
+ *     `cleanupStaleMaestroSessions` (same pattern as `file-state.ts`) so the
+ *     module-level map can't outlive its sessions.
+ *
+ * Invariants enforced at upsert time:
+ *   - At most one entry is `in_progress`. Setting a second one to
+ *     `in_progress` flips any prior one to `pending` and warns the caller
+ *     via the tool result. Mirrors Claude Code's TodoWrite contract.
+ *   - IDs are auto-assigned (`task-1`, `task-2`, …) when omitted. Short IDs
+ *     so the model can refer back to them in prose without bloat.
+ */
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export interface TodoEntry {
+    id: string;
+    content: string;
+    status: TodoStatus;
+    /** Optional present-continuous form for spinner/status display
+     *  ("Reading config" vs the imperative "Read config"). */
+    activeForm?: string;
+}
+export interface TodoUpsert {
+    id?: string;
+    content: string;
+    status: TodoStatus;
+    activeForm?: string;
+}
+export interface UpsertResult {
+    todos: TodoEntry[];
+    /** Set when the upsert had to flip a prior in_progress to pending to
+     *  enforce the 1-in-progress invariant. The tool surfaces this in its
+     *  result so the model knows the previously-active item was bumped. */
+    demotedId?: string;
+}
+export declare class TodoStore {
+    private readonly path;
+    private todos;
+    private nextCounter;
+    constructor(path: string);
+    /** Read the current list. Caller must not mutate. */
+    list(): readonly TodoEntry[];
+    /** True when the list is empty (no in-flight or pending work). */
+    isEmpty(): boolean;
+    /**
+     * Replace / upsert the entire list. Entries with an `id` that matches an
+     * existing one update that entry; entries without an id (or with an id
+     * not in the current list) become new entries with an auto-assigned id.
+     *
+     * The shape mirrors Claude Code's TodoWrite: the model passes a complete
+     * snapshot of "what I want the list to look like now," and we reconcile.
+     * That means an existing id NOT included in the incoming snapshot is
+     * dropped — TodoWrite is a snapshot replace, not a partial update.
+     *
+     * Returns `{todos, demotedId?}` so the tool can tell the model exactly
+     * what landed (incl. any in-progress demotion).
+     */
+    upsert(incoming: TodoUpsert[]): UpsertResult;
+    /** Drop the on-disk file. Called by deleteMaestroSession via dropTodoStore. */
+    unlinkFile(): void;
+    /** Test-only: snapshot the path the store is backed by. */
+    __path(): string;
+    private nextId;
+    private hydrate;
+    /** Recover the counter from existing IDs when the file lacked the field
+     *  (defensive — recent hydrate writes always include it). */
+    private deriveCounter;
+    private persist;
+}
+/** Resolve the absolute todos-file path for a session. Mirrors
+ *  `maestroSessionPath` but with `.todos.json` instead of `.jsonl`. */
+export declare function todosPathFor(sessionId: string): string;
+export declare function getTodoStore(sessionId: string): TodoStore;
+/** Drop a session's store + unlink its on-disk file. */
+export declare function dropTodoStore(sessionId: string): void;
+/** Test-only. Reset every store. */
+export declare function __resetAllStores(): void;
+/** Test-only. Count of currently-tracked sessions. */
+export declare function __storeCount(): number;
+//# sourceMappingURL=todos.d.ts.map

package/dist/state/todos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todos.d.ts","sourceRoot":"","sources":["../../src/state/todos.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB;8DAC0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AASD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;2EAEuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,WAAW,CAAK;gBAEK,IAAI,EAAE,MAAM;IAIzC,qDAAqD;IACrD,IAAI,IAAI,SAAS,SAAS,EAAE;IAI5B,kEAAkE;IAClE,OAAO,IAAI,OAAO;IAIlB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,YAAY;IAwC5C,+EAA+E;IAC/E,UAAU,IAAI,IAAI;IAUlB,2DAA2D;IAC3D,MAAM,IAAI,MAAM;IAMhB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,OAAO;IAgBf;iEAC6D;IAC7D,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,OAAO;CAQhB;AAqBD;uEACuE;AACvE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAeD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAOzD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,sDAAsD;AACtD,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/state/todos.js

@@ -0,0 +1,198 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { logger } from "../platform/logger.js";
+/** Mirror of `maestroSessionsDir()` from session-store.ts — inlined here to
+ *  avoid a circular import (session-store.ts needs to call
+ *  `dropTodoStore` for cleanup). Two single-line copies are cheaper than
+ *  extracting a shared util file for one path. */
+function sessionsDir() {
+    return join(homedir(), ".maestro", "sessions");
+}
+export class TodoStore {
+    path;
+    todos = [];
+    nextCounter = 1;
+    constructor(path) {
+        this.path = path;
+        this.hydrate();
+    }
+    /** Read the current list. Caller must not mutate. */
+    list() {
+        return this.todos;
+    }
+    /** True when the list is empty (no in-flight or pending work). */
+    isEmpty() {
+        return this.todos.length === 0;
+    }
+    /**
+     * Replace / upsert the entire list. Entries with an `id` that matches an
+     * existing one update that entry; entries without an id (or with an id
+     * not in the current list) become new entries with an auto-assigned id.
+     *
+     * The shape mirrors Claude Code's TodoWrite: the model passes a complete
+     * snapshot of "what I want the list to look like now," and we reconcile.
+     * That means an existing id NOT included in the incoming snapshot is
+     * dropped — TodoWrite is a snapshot replace, not a partial update.
+     *
+     * Returns `{todos, demotedId?}` so the tool can tell the model exactly
+     * what landed (incl. any in-progress demotion).
+     */
+    upsert(incoming) {
+        const out = [];
+        let demotedId;
+        // First pass: build the new list, assigning IDs to entries that need
+        // them. We do this BEFORE the 1-in-progress sweep so the auto-IDs are
+        // available for the warning message.
+        for (const item of incoming) {
+            const id = item.id?.trim() || this.nextId();
+            out.push({
+                id,
+                content: item.content,
+                status: item.status,
+                ...(item.activeForm ? { activeForm: item.activeForm } : {}),
+            });
+        }
+        // Second pass: enforce 1-in-progress. Walk in incoming order; the LAST
+        // in_progress wins (mirrors how a model batch-updates and the final
+        // entry expresses current intent). Earlier in_progress entries are
+        // flipped to pending and surfaced via `demotedId`.
+        let lastInProgressIdx = -1;
+        for (let i = 0; i < out.length; i++) {
+            if (out[i].status === "in_progress")
+                lastInProgressIdx = i;
+        }
+        if (lastInProgressIdx >= 0) {
+            for (let i = 0; i < out.length; i++) {
+                if (i === lastInProgressIdx)
+                    continue;
+                if (out[i].status === "in_progress") {
+                    out[i] = { ...out[i], status: "pending" };
+                    demotedId = out[i].id;
+                }
+            }
+        }
+        this.todos = out;
+        this.persist();
+        return demotedId !== undefined ? { todos: out, demotedId } : { todos: out };
+    }
+    /** Drop the on-disk file. Called by deleteMaestroSession via dropTodoStore. */
+    unlinkFile() {
+        try {
+            unlinkSync(this.path);
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT") {
+                logger.warn({ err: e, path: this.path }, "TodoStore.unlinkFile failed");
+            }
+        }
+    }
+    /** Test-only: snapshot the path the store is backed by. */
+    __path() {
+        return this.path;
+    }
+    // --- internals ---------------------------------------------------------
+    nextId() {
+        const id = `task-${this.nextCounter}`;
+        this.nextCounter++;
+        return id;
+    }
+    hydrate() {
+        if (!existsSync(this.path))
+            return;
+        try {
+            const raw = readFileSync(this.path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== 1 || !Array.isArray(parsed.todos)) {
+                logger.warn({ path: this.path }, "TodoStore.hydrate: unsupported schema, ignoring");
+                return;
+            }
+            this.todos = parsed.todos.filter(isWellFormedEntry);
+            this.nextCounter = Math.max(1, parsed.nextCounter ?? this.deriveCounter());
+        }
+        catch (e) {
+            logger.warn({ err: e, path: this.path }, "TodoStore.hydrate: parse failed, starting empty");
+        }
+    }
+    /** Recover the counter from existing IDs when the file lacked the field
+     *  (defensive — recent hydrate writes always include it). */
+    deriveCounter() {
+        let max = 0;
+        for (const t of this.todos) {
+            const m = /^task-(\d+)$/.exec(t.id);
+            if (m)
+                max = Math.max(max, Number.parseInt(m[1], 10));
+        }
+        return max + 1;
+    }
+    persist() {
+        const file = {
+            version: 1,
+            nextCounter: this.nextCounter,
+            todos: this.todos,
+        };
+        writeAtomic(this.path, file);
+    }
+}
+/** Atomic write: tmp → rename. Same pattern as skills/usage.ts. */
+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);
+}
+function isWellFormedEntry(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    if (typeof o.id !== "string" || typeof o.content !== "string")
+        return false;
+    if (o.status !== "pending" && o.status !== "in_progress" && o.status !== "completed") {
+        return false;
+    }
+    if (o.activeForm !== undefined && typeof o.activeForm !== "string")
+        return false;
+    return true;
+}
+/** Resolve the absolute todos-file path for a session. Mirrors
+ *  `maestroSessionPath` but with `.todos.json` instead of `.jsonl`. */
+export function todosPathFor(sessionId) {
+    return join(sessionsDir(), `${sessionId}.todos.json`);
+}
+/**
+ * Module-level registry — same pattern as `file-state.ts`.
+ *
+ * The maestroProvider rebuilds tools each turn but the sessionId persists
+ * across turns. A registry-local store would re-hydrate every turn (cheap
+ * but wasteful); a module-level cache keeps the in-memory list hot.
+ *
+ * Cleanup is wired into `deleteMaestroSession` and
+ * `cleanupStaleMaestroSessions` (see session-store.ts) so the map can't
+ * outlive its sessions.
+ */
+const stores = new Map();
+export function getTodoStore(sessionId) {
+    let s = stores.get(sessionId);
+    if (!s) {
+        s = new TodoStore(todosPathFor(sessionId));
+        stores.set(sessionId, s);
+    }
+    return s;
+}
+/** Drop a session's store + unlink its on-disk file. */
+export function dropTodoStore(sessionId) {
+    const s = stores.get(sessionId);
+    if (s) {
+        s.unlinkFile();
+        stores.delete(sessionId);
+    }
+}
+/** Test-only. Reset every store. */
+export function __resetAllStores() {
+    stores.clear();
+}
+/** Test-only. Count of currently-tracked sessions. */
+export function __storeCount() {
+    return stores.size;
+}
+//# sourceMappingURL=todos.js.map

package/dist/state/todos.js.map

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

package/dist/storage/conversations.d.ts

@@ -0,0 +1,28 @@
+import type { AgentKind, UnifiedEvent } from "../types.js";
+/**
+ * Provider-agnostic conversation entry.
+ *
+ * The SDK does **not** persist conversations itself — that's the host's job.
+ * This interface is exposed so hosts can hand the SDK a back-fill of past
+ * turns (`registry.forkSession` rehydrates from this shape) and so SDK
+ * code that needs to encode/decode rollout entries shares a single type.
+ */
+export interface ConversationEntry {
+    /** ISO timestamp the event was recorded. */
+    ts: string;
+    /** Agent that produced this event, frozen at write time. */
+    agent: AgentKind;
+    /** Normalized event payload. */
+    event: UnifiedEvent;
+}
+/**
+ * Host-supplied callback that returns the conversation log for a session.
+ *
+ * The SDK calls this from `registry.forkSession()` when synthesizing a maestro
+ * rollout from cross-agent history. Hosts that don't need cross-agent
+ * bridging can leave the default (returns `[]`) in place.
+ */
+export type ConversationReader = (userId: number | string, topicName: string, groupId?: number) => ConversationEntry[];
+export declare function setConversationReader(reader: ConversationReader): void;
+export declare function readConversation(userId: number | string, topicName: string, groupId?: number): ConversationEntry[];
+//# sourceMappingURL=conversations.d.ts.map

package/dist/storage/conversations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../src/storage/conversations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,SAAS,CAAC;IACjB,gCAAgC;IAChC,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,KACb,iBAAiB,EAAE,CAAC;AAIzB,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAEtE;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,EAAE,CAErB"}

package/dist/storage/conversations.js

@@ -0,0 +1,8 @@
+let _reader = () => [];
+export function setConversationReader(reader) {
+    _reader = reader;
+}
+export function readConversation(userId, topicName, groupId) {
+    return _reader(userId, topicName, groupId);
+}
+//# sourceMappingURL=conversations.js.map

package/dist/storage/conversations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.js","sourceRoot":"","sources":["../../src/storage/conversations.ts"],"names":[],"mappings":"AAgCA,IAAI,OAAO,GAAuB,GAAG,EAAE,CAAC,EAAE,CAAC;AAE3C,MAAM,UAAU,qBAAqB,CAAC,MAA0B;IAC9D,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,MAAuB,EACvB,SAAiB,EACjB,OAAgB;IAEhB,OAAO,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC"}

package/dist/sub-agent/runner.d.ts

@@ -0,0 +1,78 @@
+import { loadSkillsCached, type SkillEntry } from "../skills/loader.js";
+import type { EffortLevel, TokenUsage } from "../types.js";
+/**
+ * Sub-agent runner — spawns a fresh maestro loop for a delegated task.
+ *
+ * Architecture decisions (advisor-reviewed):
+ *   - **No MCP in v1.** Sub-agents are scoped roles, not parent-lite. If
+ *     MCP-rich exploration is needed, the user spawns a new topic.
+ *   - **Inherit parent model + effort.** Uses `providerForModel()` to
+ *     select the correct provider (Anthropic / DeepSeek) based on parent
+ *     model. No override knob — keeps the model from picking a smaller
+ *     model "to save cost" and missing things.
+ *   - **Separate file-state tracker per sub-session.** Sharing the parent's
+ *     would break the Read-before-Edit invariant in both directions.
+ *   - **Inherit parent's systemPrompt + overlay.** Parent persona is the
+ *     base; the sub-agent prompt adds the "you are a sub-agent" role.
+ *   - **Hard JSONL cleanup on RETURN (success/failure).** NOT on abort —
+ *     a parent abort mid-sub-call leaves the JSONL for postmortem and
+ *     the 30-day TTL sweep eventually clears it.
+ *   - **Silent by default.** Parent's event stream only carries the Agent
+ *     tool's `tool_use` + final text. The sub-agent's text_deltas /
+ *     tool_uses are NOT forwarded to telegram.
+ *   - **depth=1 cap.** Sub-agents do NOT get the Agent tool — implicit
+ *     because runSubAgent doesn't register one in the child registry.
+ *     No recursion. Grandchildren require the parent to re-delegate.
+ */
+export type SubagentType = "general" | "explore";
+export interface RunSubAgentOptions {
+    subagentType: SubagentType;
+    /** Self-contained task brief. The sub-agent sees only this as the user
+     *  message. */
+    prompt: string;
+    /** Parent's resolved maestro sessionId. Used only for logging — the
+     *  sub-agent has its own freshly-minted session id. */
+    parentSessionId: string;
+    /** Parent's augmented systemPrompt (caller-prompt + skills index).
+     *  Used as the base layer of the sub-agent's prompt. */
+    parentSystemPrompt: string;
+    /** Parent's resolved model id (full, alias already expanded). */
+    parentModel: string;
+    /** Parent's effort level. Passed through to the provider (Anthropic:
+     *   thinking budget; DeepSeek: reasoning_effort). */
+    parentEffort?: EffortLevel;
+    /** Parent's abort signal. When the parent aborts, the sub-agent's
+     *  in-flight provider call cancels too. */
+    parentAbortSignal?: AbortSignal;
+    /** Pre-loaded skill catalog. Same set the parent sees. */
+    skills: SkillEntry[];
+}
+export interface RunSubAgentResult {
+    /** The sub-agent's final assistant text. This becomes the Agent tool's
+     *  return value to the parent model. */
+    text: string;
+    /** Accumulated usage across every API call the sub-agent made. */
+    usage: TokenUsage;
+    /** The sub-agent's own session id. Surfaced for diagnostics + so the
+     *  Agent tool can include it in the result text for traceability. */
+    subSessionId: string;
+    /** True when the parent's abort signal fired mid-execution. */
+    aborted: boolean;
+}
+/**
+ * Run a sub-agent to completion. Returns its final text + accumulated
+ * usage; the caller (Agent tool) decides how to surface that to the
+ * parent model.
+ *
+ * Cleanup contract (load-bearing):
+ *   - Clean drain or thrown error → `deleteMaestroSession(subSessionId)`
+ *     in the finally block. Frees the JSONL + file-state tracker + (any)
+ *     todo store for this sub-session.
+ *   - Abort → leave JSONL on disk. The 30-day TTL sweep will eventually
+ *     clear it; meanwhile it's available for postmortem.
+ */
+export declare function runSubAgent(opts: RunSubAgentOptions): Promise<RunSubAgentResult>;
+/** Convenience re-export for test setup — lets tests prime the loaded
+ *  catalog without re-fetching from disk. */
+export { loadSkillsCached };
+//# sourceMappingURL=runner.d.ts.map

package/dist/sub-agent/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/sub-agent/runner.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAWpE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B;mBACe;IACf,MAAM,EAAE,MAAM,CAAC;IACf;2DACuD;IACvD,eAAe,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;yDACqD;IACrD,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B;+CAC2C;IAC3C,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC,0DAA0D;IAC1D,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC;4CACwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,UAAU,CAAC;IAClB;yEACqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;CAClB;AAyED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+GtF;AAgBD;6CAC6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,CAAC"}