maestro-agent-sdk 0.1.0

package/dist/sub-agent/runner.js

@@ -0,0 +1,215 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AIAgent } from "../core/agent.js";
+import { runConversation } from "../core/loop.js";
+import { buildSystemReminder } from "../memory/reminder.js";
+import { effortToThinkingBudget } from "../providers/anthropic.js";
+import { providerForModel } from "../provider.js";
+import { deleteMaestroSession } from "../session-store.js";
+import { loadSkillsCached } from "../skills/loader.js";
+import { bashTool } from "../tools/builtin/bash.js";
+import { createEditTool } from "../tools/builtin/edit.js";
+import { createReadTool } from "../tools/builtin/read.js";
+import { createSkillViewTool } from "../tools/builtin/skill_view.js";
+import { webFetchTool } from "../tools/builtin/web_fetch.js";
+import { createWriteTool } from "../tools/builtin/write.js";
+import { getFileStateTracker } from "../tools/file-state.js";
+import { createSandboxFsHook } from "../tools/hooks/sandbox-fs.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { logger } from "../platform/logger.js";
+/** Hard cap on the sub-agent's per-API-call max output tokens. Defaults
+ *  to 4096 (same as parent's default in AIAgent.config). Env-override for
+ *  large delegated reports. */
+function resolveMaxTokens() {
+    const env = process.env.MAESTRO_SUBAGENT_MAX_TOKENS;
+    if (env) {
+        const n = Number.parseInt(env, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 4096;
+}
+/** Where the sub-agent overlay prompts live on disk. Co-located with the
+ *  other prompt resources under `src/prompts/`. Resolved via `fileURLToPath`
+ *  for Node compatibility (clawgram's Bun build used `import.meta.dir`). */
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OVERLAY_DIR = join(__dirname, "..", "prompts", "sub-agents");
+function loadOverlay(kind) {
+    const path = join(OVERLAY_DIR, `${kind}.md`);
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (e) {
+        // Fall back to a tiny inline reminder so a missing prompt file doesn't
+        // crash the whole call. The sub-agent will still know it's scoped.
+        logger.warn({ err: e, path }, "runSubAgent: overlay file missing, using fallback");
+        return "You are a focused sub-agent. Return one final text answer to the parent.";
+    }
+}
+/**
+ * Build the per-subagent-type tool registry.
+ *
+ * `general` — bash + Read + Write + Edit + WebFetch + skill_view.
+ * `explore` — Read + WebFetch + skill_view only. NO bash, write, edit —
+ *             the role is read-only by construction.
+ *
+ * Both types share the same sandbox-fs hook. Neither registers `Agent`
+ * (recursion cap) or `todo_write` (sub-agents don't plan iteratively).
+ */
+function buildToolRegistry(kind, subSessionId, skills, abortSignal) {
+    void abortSignal; // reserved for future bash abort wiring
+    const tools = new ToolRegistry();
+    tools.use(createSandboxFsHook());
+    // Sub-agent's OWN file-state tracker — keyed off subSessionId, NOT the
+    // parent's. Sharing would mean the parent's Read could let the sub-agent
+    // skip Read-before-Edit (or vice-versa), defeating the invariant.
+    const fileTracker = getFileStateTracker(subSessionId);
+    tools.register(createReadTool({ tracker: fileTracker }));
+    tools.register(webFetchTool);
+    if (skills.length > 0) {
+        tools.register(createSkillViewTool({ skills, sessionId: subSessionId }));
+    }
+    if (kind === "general") {
+        tools.register(bashTool);
+        tools.register(createWriteTool({ tracker: fileTracker }));
+        tools.register(createEditTool({ tracker: fileTracker }));
+    }
+    // `explore` stops here — read-only.
+    return tools;
+}
+/**
+ * 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 async function runSubAgent(opts) {
+    const subSessionId = randomUUID();
+    let provider;
+    try {
+        provider = providerForModel(opts.parentModel);
+    }
+    catch (e) {
+        return {
+            text: `[sub-agent failed to start: ${e instanceof Error ? e.message : String(e)}]`,
+            usage: { inputTokens: 0, outputTokens: 0 },
+            subSessionId,
+            aborted: false,
+        };
+    }
+    const tools = buildToolRegistry(opts.subagentType, subSessionId, opts.skills, opts.parentAbortSignal);
+    const overlay = loadOverlay(opts.subagentType);
+    const systemPrompt = `${opts.parentSystemPrompt}\n\n${overlay}`;
+    const maxTokens = resolveMaxTokens();
+    const thinkingBudget = opts.parentEffort ? effortToThinkingBudget(opts.parentEffort) : undefined;
+    // Sub-agent's user message follows the parent contract: prompt + own
+    // system reminder. The reminder reflects the SUB-SESSION's state
+    // (its own session id), not the parent's.
+    const reminderText = buildSystemReminder({ sessionId: subSessionId });
+    const userBlocks = [
+        { type: "text", text: opts.prompt },
+        { type: "text", text: reminderText },
+    ];
+    const messages = [{ role: "user", content: userBlocks }];
+    const agent = new AIAgent(provider, tools, {
+        model: opts.parentModel,
+        systemPrompt,
+        maxTokens,
+        ...(thinkingBudget ? { thinkingBudget } : {}),
+        ...(opts.parentEffort ? { effort: opts.parentEffort } : {}),
+        ...(opts.parentAbortSignal ? { abortSignal: opts.parentAbortSignal } : {}),
+    });
+    logger.info({
+        parentSessionId: opts.parentSessionId,
+        subSessionId,
+        subagentType: opts.subagentType,
+        model: opts.parentModel,
+    }, "runSubAgent: starting");
+    let finalText = "";
+    let usage = { inputTokens: 0, outputTokens: 0 };
+    let aborted = false;
+    let crashed = false;
+    try {
+        for await (const event of runConversation(agent, messages)) {
+            // Silent-by-default: we only consume terminal events. text_deltas,
+            // tool_uses, tool_results all stay inside the sub-agent's loop.
+            if (event.type === "result") {
+                finalText = event.content;
+                if (event.usage)
+                    usage = event.usage;
+            }
+            else if (event.type === "error") {
+                // Surface as part of the final text so the parent sees the failure
+                // reason. The sub-agent's error event is its terminal state when
+                // it can't return a normal result.
+                finalText = finalText
+                    ? `${finalText}\n\n[sub-agent error: ${event.content}]`
+                    : `[sub-agent error: ${event.content}]`;
+            }
+        }
+    }
+    catch (e) {
+        if (isAbortError(e) || opts.parentAbortSignal?.aborted) {
+            aborted = true;
+        }
+        else {
+            crashed = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            finalText = finalText
+                ? `${finalText}\n\n[sub-agent crashed: ${msg}]`
+                : `[sub-agent crashed: ${msg}]`;
+        }
+    }
+    finally {
+        if (!aborted) {
+            // Clean drain OR provider-crashed: nuke the sub-session JSONL +
+            // in-memory caches. Aborts intentionally skip this so a parent
+            // interrupt leaves the JSONL for postmortem; the 30-day TTL sweep
+            // (cleanupStaleMaestroSessions) eventually clears it.
+            try {
+                deleteMaestroSession(subSessionId);
+            }
+            catch (e) {
+                logger.warn({ err: e, subSessionId }, "runSubAgent: cleanup failed");
+            }
+        }
+        logger.info({
+            parentSessionId: opts.parentSessionId,
+            subSessionId,
+            subagentType: opts.subagentType,
+            aborted,
+            crashed,
+            textLen: finalText.length,
+            usage,
+        }, "runSubAgent: finished");
+    }
+    return { text: finalText, usage, subSessionId, aborted };
+}
+/**
+ * Mirror of `maestroProvider`'s `isAbortError`. Inlined to avoid an extra
+ * import path and keep this module self-contained for the sub-agent
+ * boundary — the abort-shape detection is small and the runner is the
+ * only sub-agent caller in v1.
+ */
+function isAbortError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.name === "AbortError")
+        return true;
+    if (e.code === 20 || e.code === "ABORT_ERR")
+        return true;
+    return false;
+}
+/** Convenience re-export for test setup — lets tests prime the loaded
+ *  catalog without re-fetching from disk. */
+export { loadSkillsCached };
+//# sourceMappingURL=runner.js.map

package/dist/sub-agent/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/sub-agent/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAkE3C;;+BAE+B;AAC/B,SAAS,gBAAgB;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;IACpD,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACnC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;4EAE4E;AAC5E,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAEnE,SAAS,WAAW,CAAC,IAAkB;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,uEAAuE;QACvE,mEAAmE;QACnE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,mDAAmD,CAAC,CAAC;QACnF,OAAO,0EAA0E,CAAC;IACpF,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CACxB,IAAkB,EAClB,YAAoB,EACpB,MAAoB,EACpB,WAAyB;IAEzB,KAAK,WAAW,CAAC,CAAC,wCAAwC;IAC1D,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;IACjC,KAAK,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAEjC,uEAAuE;IACvE,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,WAAW,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAEtD,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IACzD,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC7B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACzB,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;QAC1D,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,oCAAoC;IAEpC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAwB;IACxD,MAAM,YAAY,GAAG,UAAU,EAAE,CAAC;IAClC,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO;YACL,IAAI,EAAE,+BAA+B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG;YAClF,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE;YAC1C,YAAY;YACZ,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,CAC7B,IAAI,CAAC,YAAY,EACjB,YAAY,EACZ,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,iBAAiB,CACvB,CAAC;IACF,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,kBAAkB,OAAO,OAAO,EAAE,CAAC;IAChE,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjG,qEAAqE;IACrE,iEAAiE;IACjE,0CAA0C;IAC1C,MAAM,YAAY,GAAG,mBAAmB,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;IACtE,MAAM,UAAU,GAA2B;QACzC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;QACnC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE;KACrC,CAAC;IACF,MAAM,QAAQ,GAAsB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAE5E,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE;QACzC,KAAK,EAAE,IAAI,CAAC,WAAW;QACvB,YAAY;QACZ,SAAS;QACT,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CACT;QACE,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,YAAY;QACZ,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,KAAK,EAAE,IAAI,CAAC,WAAW;KACxB,EACD,uBAAuB,CACxB,CAAC;IAEF,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,KAAK,GAAe,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC5D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC3D,mEAAmE;YACnE,gEAAgE;YAChE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5B,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC;gBAC1B,IAAI,KAAK,CAAC,KAAK;oBAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YACvC,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAClC,mEAAmE;gBACnE,iEAAiE;gBACjE,mCAAmC;gBACnC,SAAS,GAAG,SAAS;oBACnB,CAAC,CAAC,GAAG,SAAS,yBAAyB,KAAK,CAAC,OAAO,GAAG;oBACvD,CAAC,CAAC,qBAAqB,KAAK,CAAC,OAAO,GAAG,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,YAAY,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,iBAAiB,EAAE,OAAO,EAAE,CAAC;YACvD,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvD,SAAS,GAAG,SAAS;gBACnB,CAAC,CAAC,GAAG,SAAS,2BAA2B,GAAG,GAAG;gBAC/C,CAAC,CAAC,uBAAuB,GAAG,GAAG,CAAC;QACpC,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,gEAAgE;YAChE,+DAA+D;YAC/D,kEAAkE;YAClE,sDAAsD;YACtD,IAAI,CAAC;gBACH,oBAAoB,CAAC,YAAY,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,6BAA6B,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;QACD,MAAM,CAAC,IAAI,CACT;YACE,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,YAAY;YACZ,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO;YACP,OAAO;YACP,OAAO,EAAE,SAAS,CAAC,MAAM;YACzB,KAAK;SACN,EACD,uBAAuB,CACxB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,CAAC,GAAG,GAAyC,CAAC;IACpD,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,CAAC,CAAC,IAAI,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;6CAC6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/tools/builtin/agent.d.ts

@@ -0,0 +1,33 @@
+import { type RunSubAgentOptions } from "../../sub-agent/runner.js";
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * `Agent` builtin — spawn a focused sub-agent for one delegated task.
+ *
+ * Returns only the sub-agent's final text to the parent model — tool calls,
+ * intermediate text, and the sub-agent's own session id are not surfaced
+ * mid-stream. This is the same contract Claude Code's Task tool exposes.
+ *
+ * Two scoped types in v1:
+ *   - `general` — full builtin toolkit (bash + Read + Write + Edit +
+ *     WebFetch + skill_view). Use for self-contained units of work.
+ *   - `explore` — read-only (Read + WebFetch + skill_view). Use for
+ *     finding / surveying / reporting tasks where you don't want the
+ *     sub-agent mutating files by accident.
+ *
+ * `parallelSafe: false` — sub-agent invocation spawns a child loop with
+ * side effects (file writes for `general`, MCP-less Anthropic API calls
+ * for both). Running two in parallel would race the API rate limits + the
+ * shared file-state tracker registry.
+ *
+ * No `description` field on the schema (advisor): the model would either
+ * skip it or duplicate the prompt into it. We derive a log label from the
+ * prompt's first line internally.
+ */
+export interface AgentToolFactoryOptions {
+    /** Parent context the sub-agent inherits from. The runner uses these to
+     *  build the sub-agent's system prompt, model, abort signal, and skill
+     *  catalog — none of which the model needs to (or should) pass. */
+    parent: Pick<RunSubAgentOptions, "parentSessionId" | "parentSystemPrompt" | "parentModel" | "parentEffort" | "parentAbortSignal" | "skills">;
+}
+export declare function createAgentTool(opts: AgentToolFactoryOptions): ToolHandler;
+//# sourceMappingURL=agent.d.ts.map

package/dist/tools/builtin/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,uBAAuB;IACtC;;uEAEmE;IACnE,MAAM,EAAE,IAAI,CACV,kBAAkB,EAChB,iBAAiB,GACjB,oBAAoB,GACpB,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,QAAQ,CACX,CAAC;CACH;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,GAAG,WAAW,CAiF1E"}

package/dist/tools/builtin/agent.js

@@ -0,0 +1,76 @@
+import { runSubAgent, } from "../../sub-agent/runner.js";
+const VALID_TYPES = new Set(["general", "explore"]);
+export function createAgentTool(opts) {
+    return {
+        parallelSafe: false,
+        schema: {
+            name: "Agent",
+            description: "Spawn a focused sub-agent to do ONE delegated task and return its final text. " +
+                "The sub-agent has its own context — your tool calls, files-Read state, and todo list " +
+                "are NOT shared with it. Use `general` for self-contained work that may need bash/Write/Edit, " +
+                "and `explore` for read-only surveys (Read/WebFetch/skill_view only). " +
+                "The sub-agent cannot spawn its own sub-agents (no recursion). Pass a self-contained " +
+                "prompt — the sub-agent sees ONLY that prompt and the inherited system context.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    subagent_type: {
+                        type: "string",
+                        description: "Sub-agent role. 'general' = full builtin toolkit. 'explore' = read-only " +
+                            "(Read/WebFetch/skill_view only — no bash, no write, no edit).",
+                    },
+                    prompt: {
+                        type: "string",
+                        description: "Self-contained task brief. The sub-agent sees ONLY this text as its initial " +
+                            "user message. State the goal, any constraints, and what 'done' looks like.",
+                    },
+                },
+                required: ["subagent_type", "prompt"],
+            },
+        },
+        async execute(input) {
+            const subagentTypeRaw = input.subagent_type;
+            const prompt = input.prompt;
+            if (typeof subagentTypeRaw !== "string" ||
+                !VALID_TYPES.has(subagentTypeRaw)) {
+                return JSON.stringify({
+                    error: `Agent: subagent_type must be one of ${Array.from(VALID_TYPES).join(", ")}, got '${subagentTypeRaw}'`,
+                });
+            }
+            if (typeof prompt !== "string" || prompt.trim().length === 0) {
+                return JSON.stringify({
+                    error: "Agent: prompt must be a non-empty string",
+                });
+            }
+            const subagentType = subagentTypeRaw;
+            const result = await runSubAgent({
+                subagentType,
+                prompt,
+                parentSessionId: opts.parent.parentSessionId,
+                parentSystemPrompt: opts.parent.parentSystemPrompt,
+                parentModel: opts.parent.parentModel,
+                ...(opts.parent.parentEffort ? { parentEffort: opts.parent.parentEffort } : {}),
+                ...(opts.parent.parentAbortSignal
+                    ? { parentAbortSignal: opts.parent.parentAbortSignal }
+                    : {}),
+                skills: opts.parent.skills,
+            });
+            if (result.aborted) {
+                // Aborted sub-agent: don't pretend a normal result. The parent
+                // model's next turn (if any) sees this and can decide.
+                return JSON.stringify({
+                    error: "Agent: sub-agent was aborted (parent abort signal fired)",
+                    subSessionId: result.subSessionId,
+                });
+            }
+            // Final text + a one-line provenance footer the model can use to
+            // attribute facts ("from the explore sub-agent: ...") and so the
+            // unified conversation log carries traceability without needing a
+            // separate event type. Usage is included for cost transparency.
+            const footer = `\n\n— end of ${subagentType} sub-agent (${result.subSessionId.slice(0, 8)}) — ` +
+                `${result.usage.inputTokens} in / ${result.usage.outputTokens} out`;
+            return `${result.text}${footer}`;
+        },
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/tools/builtin/agent.js.map

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

package/dist/tools/builtin/bash.d.ts

@@ -0,0 +1,11 @@
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * Bash tool — PoC for Phase 1.
+ *
+ * Minimal: shell out, capture stdout/stderr, enforce a 30s timeout and a
+ * 16KB output cap. NOT a long-term solution — Phase 5 will replace this with
+ * an adapter to Clawgram's MCP terminal tool so the Maestro loop inherits
+ * Clawgram's permission system instead of having an unguarded subprocess.
+ */
+export declare const bashTool: ToolHandler;
+//# sourceMappingURL=bash.d.ts.map

package/dist/tools/builtin/bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/bash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,WAmFtB,CAAC"}

package/dist/tools/builtin/bash.js

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+const BASH_TIMEOUT_MS = 30_000;
+const BASH_MAX_OUTPUT = 16_000;
+/**
+ * Bash tool — PoC for Phase 1.
+ *
+ * Minimal: shell out, capture stdout/stderr, enforce a 30s timeout and a
+ * 16KB output cap. NOT a long-term solution — Phase 5 will replace this with
+ * an adapter to Clawgram's MCP terminal tool so the Maestro loop inherits
+ * Clawgram's permission system instead of having an unguarded subprocess.
+ */
+export const bashTool = {
+    schema: {
+        name: "bash",
+        description: "Execute a bash command and return stdout/stderr. 30s timeout, 16KB output cap.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Bash command to execute",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Working directory (optional)",
+                },
+            },
+            required: ["command"],
+        },
+    },
+    async execute(input) {
+        const command = String(input.command ?? "");
+        if (!command.trim()) {
+            return JSON.stringify({ error: "empty command" });
+        }
+        const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
+        return new Promise((resolve) => {
+            const child = spawn("bash", ["-c", command], {
+                ...(cwd ? { cwd } : {}),
+                env: process.env,
+            });
+            let stdout = "";
+            let stderr = "";
+            let truncated = false;
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolve(JSON.stringify({
+                    error: `timeout after ${BASH_TIMEOUT_MS}ms`,
+                    stdout,
+                    stderr,
+                }));
+            }, BASH_TIMEOUT_MS);
+            child.stdout?.on("data", (chunk) => {
+                const text = chunk.toString("utf-8");
+                if (stdout.length + text.length > BASH_MAX_OUTPUT) {
+                    stdout += text.slice(0, BASH_MAX_OUTPUT - stdout.length);
+                    truncated = true;
+                    child.stdout?.destroy();
+                }
+                else {
+                    stdout += text;
+                }
+            });
+            child.stderr?.on("data", (chunk) => {
+                const text = chunk.toString("utf-8");
+                if (stderr.length + text.length > BASH_MAX_OUTPUT) {
+                    stderr += text.slice(0, BASH_MAX_OUTPUT - stderr.length);
+                    truncated = true;
+                    child.stderr?.destroy();
+                }
+                else {
+                    stderr += text;
+                }
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                resolve(JSON.stringify({
+                    exitCode: code,
+                    stdout,
+                    stderr,
+                    ...(truncated ? { truncated: true } : {}),
+                }));
+            });
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                resolve(JSON.stringify({ error: err.message }));
+            });
+        });
+    },
+};
+//# sourceMappingURL=bash.js.map

package/dist/tools/builtin/bash.js.map

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

package/dist/tools/builtin/edit.d.ts

@@ -0,0 +1,21 @@
+import type { FileStateTracker } from "../../tools/file-state.js";
+import type { ToolHandler } from "../../tools/registry.js";
+export interface EditToolOptions {
+    /**
+     * Per-session file-state tracker. When provided, Edit enforces the
+     * Read-before-Edit invariant: the path must have been Read in this session
+     * AND its mtime/size must still match the recorded values.
+     */
+    tracker?: FileStateTracker;
+}
+export declare function createEditTool(opts?: EditToolOptions): ToolHandler;
+/** Backwards-compatible singleton (no tracker — Read-before-Edit gate off). */
+export declare const editTool: ToolHandler;
+/**
+ * Count non-overlapping occurrences of `needle` in `haystack`. We use this
+ * to drive the unique-match check; `indexOf` in a loop is fast enough for
+ * the 10MB cap and avoids the regex escaping the model would have to do.
+ */
+export declare function countOccurrences(haystack: string, needle: string): number;
+export declare const __MAX_FILE_BYTES: number;
+//# sourceMappingURL=edit.d.ts.map

package/dist/tools/builtin/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/edit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAqCpD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,WAAW,CA4JtE;AAED,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,EAAE,WAA8B,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUzE;AAqCD,eAAO,MAAM,gBAAgB,QAAiB,CAAC"}