maestro-core 0.2.0 → 0.2.2

package/dist/runtime/run-chat-turn.js

@@ -0,0 +1,329 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { convertToModelMessages, streamText } from 'ai';
+import { buildAiSdkTools } from '../adapters/ai-sdk.js';
+import { applyCacheBreakpoints } from '../cache-control.js';
+import { estimateCost } from '../cost.js';
+import { selectChatModel } from '../models.js';
+import { SystemClock } from '../ports/clock.js';
+import { SilentLogger } from '../ports/logger.js';
+import { NoopTelemetrySink } from '../ports/telemetry-sink.js';
+import { loadMemoryBlock } from './memory.js';
+import { AiQuotaDeniedError, checkAndEnforce } from './quota.js';
+export async function runChatTurn(args) {
+    const clock = args.ports.clock ?? new SystemClock();
+    const logger = args.ports.logger ?? new SilentLogger();
+    const telemetry = args.ports.telemetry ?? new NoopTelemetrySink();
+    const failOpenOnQuotaError = args.failOpenOnQuotaError ?? true;
+    // ── 0. Quota pre-call gate ──────────────────────────────────────
+    // Runs before any LLM/key/storage work so a denied tenant pays
+    // zero side-effects. `AiQuotaDeniedError` is the only error this
+    // block intentionally surfaces; everything else is fail-open by
+    // default so a Redis/Postgres hiccup never blocks paying tenants.
+    if (args.ports.quotaStore) {
+        try {
+            await checkAndEnforce({
+                quotaStore: args.ports.quotaStore,
+                tenantId: args.ctx.tenantId,
+                surface: args.ctx.transport,
+            });
+        }
+        catch (e) {
+            if (e instanceof AiQuotaDeniedError) {
+                // Fire-and-forget telemetry for the deny — it landed
+                // in the audit log via the host's own `record` call
+                // when the over-cap call originally went through;
+                // this just surfaces the deny event for dashboards.
+                void telemetry.emit([
+                    {
+                        type: 'quota.consumed',
+                        tenantId: args.ctx.tenantId,
+                        surface: args.ctx.transport,
+                        window: 'day',
+                        used: e.payload.current,
+                        ceiling: e.payload.ceiling,
+                        denied: true,
+                        occurredAt: clock.now(),
+                    },
+                ]);
+                throw e;
+            }
+            if (failOpenOnQuotaError) {
+                logger.warn('runChatTurn quotaStore.check failed; failing open', {
+                    tenantId: args.ctx.tenantId,
+                    surface: args.ctx.transport,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    // ── 1. Model selection ──────────────────────────────────────────
+    const lastUserMessage = [...args.messages].reverse().find((m) => m.role === 'user');
+    const lastUserText = extractText(lastUserMessage);
+    const turnIndex = args.messages.filter((m) => m.role === 'user').length;
+    const selection = selectChatModel({
+        userMessage: lastUserText,
+        turnIndex,
+        forceTier: args.modelHint?.tier,
+        models: args.models,
+    });
+    // ── 2. Provider key + model instance ────────────────────────────
+    const apiKey = await args.ports.keyProvider.getKey('anthropic', args.ctx.tenantId);
+    const anthropic = createAnthropic({ apiKey });
+    const model = anthropic(selection.modelId);
+    // ── 3. Tools (adapter handles per-call audit) ───────────────────
+    const rawTools = buildAiSdkTools({
+        registry: args.tools,
+        ctx: args.ctx,
+        audit: args.ports.auditStore,
+        clock,
+    });
+    // ── 3b. Memory pull (optional) ──────────────────────────────────
+    // Load + format memory facts BEFORE the cache split so the facts
+    // land in the dynamic (uncached) segment. Memory varies per
+    // principal — caching it would split the prompt cache by user and
+    // kill cross-tenant reuse.
+    let memoryBlock = '';
+    if (args.ports.memoryStore && args.ctx.principal) {
+        try {
+            memoryBlock = await loadMemoryBlock({
+                memoryStore: args.ports.memoryStore,
+                scope: {
+                    tenantId: args.ctx.tenantId,
+                    principalId: args.ctx.principal.id,
+                    namespace: args.memoryNamespace,
+                },
+            });
+        }
+        catch (e) {
+            // Fail-open — memory is a UX enhancement, not a correctness
+            // requirement. Log and proceed without it.
+            logger.warn('runChatTurn memoryStore.load failed; proceeding without memory', {
+                tenantId: args.ctx.tenantId,
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    // ── 3c. Cache split ─────────────────────────────────────────────
+    // applyCacheBreakpoints renders `system` as a two-element array:
+    //   [0] static  — cached (cacheControl ephemeral marker)
+    //   [1] dynamic — uncached (tenant context + memory + now)
+    // The last tool in the registry also gets the cache marker so the
+    // tool schema block is served from cache on hot turns.
+    const dynamicLines = [args.systemPrompt.dynamic ?? '', memoryBlock]
+        .filter((s) => s.length > 0)
+        .join('\n\n');
+    const nowAtCacheSplit = clock.now();
+    const cached = applyCacheBreakpoints({
+        static: {
+            intro: args.systemPrompt.static,
+            corpus: '',
+            tools: rawTools,
+        },
+        dynamic: {
+            tenant: {
+                id: args.ctx.tenantId,
+                timezone: args.ctx.timezone,
+            },
+            principal: args.ctx.principal ? { id: args.ctx.principal.id } : undefined,
+            nowIso: nowAtCacheSplit.toISOString(),
+        },
+    });
+    // Append the host-supplied dynamic + memory content to the
+    // generated dynamic system segment so it lands AFTER the
+    // breakpoint. The structured tenant context that
+    // applyCacheBreakpoints synthesises is the first dynamic line;
+    // anything host-supplied follows it.
+    const dynamicMsg = cached.system[1];
+    if (dynamicMsg && dynamicLines.length > 0) {
+        dynamicMsg.content = `${dynamicMsg.content}\n${dynamicLines}`;
+    }
+    // ── 4. Reserve assistant turn row ───────────────────────────────
+    const startedAt = clock.now();
+    // Host-supplied turnId wins when present so the port impl can
+    // address rows it pre-created (typical pattern: route inserts
+    // a row, takes its primary key, passes it here as a string).
+    const turnId = args.turnId ?? makeTurnId(startedAt, args.ctx.requestId);
+    await args.ports.turnStore.upsert({
+        id: turnId,
+        threadId: args.threadId,
+        tenantId: args.ctx.tenantId,
+        role: 'assistant',
+        content: null,
+        status: 'pending',
+        modelId: selection.modelId,
+        createdAt: startedAt,
+        updatedAt: startedAt,
+    });
+    // ── 5. Stream ───────────────────────────────────────────────────
+    // Pass cached.system as the first messages so the Anthropic prompt
+    // cache picks up the static segment + tool schema on hot turns.
+    // streamText accepts both top-level `system` and inline system
+    // messages in `messages[]`; using inline lets us carry the
+    // cacheControl providerOptions through unchanged.
+    const userMessages = await convertToModelMessages(args.messages);
+    const stream = streamText({
+        model,
+        messages: [...cached.system, ...userMessages],
+        tools: cached.tools,
+        abortSignal: args.abortSignal,
+        onFinish: async (event) => {
+            const finishedAt = clock.now();
+            const durationMs = finishedAt.getTime() - startedAt.getTime();
+            // AI SDK v6 surfaces usage as `event.usage` with the
+            // shape { inputTokens, outputTokens, totalTokens } and
+            // optionally cachedInputTokens for providers that support
+            // prompt caching. Fall back to 0 to keep the cost
+            // arithmetic safe when fields are missing.
+            const usage = (event.usage ?? null);
+            const tokensIn = usage?.inputTokens ?? 0;
+            const tokensOut = usage?.outputTokens ?? 0;
+            const cacheReadTokens = usage?.cachedInputTokens ?? 0;
+            // Cache-write token count isn't exposed in the v6 usage
+            // object today. Tracked separately in cache-control.ts
+            // bookkeeping once slice 4 lands.
+            const cacheWriteTokens = 0;
+            const costUsd = estimateCost({
+                input: tokensIn,
+                output: tokensOut,
+                cacheRead: cacheReadTokens,
+                cacheWrite: cacheWriteTokens,
+            }, selection.modelId);
+            const costUsdMicro = Math.max(0, Math.round(costUsd * 1_000_000));
+            const finalTurn = {
+                id: turnId,
+                threadId: args.threadId,
+                tenantId: args.ctx.tenantId,
+                role: 'assistant',
+                content: event.text,
+                status: 'completed',
+                modelId: selection.modelId,
+                tokensIn,
+                tokensOut,
+                cacheReadTokens,
+                cacheWriteTokens,
+                costUsdMicro,
+                durationMs,
+                createdAt: startedAt,
+                updatedAt: finishedAt,
+            };
+            try {
+                await args.ports.turnStore.upsert(finalTurn);
+            }
+            catch (e) {
+                logger.error('runChatTurn turnStore.upsert failed', {
+                    turnId,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+            // Post-call quota accounting. Fire-and-forget — a slow
+            // ledger write must not stall the SSE finalisation. The
+            // tool-calls count comes from the AI SDK toolCalls list
+            // (may be absent if the turn didn't invoke any tools).
+            if (args.ports.quotaStore) {
+                const toolCallsCount = Array.isArray(event.toolCalls)
+                    ? (event.toolCalls.length)
+                    : 0;
+                args.ports.quotaStore
+                    .record({
+                    tenantId: args.ctx.tenantId,
+                    surface: args.ctx.transport,
+                    tokensIn,
+                    tokensOut,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                    toolCalls: toolCallsCount,
+                    costUsdMicro,
+                    modelId: selection.modelId,
+                    occurredAt: finishedAt,
+                })
+                    .catch((e) => {
+                    logger.warn('runChatTurn quotaStore.record failed', {
+                        turnId,
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                });
+            }
+            // Telemetry is fire-and-forget; emit failures are swallowed
+            // inside the sink and never block the stream finalisation.
+            void telemetry.emit([
+                {
+                    type: 'turn.finalized',
+                    turnId,
+                    threadId: args.threadId,
+                    tenantId: args.ctx.tenantId,
+                    modelId: selection.modelId,
+                    tier: selection.tier,
+                    tokensIn,
+                    tokensOut,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                    costUsdMicro,
+                    durationMs,
+                    occurredAt: finishedAt,
+                },
+            ]);
+            if (args.onTurnFinalized) {
+                try {
+                    await args.onTurnFinalized(finalTurn);
+                }
+                catch (e) {
+                    logger.error('runChatTurn onTurnFinalized hook threw', {
+                        turnId,
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            }
+        },
+        onError: async ({ error }) => {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error('runChatTurn streamText error', { turnId, message });
+            try {
+                await args.ports.turnStore.markFailed(turnId, {
+                    code: 'stream_error',
+                    message,
+                });
+            }
+            catch (e) {
+                logger.error('runChatTurn turnStore.markFailed failed', {
+                    turnId,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        },
+        onAbort: async () => {
+            try {
+                await args.ports.turnStore.markAborted(turnId, 'client-abort');
+            }
+            catch (e) {
+                logger.error('runChatTurn turnStore.markAborted failed', {
+                    turnId,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        },
+    });
+    return stream.toUIMessageStreamResponse();
+}
+/**
+ * Compose a turn id. Includes the request id when present so the
+ * persisted row can be cross-referenced against tracing without an
+ * extra join. Random suffix breaks ties on rapid same-ms turns.
+ */
+function makeTurnId(startedAt, requestId) {
+    const epochMs = startedAt.getTime();
+    const rand = Math.random().toString(36).slice(2, 8);
+    return requestId ? `turn_${epochMs}_${requestId}_${rand}` : `turn_${epochMs}_${rand}`;
+}
+function extractText(message) {
+    if (!message)
+        return '';
+    return message.parts
+        .filter((p) => p.type === 'text')
+        .map((p) => p.text)
+        .join('')
+        .trim();
+}
+//# sourceMappingURL=run-chat-turn.js.map

package/dist/runtime/run-chat-turn.js.map

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

package/dist/windows.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure window-math helpers for `QuotaStore` implementations.
+ *
+ * The kernel itself does NOT use these directly — `runChatTurn` calls
+ * `quotaStore.check()` and `quotaStore.record()` and trusts the port
+ * to handle the storage. These helpers are EXPORTED for hosts so each
+ * port impl computes consistent counter keys, TTLs, and reset times
+ * without re-deriving them.
+ *
+ * Naming + TTL conventions:
+ *   - Counter key:  `ai_quota:<metric>:<tenant>:<surface>:<window>`
+ *   - Daily TTL:    26h (survives DST + late writes after midnight).
+ *   - Hourly TTL:   65m (survives clock skew + late writes).
+ *
+ * All windows anchor to UTC. Multi-region replicas compute identical
+ * keys without coordinating clocks. Hosts that want a different
+ * timezone anchor should write their own helpers — most production
+ * deployments are happiest on UTC.
+ */
+export declare const DAY_SECONDS: number;
+export declare const HOUR_SECONDS: number;
+export declare const DAY_TTL_SECONDS: number;
+export declare const HOUR_TTL_SECONDS: number;
+/** UTC date key for daily windows. Format: `YYYY-MM-DD`. */
+export declare function dayKeyUtc(now?: Date): string;
+/** UTC hour key for hourly windows. Format: `YYYY-MM-DD-HH`. */
+export declare function hourKeyUtc(now?: Date): string;
+/** Unix seconds at the next UTC midnight from `now`. */
+export declare function nextUtcMidnight(now?: Date): number;
+/** Unix seconds at the next UTC hour boundary from `now`. */
+export declare function nextUtcHour(now?: Date): number;
+export interface WindowDescriptor {
+    /** Storage key — Redis, Postgres column, KV namespace — host's choice. */
+    key: string;
+    /** TTL in seconds for the storage backend (where applicable). */
+    ttl: number;
+    /** Unix seconds at which this window resets — render on the deny UX. */
+    resetAt: number;
+}
+interface WindowArgs {
+    tenantId: string;
+    surface: string;
+    now?: Date;
+}
+export declare function dailyTokensWindow({ tenantId, surface, now }: WindowArgs): WindowDescriptor;
+export declare function dailyCostWindow({ tenantId, surface, now }: WindowArgs): WindowDescriptor;
+export declare function hourlyToolCallsWindow({ tenantId, surface, now, }: WindowArgs): WindowDescriptor;
+export {};
+//# sourceMappingURL=windows.d.ts.map

package/dist/windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.d.ts","sourceRoot":"","sources":["../src/windows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,QAAe,CAAA;AACvC,eAAO,MAAM,YAAY,QAAU,CAAA;AACnC,eAAO,MAAM,eAAe,QAA6B,CAAA;AACzD,eAAO,MAAM,gBAAgB,QAAwB,CAAA;AAErD,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAExD;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAEzD;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAK9D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAa1D;AAED,MAAM,WAAW,gBAAgB;IAC7B,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,IAAI,CAAA;CACb;AAED,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAgB,EAAE,EAAE,UAAU,GAAG,gBAAgB,CAMvG;AAED,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAgB,EAAE,EAAE,UAAU,GAAG,gBAAgB,CAMrG;AAED,wBAAgB,qBAAqB,CAAC,EAClC,QAAQ,EACR,OAAO,EACP,GAAgB,GACnB,EAAE,UAAU,GAAG,gBAAgB,CAM/B"}

package/dist/windows.js

@@ -0,0 +1,63 @@
+/**
+ * Pure window-math helpers for `QuotaStore` implementations.
+ *
+ * The kernel itself does NOT use these directly — `runChatTurn` calls
+ * `quotaStore.check()` and `quotaStore.record()` and trusts the port
+ * to handle the storage. These helpers are EXPORTED for hosts so each
+ * port impl computes consistent counter keys, TTLs, and reset times
+ * without re-deriving them.
+ *
+ * Naming + TTL conventions:
+ *   - Counter key:  `ai_quota:<metric>:<tenant>:<surface>:<window>`
+ *   - Daily TTL:    26h (survives DST + late writes after midnight).
+ *   - Hourly TTL:   65m (survives clock skew + late writes).
+ *
+ * All windows anchor to UTC. Multi-region replicas compute identical
+ * keys without coordinating clocks. Hosts that want a different
+ * timezone anchor should write their own helpers — most production
+ * deployments are happiest on UTC.
+ */
+export const DAY_SECONDS = 60 * 60 * 24;
+export const HOUR_SECONDS = 60 * 60;
+export const DAY_TTL_SECONDS = DAY_SECONDS + HOUR_SECONDS; // 26h
+export const HOUR_TTL_SECONDS = HOUR_SECONDS + 60 * 5; // 65m
+/** UTC date key for daily windows. Format: `YYYY-MM-DD`. */
+export function dayKeyUtc(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/** UTC hour key for hourly windows. Format: `YYYY-MM-DD-HH`. */
+export function hourKeyUtc(now = new Date()) {
+    return now.toISOString().slice(0, 13);
+}
+/** Unix seconds at the next UTC midnight from `now`. */
+export function nextUtcMidnight(now = new Date()) {
+    const next = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1, 0, 0, 0, 0));
+    return Math.floor(next.getTime() / 1000);
+}
+/** Unix seconds at the next UTC hour boundary from `now`. */
+export function nextUtcHour(now = new Date()) {
+    const next = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), now.getUTCHours() + 1, 0, 0, 0));
+    return Math.floor(next.getTime() / 1000);
+}
+export function dailyTokensWindow({ tenantId, surface, now = new Date() }) {
+    return {
+        key: `ai_quota:tokens:${tenantId}:${surface}:${dayKeyUtc(now)}`,
+        ttl: DAY_TTL_SECONDS,
+        resetAt: nextUtcMidnight(now),
+    };
+}
+export function dailyCostWindow({ tenantId, surface, now = new Date() }) {
+    return {
+        key: `ai_quota:cost_cents:${tenantId}:${surface}:${dayKeyUtc(now)}`,
+        ttl: DAY_TTL_SECONDS,
+        resetAt: nextUtcMidnight(now),
+    };
+}
+export function hourlyToolCallsWindow({ tenantId, surface, now = new Date(), }) {
+    return {
+        key: `ai_quota:tool_calls:${tenantId}:${surface}:${hourKeyUtc(now)}`,
+        ttl: HOUR_TTL_SECONDS,
+        resetAt: nextUtcHour(now),
+    };
+}
+//# sourceMappingURL=windows.js.map

package/dist/windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.js","sourceRoot":"","sources":["../src/windows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,CAAA;AACnC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAA,CAAC,MAAM;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,GAAG,EAAE,GAAG,CAAC,CAAA,CAAC,MAAM;AAE5D,4DAA4D;AAC5D,MAAM,UAAU,SAAS,CAAC,MAAY,IAAI,IAAI,EAAE;IAC5C,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACzC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,MAAY,IAAI,IAAI,EAAE;IAC7C,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACzC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,MAAY,IAAI,IAAI,EAAE;IAClD,MAAM,IAAI,GAAG,IAAI,IAAI,CACjB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CACtF,CAAA;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAA;AAC5C,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAAC,MAAY,IAAI,IAAI,EAAE;IAC9C,MAAM,IAAI,GAAG,IAAI,IAAI,CACjB,IAAI,CAAC,GAAG,CACJ,GAAG,CAAC,cAAc,EAAE,EACpB,GAAG,CAAC,WAAW,EAAE,EACjB,GAAG,CAAC,UAAU,EAAE,EAChB,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,EACrB,CAAC,EACD,CAAC,EACD,CAAC,CACJ,CACJ,CAAA;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAA;AAC5C,CAAC;AAiBD,MAAM,UAAU,iBAAiB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE,EAAc;IACjF,OAAO;QACH,GAAG,EAAE,mBAAmB,QAAQ,IAAI,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE;QAC/D,GAAG,EAAE,eAAe;QACpB,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC;KAChC,CAAA;AACL,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE,EAAc;IAC/E,OAAO;QACH,GAAG,EAAE,uBAAuB,QAAQ,IAAI,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE;QACnE,GAAG,EAAE,eAAe;QACpB,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC;KAChC,CAAA;AACL,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,EAClC,QAAQ,EACR,OAAO,EACP,GAAG,GAAG,IAAI,IAAI,EAAE,GACP;IACT,OAAO;QACH,GAAG,EAAE,uBAAuB,QAAQ,IAAI,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE;QACpE,GAAG,EAAE,gBAAgB;QACrB,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC;KAC5B,CAAA;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "maestro-core",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "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",