maestro-agent-sdk 0.1.0

package/dist/tools/file-state.js

@@ -0,0 +1,133 @@
+import { existsSync, statSync } from "node:fs";
+/**
+ * One tracker per session — `Map<absPath, FileStateEntry>`.
+ *
+ * Wrapped (instead of a raw Map) so the public surface is explicit: callers
+ * only record and check, they don't iterate or mutate entries directly.
+ */
+export class FileStateTracker {
+    entries = new Map();
+    /**
+     * Record a successful Read of `absPath`. Called from Read's execute()
+     * after the file has been stat'd and the contents handed back to the
+     * model. A subsequent Read of the same path overwrites the entry — the
+     * latest Read is what Edit's drift check compares against.
+     */
+    recordRead(absPath, mtime, size) {
+        this.entries.set(absPath, { mtime, size, readAt: Date.now() });
+    }
+    /**
+     * Forget the recorded state for `absPath`. Called when Edit / Write
+     * mutates the file so the next Edit must Re-read first (its prior cached
+     * stat is now stale by definition). Also called when a Write creates a
+     * file — the next Edit on the same path must Read it back to confirm
+     * the model's mental model matches what landed on disk.
+     */
+    forget(absPath) {
+        this.entries.delete(absPath);
+    }
+    /**
+     * Check whether `absPath` may be Edit/Write'd. Returns null on allow,
+     * or a string error on deny — callers stringify into `{error}` so the
+     * model sees the same shape as sandbox / arg-validation rejections.
+     *
+     * Three reject paths:
+     *   - "no_read": never Read this session. Forces the model to Read first.
+     *   - "stale_mtime": mtime drifted vs recorded — file changed externally.
+     *   - "stale_size": same as above but size changed (covers same-ms writes).
+     *
+     * Allow path: live stat matches recorded mtime AND size.
+     *
+     * One subtlety: if the path doesn't exist, we return null (allow). Write
+     * legitimately creates files, and Edit's "must exist" check runs after
+     * this gate inside the tool — so a missing file in Edit will reject with
+     * "file does not exist, use Write to create". Read-before-Mutate is about
+     * content drift, not existence.
+     */
+    checkBeforeMutate(absPath, tool) {
+        if (!existsSync(absPath))
+            return null;
+        // Write on an existing file requires prior Read — same invariant as Edit.
+        // The model must see the current line-numbered content before overwriting
+        // to prevent blind overwrites and stale-content races.
+        // Write on a non-existent path (creation) is always allowed; the gate
+        // short-circuits at the `existsSync` check above.
+        const entry = this.entries.get(absPath);
+        if (!entry) {
+            return (`${tool}: file '${absPath}' has not been Read in this session. ` +
+                `Read it first so the model sees the current line-numbered content, ` +
+                `then re-issue the ${tool}.`);
+        }
+        let live;
+        try {
+            const s = statSync(absPath);
+            live = { mtimeMs: s.mtimeMs, size: s.size };
+        }
+        catch {
+            // If we can't stat, fall through to the tool's own error handler — it
+            // will surface a clearer message than we can.
+            return null;
+        }
+        if (live.mtimeMs !== entry.mtime) {
+            const ageMs = Date.now() - entry.readAt;
+            return (`${tool}: file '${absPath}' was modified externally since the last Read ` +
+                `(recorded mtime ${entry.mtime}, live mtime ${live.mtimeMs}, ` +
+                `Read was ${Math.round(ageMs / 1000)}s ago). ` +
+                `Re-Read the file to refresh the line-numbered view, then re-issue the ${tool}.`);
+        }
+        if (live.size !== entry.size) {
+            return (`${tool}: file '${absPath}' size changed since the last Read ` +
+                `(recorded ${entry.size}, live ${live.size}). ` +
+                `Re-Read the file before ${tool.toLowerCase()}ing.`);
+        }
+        return null;
+    }
+    /** Used by tests + diagnostics. Not part of the per-turn contract. */
+    has(absPath) {
+        return this.entries.has(absPath);
+    }
+    /** Total number of tracked paths. Diagnostic. */
+    size() {
+        return this.entries.size;
+    }
+}
+/**
+ * Module-level registry: `sessionId → FileStateTracker`.
+ *
+ * Why module scope (not registry-scope or agent-scope): `maestroProvider`
+ * builds a fresh `ToolRegistry` per turn but the sessionId persists across
+ * turns. A registry-local tracker would reset every turn and the Read-before-
+ * Edit gate would become useless because the Read happened "last turn" and
+ * the tracker forgot.
+ *
+ * Cleanup is wired in two places — `deleteMaestroSession` (explicit) and
+ * `cleanupStaleMaestroSessions` (per-file unlink loop) — so the map can't
+ * outlive its sessions.
+ */
+const sessions = new Map();
+/** Get or create the tracker for a session. */
+export function getFileStateTracker(sessionId) {
+    let t = sessions.get(sessionId);
+    if (!t) {
+        t = new FileStateTracker();
+        sessions.set(sessionId, t);
+    }
+    return t;
+}
+/**
+ * Drop a session's tracker. Called from `deleteMaestroSession` and from
+ * `cleanupStaleMaestroSessions` after the on-disk JSONL is unlinked.
+ * ENOENT-equivalent: deleting a session that was never tracked is a no-op.
+ */
+export function dropFileStateTracker(sessionId) {
+    sessions.delete(sessionId);
+}
+/** Test-only. Drops every tracker. */
+export function __resetAllTrackers() {
+    sessions.clear();
+}
+/** Test-only. Snapshot of how many sessions are currently tracked. */
+export function __trackerCount() {
+    return sessions.size;
+}
+//# sourceMappingURL=file-state.js.map

package/dist/tools/file-state.js.map

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

package/dist/tools/hooks/sandbox-fs.d.ts

@@ -0,0 +1,25 @@
+import type { HookRegistration } from "../../tools/registry.js";
+/**
+ * Filesystem sandbox as a PreToolUse hook.
+ *
+ * Centralized opt-in gate for any tool whose input carries a `file_path`
+ * argument (Read/Write/Edit today, future FS-touching MCP tools by
+ * inheritance). Default is **disabled** to match the unconstrained FS
+ * posture of claude (`bypassPermissions`) and codex (`danger-full-access`)
+ * providers — divergence here used to silently break maestro-only workflows
+ * that legitimately reach outside the workspace. Operator opts in by
+ * exporting `MAESTRO_FS_SANDBOX_ENABLED=1`.
+ *
+ * Scope: only tools whose `input.file_path` is a non-empty string are
+ * inspected. Tools that don't surface a file path (bash, web_fetch, MCP
+ * tools without an FS argument) are unaffected — this hook is FS-specific
+ * by design. A future bash-sandbox hook would be a separate registration.
+ *
+ * Absolute-path enforcement is left to the tool itself: the model's error
+ * message is clearer when it comes from the tool (`Read: file_path must be
+ * absolute`) than from the sandbox hook ("path is not absolute"). The
+ * sandbox only weighs in once an absolute path has been confirmed —
+ * mirroring how the inline check used to work.
+ */
+export declare function createSandboxFsHook(): HookRegistration;
+//# sourceMappingURL=sandbox-fs.d.ts.map

package/dist/tools/hooks/sandbox-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-fs.d.ts","sourceRoot":"","sources":["../../../src/tools/hooks/sandbox-fs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAsBtD"}

package/dist/tools/hooks/sandbox-fs.js

@@ -0,0 +1,48 @@
+import { isAbsolute } from "node:path";
+import { checkFilesystemAccess, isSandboxEnabled } from "../../tools/builtin/sandbox.js";
+/**
+ * Filesystem sandbox as a PreToolUse hook.
+ *
+ * Centralized opt-in gate for any tool whose input carries a `file_path`
+ * argument (Read/Write/Edit today, future FS-touching MCP tools by
+ * inheritance). Default is **disabled** to match the unconstrained FS
+ * posture of claude (`bypassPermissions`) and codex (`danger-full-access`)
+ * providers — divergence here used to silently break maestro-only workflows
+ * that legitimately reach outside the workspace. Operator opts in by
+ * exporting `MAESTRO_FS_SANDBOX_ENABLED=1`.
+ *
+ * Scope: only tools whose `input.file_path` is a non-empty string are
+ * inspected. Tools that don't surface a file path (bash, web_fetch, MCP
+ * tools without an FS argument) are unaffected — this hook is FS-specific
+ * by design. A future bash-sandbox hook would be a separate registration.
+ *
+ * Absolute-path enforcement is left to the tool itself: the model's error
+ * message is clearer when it comes from the tool (`Read: file_path must be
+ * absolute`) than from the sandbox hook ("path is not absolute"). The
+ * sandbox only weighs in once an absolute path has been confirmed —
+ * mirroring how the inline check used to work.
+ */
+export function createSandboxFsHook() {
+    return {
+        name: "sandbox-fs",
+        pre(ctx) {
+            // Cheap exit when the operator hasn't opted into the sandbox — the
+            // common case, so skip the work before doing any property reads.
+            if (!isSandboxEnabled())
+                return { decision: "allow" };
+            const filePath = ctx.input.file_path;
+            if (typeof filePath !== "string" || filePath.length === 0) {
+                return { decision: "allow" };
+            }
+            // Defer absolute-path errors to the tool — its message is clearer.
+            if (!isAbsolute(filePath))
+                return { decision: "allow" };
+            const err = checkFilesystemAccess(filePath);
+            if (err) {
+                return { decision: "block", error: `${ctx.toolName}: ${err}` };
+            }
+            return { decision: "allow" };
+        },
+    };
+}
+//# sourceMappingURL=sandbox-fs.js.map

package/dist/tools/hooks/sandbox-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-fs.js","sourceRoot":"","sources":["../../../src/tools/hooks/sandbox-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,GAAG,CAAC,GAAG;YACL,mEAAmE;YACnE,iEAAiE;YACjE,IAAI,CAAC,gBAAgB,EAAE;gBAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAEtD,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;YACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1D,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAC/B,CAAC;YACD,mEAAmE;YACnE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAExD,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,EAAE,EAAE,CAAC;YACjE,CAAC;YACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,102 @@
+import type { ProviderToolSchema } from "../providers/base.js";
+/**
+ * Maestro tool registry — TS port of upstream `tools/registry.py`.
+ *
+ * Holds a flat map of tool name → handler. Schemas are surfaced to the
+ * provider via `schemas()` so the model knows what's callable; dispatch
+ * routes a `tool_use` block back to the registered handler.
+ *
+ * Phase 2 adds a hook chain around `dispatch` (PreToolUse / PostToolUse)
+ * matching Claude Code's settings.json hook surface. Hooks centralize
+ * policy that would otherwise be sprinkled across tools — sandbox gates,
+ * automatic redaction, telemetry.
+ */
+/**
+ * Decision returned by a PreToolUse hook.
+ *   - `allow`  → continue to the next hook (or execute() if last).
+ *   - `modify` → continue with the supplied `input` substituted.
+ *   - `block`  → short-circuit chain. `error` wraps to `{error}`; PostToolUse
+ *                hooks do NOT run on blocked calls.
+ */
+export type PreToolUseDecision = {
+    decision: "allow";
+} | {
+    decision: "modify";
+    input: Record<string, unknown>;
+} | {
+    decision: "block";
+    error: string;
+};
+export interface PreToolUseContext {
+    toolName: string;
+    input: Record<string, unknown>;
+}
+export interface PostToolUseContext {
+    toolName: string;
+    /** The input the tool actually saw — already mutated if a Pre hook modified. */
+    input: Record<string, unknown>;
+    /** The string returned by `execute()` (or by an upstream Post hook). */
+    output: string;
+}
+/**
+ * PostToolUse result. All optional:
+ *   - `output` → replace the surfaced result (redaction, truncation).
+ *   - `log`    → fire-and-forget structured payload for telemetry sinks.
+ */
+export interface PostToolUseResult {
+    output?: string;
+    log?: Record<string, unknown>;
+}
+export type PreToolUseHook = (ctx: PreToolUseContext) => Promise<PreToolUseDecision> | PreToolUseDecision;
+export type PostToolUseHook = (ctx: PostToolUseContext) => Promise<PostToolUseResult> | PostToolUseResult;
+export interface HookRegistration {
+    name?: string;
+    pre?: PreToolUseHook;
+    post?: PostToolUseHook;
+}
+export interface ToolHandler {
+    schema: ProviderToolSchema;
+    /**
+     * Whether this tool is safe to dispatch in parallel with other parallel-
+     * safe tools in the same turn. Anthropic can return multiple `tool_use`
+     * blocks in one assistant response; running independent reads in parallel
+     * cuts latency dramatically. Default false (safer). Mark true on tools
+     * with no observable side effects (pure reads, idempotent fetches).
+     */
+    parallelSafe?: boolean;
+    execute(input: Record<string, unknown>): Promise<string>;
+}
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly hooks;
+    register(handler: ToolHandler): void;
+    /**
+     * Register a hook pair (pre and/or post). Hooks fire in registration
+     * order — pre forward, post forward. "Last in, last to react" beats a
+     * Koa-style onion model here because each hook is independent; a
+     * telemetry hook generally wants to log AFTER a redaction hook has
+     * scrubbed the output, which matches registration intent.
+     */
+    use(reg: HookRegistration): void;
+    /** Diagnostic: count of registered hooks. */
+    __hookCount(): number;
+    has(name: string): boolean;
+    schemas(): ProviderToolSchema[];
+    /**
+     * Dispatch through the full hook chain:
+     *   1. Pre hooks in order. First `block` wins → wrapped as {error}; skip
+     *      execute() and skip every Post hook (no clean result to process).
+     *   2. `execute()`. Thrown errors → {error}; Post hooks skipped.
+     *   3. Post hooks in order; each may mutate output and/or emit a log.
+     *      A Post hook that throws is swallowed so it can't poison the result.
+     */
+    dispatch(name: string, input: Record<string, unknown>): Promise<string>;
+    /**
+     * True when `name` is registered AND its handler is flagged parallelSafe.
+     * Unknown tools and unflagged tools default to false — the loop falls
+     * through to sequential dispatch, which is the safe default for any tool
+     * with side effects (write/edit/bash/most MCP).
+     */
+    isParallelSafe(name: string): boolean;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GACrB;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtD;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,iBAAiB,KACnB,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,kBAAkB,KACpB,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAEhD,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAQpC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IAIhC,6CAA6C;IAC7C,WAAW,IAAI,MAAM;IAIrB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,OAAO,IAAI,kBAAkB,EAAE;IAI/B;;;;;;;OAOG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA6C7E;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGtC"}

package/dist/tools/registry.js

@@ -0,0 +1,93 @@
+export class ToolRegistry {
+    tools = new Map();
+    hooks = [];
+    register(handler) {
+        const name = handler.schema.name;
+        if (this.tools.has(name)) {
+            throw new Error(`Maestro ToolRegistry: tool '${name}' is already registered`);
+        }
+        this.tools.set(name, handler);
+    }
+    /**
+     * Register a hook pair (pre and/or post). Hooks fire in registration
+     * order — pre forward, post forward. "Last in, last to react" beats a
+     * Koa-style onion model here because each hook is independent; a
+     * telemetry hook generally wants to log AFTER a redaction hook has
+     * scrubbed the output, which matches registration intent.
+     */
+    use(reg) {
+        this.hooks.push(reg);
+    }
+    /** Diagnostic: count of registered hooks. */
+    __hookCount() {
+        return this.hooks.length;
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    schemas() {
+        return Array.from(this.tools.values()).map((h) => h.schema);
+    }
+    /**
+     * Dispatch through the full hook chain:
+     *   1. Pre hooks in order. First `block` wins → wrapped as {error}; skip
+     *      execute() and skip every Post hook (no clean result to process).
+     *   2. `execute()`. Thrown errors → {error}; Post hooks skipped.
+     *   3. Post hooks in order; each may mutate output and/or emit a log.
+     *      A Post hook that throws is swallowed so it can't poison the result.
+     */
+    async dispatch(name, input) {
+        const handler = this.tools.get(name);
+        if (!handler) {
+            return JSON.stringify({ error: `unknown tool: ${name}` });
+        }
+        let currentInput = input;
+        for (const hook of this.hooks) {
+            if (!hook.pre)
+                continue;
+            const decision = await hook.pre({ toolName: name, input: currentInput });
+            if (decision.decision === "block") {
+                return JSON.stringify({ error: decision.error });
+            }
+            if (decision.decision === "modify") {
+                currentInput = decision.input;
+            }
+        }
+        let output;
+        try {
+            output = await handler.execute(currentInput);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return JSON.stringify({ error: msg });
+        }
+        for (const hook of this.hooks) {
+            if (!hook.post)
+                continue;
+            try {
+                const result = await hook.post({ toolName: name, input: currentInput, output });
+                if (typeof result.output === "string") {
+                    output = result.output;
+                }
+                // `log` is fire-and-forget. Registry has no opinion on sink; the
+                // hook owns wherever it routes the payload.
+            }
+            catch (e) {
+                // Post-hook crash must not corrupt the user-visible result.
+                // Telemetry hooks should be the ones capturing these errors.
+                void e;
+            }
+        }
+        return output;
+    }
+    /**
+     * True when `name` is registered AND its handler is flagged parallelSafe.
+     * Unknown tools and unflagged tools default to false — the loop falls
+     * through to sequential dispatch, which is the safe default for any tool
+     * with side effects (write/edit/bash/most MCP).
+     */
+    isParallelSafe(name) {
+        return this.tools.get(name)?.parallelSafe === true;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Core SDK types — narrowed from the upstream clawgram types.
+ *
+ * The host application provides the rest (PII context, session bookkeeping,
+ * Telegram-specific fields). The SDK only needs the pieces the agent loop,
+ * providers, and tools actually consume.
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+/**
+ * Effort levels accepted by Maestro providers.
+ *
+ * Anthropic ignores this and uses `thinkingBudget`; DeepSeek maps it to
+ * `reasoning_effort` directly. Hosts can pass either string form.
+ */
+export declare const MAESTRO_EFFORT_VALUES: readonly ["low", "medium", "high", "xhigh", "max"];
+export type EffortLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Identifier returned by the SDK's session-store. Hosts may map their own
+ * notion of "session" (e.g. a topic, a thread, a user) onto this.
+ */
+export type AgentKind = "claude" | "codex" | "maestro";
+export declare const SUPPORTED_AGENTS: readonly AgentKind[];
+export declare const FALLBACK_AGENT: AgentKind;
+export declare function isAgentKind(value: unknown): value is AgentKind;
+/**
+ * Normalized event stream emitted by the agent loop. Hosts iterate this
+ * async generator and render / persist whichever variants they care about.
+ */
+export type UnifiedEvent = {
+    type: "user_message";
+    content: string;
+} | {
+    type: "session";
+    sessionId: string;
+} | {
+    type: "tool_use";
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "tool_progress";
+    toolName: string;
+    elapsed: number;
+} | {
+    type: "tool_use_summary";
+    summary: string;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+} | {
+    type: "text_delta";
+    content: string;
+} | {
+    type: "text";
+    content: string;
+} | {
+    type: "result";
+    content: string;
+    stopReason: string;
+    usage?: TokenUsage;
+} | {
+    type: "file";
+    path: string;
+    source: string;
+    origin: "tag" | "extension";
+} | {
+    type: "error";
+    content: string;
+};
+/**
+ * Options accepted by `maestroProvider.query()` — the host-facing entry point.
+ *
+ * Most fields are optional; only `prompt`, `cwd`, `systemPrompt` are strictly
+ * required to drive the loop. The rest let the host plug in session
+ * persistence, sub-agent delegation, MCP servers, and abort control.
+ */
+export interface AgentQueryOptions {
+    agent: AgentKind;
+    prompt: string;
+    sessionId?: string | null;
+    cwd: string;
+    systemPrompt: string;
+    userId?: string;
+    session?: string;
+    sessionType?: "dm" | "forum" | "ephemeral" | "manager";
+    groupId?: number;
+    abortController?: AbortController;
+    model?: string;
+    depth?: number;
+    agents?: Record<string, {
+        description: string;
+        prompt: string;
+        model?: string;
+        tools?: string[];
+        maxTurns?: number;
+        effort?: EffortLevel | number;
+    }>;
+    effort?: EffortLevel;
+    mcpEnabled?: string[] | null;
+    mcpExtra?: Record<string, unknown>;
+    isCron?: boolean;
+    silent?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,20 @@
+/**
+ * Core SDK types — narrowed from the upstream clawgram types.
+ *
+ * The host application provides the rest (PII context, session bookkeeping,
+ * Telegram-specific fields). The SDK only needs the pieces the agent loop,
+ * providers, and tools actually consume.
+ */
+/**
+ * Effort levels accepted by Maestro providers.
+ *
+ * Anthropic ignores this and uses `thinkingBudget`; DeepSeek maps it to
+ * `reasoning_effort` directly. Hosts can pass either string form.
+ */
+export const MAESTRO_EFFORT_VALUES = ["low", "medium", "high", "xhigh", "max"];
+export const SUPPORTED_AGENTS = ["claude", "codex", "maestro"];
+export const FALLBACK_AGENT = "claude";
+export function isAgentKind(value) {
+    return typeof value === "string" && SUPPORTED_AGENTS.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAQxF,MAAM,CAAC,MAAM,gBAAgB,GAAyB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAc,QAAQ,CAAC;AAElD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "maestro-agent-sdk",
+  "version": "0.1.0",
+  "description": "Embeddable, provider-agnostic TypeScript agent SDK — pluggable providers, built-in tools, skills, memory, and MCP.",
+  "license": "MIT",
+  "author": "Yeonwoo Jeong <aadd4020@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maestrojeong/maestro-agent-sdk.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providers/anthropic": {
+      "types": "./dist/providers/anthropic.d.ts",
+      "import": "./dist/providers/anthropic.js"
+    },
+    "./providers/deepseek": {
+      "types": "./dist/providers/deepseek.d.ts",
+      "import": "./dist/providers/deepseek.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "llm",
+    "anthropic",
+    "claude",
+    "deepseek",
+    "mcp",
+    "tool-use",
+    "agent-sdk",
+    "hermes-agent",
+    "maestro"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "cheerio": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5",
+    "vitest": "^4.1.6"
+  }
+}