maestro-core 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,21 @@
 # maestro-core
 
-Runtime kernel for the Maestro agent platform. In-process tool-calling runtime with port-based governance — model-agnostic, transport-agnostic, framework-agnostic kernel that powers user-support chat and tool calling for SaaS products.
+In-process tool-calling agent runtime for SaaS products. Model-agnostic, transport-agnostic, framework-agnostic kernel with port-based governance — powers user-support chat with shared quota, cost, audit, memory, and prompt-cache machinery without a remote gateway hop.
 
-`0.1.0` ships:
+## What ships
+
+### `0.2.0` (current)
+
+- **`runChatTurn`** — one call replaces ~300 LoC of stream orchestration. Pre-call quota gate, model selection, AI SDK tool building, prompt-cache breakpoints, memory injection, turn-row persistence, post-call accounting, SSE response. Lives at `maestro-core/runtime`.
+- Quota gate: `AiQuotaDeniedError`, `enforceQuotaOrThrow`, `checkAndEnforce`
+- Memory load + format: `loadMemoryBlock`, `formatMemoryBlock`
+- Empty-recovery decision: `decideEmptyRecovery`
+- Provider fallback helpers: `shouldFallback`, `mapModelIdToOpenAI`
+- Window-math helpers for `QuotaStore` impls: `dailyTokensWindow`, `hourlyToolCallsWindow`, etc.
+- Model router: `selectChatModel` (fast/smart heuristic, configurable thresholds)
+- Cost estimator: `estimateCost` with built-in Anthropic + OpenAI pricing
+
+### `0.1.x` (carried forward)
 
 - `ToolEnvelope<T>` — uniform success/failure shape every tool returns
 - `defineAgentTool<TInput, TOutput, TCtx>` — tool definition factory with generic context extension
@@ -13,19 +26,17 @@ Runtime kernel for the Maestro agent platform. In-process tool-calling runtime w
 - AI SDK adapter (`maestro-core/adapters/ai-sdk`) — wraps registry into `ToolSet` with audit + cache breakpoint
 - MCP server adapter (`maestro-core/adapters/mcp-server`) — registers the same registry on an MCP server
 
-`runChatTurn` (the full streaming orchestrator) lands in `0.2.0`.
-
 ## Install
 
 ```bash
 pnpm add maestro-core zod
-# optional, for the AI SDK adapter:
-pnpm add ai
-# optional, for the MCP server adapter:
+# for the runtime + AI SDK adapter:
+pnpm add ai @ai-sdk/anthropic
+# for the MCP server adapter:
 pnpm add @modelcontextprotocol/sdk
 ```
 
-## Quickstart
+## Quickstart — defining a tool
 
 ```ts
 import { ok, err, defineAgentTool, type BaseToolContext } from 'maestro-core'
@@ -46,9 +57,78 @@ export const lookupTool = defineAgentTool<z.ZodObject<{ id: z.ZodNumber }>, { na
 })
 ```
 
+## Quickstart — running a chat turn
+
+```ts
+import { runChatTurn, AiQuotaDeniedError } from 'maestro-core/runtime'
+
+export async function POST(req: Request) {
+    const { messages } = await req.json()
+    const ctx: MyCtx = { /* tenantId, principal, transport, locale, timezone, requestId, role */ }
+
+    try {
+        return await runChatTurn({
+            threadId,
+            ctx,
+            messages,
+            tools: [lookupTool /* ... */],
+            systemPrompt: {
+                static: 'You are a helpful assistant for record lookups.',
+                dynamic: undefined, // optional per-tenant prose; memory facts auto-append
+            },
+            models: {
+                fast: 'claude-haiku-4-5-20251001',
+                smart: 'claude-sonnet-4-6',
+            },
+            ports: {
+                turnStore: myTurnStore,
+                keyProvider: myKeyProvider,
+                auditStore: myAuditStore,
+                memoryStore: myMemoryStore, // optional
+                quotaStore: myQuotaStore,   // optional but recommended
+                telemetry: myTelemetrySink, // defaults to Noop
+            },
+        })
+    } catch (e) {
+        if (e instanceof AiQuotaDeniedError) {
+            return Response.json(
+                { error: 'quota_exceeded', payload: e.payload },
+                { status: 429 }
+            )
+        }
+        throw e
+    }
+}
+```
+
+## Provider fallback
+
+`shouldFallback` + `mapModelIdToOpenAI` give you composable retry against OpenAI when Anthropic hits a transient failure:
+
+```ts
+import { runChatTurn, shouldFallback, mapModelIdToOpenAI } from 'maestro-core/runtime'
+
+try {
+    return await runChatTurn({ ..., models: anthropicModels })
+} catch (e) {
+    if (shouldFallback(e)) {
+        return runChatTurn({
+            ...,
+            models: {
+                fast: mapModelIdToOpenAI(anthropicModels.fast),
+                smart: mapModelIdToOpenAI(anthropicModels.smart),
+            },
+        })
+    }
+    throw e
+}
+```
+
+Built-in retry wrapper inside `runChatTurn` is tracked for `0.2.1`.
+
 ## Design
 
-See [DESIGN.md](https://github.com/costasoftware/maestro/blob/main/DESIGN.md) for the architecture, port interfaces, and migration roadmap.
+See [DESIGN.md](https://github.com/costasoftware/maestro/blob/main/DESIGN.md) for the architecture, port interfaces, migration roadmap, and what's explicitly deferred.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "maestro-core",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "Runtime kernel for the Maestro agent platform — tool envelope, tool definition factory, base context, port interfaces, and AI-SDK + MCP adapters.",
     "license": "Apache-2.0",
     "author": "Costa Software",
@@ -43,6 +43,10 @@
         "./adapters/mcp-server": {
             "types": "./dist/adapters/mcp-server.d.ts",
             "import": "./dist/adapters/mcp-server.js"
+        },
+        "./runtime": {
+            "types": "./dist/runtime/index.d.ts",
+            "import": "./dist/runtime/index.js"
         }
     },
     "files": [
@@ -57,11 +61,15 @@
         "clean": "rm -rf dist .turbo *.tsbuildinfo"
     },
     "peerDependencies": {
+        "@ai-sdk/anthropic": "^3.0.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "ai": "^6.0.0",
         "zod": "^3.25.0"
     },
     "peerDependenciesMeta": {
+        "@ai-sdk/anthropic": {
+            "optional": true
+        },
         "@modelcontextprotocol/sdk": {
             "optional": true
         },
@@ -70,6 +78,7 @@
         }
     },
     "devDependencies": {
+        "@ai-sdk/anthropic": "^3.0.71",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "@types/node": "^22.10.0",
         "ai": "^6.0.0",