maestro-agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeonwoo Jeong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,24 @@
+maestro-agent-sdk
+=================
+
+This project is a derivative work based on the Maestro agent runtime
+originally developed by Nous Research as part of the hermes-agent project:
+
+  https://github.com/NousResearch/hermes-agent
+  Snapshot reference: v0.13.0 (2026-05-07)
+  Original license: MIT
+
+Original copyright (MIT):
+  Copyright (c) 2025-2026 Nous Research
+
+Changes in this distribution:
+  - Ported the Maestro Python runtime to TypeScript.
+  - Decoupled the agent loop, tool registry, providers (Anthropic, DeepSeek),
+    skills system, and memory compressor into an embeddable npm package.
+  - Removed the Telegram / Discord / Slack gateway, cron scheduler, and other
+    end-user surfaces that exist in the upstream standalone application.
+  - Replaced the host process's bespoke logger/lifecycle/config with
+    injectable interfaces so the SDK can be embedded by any host application.
+
+The upstream MIT license terms continue to apply to the ported code; see
+LICENSE for the SDK distribution license (also MIT).

package/README.md

@@ -0,0 +1,133 @@
+# maestro-agent-sdk
+
+[![CI](https://github.com/maestrojeong/maestro-agent-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/maestrojeong/maestro-agent-sdk/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/maestro-agent-sdk.svg)](https://www.npmjs.com/package/maestro-agent-sdk)
+[![license](https://img.shields.io/npm/l/maestro-agent-sdk.svg)](./LICENSE)
+
+**Embeddable, provider-agnostic TypeScript agent SDK** — pluggable providers, built-in tools, skills, memory, and MCP.
+
+> **Status:** Early port (v0.1.x). Active development. API surface may change before 1.0.
+
+This package extracts the Maestro agent runtime — originally built into [Nous Research's `hermes-agent`](https://github.com/NousResearch/hermes-agent) — into a standalone npm package you can drop into any TypeScript / Node app.
+
+## What's in the box
+
+- **Agent loop** — provider-driven tool-calling loop with iteration cap, abort signal, and event stream.
+- **Pluggable providers** — first-class adapters for Anthropic (Claude) and DeepSeek V4; provider-neutral message schema so adding OpenAI / Gemini / Ollama is a thin file.
+- **Built-in tools** — `bash`, `read`, `write`, `edit`, `agent` (sub-agent delegation), `todo_write`, `skill_view`, `web_fetch`. Bring your own via `ToolRegistry`.
+- **MCP** — built-in client pool (stdio + SSE) so any MCP server (`@modelcontextprotocol/sdk`) shows up as tools.
+- **Skills** — Anthropic-style `SKILL.md` packages with FTS-style indexing and on-demand expansion.
+- **Memory** — automatic context compression (summarization + pruning) when the token budget is hit.
+- **Filesystem sandbox** — optional path-allowlist hook for read/write/edit/bash.
+- **Host integration via DI** — `setLogger`, `setMcpResolver`, `setConversationReader` let you embed without inheriting any one host's opinions.
+
+## Install
+
+```bash
+npm install maestro-agent-sdk
+# or
+bun add maestro-agent-sdk
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```ts
+import {
+  AIAgent,
+  AnthropicProvider,
+  bashTool,
+  createReadTool,
+  createWriteTool,
+  ToolRegistry,
+  runConversation,
+} from "maestro-agent-sdk";
+
+const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! });
+
+const tools = new ToolRegistry();
+tools.register(bashTool());
+tools.register(createReadTool());
+tools.register(createWriteTool());
+
+const agent = new AIAgent(provider, tools, {
+  model: "claude-sonnet-4-6",
+  systemPrompt: "You are a helpful assistant.",
+  maxIterations: 30,
+  maxTokens: 4096,
+});
+
+for await (const event of runConversation(agent, "List files in /tmp.")) {
+  if (event.type === "text_delta") process.stdout.write(event.content);
+  if (event.type === "tool_use") console.error(`\n[tool] ${event.name}`);
+}
+```
+
+More runnable examples live under [`examples/`](./examples).
+
+## Architecture
+
+```
+src/
+├── core/         AIAgent class + run_conversation loop
+├── tools/        ToolRegistry + builtin tools + hooks (sandbox-fs)
+├── providers/    Provider adapters (anthropic, deepseek)
+├── mcp/          MCP client pool (stdio + SSE)
+├── skills/       SKILL.md loader, index builder, usage tracker, curator
+├── memory/       Context compressor, token estimator, reminders, scrubber
+├── state/        Per-session todo store
+├── sub-agent/    Sub-agent runner for the `agent` tool
+├── platform/     Injectable host adapters (logger, lifecycle, config, jsonl, mcp-config)
+├── agents/       Cross-agent rollout helpers + per-agent registry contract
+├── storage/      ConversationReader DI (host supplies past turns for cross-agent forks)
+└── media/        File-event extraction from inline `[FILE:/path]` tags
+```
+
+The `platform/`, `storage/`, and `agents/contracts` modules expose **injection points** so the SDK never assumes a particular host process.
+
+## Host integration (DI)
+
+```ts
+import {
+  setLogger,
+  setMcpResolver,
+  setConversationReader,
+} from "maestro-agent-sdk";
+
+// 1) Replace the console logger with your structured logger (pino, winston, ...).
+setLogger(myPinoLogger);
+
+// 2) Provide MCP server specs per-query.
+setMcpResolver((opts) => ({
+  "playwright": { command: "playwright-mcp", args: [] },
+  "fs": { command: "mcp-fs", args: ["--root", opts.cwd] },
+}));
+
+// 3) Back-fill conversation history for cross-agent forks.
+setConversationReader((userId, topic, groupId) => myStore.read({ userId, topic, groupId }));
+```
+
+## Development
+
+```bash
+git clone git@github.com:maestrojeong/maestro-agent-sdk.git
+cd maestro-agent-sdk
+npm install
+npm run typecheck   # tsc --noEmit
+npm run build       # tsc + tsc-alias → dist/
+npm test            # vitest, 343 tests
+```
+
+### Known gaps
+
+Two test files are currently excluded in `vitest.config.ts`:
+
+- `maestro-registry.test.ts`
+- `maestro-session-store.test.ts`
+
+They rely on host-side helpers (`appendConversationEvent`, `getConversationPath`) and on the strict workspace-root check that the SDK loosened. They'll come back online once we wire them through the `ConversationReader` DI hook.
+
+## License
+
+MIT. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for upstream attribution to Nous Research.

package/dist/agents/contracts.d.ts

@@ -0,0 +1,49 @@
+import type { ConversationEntry } from "../storage/conversations.js";
+import type { AgentKind, EffortLevel } from "../types.js";
+/**
+ * Per-agent runtime config contract.
+ *
+ * The SDK ships `maestroRegistry` (see `src/registry.ts`) which implements
+ * this interface. Hosts that orchestrate multiple agents (claude, codex,
+ * maestro) typically build sibling registries for the others and select
+ * between them at query time.
+ */
+export interface WriteRolloutOptions {
+    cwd: string;
+    entries: ConversationEntry[];
+    reuseSessionId?: string;
+}
+export interface WriteRolloutResult {
+    sessionId: string;
+    rolloutPath: string;
+}
+export interface ForkRegistryOptions {
+    parentSessionId: string;
+    cwd: string;
+    userId: number | string;
+    topicName: string;
+    groupId?: number;
+    title?: string;
+}
+export interface ForkRegistryResult {
+    forkId: string;
+    rolloutPath: string;
+}
+export interface CleanupRolloutsOptions {
+    cwd: string;
+    sessionIds: string[];
+}
+export interface AgentRegistry {
+    kind: AgentKind;
+    defaultModel: string;
+    defaultEffort?: EffortLevel;
+    expandModelAlias(s: string): string;
+    validateModel(s: string): boolean;
+    validEfforts: readonly EffortLevel[];
+    validateEffort(s: EffortLevel): boolean;
+    footerLabel(model: string, effort?: EffortLevel): string;
+    writeRollout(opts: WriteRolloutOptions): WriteRolloutResult;
+    forkSession(opts: ForkRegistryOptions): Promise<ForkRegistryResult>;
+    cleanupRollouts(opts: CleanupRolloutsOptions): Promise<void>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/agents/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/agents/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;GAOG;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,cAAc,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IACxC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IACzD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,kBAAkB,CAAC;IAC5D,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpE,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D"}

package/dist/agents/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/agents/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/agents/contracts.ts"],"names":[],"mappings":""}

package/dist/agents/rollout/shared.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Helpers shared by every agent's rollout encoder.
+ *
+ * Ported from clawgram. The cwd-validation step that hard-references
+ * WORKSPACE_DIR/ONBOARDING_DIR is loosened in the SDK build: hosts may
+ * route any cwd through the agent loop, and the SDK has no business
+ * dictating where a session may live. The other helpers (UUID shape,
+ * `extractChatPairs`) are kept verbatim.
+ */
+import type { ConversationEntry } from "../../storage/conversations.js";
+export declare function clone<T>(obj: T): T;
+export declare function assertUuidLike(label: string, value: string): void;
+/** Best-effort guarantee that the resumed cwd will exist when the SDK stats it. */
+export declare function ensureCwdExists(cwd: string): void;
+export type ChatPair = {
+    userText: string;
+    assistantText: string;
+};
+interface ExtractOptions {
+    includeToolAnnotations: boolean;
+}
+export declare function extractChatPairs(entries: ConversationEntry[], opts?: ExtractOptions): ChatPair[];
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/agents/rollout/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/agents/rollout/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAElC;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjE;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMjD;AAOD,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,UAAU,cAAc;IACtB,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,EAAE,EAC5B,IAAI,GAAE,cAAiD,GACtD,QAAQ,EAAE,CAwEZ"}

package/dist/agents/rollout/shared.js

@@ -0,0 +1,105 @@
+/**
+ * Helpers shared by every agent's rollout encoder.
+ *
+ * Ported from clawgram. The cwd-validation step that hard-references
+ * WORKSPACE_DIR/ONBOARDING_DIR is loosened in the SDK build: hosts may
+ * route any cwd through the agent loop, and the SDK has no business
+ * dictating where a session may live. The other helpers (UUID shape,
+ * `extractChatPairs`) are kept verbatim.
+ */
+import { mkdirSync } from "node:fs";
+import { logger } from "../../platform/logger.js";
+export function clone(obj) {
+    return structuredClone(obj);
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function assertUuidLike(label, value) {
+    if (!UUID_RE.test(value)) {
+        throw new Error(`rollout: ${label} is not a UUID-shaped string: ${value}`);
+    }
+}
+/** Best-effort guarantee that the resumed cwd will exist when the SDK stats it. */
+export function ensureCwdExists(cwd) {
+    try {
+        mkdirSync(cwd, { recursive: true });
+    }
+    catch (err) {
+        logger.warn({ err, cwd }, "rollout: ensureCwdExists failed — caller should pre-create cwd");
+    }
+}
+function truncate(text, n) {
+    const cps = Array.from(text);
+    return cps.length > n ? `${cps.slice(0, n).join("")}…` : text;
+}
+export function extractChatPairs(entries, opts = { includeToolAnnotations: true }) {
+    const pairs = [];
+    let pendingUser = null;
+    let pendingAssistantParts = [];
+    let toolBuffer = [];
+    const flushAssistant = () => {
+        if (pendingUser === null)
+            return;
+        const tools = opts.includeToolAnnotations && toolBuffer.length > 0 ? `\n\n${toolBuffer.join("\n")}` : "";
+        const assistantText = pendingAssistantParts.join("").trim() + tools;
+        if (assistantText.trim()) {
+            pairs.push({ userText: pendingUser, assistantText });
+        }
+        pendingUser = null;
+        pendingAssistantParts = [];
+        toolBuffer = [];
+    };
+    for (const entry of entries) {
+        const ev = entry.event;
+        switch (ev.type) {
+            case "user_message": {
+                flushAssistant();
+                pendingUser = ev.content;
+                break;
+            }
+            case "session":
+                if (pendingAssistantParts.length > 0 || toolBuffer.length > 0) {
+                    flushAssistant();
+                }
+                break;
+            case "text": {
+                if (pendingUser === null) {
+                    pendingUser = "(continued)";
+                }
+                pendingAssistantParts.push(ev.content);
+                break;
+            }
+            case "result": {
+                if (pendingUser === null) {
+                    pendingUser = "(continued)";
+                }
+                pendingAssistantParts = [ev.content];
+                flushAssistant();
+                break;
+            }
+            case "text_delta":
+                break;
+            case "tool_use": {
+                const u = ev;
+                toolBuffer.push(`[Tool: ${u.name} ${truncate(JSON.stringify(u.input), 200)}]`);
+                break;
+            }
+            case "tool_result": {
+                const u = ev;
+                toolBuffer.push(`[Tool result: ${truncate(u.content, 200)}]`);
+                break;
+            }
+            case "error": {
+                const u = ev;
+                toolBuffer.push(`[Error: ${truncate(u.content, 200)}]`);
+                break;
+            }
+            case "tool_progress":
+            case "tool_use_summary":
+            case "file":
+                break;
+        }
+    }
+    flushAssistant();
+    return pairs;
+}
+//# sourceMappingURL=shared.js.map

package/dist/agents/rollout/shared.js.map

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

package/dist/core/agent.d.ts

@@ -0,0 +1,71 @@
+import type { Provider } from "../providers/base.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { EffortLevel } from "../types.js";
+/**
+ * AIAgent — minimal TS port of upstream `run_agent.py::AIAgent`.
+ *
+ * Upstream's AIAgent takes ~60 constructor params (credentials, callbacks,
+ * checkpoints, prefill messages, smart routing, reasoning configs, etc.).
+ * Phase 1 keeps the bare minimum needed to run a conversation against
+ * Anthropic with a tool registry — the rest of upstream's surface area is
+ * deferred or dropped because Clawgram owns the equivalent (gateway,
+ * permissions, conversation log, etc.).
+ */
+export interface AIAgentConfig {
+    /** Resolved model id (e.g. `claude-sonnet-4-6`). */
+    model: string;
+    /** System prompt — built by Clawgram's prompt-builder before calling. */
+    systemPrompt: string;
+    /** Hard cap on tool-calling iterations. Default 90 to match upstream. */
+    maxIterations?: number;
+    /** Per-API-call max output tokens. Default 4096. */
+    maxTokens?: number;
+    /**
+     * Extended thinking budget in tokens. When > 0 the Anthropic provider sends
+     * `thinking: { type: "enabled", budget_tokens }` and auto-boosts max_tokens
+     * past the budget (Anthropic requires max_tokens > budget_tokens). Omit to
+     * skip thinking — the model emits no reasoning chain.
+     *
+     * Maps from `AgentQueryOptions.effort` in `maestroProvider`; values follow
+     * the rough scale claude-agent-sdk uses internally (low ≈ 2K, xhigh ≈ 32K).
+     */
+    thinkingBudget?: number;
+    /**
+     * Native effort level — passed straight through to providers that map it
+     * themselves (DeepSeek's `reasoning_effort`). Anthropic ignores this and
+     * uses `thinkingBudget`; both fields are populated by the call site so
+     * the provider picks its preferred shape.
+     */
+    effort?: EffortLevel;
+    /** External abort signal — wired to the AgentQueryOptions.abortController. */
+    abortSignal?: AbortSignal;
+    /**
+     * Per-iteration system-reminder builder. Invoked by `runConversation`
+     * just before pushing each `tool_result` user message; the returned text
+     * is appended as a trailing `text` block on that user message so the
+     * model sees a fresh "iterations remaining" line on every turn.
+     *
+     * Freezing the reminder into the canonical `messages` array (rather than
+     * mutating wireMessages on-the-fly) keeps Anthropic's prefix cache intact:
+     * each historical user message permanently carries the budget that was
+     * live at THAT turn, byte-stable across future calls.
+     *
+     * Return `null`/empty to skip injection for a given iteration (e.g. when
+     * the caller has nothing dynamic to surface). The FIRST user message's
+     * reminder is built by the caller before the loop starts — this callback
+     * only fires for subsequent tool_result turns.
+     */
+    buildIterReminder?: (iterationsRemaining: number) => string | null;
+}
+export declare class AIAgent {
+    readonly provider: Provider;
+    readonly tools: ToolRegistry;
+    readonly config: Required<Pick<AIAgentConfig, "model" | "systemPrompt" | "maxIterations" | "maxTokens">> & {
+        thinkingBudget?: number;
+        effort?: EffortLevel;
+        abortSignal?: AbortSignal;
+        buildIterReminder?: (iterationsRemaining: number) => string | null;
+    };
+    constructor(provider: Provider, tools: ToolRegistry, config: AIAgentConfig);
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED,qBAAa,OAAO;IAClB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CACvB,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,GAAG,WAAW,CAAC,CAC9E,GAAG;QACF,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,iBAAiB,CAAC,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;KACpE,CAAC;gBAEU,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa;CAgB3E"}

package/dist/core/agent.js

@@ -0,0 +1,22 @@
+export class AIAgent {
+    provider;
+    tools;
+    config;
+    constructor(provider, tools, config) {
+        this.provider = provider;
+        this.tools = tools;
+        this.config = {
+            model: config.model,
+            systemPrompt: config.systemPrompt,
+            maxIterations: config.maxIterations ?? 90,
+            maxTokens: config.maxTokens ?? 4096,
+            ...(config.thinkingBudget && config.thinkingBudget > 0
+                ? { thinkingBudget: config.thinkingBudget }
+                : {}),
+            ...(config.effort ? { effort: config.effort } : {}),
+            ...(config.abortSignal ? { abortSignal: config.abortSignal } : {}),
+            ...(config.buildIterReminder ? { buildIterReminder: config.buildIterReminder } : {}),
+        };
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AA8DA,MAAM,OAAO,OAAO;IACT,QAAQ,CAAW;IACnB,KAAK,CAAe;IACpB,MAAM,CAOb;IAEF,YAAY,QAAkB,EAAE,KAAmB,EAAE,MAAqB;QACxE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG;YACZ,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;YACzC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;YACnC,GAAG,CAAC,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC;gBACpD,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;gBAC3C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF,CAAC;IACJ,CAAC;CACF"}

package/dist/core/loop.d.ts

@@ -0,0 +1,26 @@
+import type { AIAgent } from "../core/agent.js";
+import type { ProviderMessage } from "../providers/base.js";
+import type { UnifiedEvent } from "../types.js";
+/**
+ * run_conversation — Maestro agent loop (TS port).
+ *
+ * Yields UnifiedEvents so the Clawgram dispatcher can stream them to telegram
+ * without caring about the underlying provider format.
+ *
+ * Multi-turn: the caller owns the `messages` array and passes it in
+ * pre-populated with prior history (loaded from `~/.maestro/sessions/<id>.jsonl`
+ * by `maestroProvider`) plus the new user prompt as the last entry. The loop
+ * mutates that array in place, appending assistant turns and tool-result
+ * user turns as the conversation progresses; once the generator drains, the
+ * caller persists the final `messages` back to disk for the next resume.
+ *
+ * This shape avoids returning the final history through the async iterator
+ * (which would either require a special "internal" UnifiedEvent variant or a
+ * companion side-channel — both worse than just sharing the array).
+ *
+ * Upstream reference: `run_agent.py::AIAgent.run_conversation` — same control
+ * flow, just `client.chat.completions.create` swapped for `provider.complete`
+ * and OpenAI message blocks swapped for Anthropic blocks.
+ */
+export declare function runConversation(agent: AIAgent, messages: ProviderMessage[]): AsyncGenerator<UnifiedEvent>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/core/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/core/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,KAAK,EAEV,eAAe,EAEhB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,SAAS,CAAC;AAkBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAuB,eAAe,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,EAAE,GAC1B,cAAc,CAAC,YAAY,CAAC,CAiS9B"}