maestro-agent-sdk 0.1.0

package/dist/memory/reminder.js

@@ -0,0 +1,57 @@
+import { isSandboxEnabled } from "../tools/builtin/sandbox.js";
+import { WORKSPACE_DIR } from "../platform/config.js";
+/**
+ * Build the `<system-reminder>` block. Returns a self-contained string that
+ * callers attach verbatim as a `text` content block on a user message.
+ *
+ * Empty extras + sandbox-enabled (default) state renders to ~3 lines so
+ * the per-turn token cost is bounded; the catalog of facts only grows as
+ * later phases add semantic state (Phase 3.2 task list, etc.).
+ */
+export function buildSystemReminder(ctx) {
+    const lines = ["<system-reminder>"];
+    // Sandbox state — the model needs to know whether file paths outside
+    // WORKSPACE_DIR will be rejected, so it can either prefix paths correctly
+    // or pre-emptively flag the limitation when the user asks for an
+    // out-of-workspace operation. Default is unsandboxed (parity with
+    // claude/codex providers); the operator opts in by exporting
+    // `MAESTRO_FS_SANDBOX_ENABLED=1`.
+    if (isSandboxEnabled()) {
+        lines.push(`Filesystem sandbox: enabled. Allowed root: ${WORKSPACE_DIR}`);
+        lines.push("  Paths outside this root will be rejected by Read/Write/Edit. " +
+            "Prefer relative-to-workspace paths.");
+    }
+    else {
+        lines.push("Filesystem sandbox: disabled (any absolute path may be read/written).");
+    }
+    // Session id — emitted so cross-session tools (ask_session, tell_session,
+    // fork helpers) have a stable handle to reference without round-tripping.
+    lines.push(`Session: ${ctx.sessionId}`);
+    // TodoWrite read-side: render the current list (if any) so the model
+    // doesn't need a `todo_list` tool. Compact one-line-per-entry format
+    // tracks `[✓/→/ ] task-N  content` — matches the tool result preview
+    // so the model sees the same shape it wrote.
+    if (ctx.todos && ctx.todos.length > 0) {
+        lines.push(`Task list (${todoSummaryCount(ctx.todos)}):`);
+        for (const t of ctx.todos) {
+            const mark = t.status === "completed" ? "✓" : t.status === "in_progress" ? "→" : " ";
+            lines.push(`  [${mark}] ${t.id}  ${t.content}`);
+        }
+        lines.push("Update this list with `todo_write` whenever you start a step, finish one, " +
+            "or change the plan. Only ONE item may be in_progress at a time.");
+    }
+    // Caller-supplied tail. Each extra is one line — caller owns formatting.
+    for (const e of ctx.extras ?? []) {
+        if (e.length > 0)
+            lines.push(e);
+    }
+    lines.push("</system-reminder>");
+    return lines.join("\n");
+}
+/** Compact "3/5" style summary — completed over total. Used in the list
+ *  header so the model gets progress at a glance without re-counting. */
+function todoSummaryCount(todos) {
+    const done = todos.filter((t) => t.status === "completed").length;
+    return `${done}/${todos.length}`;
+}
+//# sourceMappingURL=reminder.js.map

package/dist/memory/reminder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder.js","sourceRoot":"","sources":["../../src/memory/reminder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAkDlD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAA0B;IAC5D,MAAM,KAAK,GAAa,CAAC,mBAAmB,CAAC,CAAC;IAE9C,qEAAqE;IACrE,0EAA0E;IAC1E,iEAAiE;IACjE,kEAAkE;IAClE,6DAA6D;IAC7D,kCAAkC;IAClC,IAAI,gBAAgB,EAAE,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,8CAA8C,aAAa,EAAE,CAAC,CAAC;QAC1E,KAAK,CAAC,IAAI,CACR,iEAAiE;YAC/D,qCAAqC,CACxC,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;IACtF,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAExC,qEAAqE;IACrE,qEAAqE;IACrE,qEAAqE;IACrE,6CAA6C;IAC7C,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,cAAc,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1D,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YACrF,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,KAAK,CAAC,IAAI,CACR,4EAA4E;YAC1E,iEAAiE,CACpE,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;yEACyE;AACzE,SAAS,gBAAgB,CAAC,KAA2B;IACnD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC;IAClE,OAAO,GAAG,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;AACnC,CAAC"}

package/dist/memory/scrubber.d.ts

@@ -0,0 +1,28 @@
+export declare class StreamingContextScrubber {
+    private state;
+    private readonly bufferCap;
+    /**
+     * Push a chunk of streamed text. Returns the bytes that should be
+     * emitted downstream (the unscrubbed part). Internal state advances so
+     * subsequent calls pick up where the last one left off.
+     *
+     * Safe on empty chunks (returns empty string).
+     */
+    feed(chunk: string): string;
+    /**
+     * Stream ended. Flush any safe-to-emit pending bytes. If we're still
+     * matching-open (the model said `<comp` and stopped), flush the buffered
+     * candidate (it wasn't a real marker after all). If we're inside a fence
+     * that never closed, drop the rest silently — better than leaking
+     * partial summary text.
+     */
+    finish(): string;
+}
+/**
+ * One-shot helper for non-streaming cases: scrub an entire string by
+ * feeding it through a scrubber and finishing. Used by the
+ * `text` (consolidated) UnifiedEvent emit at end-of-turn so non-streaming
+ * consumers (recorders, logs) also see the cleaned text.
+ */
+export declare function scrubString(input: string): string;
+//# sourceMappingURL=scrubber.d.ts.map

package/dist/memory/scrubber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrubber.d.ts","sourceRoot":"","sources":["../../src/memory/scrubber.ts"],"names":[],"mappings":"AAgFA,qBAAa,wBAAwB;IACnC,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAE5C;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAqE3B;;;;;;OAMG;IACH,MAAM,IAAI,MAAM;CAUjB;AAmBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/memory/scrubber.js

@@ -0,0 +1,147 @@
+import { COMPACTED_MARKER_CLOSE, COMPACTED_MARKER_OPEN, } from "../memory/active-task-template.js";
+/** Anthropic models occasionally surface their chain-of-thought as
+ *  literal `<thinking>...</thinking>` text in the assistant message body
+ *  (a pretrained pattern, separate from extended-thinking blocks which we
+ *  already keep server-side via the `thinking` content type). On telegram
+ *  this leaks raw reasoning the user explicitly asked to hide. Treat the
+ *  fence identically to compacted-history: drop entire block including
+ *  the markers. */
+const THINKING_MARKER_OPEN = "<thinking>";
+const THINKING_MARKER_CLOSE = "</thinking>";
+const MARKERS = [
+    { open: COMPACTED_MARKER_OPEN, close: COMPACTED_MARKER_CLOSE },
+    { open: THINKING_MARKER_OPEN, close: THINKING_MARKER_CLOSE },
+];
+/** Longest prefix of any open/close marker we might still be matching.
+ *  Tracked so we know how many trailing bytes to buffer (waiting for the
+ *  next chunk) vs. flush. */
+function maxMarkerLen() {
+    let m = 0;
+    for (const p of MARKERS) {
+        if (p.open.length > m)
+            m = p.open.length;
+        if (p.close.length > m)
+            m = p.close.length;
+    }
+    return m;
+}
+export class StreamingContextScrubber {
+    state = { kind: "outside" };
+    bufferCap = maxMarkerLen();
+    /**
+     * Push a chunk of streamed text. Returns the bytes that should be
+     * emitted downstream (the unscrubbed part). Internal state advances so
+     * subsequent calls pick up where the last one left off.
+     *
+     * Safe on empty chunks (returns empty string).
+     */
+    feed(chunk) {
+        if (!chunk)
+            return "";
+        let i = 0;
+        let out = "";
+        while (i < chunk.length) {
+            const remaining = chunk.slice(i);
+            if (this.state.kind === "outside") {
+                // Look for the earliest start-of-marker candidate in `remaining`.
+                const startIdx = findPossibleMarkerStart(remaining);
+                if (startIdx < 0) {
+                    // No partial marker — entire remaining is safe to emit.
+                    out += remaining;
+                    break;
+                }
+                // Emit everything before the candidate position.
+                out += remaining.slice(0, startIdx);
+                this.state = { kind: "matching-open", buffer: "" };
+                i += startIdx;
+                continue;
+            }
+            if (this.state.kind === "matching-open") {
+                this.state.buffer += remaining[0];
+                i++;
+                // Did we complete an open marker?
+                const match = MARKERS.find((m) => this.state.kind === "matching-open" && this.state.buffer === m.open);
+                if (match) {
+                    this.state = { kind: "inside", pending: match, buffer: "" };
+                    continue;
+                }
+                // Still a viable prefix of any open marker?
+                const isViable = MARKERS.some((m) => this.state.kind === "matching-open" && m.open.startsWith(this.state.buffer));
+                if (!isViable) {
+                    // False alarm — flush the buffered candidate and resume outside.
+                    out += this.state.buffer;
+                    this.state = { kind: "outside" };
+                    continue;
+                }
+                if (this.state.buffer.length >= this.bufferCap) {
+                    // Saturated without matching — flush and resume.
+                    out += this.state.buffer;
+                    this.state = { kind: "outside" };
+                }
+                continue;
+            }
+            // state.kind === "inside" — drop bytes until close marker found.
+            this.state.buffer += remaining[0];
+            i++;
+            const closeIdx = this.state.buffer.indexOf(this.state.pending.close);
+            if (closeIdx >= 0) {
+                // Consumed (and dropped) up to and including the close marker.
+                this.state = { kind: "outside" };
+                continue;
+            }
+            // Cap the inside buffer so a runaway (unclosed) fence doesn't grow
+            // forever — keep only the last `bufferCap` bytes (enough to detect
+            // the close marker spanning into the next chunk).
+            if (this.state.buffer.length > this.bufferCap) {
+                this.state.buffer = this.state.buffer.slice(-this.bufferCap);
+            }
+        }
+        return out;
+    }
+    /**
+     * Stream ended. Flush any safe-to-emit pending bytes. If we're still
+     * matching-open (the model said `<comp` and stopped), flush the buffered
+     * candidate (it wasn't a real marker after all). If we're inside a fence
+     * that never closed, drop the rest silently — better than leaking
+     * partial summary text.
+     */
+    finish() {
+        if (this.state.kind === "matching-open") {
+            const tail = this.state.buffer;
+            this.state = { kind: "outside" };
+            return tail;
+        }
+        // outside → nothing to flush. inside → drop.
+        this.state = { kind: "outside" };
+        return "";
+    }
+}
+/**
+ * Index of the earliest position in `text` where a marker open sequence
+ * COULD begin. Looks for the first character of any open marker. Returns
+ * -1 when none found. Cheap pre-filter so the scrubber only enters
+ * matching-open state when it has a real candidate.
+ */
+function findPossibleMarkerStart(text) {
+    // All current markers start with `<`. If new marker types are added with
+    // a different leading char, extend this set.
+    const candidates = new Set();
+    for (const m of MARKERS)
+        candidates.add(m.open[0]);
+    for (let i = 0; i < text.length; i++) {
+        if (candidates.has(text[i]))
+            return i;
+    }
+    return -1;
+}
+/**
+ * One-shot helper for non-streaming cases: scrub an entire string by
+ * feeding it through a scrubber and finishing. Used by the
+ * `text` (consolidated) UnifiedEvent emit at end-of-turn so non-streaming
+ * consumers (recorders, logs) also see the cleaned text.
+ */
+export function scrubString(input) {
+    const s = new StreamingContextScrubber();
+    return s.feed(input) + s.finish();
+}
+//# sourceMappingURL=scrubber.js.map

package/dist/memory/scrubber.js.map

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

package/dist/memory/token-estimate.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderContentBlock, ProviderMessage } from "../providers/base.js";
+/** Estimate tokens for a single content block. Unknown block types fall back
+ *  to the text rate since their wire encoding is JSON-ish. */
+export declare function estimateBlockTokens(block: ProviderContentBlock): number;
+/** Estimate tokens for one message. Includes a small overhead per message
+ *  for the role marker + JSON framing the API adds on the wire. */
+export declare function estimateMessageTokens(msg: ProviderMessage): number;
+/** Estimate total tokens for a message array. */
+export declare function estimateTokens(messages: readonly ProviderMessage[]): number;
+//# sourceMappingURL=token-estimate.d.ts.map

package/dist/memory/token-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimate.d.ts","sourceRoot":"","sources":["../../src/memory/token-estimate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA4B9E;8DAC8D;AAC9D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAuBvE;AAED;mEACmE;AACnE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAQlE;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAI3E"}

package/dist/memory/token-estimate.js

@@ -0,0 +1,69 @@
+/**
+ * Cheap token estimator for the maestro compaction trigger.
+ *
+ * We don't want a tokenizer dependency on the per-turn hot path — running a
+ * BPE encoder over every message before each provider call would cost more
+ * than the cache hit it saves. Instead we approximate token count by
+ * character length divided by a per-content-type factor, calibrated against
+ * Claude Sonnet 4 BPE empirics on representative dialogue:
+ *
+ *   plain text:        chars / 3.5   (English-leaning; CJK runs lower)
+ *   tool_use input:    chars / 4.0   (JSON literals compress further)
+ *   tool_result:       chars / 3.8   (mix of text + JSON)
+ *
+ * The estimator is intentionally biased **high** — over-counting triggers
+ * compaction slightly earlier than necessary, which is the safer failure
+ * mode (compacting a turn early is mildly wasteful; missing a compact and
+ * blowing past the context window is a hard 400 error).
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/agent/context_compressor.py`
+ * uses a similar char-based approximation when no tokenizer is plugged in.
+ */
+const CHARS_PER_TEXT_TOKEN = 3.5;
+const CHARS_PER_TOOL_USE_TOKEN = 4.0;
+const CHARS_PER_TOOL_RESULT_TOKEN = 3.8;
+/** Estimate tokens for a single content block. Unknown block types fall back
+ *  to the text rate since their wire encoding is JSON-ish. */
+export function estimateBlockTokens(block) {
+    switch (block.type) {
+        case "text":
+            return Math.ceil(block.text.length / CHARS_PER_TEXT_TOKEN);
+        case "tool_use": {
+            // name + JSON-stringified input. Don't pretty-print — the wire format
+            // is compact and that's what the API actually counts against the cap.
+            const len = block.name.length + JSON.stringify(block.input).length;
+            return Math.ceil(len / CHARS_PER_TOOL_USE_TOKEN);
+        }
+        case "tool_result": {
+            const content = typeof block.content === "string" ? block.content : JSON.stringify(block.content);
+            return Math.ceil(content.length / CHARS_PER_TOOL_RESULT_TOKEN);
+        }
+        default: {
+            // Defensive: unknown future block shapes (e.g. image). JSON-encode and
+            // charge the text rate. Better to over-count than to silently zero out
+            // a block we don't recognize.
+            const json = JSON.stringify(block);
+            return Math.ceil(json.length / CHARS_PER_TEXT_TOKEN);
+        }
+    }
+}
+/** Estimate tokens for one message. Includes a small overhead per message
+ *  for the role marker + JSON framing the API adds on the wire. */
+export function estimateMessageTokens(msg) {
+    const overhead = 4; // role + framing
+    if (typeof msg.content === "string") {
+        return overhead + Math.ceil(msg.content.length / CHARS_PER_TEXT_TOKEN);
+    }
+    let sum = overhead;
+    for (const block of msg.content)
+        sum += estimateBlockTokens(block);
+    return sum;
+}
+/** Estimate total tokens for a message array. */
+export function estimateTokens(messages) {
+    let sum = 0;
+    for (const msg of messages)
+        sum += estimateMessageTokens(msg);
+    return sum;
+}
+//# sourceMappingURL=token-estimate.js.map

package/dist/memory/token-estimate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimate.js","sourceRoot":"","sources":["../../src/memory/token-estimate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC;8DAC8D;AAC9D,MAAM,UAAU,mBAAmB,CAAC,KAA2B;IAC7D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;QAC7D,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,sEAAsE;YACtE,sEAAsE;YACtE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;YACnE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,wBAAwB,CAAC,CAAC;QACnD,CAAC;QACD,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,MAAM,OAAO,GACX,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACpF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,2BAA2B,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,uEAAuE;YACvE,uEAAuE;YACvE,8BAA8B;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;AACH,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,qBAAqB,CAAC,GAAoB;IACxD,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,iBAAiB;IACrC,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO;QAAE,GAAG,IAAI,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,QAAoC;IACjE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,GAAG,IAAI,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/platform/config.d.ts

@@ -0,0 +1,12 @@
+export declare const DATA_DIR: string;
+export declare const WORKSPACE_DIR: string;
+export declare const MODEL_HAIKU: string;
+export declare const MODEL_SONNET: string;
+export declare const MODEL_OPUS: string;
+export declare const MODEL_DEEPSEEK_V4_PRO: string;
+export declare const MODEL_DEEPSEEK_V4_FLASH: string;
+export declare const FILE_TAG_REGEX: RegExp;
+/** Returns `process.env` without `CLAUDECODE` so spawned subprocesses don't
+ *  inherit a nested-claude-code detection flag from a parent harness. */
+export declare function getCleanEnv(): NodeJS.ProcessEnv;
+//# sourceMappingURL=config.d.ts.map

package/dist/platform/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/platform/config.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,QAAQ,EAAE,MAEY,CAAC;AAEpC,eAAO,MAAM,aAAa,EAAE,MAEU,CAAC;AAEvC,eAAO,MAAM,WAAW,EAAE,MAC4C,CAAC;AAKvE,eAAO,MAAM,YAAY,EAAE,MAA4B,CAAC;AACxD,eAAO,MAAM,UAAU,EAAE,MAA0B,CAAC;AAGpD,eAAO,MAAM,qBAAqB,EAAE,MAA0B,CAAC;AAC/D,eAAO,MAAM,uBAAuB,EAAE,MAA4B,CAAC;AAEnE,eAAO,MAAM,cAAc,EAAE,MAAgC,CAAC;AAgB9D;yEACyE;AACzE,wBAAgB,WAAW,IAAI,MAAM,CAAC,UAAU,CAI/C"}

package/dist/platform/config.js

@@ -0,0 +1,54 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+/**
+ * SDK runtime configuration — replaces clawgram's bespoke `platform/config`.
+ *
+ * Values are resolved once at module load. Hosts that need non-default paths
+ * must set the corresponding env var (`MAESTRO_DATA_DIR`, `MAESTRO_WORKSPACE_DIR`,
+ * `MAESTRO_COMPRESSION_MODEL`) **before** importing any SDK module that
+ * depends on them.
+ *
+ * For per-call overrides, prefer `AgentQueryOptions.cwd` (filesystem root)
+ * and `AIAgentConfig.model` (compression model is wired through there too).
+ */
+const HOME = homedir();
+export const DATA_DIR = process.env.MAESTRO_DATA_DIR
+    ? resolve(process.env.MAESTRO_DATA_DIR)
+    : resolve(HOME, ".maestro-agent");
+export const WORKSPACE_DIR = process.env.MAESTRO_WORKSPACE_DIR
+    ? resolve(process.env.MAESTRO_WORKSPACE_DIR)
+    : resolve(HOME, "maestro-workspace");
+export const MODEL_HAIKU = process.env.MAESTRO_COMPRESSION_MODEL ?? "claude-haiku-4-5-20251001";
+// Canonical model IDs used by the SDK's maestro registry. Hosts can pick a
+// different default per-query via `AgentQueryOptions.model`, so these are
+// just baseline references.
+export const MODEL_SONNET = "claude-sonnet-4-6";
+export const MODEL_OPUS = "claude-opus-4-7";
+// DeepSeek V4 (released 2026-04-24). OpenAI-compatible chat-completions API.
+export const MODEL_DEEPSEEK_V4_PRO = "deepseek-v4-pro";
+export const MODEL_DEEPSEEK_V4_FLASH = "deepseek-v4-flash";
+export const FILE_TAG_REGEX = /\[FILE:(\/[^\]]+)\]/gi;
+// Make sure DATA_DIR and WORKSPACE_DIR exist before any tool/skill code tries
+// to mkdtemp/readdir into them. Idempotent and best-effort — hosts that point
+// these at read-only mount points should override before importing the SDK.
+try {
+    mkdirSync(DATA_DIR, { recursive: true });
+}
+catch {
+    // ignore — host may have pre-created with stricter perms
+}
+try {
+    mkdirSync(WORKSPACE_DIR, { recursive: true });
+}
+catch {
+    // ignore — host may have pre-created with stricter perms
+}
+/** Returns `process.env` without `CLAUDECODE` so spawned subprocesses don't
+ *  inherit a nested-claude-code detection flag from a parent harness. */
+export function getCleanEnv() {
+    const env = { ...process.env };
+    delete env.CLAUDECODE;
+    return env;
+}
+//# sourceMappingURL=config.js.map

package/dist/platform/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/platform/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;GAUG;AAEH,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;AAEvB,MAAM,CAAC,MAAM,QAAQ,GAAW,OAAO,CAAC,GAAG,CAAC,gBAAgB;IAC1D,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACvC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,aAAa,GAAW,OAAO,CAAC,GAAG,CAAC,qBAAqB;IACpE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC5C,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,WAAW,GACtB,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,2BAA2B,CAAC;AAEvE,2EAA2E;AAC3E,0EAA0E;AAC1E,4BAA4B;AAC5B,MAAM,CAAC,MAAM,YAAY,GAAW,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,UAAU,GAAW,iBAAiB,CAAC;AAEpD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,qBAAqB,GAAW,iBAAiB,CAAC;AAC/D,MAAM,CAAC,MAAM,uBAAuB,GAAW,mBAAmB,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAW,uBAAuB,CAAC;AAE9D,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,IAAI,CAAC;IACH,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC;AAAC,MAAM,CAAC;IACP,yDAAyD;AAC3D,CAAC;AACD,IAAI,CAAC;IACH,SAAS,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAAC,MAAM,CAAC;IACP,yDAAyD;AAC3D,CAAC;AAED;yEACyE;AACzE,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC/B,OAAO,GAAG,CAAC,UAAU,CAAC;IACtB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/platform/jsonl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrowed JSONL helpers for the SDK.
+ *
+ * Upstream clawgram exposes cross-process append locks via a sidecar
+ * `.lock` file and `Bun.sleepSync`. The SDK only ships single-process
+ * read/write helpers — the agent loop and session-store never share a
+ * JSONL file with another process — so the lock complexity (and Bun
+ * dependency) is dropped here.
+ */
+export declare function readJsonlLines(filePath: string): string[];
+export declare function parseJsonlText<T = unknown>(raw: string): T[];
+export declare function readJsonFile<T = unknown>(filePath: string): T | null;
+/** Overwrite a JSONL file atomically (write to temp, fsync, rename). */
+export declare function writeJsonlFile(filePath: string, entries: readonly unknown[]): void;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/platform/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/platform/jsonl.ts"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AAEH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAEzD;AAED,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,CAM5D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAMpE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CA2BlF"}

package/dist/platform/jsonl.js

@@ -0,0 +1,80 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Narrowed JSONL helpers for the SDK.
+ *
+ * Upstream clawgram exposes cross-process append locks via a sidecar
+ * `.lock` file and `Bun.sleepSync`. The SDK only ships single-process
+ * read/write helpers — the agent loop and session-store never share a
+ * JSONL file with another process — so the lock complexity (and Bun
+ * dependency) is dropped here.
+ */
+export function readJsonlLines(filePath) {
+    return readFileSync(filePath, "utf-8").trim().split("\n").filter(Boolean);
+}
+export function parseJsonlText(raw) {
+    return raw
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Overwrite a JSONL file atomically (write to temp, fsync, rename). */
+export function writeJsonlFile(filePath, entries) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(16)
+        .slice(2)}`;
+    const payload = `${entries.map((e) => JSON.stringify(e)).join("\n")}\n`;
+    let fd = null;
+    try {
+        fd = openSync(tmpPath, "w");
+        writeFileSync(fd, payload);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = null;
+        renameSync(tmpPath, filePath);
+        fsyncDirectoryBestEffort(dir);
+    }
+    catch (err) {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { }
+        }
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { }
+        throw err;
+    }
+}
+function fsyncDirectoryBestEffort(dir) {
+    let fd = null;
+    try {
+        fd = openSync(dir, "r");
+        fsyncSync(fd);
+    }
+    catch {
+        // Directory fsync is not portable across every runtime/filesystem.
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}
+//# sourceMappingURL=jsonl.js.map

package/dist/platform/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/platform/jsonl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;GAQG;AAEH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,cAAc,CAAc,GAAW;IACrD,OAAO,GAAG;SACP,IAAI,EAAE;SACN,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,YAAY,CAAc,QAAgB;IACxD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAM,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,OAA2B;IAC1E,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,GAAG,QAAQ,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE;SAC1E,QAAQ,CAAC,EAAE,CAAC;SACZ,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACd,MAAM,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxE,IAAI,EAAE,GAAkB,IAAI,CAAC;IAC7B,IAAI,CAAC;QACH,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC3B,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,EAAE,GAAG,IAAI,CAAC;QACV,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9B,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,SAAS,CAAC,EAAE,CAAC,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC;QACD,IAAI,CAAC;YACH,UAAU,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QACV,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAAC,GAAW;IAC3C,IAAI,EAAE,GAAkB,IAAI,CAAC;IAC7B,IAAI,CAAC;QACH,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxB,SAAS,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;YAAS,CAAC;QACT,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,SAAS,CAAC,EAAE,CAAC,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/platform/lifecycle.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared process-shutdown registry for SDK subsystems (MCP pool, sub-agents).
+ *
+ * Ported verbatim from clawgram. Modules call `onShutdown(name, priority, fn)`;
+ * the first SIGINT/SIGTERM/beforeExit drains them in descending priority order
+ * with a per-handler timeout and a hard exit ceiling.
+ *
+ * Priority convention (rough):
+ *   - 100+: stateful network/connection resources (MCP pool, DB conns).
+ *   - 50:   subsystems that kill external processes (subprocess pools).
+ *   - 10:   final reporting / metrics flushing.
+ */
+export interface ShutdownHandler {
+    name: string;
+    priority: number;
+    fn: () => Promise<void> | void;
+}
+export type SignalReason = "beforeExit" | "SIGINT" | "SIGTERM" | "test";
+export declare function onShutdown(name: string, priority: number, fn: () => Promise<void> | void): void;
+export declare function runShutdown(reason: SignalReason): Promise<void>;
+export declare function __resetForTests(): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/platform/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/platform/lifecycle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChC;AASD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAExE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAG/F;AAgBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCrE;AAED,wBAAgB,eAAe,IAAI,IAAI,CAItC"}

package/dist/platform/lifecycle.js

@@ -0,0 +1,60 @@
+import { logger } from "../platform/logger.js";
+const handlers = [];
+let signalHooksInstalled = false;
+let triggered = false;
+const HANDLER_TIMEOUT_MS = 5_000;
+const HARD_EXIT_TIMEOUT_MS = 15_000;
+export function onShutdown(name, priority, fn) {
+    handlers.push({ name, priority, fn });
+    ensureSignalHooks();
+}
+function ensureSignalHooks() {
+    if (signalHooksInstalled)
+        return;
+    signalHooksInstalled = true;
+    process.once("beforeExit", () => {
+        void runShutdown("beforeExit");
+    });
+    process.once("SIGINT", () => {
+        void runShutdown("SIGINT");
+    });
+    process.once("SIGTERM", () => {
+        void runShutdown("SIGTERM");
+    });
+}
+export async function runShutdown(reason) {
+    if (triggered)
+        return;
+    triggered = true;
+    logger.info({ reason, handlerCount: handlers.length }, "lifecycle: shutdown sequence starting");
+    const ordered = handlers
+        .map((h, i) => ({ h, i }))
+        .sort((a, b) => b.h.priority - a.h.priority || a.i - b.i)
+        .map(({ h }) => h);
+    const hardExit = setTimeout(() => {
+        logger.error({ reason }, "lifecycle: hard-exit ceiling reached, forcing process.exit");
+        process.exit(1);
+    }, HARD_EXIT_TIMEOUT_MS);
+    hardExit.unref?.();
+    for (const h of ordered) {
+        const start = Date.now();
+        try {
+            await Promise.race([
+                Promise.resolve(h.fn()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("handler timeout")), HANDLER_TIMEOUT_MS)),
+            ]);
+            logger.info({ handler: h.name, priority: h.priority, ms: Date.now() - start }, "lifecycle: shutdown handler completed");
+        }
+        catch (err) {
+            logger.warn({ err, handler: h.name, priority: h.priority, ms: Date.now() - start }, "lifecycle: shutdown handler failed or timed out (continuing)");
+        }
+    }
+    clearTimeout(hardExit);
+    logger.info({ reason }, "lifecycle: shutdown sequence complete");
+}
+export function __resetForTests() {
+    handlers.length = 0;
+    triggered = false;
+    signalHooksInstalled = false;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/platform/lifecycle.js.map

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