maestro-core 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# 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.
+
+`0.1.0` ships:
+
+- `ToolEnvelope<T>` — uniform success/failure shape every tool returns
+- `defineAgentTool<TInput, TOutput, TCtx>` — tool definition factory with generic context extension
+- `BaseToolContext` — extensible per-request context
+- 8 port interfaces: `TurnStore`, `AuditStore`, `MemoryStore`, `QuotaStore`, `ModelKeyProvider`, `TelemetrySink`, `Clock`, `Logger`
+- `applyCacheBreakpoints` — Anthropic ephemeral prompt-cache helper
+- `captureToolException` — observability hook for tool execute exceptions
+- 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:
+pnpm add @modelcontextprotocol/sdk
+```
+
+## Quickstart
+
+```ts
+import { ok, err, defineAgentTool, type BaseToolContext } from 'maestro-core'
+import { z } from 'zod'
+
+type MyCtx = BaseToolContext & { role: 'admin' | 'guest' }
+
+export const lookupTool = defineAgentTool<z.ZodObject<{ id: z.ZodNumber }>, { name: string }, MyCtx>({
+    name: 'lookup',
+    description: 'Look up a record by id. Admin only.',
+    transports: ['chat'],
+    inputSchema: z.object({ id: z.number() }),
+    isAvailable: (ctx) => ctx.role === 'admin',
+    execute: async (input, ctx) => {
+        if (input.id === 0) return err('NOT_FOUND', 'no such record')
+        return ok({ name: `record-${input.id}` })
+    },
+})
+```
+
+## Design
+
+See [DESIGN.md](https://github.com/costasoftware/maestro/blob/main/DESIGN.md) for the architecture, port interfaces, and migration roadmap.
+
+## License
+
+Apache-2.0

package/dist/adapters/ai-sdk.d.ts

@@ -0,0 +1,60 @@
+import { type ToolSet } from 'ai';
+import { type CacheableBlock, type CachedMessages } from '../cache-control.js';
+import type { BaseToolContext } from '../context.js';
+import type { AuditStore } from '../ports/audit-store.js';
+import type { Clock } from '../ports/clock.js';
+import { type ToolExceptionHandler } from '../safe-tool.js';
+import type { AnyAgentToolDefinition } from '../tool.js';
+/**
+ * Translate a registry of `AgentToolDefinition`s into a Vercel AI SDK
+ * `ToolSet` ready to pass to `streamText` / `generateText`.
+ *
+ * Filtering happens BEFORE this call: the host runs each tool's
+ * `isAvailable(ctx)` + `def.transports.includes(ctx.transport)` to
+ * decide what to advertise; only the eligible subset reaches here.
+ * Keeping eligibility outside the adapter means hosts can layer their
+ * own gates (OAuth scopes, feature flags) on top without forking.
+ *
+ * Each tool's `execute` is wrapped in try/catch:
+ *   1. On success: writes an audit row (if `audit` port provided).
+ *   2. On envelope-error (`ok: false`): same audit row, just with the
+ *      error code/message.
+ *   3. On thrown exception: audit row tagged `tool_exception`, calls
+ *      `onError` for observability, THEN rethrows so the AI SDK marks
+ *      the tool result as `error` and the model sees it.
+ *
+ * The last tool in iteration order receives the Anthropic ephemeral
+ * cacheControl marker (`applyCacheBreakpoints`). Cross-tenant cache
+ * reuse depends on the tool registry bytes being identical across
+ * tenants — keep tool descriptions tenant-invariant.
+ */
+export interface BuildAiSdkToolsArgs<TCtx extends BaseToolContext> {
+    /** Registry already filtered for the active surface + actor + isAvailable. */
+    registry: readonly AnyAgentToolDefinition<TCtx>[];
+    /** Request context — passed to every `execute` call. */
+    ctx: TCtx;
+    /** Optional audit port. Calls are fire-and-forget. */
+    audit?: AuditStore;
+    /** Optional observability hook for thrown exceptions. */
+    onError?: ToolExceptionHandler;
+    /** Optional clock override (testing). */
+    clock?: Clock;
+}
+export declare function buildAiSdkTools<TCtx extends BaseToolContext>(args: BuildAiSdkToolsArgs<TCtx>): ToolSet;
+/**
+ * Convenience wrapper: builds the ToolSet AND applies the
+ * static-vs-dynamic system-prompt cache breakpoint in one call.
+ *
+ * Hosts that prefer to manage cache placement themselves (e.g. an
+ * adapter combining a multi-segment system prompt with a third-party
+ * RAG corpus) should call `buildAiSdkTools` + `applyCacheBreakpoints`
+ * separately.
+ */
+export declare function buildCachedAiSdkSetup<TCtx extends BaseToolContext>(args: {
+    build: BuildAiSdkToolsArgs<TCtx>;
+    cache: Omit<CacheableBlock<ToolSet>, 'static'> & {
+        static: Omit<CacheableBlock<ToolSet>['static'], 'tools'>;
+    };
+}): CachedMessages<ToolSet>;
+export { type ToolSet } from 'ai';
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/adapters/ai-sdk.d.ts.map

@@ -0,0 +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"}

package/dist/adapters/ai-sdk.js

@@ -0,0 +1,86 @@
+import { tool } from 'ai';
+import { applyCacheBreakpoints } from '../cache-control.js';
+import { SystemClock } from '../ports/clock.js';
+import { captureToolException } from '../safe-tool.js';
+export function buildAiSdkTools(args) {
+    const clock = args.clock ?? new SystemClock();
+    const rawTools = {};
+    for (const def of args.registry) {
+        rawTools[def.name] = tool({
+            description: def.description,
+            inputSchema: def.inputSchema,
+            execute: async (input) => {
+                const startedAt = clock.now();
+                try {
+                    const envelope = await def.execute(input, args.ctx);
+                    if (args.audit) {
+                        void args.audit.recordToolCall({
+                            toolName: def.name,
+                            transport: args.ctx.transport,
+                            actor: args.ctx.actor,
+                            tenantId: args.ctx.tenantId,
+                            principalId: args.ctx.principal?.id ?? null,
+                            requestId: args.ctx.requestId ?? null,
+                            input,
+                            output: envelope.ok
+                                ? { ok: true }
+                                : {
+                                    ok: false,
+                                    code: envelope.error.code,
+                                    message: envelope.error.message,
+                                },
+                            durationMs: clock.now().getTime() - startedAt.getTime(),
+                            createdAt: startedAt,
+                        });
+                    }
+                    return envelope;
+                }
+                catch (e) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    if (args.audit) {
+                        void args.audit.recordToolCall({
+                            toolName: def.name,
+                            transport: args.ctx.transport,
+                            actor: args.ctx.actor,
+                            tenantId: args.ctx.tenantId,
+                            principalId: args.ctx.principal?.id ?? null,
+                            requestId: args.ctx.requestId ?? null,
+                            input,
+                            output: { ok: false, code: 'tool_exception', message },
+                            durationMs: clock.now().getTime() - startedAt.getTime(),
+                            createdAt: startedAt,
+                        });
+                    }
+                    captureToolException(e, {
+                        toolName: def.name,
+                        transport: args.ctx.transport,
+                        actor: args.ctx.actor,
+                        tenantId: args.ctx.tenantId,
+                        principalId: args.ctx.principal?.id ?? null,
+                        requestId: args.ctx.requestId ?? null,
+                    }, args.onError);
+                    throw e;
+                }
+            },
+        });
+    }
+    return rawTools;
+}
+/**
+ * Convenience wrapper: builds the ToolSet AND applies the
+ * static-vs-dynamic system-prompt cache breakpoint in one call.
+ *
+ * Hosts that prefer to manage cache placement themselves (e.g. an
+ * adapter combining a multi-segment system prompt with a third-party
+ * RAG corpus) should call `buildAiSdkTools` + `applyCacheBreakpoints`
+ * separately.
+ */
+export function buildCachedAiSdkSetup(args) {
+    const tools = buildAiSdkTools(args.build);
+    return applyCacheBreakpoints({
+        static: { ...args.cache.static, tools },
+        dynamic: args.cache.dynamic,
+    });
+}
+export {} from 'ai';
+//# sourceMappingURL=ai-sdk.js.map

package/dist/adapters/ai-sdk.js.map

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

package/dist/adapters/mcp-server.d.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BaseToolContext } from '../context.js';
+import type { AuditStore } from '../ports/audit-store.js';
+import { type Clock } from '../ports/clock.js';
+import type { AnyAgentToolDefinition } from '../tool.js';
+/**
+ * Register a registry of `AgentToolDefinition`s on an MCP server
+ * instance. The host owns the `McpServer` lifecycle (per-request in
+ * stateless HTTP mode, long-lived in stdio mode) — this adapter only
+ * fills the tool list.
+ *
+ * Filtering (surface, actor scope, OAuth scopes, isAvailable) happens
+ * BEFORE this call. Same pattern as `buildAiSdkTools`.
+ *
+ * On execute:
+ *   - Success or envelope-error → JSON-stringified envelope returned
+ *     as `text` content. `isError` mirrors `envelope.ok === false`.
+ *   - Thrown exception → audit + the host's `onError` hook are
+ *     called, then a JSON `{ ok: false, error }` payload is returned
+ *     with `isError: true`. The throw is NOT propagated (MCP SDK
+ *     expects the handler to resolve with an error result, not
+ *     throw — different contract from AI SDK).
+ */
+export interface RegisterMcpToolsArgs<TCtx extends BaseToolContext> {
+    server: McpServer;
+    registry: readonly AnyAgentToolDefinition<TCtx>[];
+    ctx: TCtx;
+    audit?: AuditStore;
+    clock?: Clock;
+    /**
+     * Observability hook for thrown exceptions (Sentry, OTel, etc.).
+     * Receives the raw error and a tag bag.
+     */
+    onError?: (error: unknown, tags: Record<string, unknown>) => void;
+}
+export declare function registerMcpTools<TCtx extends BaseToolContext>(args: RegisterMcpToolsArgs<TCtx>): void;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/adapters/mcp-server.d.ts.map

@@ -0,0 +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"}

package/dist/adapters/mcp-server.js

@@ -0,0 +1,99 @@
+import { SystemClock } from '../ports/clock.js';
+export function registerMcpTools(args) {
+    const clock = args.clock ?? new SystemClock();
+    for (const def of args.registry) {
+        args.server.registerTool(def.name, {
+            description: def.description,
+            inputSchema: zodToRawShape(def.inputSchema),
+        }, async (input) => {
+            const startedAt = clock.now();
+            try {
+                const envelope = await def.execute(input, args.ctx);
+                if (args.audit) {
+                    void args.audit.recordToolCall({
+                        toolName: def.name,
+                        transport: args.ctx.transport,
+                        actor: args.ctx.actor,
+                        tenantId: args.ctx.tenantId,
+                        principalId: args.ctx.principal?.id ?? null,
+                        requestId: args.ctx.requestId ?? null,
+                        input,
+                        output: envelope.ok
+                            ? { ok: true }
+                            : {
+                                ok: false,
+                                code: envelope.error.code,
+                                message: envelope.error.message,
+                            },
+                        durationMs: clock.now().getTime() - startedAt.getTime(),
+                        createdAt: startedAt,
+                    });
+                }
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify(envelope, null, 2) },
+                    ],
+                    isError: !envelope.ok,
+                };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                if (args.audit) {
+                    void args.audit.recordToolCall({
+                        toolName: def.name,
+                        transport: args.ctx.transport,
+                        actor: args.ctx.actor,
+                        tenantId: args.ctx.tenantId,
+                        principalId: args.ctx.principal?.id ?? null,
+                        requestId: args.ctx.requestId ?? null,
+                        input,
+                        output: { ok: false, code: 'tool_exception', message },
+                        durationMs: clock.now().getTime() - startedAt.getTime(),
+                        createdAt: startedAt,
+                    });
+                }
+                if (args.onError) {
+                    try {
+                        args.onError(e, {
+                            toolName: def.name,
+                            transport: args.ctx.transport,
+                            actor: args.ctx.actor,
+                            tenantId: args.ctx.tenantId,
+                            principalId: args.ctx.principal?.id ?? null,
+                            requestId: args.ctx.requestId ?? null,
+                        });
+                    }
+                    catch {
+                        // Observability must never crash the tool result.
+                    }
+                }
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify({ ok: false, error: message }) },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+}
+/**
+ * The MCP SDK's `registerTool` wants the input schema as a raw Zod
+ * shape (`{ key: z.foo() }`), not the wrapped `z.object`. We crack
+ * open the internal `_def.shape()` getter to extract it.
+ *
+ * Unknown / non-object schemas fall through to an empty shape — the
+ * MCP server will accept any input for tools that don't declare one,
+ * matching the behaviour of barbeiro's original adapter.
+ */
+function zodToRawShape(schema) {
+    const s = schema;
+    if (s && typeof s._def?.shape === 'function') {
+        return s._def.shape();
+    }
+    if (s && typeof s.shape === 'object' && s.shape !== null) {
+        return s.shape;
+    }
+    return {};
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/adapters/mcp-server.js.map

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

package/dist/cache-control.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Anthropic prompt-cache breakpoint helper.
+ *
+ * The model provider supports `cacheControl: { type: 'ephemeral' }`
+ * markers — content BEFORE the breakpoint is hashed into the cache key,
+ * content AFTER is rendered as a separate uncached segment. 5-minute TTL.
+ * Cold call pays cache-write (≈1.25× input rate); hot call pays
+ * cache-read (≈10% input rate).
+ *
+ * The TS-typed boundary between `static` and `dynamic` is the discipline.
+ * A developer physically can't put `business.name` into the cached block
+ * because the `static` slot only accepts the documented stable fields.
+ * Cross-tenant cache reuse is deliberate: tenant-invariant static block
+ * means many tenants share the same cache entry; per-tenant data lives
+ * in the dynamic segment that the cache key ignores.
+ *
+ * This helper deals only with the system-prompt + tools shape. The
+ * caller passes the result straight to `streamText` / `generateText`
+ * (AI SDK) as `system: [...]` and `tools: {...}`.
+ *
+ * The tools map is kept opaque (`Record<string, unknown>`) so this
+ * module has no `ai` dependency; the AI-SDK adapter feeds a properly
+ * typed `ToolSet` in, and TypeScript flows the type through.
+ */
+export interface CacheableBlock<TTools extends Record<string, unknown>> {
+    /**
+     * Tenant-stable content — hashed for the cache key. MUST NOT
+     * contain user/business names or any per-tenant interpolated
+     * strings. Integer ids inside tool parameter descriptions are
+     * fine; rendered-into-prose strings are not.
+     */
+    static: {
+        /** Fixed introduction / persona block (surface-level instructions). */
+        intro: string;
+        /** Help corpus or business catalog static reference block. */
+        corpus: string;
+        /** Tool registry for this surface. The last tool receives the cacheControl marker. */
+        tools: TTools;
+    };
+    /**
+     * Tenant-specific content. Rendered as a separate uncached system
+     * segment so it never influences the cache key.
+     */
+    dynamic: {
+        /** Tenant id as an integer-safe shape — never interpolated into cached strings. */
+        tenant: {
+            id: string;
+            timezone: string;
+        };
+        principal?: {
+            id: string;
+        };
+        /** ISO timestamp for "now" context — varies per turn; must NOT be cached. */
+        nowIso: string;
+    };
+}
+export interface CachedMessages<TTools extends Record<string, unknown>> {
+    /**
+     * Two-element array:
+     *   [0] static system message — carries the Anthropic ephemeral cacheControl marker.
+     *   [1] dynamic system message — no marker; rendered after the breakpoint.
+     */
+    system: Array<{
+        role: 'system';
+        content: string;
+        providerOptions?: {
+            anthropic?: {
+                cacheControl?: {
+                    type: 'ephemeral';
+                };
+            };
+        };
+    }>;
+    /** Tool registry — the last tool carries the cacheControl marker. */
+    tools: TTools;
+}
+export declare function applyCacheBreakpoints<TTools extends Record<string, unknown>>(input: CacheableBlock<TTools>): CachedMessages<TTools>;
+//# sourceMappingURL=cache-control.d.ts.map

package/dist/cache-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.d.ts","sourceRoot":"","sources":["../src/cache-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE;;;;;OAKG;IACH,MAAM,EAAE;QACJ,uEAAuE;QACvE,KAAK,EAAE,MAAM,CAAA;QACb,8DAA8D;QAC9D,MAAM,EAAE,MAAM,CAAA;QACd,sFAAsF;QACtF,KAAK,EAAE,MAAM,CAAA;KAChB,CAAA;IACD;;;OAGG;IACH,OAAO,EAAE;QACL,mFAAmF;QACnF,MAAM,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;QACxC,SAAS,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;QAC1B,6EAA6E;QAC7E,MAAM,EAAE,MAAM,CAAA;KACjB,CAAA;CACJ;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE;;;;OAIG;IACH,MAAM,EAAE,KAAK,CAAC;QACV,IAAI,EAAE,QAAQ,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,eAAe,CAAC,EAAE;YAAE,SAAS,CAAC,EAAE;gBAAE,YAAY,CAAC,EAAE;oBAAE,IAAI,EAAE,WAAW,CAAA;iBAAE,CAAA;aAAE,CAAA;SAAE,CAAA;KAC7E,CAAC,CAAA;IACF,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,GAC9B,cAAc,CAAC,MAAM,CAAC,CA4DxB"}

package/dist/cache-control.js

@@ -0,0 +1,57 @@
+export function applyCacheBreakpoints(input) {
+    const { static: st, dynamic: dyn } = input;
+    // ── Static system message (cached) ──────────────────────────────────
+    const staticContent = st.corpus ? `${st.intro}\n\n${st.corpus}` : st.intro;
+    const staticMessage = {
+        role: 'system',
+        content: staticContent,
+        providerOptions: {
+            anthropic: { cacheControl: { type: 'ephemeral' } },
+        },
+    };
+    // ── Dynamic system message (uncached) ───────────────────────────────
+    const dynamicLines = [
+        `Tenant context: tenant_id=${dyn.tenant.id}, timezone=${dyn.tenant.timezone}`,
+    ];
+    if (dyn.principal?.id !== undefined) {
+        dynamicLines.push(`Principal context: principal_id=${dyn.principal.id}`);
+    }
+    dynamicLines.push(`Current time (ISO): ${dyn.nowIso}`);
+    const dynamicMessage = {
+        role: 'system',
+        content: dynamicLines.join('\n'),
+    };
+    // ── Tools (cached) ──────────────────────────────────────────────────
+    // Clone the registry to avoid mutating the caller's object. Apply the
+    // cacheControl marker to the last tool in iteration order. Strip any
+    // pre-existing providerOptions on non-last tools so a previously
+    // marked registry coming back through here doesn't double-mark.
+    const toolKeys = Object.keys(st.tools);
+    const markedTools = {};
+    for (let i = 0; i < toolKeys.length; i++) {
+        const key = toolKeys[i];
+        if (key === undefined)
+            continue;
+        const original = st.tools[key];
+        if (original === undefined)
+            continue;
+        const isLast = i === toolKeys.length - 1;
+        if (isLast) {
+            markedTools[key] = {
+                ...original,
+                providerOptions: {
+                    anthropic: { cacheControl: { type: 'ephemeral' } },
+                },
+            };
+        }
+        else {
+            const { providerOptions: _drop, ...rest } = original;
+            markedTools[key] = rest;
+        }
+    }
+    return {
+        system: [staticMessage, dynamicMessage],
+        tools: markedTools,
+    };
+}
+//# sourceMappingURL=cache-control.js.map

package/dist/cache-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.js","sourceRoot":"","sources":["../src/cache-control.ts"],"names":[],"mappings":"AAmEA,MAAM,UAAU,qBAAqB,CACjC,KAA6B;IAE7B,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAA;IAE1C,uEAAuE;IACvE,MAAM,aAAa,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAA;IAC1E,MAAM,aAAa,GAAG;QAClB,IAAI,EAAE,QAAiB;QACvB,OAAO,EAAE,aAAa;QACtB,eAAe,EAAE;YACb,SAAS,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,WAAoB,EAAE,EAAE;SAC9D;KACJ,CAAA;IAED,uEAAuE;IACvE,MAAM,YAAY,GAAa;QAC3B,6BAA6B,GAAG,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE;KAChF,CAAA;IACD,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,SAAS,EAAE,CAAC;QAClC,YAAY,CAAC,IAAI,CAAC,mCAAmC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAA;IAC5E,CAAC;IACD,YAAY,CAAC,IAAI,CAAC,uBAAuB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;IACtD,MAAM,cAAc,GAAG;QACnB,IAAI,EAAE,QAAiB;QACvB,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;KACnC,CAAA;IAED,uEAAuE;IACvE,sEAAsE;IACtE,qEAAqE;IACrE,iEAAiE;IACjE,gEAAgE;IAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;IACtC,MAAM,WAAW,GAAG,EAA6B,CAAA;IAEjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,GAAG,KAAK,SAAS;YAAE,SAAQ;QAC/B,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAQ;QACpC,MAAM,MAAM,GAAG,CAAC,KAAK,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;QAExC,IAAI,MAAM,EAAE,CAAC;YACT,WAAW,CAAC,GAAG,CAAC,GAAG;gBACf,GAAI,QAAmB;gBACvB,eAAe,EAAE;oBACb,SAAS,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,WAAoB,EAAE,EAAE;iBAC9D;aACJ,CAAA;QACL,CAAC;aAAM,CAAC;YACJ,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,QAEjB,CAAA;YAC3B,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;QAC3B,CAAC;IACL,CAAC;IAED,OAAO;QACH,MAAM,EAAE,CAAC,aAAa,EAAE,cAAc,CAAC;QACvC,KAAK,EAAE,WAAqB;KAC/B,CAAA;AACL,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-request context handed to every tool. Built by the host product
+ * at the top of the chat-turn handler (route, worker, MCP request) from
+ * the authenticated principal + the surface invoking the tool.
+ *
+ * The base shape is intentionally minimal — everything that is universal
+ * to any tool-calling agent system. Hosts extend via intersection at the
+ * `defineAgentTool<TInput, TOutput, TCtx>` call site:
+ *
+ * ```ts
+ * type BarbeiroCtx = BaseToolContext & {
+ *   businessSlug?: string
+ *   guestPhone?: string
+ *   role: HelpRole | null
+ * }
+ *
+ * defineAgentTool<Input, Output, BarbeiroCtx>({ ... })
+ * ```
+ *
+ * Per-tool generic param (not TS module augmentation) is the chosen
+ * extension mechanism — keeps the augmentation scoped to one tool
+ * instead of polluting a shared global interface, so siblings in a
+ * future monorepo can't trip over each other's context shapes.
+ */
+export interface BaseToolContext {
+    /**
+     * Opaque tenant scope. The host product owns the meaning
+     * (`businessId.toString()`, workspace UUID, org slug, etc.) — kernel
+     * never parses it. Used for audit attribution, quota keys, memory
+     * scoping, and telemetry tagging.
+     */
+    tenantId: string;
+    /**
+     * Authenticated principal, or null for anonymous transports
+     * (public widget, voice). `id` is opaque; `kind` is a host-defined
+     * string that disambiguates principal populations
+     * (`'user'`, `'guest'`, `'service-account'`, `'mcp-client'`, ...).
+     */
+    principal: {
+        id: string;
+        kind: string;
+    } | null;
+    /**
+     * Who authorised the call. Logged for governance + abuse detection.
+     * String-typed; the host owns the enum.
+     */
+    actor: string;
+    /**
+     * Which surface invoked the call (`'chat'`, `'guest-chat'`,
+     * `'whatsapp'`, `'mcp'`, ...). Adapters filter the registry by
+     * `def.transports.includes(transport)`. String-typed; the host owns
+     * the vocabulary.
+     */
+    transport: string;
+    /** IETF BCP-47 locale tag, e.g. `'pt-BR'`. */
+    locale: string;
+    /** IANA timezone, e.g. `'America/Sao_Paulo'`. */
+    timezone: string;
+    /** Trace id for cross-system correlation (matches HTTP `x-request-id`). */
+    requestId: string;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;;;OAKG;IACH,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAE9C;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IAEd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAEhB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;CACpB"}

package/dist/context.js

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

package/dist/context.js.map

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

package/dist/envelope.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Uniform return shape for every Maestro tool. Wrapping success and failure
+ * in the same envelope lets the model recover gracefully ("sorry, that slot
+ * was just taken") instead of crashing the whole turn, and lets every adapter
+ * (AI SDK, MCP, transports added later) render the result with the same code
+ * path.
+ */
+export interface ToolMeta {
+    /**
+     * Set when the host UI already renders a rich card for this tool result.
+     * Chat transports with a UI surface read this and tell the model to skip
+     * restating the data — preventing the duplicate "card + paragraph saying
+     * the same thing" bubble. Advisory only on transports without UI cards
+     * (whatsapp, mcp, voice) — those still get the full LLM restatement.
+     */
+    uiRendered?: string;
+}
+export type ToolEnvelope<T> = {
+    ok: true;
+    data: T;
+    meta?: ToolMeta;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare const ok: <T>(data: T, meta?: ToolMeta) => ToolEnvelope<T>;
+export declare const err: (code: string, message: string) => ToolEnvelope<never>;
+export declare function isOk<T>(envelope: ToolEnvelope<T>): envelope is {
+    ok: true;
+    data: T;
+    meta?: ToolMeta;
+};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAE7D,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,QAAQ,KAAG,YAAY,CAAC,CAAC,CACP,CAAA;AAExD,eAAO,MAAM,GAAG,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,YAAY,CAAC,KAAK,CAGpE,CAAA;AAEF,wBAAgB,IAAI,CAAC,CAAC,EAClB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAC1B,QAAQ,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,CAEpD"}

package/dist/envelope.js

@@ -0,0 +1,9 @@
+export const ok = (data, meta) => meta ? { ok: true, data, meta } : { ok: true, data };
+export const err = (code, message) => ({
+    ok: false,
+    error: { code, message },
+});
+export function isOk(envelope) {
+    return envelope.ok === true;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAsBA,MAAM,CAAC,MAAM,EAAE,GAAG,CAAI,IAAO,EAAE,IAAe,EAAmB,EAAE,CAC/D,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAExD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,OAAe,EAAuB,EAAE,CAAC,CAAC;IACxE,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;CAC3B,CAAC,CAAA;AAEF,MAAM,UAAU,IAAI,CAChB,QAAyB;IAEzB,OAAO,QAAQ,CAAC,EAAE,KAAK,IAAI,CAAA;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { BaseToolContext } from './context.js';
+export { err, isOk, ok, type ToolEnvelope, type ToolMeta } from './envelope.js';
+export { type AgentToolDefinition, type AnyAgentToolDefinition, defineAgentTool, type ToolCostBand, type ToolKind, } from './tool.js';
+export { applyCacheBreakpoints, type CacheableBlock, type CachedMessages, } from './cache-control.js';
+export { captureToolException, type ToolExceptionHandler, type ToolExceptionTags, } from './safe-tool.js';
+export * from './ports/index.js';
+//# sourceMappingURL=index.d.ts.map