maestro-core 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,21 @@
1
1
  # maestro-core
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- `0.1.0` ships:
5
+ ## What ships
6
+
7
+ ### `0.2.0` (current)
8
+
9
+ - **`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`.
10
+ - Quota gate: `AiQuotaDeniedError`, `enforceQuotaOrThrow`, `checkAndEnforce`
11
+ - Memory load + format: `loadMemoryBlock`, `formatMemoryBlock`
12
+ - Empty-recovery decision: `decideEmptyRecovery`
13
+ - Provider fallback helpers: `shouldFallback`, `mapModelIdToOpenAI`
14
+ - Window-math helpers for `QuotaStore` impls: `dailyTokensWindow`, `hourlyToolCallsWindow`, etc.
15
+ - Model router: `selectChatModel` (fast/smart heuristic, configurable thresholds)
16
+ - Cost estimator: `estimateCost` with built-in Anthropic + OpenAI pricing
17
+
18
+ ### `0.1.x` (carried forward)
6
19
 
7
20
  - `ToolEnvelope<T>` — uniform success/failure shape every tool returns
8
21
  - `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
13
26
  - AI SDK adapter (`maestro-core/adapters/ai-sdk`) — wraps registry into `ToolSet` with audit + cache breakpoint
14
27
  - MCP server adapter (`maestro-core/adapters/mcp-server`) — registers the same registry on an MCP server
15
28
 
16
- `runChatTurn` (the full streaming orchestrator) lands in `0.2.0`.
17
-
18
29
  ## Install
19
30
 
20
31
  ```bash
21
32
  pnpm add maestro-core zod
22
- # optional, for the AI SDK adapter:
23
- pnpm add ai
24
- # optional, for the MCP server adapter:
33
+ # for the runtime + AI SDK adapter:
34
+ pnpm add ai @ai-sdk/anthropic
35
+ # for the MCP server adapter:
25
36
  pnpm add @modelcontextprotocol/sdk
26
37
  ```
27
38
 
28
- ## Quickstart
39
+ ## Quickstart — defining a tool
29
40
 
30
41
  ```ts
31
42
  import { ok, err, defineAgentTool, type BaseToolContext } from 'maestro-core'
@@ -46,9 +57,78 @@ export const lookupTool = defineAgentTool<z.ZodObject<{ id: z.ZodNumber }>, { na
46
57
  })
47
58
  ```
48
59
 
60
+ ## Quickstart — running a chat turn
61
+
62
+ ```ts
63
+ import { runChatTurn, AiQuotaDeniedError } from 'maestro-core/runtime'
64
+
65
+ export async function POST(req: Request) {
66
+ const { messages } = await req.json()
67
+ const ctx: MyCtx = { /* tenantId, principal, transport, locale, timezone, requestId, role */ }
68
+
69
+ try {
70
+ return await runChatTurn({
71
+ threadId,
72
+ ctx,
73
+ messages,
74
+ tools: [lookupTool /* ... */],
75
+ systemPrompt: {
76
+ static: 'You are a helpful assistant for record lookups.',
77
+ dynamic: undefined, // optional per-tenant prose; memory facts auto-append
78
+ },
79
+ models: {
80
+ fast: 'claude-haiku-4-5-20251001',
81
+ smart: 'claude-sonnet-4-6',
82
+ },
83
+ ports: {
84
+ turnStore: myTurnStore,
85
+ keyProvider: myKeyProvider,
86
+ auditStore: myAuditStore,
87
+ memoryStore: myMemoryStore, // optional
88
+ quotaStore: myQuotaStore, // optional but recommended
89
+ telemetry: myTelemetrySink, // defaults to Noop
90
+ },
91
+ })
92
+ } catch (e) {
93
+ if (e instanceof AiQuotaDeniedError) {
94
+ return Response.json(
95
+ { error: 'quota_exceeded', payload: e.payload },
96
+ { status: 429 }
97
+ )
98
+ }
99
+ throw e
100
+ }
101
+ }
102
+ ```
103
+
104
+ ## Provider fallback
105
+
106
+ `shouldFallback` + `mapModelIdToOpenAI` give you composable retry against OpenAI when Anthropic hits a transient failure:
107
+
108
+ ```ts
109
+ import { runChatTurn, shouldFallback, mapModelIdToOpenAI } from 'maestro-core/runtime'
110
+
111
+ try {
112
+ return await runChatTurn({ ..., models: anthropicModels })
113
+ } catch (e) {
114
+ if (shouldFallback(e)) {
115
+ return runChatTurn({
116
+ ...,
117
+ models: {
118
+ fast: mapModelIdToOpenAI(anthropicModels.fast),
119
+ smart: mapModelIdToOpenAI(anthropicModels.smart),
120
+ },
121
+ })
122
+ }
123
+ throw e
124
+ }
125
+ ```
126
+
127
+ Built-in retry wrapper inside `runChatTurn` is tracked for `0.2.1`.
128
+
49
129
  ## Design
50
130
 
51
- See [DESIGN.md](https://github.com/costasoftware/maestro/blob/main/DESIGN.md) for the architecture, port interfaces, and migration roadmap.
131
+ See [DESIGN.md](https://github.com/costasoftware/maestro/blob/main/DESIGN.md) for the architecture, port interfaces, migration roadmap, and what's explicitly deferred.
52
132
 
53
133
  ## License
54
134
 
@@ -4,7 +4,7 @@ import type { BaseToolContext } from '../context.js';
4
4
  import type { AuditStore } from '../ports/audit-store.js';
5
5
  import type { Clock } from '../ports/clock.js';
6
6
  import { type ToolExceptionHandler } from '../safe-tool.js';
7
- import type { AnyAgentToolDefinition } from '../tool.js';
7
+ import type { AgentToolDefinition } from '../tool.js';
8
8
  /**
9
9
  * Translate a registry of `AgentToolDefinition`s into a Vercel AI SDK
10
10
  * `ToolSet` ready to pass to `streamText` / `generateText`.
@@ -29,8 +29,13 @@ import type { AnyAgentToolDefinition } from '../tool.js';
29
29
  * tenants — keep tool descriptions tenant-invariant.
30
30
  */
31
31
  export interface BuildAiSdkToolsArgs<TCtx extends BaseToolContext> {
32
- /** Registry already filtered for the active surface + actor + isAvailable. */
33
- registry: readonly AnyAgentToolDefinition<TCtx>[];
32
+ /**
33
+ * Registry already filtered for the active surface + actor + isAvailable.
34
+ * Typed as `AgentToolDefinition<any, any, TCtx>` (not `AnyAgentToolDefinition`)
35
+ * so arrays mixing tools with different concrete input/output shapes unify
36
+ * — the `any` slot allows the variance TS otherwise rejects.
37
+ */
38
+ registry: readonly AgentToolDefinition<any, any, TCtx>[];
34
39
  /** Request context — passed to every `execute` call. */
35
40
  ctx: TCtx;
36
41
  /** Optional audit port. Calls are fire-and-forget. */
@@ -1 +1 @@
1
- {"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,IAAI,CAAA;AAEvC,OAAO,EAAyB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACrG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,SAAS,eAAe;IAC7D,8EAA8E;IAC9E,QAAQ,EAAE,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAA;IACjD,wDAAwD;IACxD,GAAG,EAAE,IAAI,CAAA;IACT,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,yCAAyC;IACzC,KAAK,CAAC,EAAE,KAAK,CAAA;CAChB;AAED,wBAAgB,eAAe,CAAC,IAAI,SAAS,eAAe,EACxD,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAChC,OAAO,CAoET;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE;IACtE,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAA;IAChC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,GAAG;QAC7C,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAA;KAC3D,CAAA;CACJ,GAAG,cAAc,CAAC,OAAO,CAAC,CAM1B;AAED,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAA"}
1
+ {"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,IAAI,CAAA;AAEvC,OAAO,EAAyB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACrG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,SAAS,eAAe;IAC7D;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAA;IACxD,wDAAwD;IACxD,GAAG,EAAE,IAAI,CAAA;IACT,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,yCAAyC;IACzC,KAAK,CAAC,EAAE,KAAK,CAAA;CAChB;AAED,wBAAgB,eAAe,CAAC,IAAI,SAAS,eAAe,EACxD,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAChC,OAAO,CAoET;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE;IACtE,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAA;IAChC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,GAAG;QAC7C,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAA;KAC3D,CAAA;CACJ,GAAG,cAAc,CAAC,OAAO,CAAC,CAM1B;AAED,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAA"}
@@ -1 +1 @@
1
- {"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"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"}
@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import type { BaseToolContext } from '../context.js';
3
3
  import type { AuditStore } from '../ports/audit-store.js';
4
4
  import { type Clock } from '../ports/clock.js';
5
- import type { AnyAgentToolDefinition } from '../tool.js';
5
+ import type { AgentToolDefinition } from '../tool.js';
6
6
  /**
7
7
  * Register a registry of `AgentToolDefinition`s on an MCP server
8
8
  * instance. The host owns the `McpServer` lifecycle (per-request in
@@ -23,7 +23,11 @@ import type { AnyAgentToolDefinition } from '../tool.js';
23
23
  */
24
24
  export interface RegisterMcpToolsArgs<TCtx extends BaseToolContext> {
25
25
  server: McpServer;
26
- registry: readonly AnyAgentToolDefinition<TCtx>[];
26
+ /**
27
+ * Registry already filtered for the surface. Typed with `any` slots so
28
+ * arrays of tools with different concrete input/output shapes unify.
29
+ */
30
+ registry: readonly AgentToolDefinition<any, any, TCtx>[];
27
31
  ctx: TCtx;
28
32
  audit?: AuditStore;
29
33
  clock?: Clock;
@@ -1 +1 @@
1
- {"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/adapters/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,eAAe;IAC9D,MAAM,EAAE,SAAS,CAAA;IACjB,QAAQ,EAAE,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAA;IACjD,GAAG,EAAE,IAAI,CAAA;IACT,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACpE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,eAAe,EACzD,IAAI,EAAE,oBAAoB,CAAC,IAAI,CAAC,GACjC,IAAI,CAgFN"}
1
+ {"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/adapters/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,eAAe;IAC9D,MAAM,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,QAAQ,EAAE,SAAS,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAA;IACxD,GAAG,EAAE,IAAI,CAAA;IACT,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACpE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,eAAe,EACzD,IAAI,EAAE,oBAAoB,CAAC,IAAI,CAAC,GACjC,IAAI,CAgFN"}
@@ -1 +1 @@
1
- {"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/adapters/mcp-server.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/adapters/mcp-server.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "maestro-core",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Runtime kernel for the Maestro agent platform — tool envelope, tool definition factory, base context, port interfaces, and AI-SDK + MCP adapters.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Costa Software",
@@ -43,6 +43,10 @@
43
43
  "./adapters/mcp-server": {
44
44
  "types": "./dist/adapters/mcp-server.d.ts",
45
45
  "import": "./dist/adapters/mcp-server.js"
46
+ },
47
+ "./runtime": {
48
+ "types": "./dist/runtime/index.d.ts",
49
+ "import": "./dist/runtime/index.js"
46
50
  }
47
51
  },
48
52
  "files": [
@@ -57,11 +61,15 @@
57
61
  "clean": "rm -rf dist .turbo *.tsbuildinfo"
58
62
  },
59
63
  "peerDependencies": {
64
+ "@ai-sdk/anthropic": "^3.0.0",
60
65
  "@modelcontextprotocol/sdk": "^1.29.0",
61
66
  "ai": "^6.0.0",
62
67
  "zod": "^3.25.0"
63
68
  },
64
69
  "peerDependenciesMeta": {
70
+ "@ai-sdk/anthropic": {
71
+ "optional": true
72
+ },
65
73
  "@modelcontextprotocol/sdk": {
66
74
  "optional": true
67
75
  },
@@ -70,6 +78,7 @@
70
78
  }
71
79
  },
72
80
  "devDependencies": {
81
+ "@ai-sdk/anthropic": "^3.0.71",
73
82
  "@modelcontextprotocol/sdk": "^1.29.0",
74
83
  "@types/node": "^22.10.0",
75
84
  "ai": "^6.0.0",