maestro-core 0.1.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,GAChB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACH,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACtB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACzB,MAAM,gBAAgB,CAAA;AAGvB,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { err, isOk, ok } from './envelope.js';
+export { defineAgentTool, } from './tool.js';
+// Cross-cutting kernel utilities
+export { applyCacheBreakpoints, } from './cache-control.js';
+export { captureToolException, } from './safe-tool.js';
+// Ports re-exported at root for ergonomic single-import setups
+export * from './ports/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAoC,MAAM,eAAe,CAAA;AAC/E,OAAO,EAGH,eAAe,GAGlB,MAAM,WAAW,CAAA;AAElB,iCAAiC;AACjC,OAAO,EACH,qBAAqB,GAGxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,oBAAoB,GAGvB,MAAM,gBAAgB,CAAA;AAEvB,+DAA+D;AAC/D,cAAc,kBAAkB,CAAA"}

package/dist/ports/audit-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Append-only log of individual tool calls. The kernel writes one row
+ * per `execute` invocation (success, error, exception). Hosts use this
+ * for governance, abuse review, and cost attribution rollups.
+ *
+ * `recordToolCall` may return before the row is durable — the kernel
+ * calls it as fire-and-forget (`void store.recordToolCall(...)`) so a
+ * slow audit write does not stall the chat turn.
+ */
+export interface ToolCallAudit {
+    toolName: string;
+    transport: string;
+    actor: string;
+    tenantId: string;
+    principalId: string | null;
+    requestId: string | null;
+    /** Tool input as the model passed it. JSON-serializable. */
+    input: unknown;
+    /** Compact result — full envelope payloads can be huge; the model output is in TurnStore. */
+    output: {
+        ok: true;
+    } | {
+        ok: false;
+        code: string;
+        message: string;
+    };
+    durationMs: number;
+    createdAt: Date;
+}
+export interface AuditStore {
+    recordToolCall(audit: ToolCallAudit): Promise<void>;
+}
+//# sourceMappingURL=audit-store.d.ts.map

package/dist/ports/audit-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-store.d.ts","sourceRoot":"","sources":["../../src/ports/audit-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAA;IACd,6FAA6F;IAC7F,MAAM,EACA;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GACZ;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACvB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD"}

package/dist/ports/audit-store.js

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

package/dist/ports/audit-store.js.map

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

package/dist/ports/clock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Time-source port. The kernel routes every "now" through this so
+ * tests can advance time deterministically without mocking
+ * `global.Date`. Production hosts wire `SystemClock`.
+ *
+ * Hard rule: NO code under `src/` may call `new Date()` /
+ * `Date.now()` directly outside of `SystemClock`. Use the injected
+ * clock or accept a `Date` argument.
+ */
+export interface Clock {
+    now(): Date;
+}
+export declare class SystemClock implements Clock {
+    now(): Date;
+}
+/** Test helper — returns a fixed instant, never advances. */
+export declare class FixedClock implements Clock {
+    private readonly fixed;
+    constructor(fixed: Date);
+    now(): Date;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/ports/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK;IAClB,GAAG,IAAI,IAAI,CAAA;CACd;AAED,qBAAa,WAAY,YAAW,KAAK;IACrC,GAAG,IAAI,IAAI;CAGd;AAED,6DAA6D;AAC7D,qBAAa,UAAW,YAAW,KAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,IAAI;IAExC,GAAG,IAAI,IAAI;CAGd"}

package/dist/ports/clock.js

@@ -0,0 +1,16 @@
+export class SystemClock {
+    now() {
+        return new Date();
+    }
+}
+/** Test helper — returns a fixed instant, never advances. */
+export class FixedClock {
+    fixed;
+    constructor(fixed) {
+        this.fixed = fixed;
+    }
+    now() {
+        return this.fixed;
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/ports/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/ports/clock.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,WAAW;IACpB,GAAG;QACC,OAAO,IAAI,IAAI,EAAE,CAAA;IACrB,CAAC;CACJ;AAED,6DAA6D;AAC7D,MAAM,OAAO,UAAU;IACU;IAA7B,YAA6B,KAAW;QAAX,UAAK,GAAL,KAAK,CAAM;IAAG,CAAC;IAE5C,GAAG;QACC,OAAO,IAAI,CAAC,KAAK,CAAA;IACrB,CAAC;CACJ"}

package/dist/ports/index.d.ts

@@ -0,0 +1,9 @@
+export type { AuditStore, ToolCallAudit } from './audit-store.js';
+export { type Clock, FixedClock, SystemClock } from './clock.js';
+export { ConsoleLogger, type Logger, SilentLogger } from './logger.js';
+export type { MemoryRecord, MemoryScope, MemoryStore } from './memory-store.js';
+export type { ModelKeyProvider, ModelProvider } from './key-provider.js';
+export type { Ceilings, QuotaState, QuotaStore, QuotaUsage, QuotaWindow, } from './quota-store.js';
+export { NoopTelemetrySink, type TelemetryEvent, type TelemetrySink } from './telemetry-sink.js';
+export type { TurnRecord, TurnStore } from './turn-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,KAAK,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,KAAK,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACtE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/E,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EACR,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,GACd,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAChG,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/ports/index.js

@@ -0,0 +1,4 @@
+export { FixedClock, SystemClock } from './clock.js';
+export { ConsoleLogger, SilentLogger } from './logger.js';
+export { NoopTelemetrySink } from './telemetry-sink.js';
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,aAAa,EAAe,YAAY,EAAE,MAAM,aAAa,CAAA;AAUtE,OAAO,EAAE,iBAAiB,EAA2C,MAAM,qBAAqB,CAAA"}

package/dist/ports/key-provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Returns the model-provider API key the kernel should use for a given
+ * call. The host wires this from `process.env`, a secrets manager, or
+ * a per-tenant BYO-key table.
+ *
+ * Why a port: secret-fetch is host-defined (env layout, rotation
+ * cadence, multi-key load balancing). Kernel must not assume any of it.
+ */
+export type ModelProvider = 'anthropic' | 'openai';
+export interface ModelKeyProvider {
+    /**
+     * Resolve the key for the given provider. `tenantId` is passed so
+     * BYO-key hosts can return per-tenant keys; hosts with a single
+     * platform key can ignore it.
+     */
+    getKey(provider: ModelProvider, tenantId?: string): Promise<string>;
+}
+//# sourceMappingURL=key-provider.d.ts.map

package/dist/ports/key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-provider.d.ts","sourceRoot":"","sources":["../../src/ports/key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElD,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACtE"}

package/dist/ports/key-provider.js

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

package/dist/ports/key-provider.js.map

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

package/dist/ports/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured-logging port. Default `ConsoleLogger` is fine for dev;
+ * hosts wire pino / winston / Sentry breadcrumbs in production by
+ * implementing this interface.
+ */
+export interface Logger {
+    debug(msg: string, meta?: object): void;
+    info(msg: string, meta?: object): void;
+    warn(msg: string, meta?: object): void;
+    error(msg: string, meta?: object): void;
+}
+export declare class ConsoleLogger implements Logger {
+    debug(msg: string, meta?: object): void;
+    info(msg: string, meta?: object): void;
+    warn(msg: string, meta?: object): void;
+    error(msg: string, meta?: object): void;
+}
+/** Test helper — discards everything. */
+export declare class SilentLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/ports/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/ports/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACnB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C;AAED,qBAAa,aAAc,YAAW,MAAM;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAGvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAGtC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAGtC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;CAG1C;AAED,yCAAyC;AACzC,qBAAa,YAAa,YAAW,MAAM;IACvC,KAAK,IAAI,IAAI;IACb,IAAI,IAAI,IAAI;IACZ,IAAI,IAAI,IAAI;IACZ,KAAK,IAAI,IAAI;CAChB"}

package/dist/ports/logger.js

@@ -0,0 +1,22 @@
+export class ConsoleLogger {
+    debug(msg, meta) {
+        meta ? console.debug(msg, meta) : console.debug(msg);
+    }
+    info(msg, meta) {
+        meta ? console.info(msg, meta) : console.info(msg);
+    }
+    warn(msg, meta) {
+        meta ? console.warn(msg, meta) : console.warn(msg);
+    }
+    error(msg, meta) {
+        meta ? console.error(msg, meta) : console.error(msg);
+    }
+}
+/** Test helper — discards everything. */
+export class SilentLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+}
+//# sourceMappingURL=logger.js.map

package/dist/ports/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/ports/logger.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,aAAa;IACtB,KAAK,CAAC,GAAW,EAAE,IAAa;QAC5B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,CAAC,GAAW,EAAE,IAAa;QAC3B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACtD,CAAC;IACD,IAAI,CAAC,GAAW,EAAE,IAAa;QAC3B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACtD,CAAC;IACD,KAAK,CAAC,GAAW,EAAE,IAAa;QAC5B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACxD,CAAC;CACJ;AAED,yCAAyC;AACzC,MAAM,OAAO,YAAY;IACrB,KAAK,KAAU,CAAC;IAChB,IAAI,KAAU,CAAC;IACf,IAAI,KAAU,CAAC;IACf,KAAK,KAAU,CAAC;CACnB"}

package/dist/ports/memory-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-principal long-lived facts that should travel between threads
+ * within the same tenant. The model uses `saveMemoryTool` /
+ * `forgetMemoryTool` to write here; the kernel loads relevant entries
+ * into the system prompt.
+ *
+ * Scopes are intentionally narrow — never sweep across tenants. A
+ * sibling host may add an extra `namespace` axis for in-tenant
+ * partitioning (e.g. `'preferences'` vs `'facts'`).
+ */
+export interface MemoryScope {
+    tenantId: string;
+    principalId: string | null;
+    /** Optional sub-scope. Hosts that don't need it leave undefined. */
+    namespace?: string;
+}
+export interface MemoryRecord {
+    id: string;
+    scope: MemoryScope;
+    /** The fact, free-form natural language. */
+    fact: string;
+    /** Where the fact came from — usually a tool name or `'system'`. */
+    source: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface MemoryStore {
+    load(scope: MemoryScope): Promise<MemoryRecord[]>;
+    save(scope: MemoryScope, fact: string, source: string): Promise<MemoryRecord>;
+    forget(scope: MemoryScope, factId: string): Promise<void>;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/ports/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/ports/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,WAAW,CAAA;IAClB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IACjD,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAC7E,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5D"}

package/dist/ports/memory-store.js

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

package/dist/ports/memory-store.js.map

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

package/dist/ports/quota-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-tenant rate-limit and cost ceiling enforcement.
+ *
+ * Boundary of responsibility:
+ *   - Kernel owns the WINDOW ARITHMETIC (sliding window math, day
+ *     rollover, soft-cap warnings, `AiQuotaDeniedError`).
+ *   - Host owns the CEILING DERIVATION (plan-tier → numbers). Kernel
+ *     does not know what a "plan" is.
+ *
+ * `getCeilings` is called on every turn — keep it cheap (cache inside
+ * the host impl). `check` returns current consumption; `record`
+ * appends to the ledger (or telemetry) post-call.
+ */
+export type QuotaWindow = 'min' | 'hour' | 'day' | 'month';
+export interface Ceilings {
+    /** Max input tokens per window. Undefined = unbounded. */
+    maxTokensIn?: number;
+    /** Max output tokens per window. Undefined = unbounded. */
+    maxTokensOut?: number;
+    /** Max LLM calls per window. Undefined = unbounded. */
+    maxCallsPerWindow?: number;
+    /** Max spend per window, in USD micro-dollars (integer). Undefined = unbounded. */
+    maxUsdMicro?: number;
+}
+export interface QuotaState {
+    ceilings: Ceilings;
+    used: {
+        tokensIn: number;
+        tokensOut: number;
+        calls: number;
+        usdMicro: number;
+    };
+    windowStart: Date;
+    windowEnd: Date;
+}
+export interface QuotaUsage {
+    tenantId: string;
+    surface: string;
+    tokensIn: number;
+    tokensOut: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** USD cost in micro-dollars (integer). */
+    costUsdMicro: number;
+    modelId: string;
+    occurredAt: Date;
+}
+export interface QuotaStore {
+    /** Plan-derived ceilings for the requested surface + window. */
+    getCeilings(query: {
+        tenantId: string;
+        surface: string;
+        window: QuotaWindow;
+    }): Promise<Ceilings>;
+    /** Current consumption against ceilings for the current window. */
+    check(query: {
+        tenantId: string;
+        surface: string;
+    }): Promise<QuotaState>;
+    /** Append-only ledger write, called post-LLM-call. */
+    record(usage: QuotaUsage): Promise<void>;
+}
+//# sourceMappingURL=quota-store.d.ts.map

package/dist/ports/quota-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-store.d.ts","sourceRoot":"","sources":["../../src/ports/quota-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,QAAQ;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE;QACF,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,IAAI,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,gEAAgE;IAChE,WAAW,CAAC,KAAK,EAAE;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,WAAW,CAAA;KACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAErB,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAExE,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C"}

package/dist/ports/quota-store.js

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

package/dist/ports/quota-store.js.map

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

package/dist/ports/telemetry-sink.d.ts

@@ -0,0 +1,71 @@
+import type { QuotaWindow } from './quota-store.js';
+/**
+ * Best-effort observability events. Kernel emits these as a batched
+ * fire-and-forget stream. Hosts ship to: maestro-plane, Sentry, OTel,
+ * Datadog, or a no-op for self-hosted-only setups.
+ *
+ * Contract: emit MUST eventually settle (resolve or reject). The
+ * kernel will not block a chat turn on this — slow emits just back up
+ * the in-memory queue and eventually drop after retries.
+ */
+export type TelemetryEvent = {
+    type: 'turn.finalized';
+    turnId: string;
+    threadId: string;
+    tenantId: string;
+    modelId: string;
+    tier: 'fast' | 'smart';
+    tokensIn: number;
+    tokensOut: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** USD cost in micro-dollars (integer). */
+    costUsdMicro: number;
+    durationMs: number;
+    occurredAt: Date;
+} | {
+    type: 'tool.called';
+    toolName: string;
+    tenantId: string;
+    transport: string;
+    actor: string;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string;
+    occurredAt: Date;
+} | {
+    type: 'quota.consumed';
+    tenantId: string;
+    surface: string;
+    window: QuotaWindow;
+    used: number;
+    ceiling: number;
+    denied: boolean;
+    occurredAt: Date;
+} | {
+    type: 'model.failover';
+    tenantId: string;
+    from: string;
+    to: string;
+    reason: string;
+    occurredAt: Date;
+} | {
+    type: 'empty.recovery';
+    tenantId: string;
+    surface: string;
+    mode: string;
+    occurredAt: Date;
+};
+export interface TelemetrySink {
+    /** Batched async send. Implementations should handle batching + retries internally. */
+    emit(events: TelemetryEvent[]): Promise<void>;
+}
+/**
+ * Default sink — drops everything. Used when the host doesn't want
+ * telemetry (single-tenant deploy, dev environment, before maestro-plane
+ * exists). Kernel always works with this wired.
+ */
+export declare class NoopTelemetrySink implements TelemetrySink {
+    emit(): Promise<void>;
+}
+//# sourceMappingURL=telemetry-sink.d.ts.map

package/dist/ports/telemetry-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-sink.d.ts","sourceRoot":"","sources":["../../src/ports/telemetry-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACpB;IACI,IAAI,EAAE,gBAAgB,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,IAAI,CAAA;CACnB,GACD;IACI,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,EAAE,EAAE,OAAO,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,IAAI,CAAA;CACnB,GACD;IACI,IAAI,EAAE,gBAAgB,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,WAAW,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,IAAI,CAAA;CACnB,GACD;IACI,IAAI,EAAE,gBAAgB,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,IAAI,CAAA;CACnB,GACD;IACI,IAAI,EAAE,gBAAgB,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,IAAI,CAAA;CACnB,CAAA;AAEP,MAAM,WAAW,aAAa;IAC1B,uFAAuF;IACvF,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}

package/dist/ports/telemetry-sink.js

@@ -0,0 +1,11 @@
+/**
+ * Default sink — drops everything. Used when the host doesn't want
+ * telemetry (single-tenant deploy, dev environment, before maestro-plane
+ * exists). Kernel always works with this wired.
+ */
+export class NoopTelemetrySink {
+    async emit() {
+        // Intentionally empty.
+    }
+}
+//# sourceMappingURL=telemetry-sink.js.map

package/dist/ports/telemetry-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-sink.js","sourceRoot":"","sources":["../../src/ports/telemetry-sink.ts"],"names":[],"mappings":"AAsEA;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAC1B,KAAK,CAAC,IAAI;QACN,uBAAuB;IAC3B,CAAC;CACJ"}

package/dist/ports/turn-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Persists chat-turn rows. The kernel writes one row per user turn and
+ * one per assistant turn, updates it as the turn completes, and reads
+ * history when assembling the next prompt.
+ *
+ * Why this is a port (not direct Prisma):
+ * - Each host has a different schema. Barbeiro's `HelpChatMessage` has
+ *   help-specific fields (`surface`, `articleSlug`, `gap_reason`) a
+ *   sibling product won't share. The port lets each host map
+ *   `TurnRecord` → its own table.
+ * - This is the test seam. Unit tests get an in-memory implementation;
+ *   integration tests get a real DB. Prisma-direct = every test needs
+ *   a DB up.
+ */
+export interface TurnRecord {
+    /** Host-generated id (cuid/uuid). */
+    id: string;
+    /** Thread the turn belongs to. */
+    threadId: string;
+    /** Tenant scope (same as `BaseToolContext.tenantId`). */
+    tenantId: string;
+    /** Conversation role. */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** JSON-serializable payload — host renders it. */
+    content: unknown;
+    /** Turn lifecycle state. */
+    status: 'pending' | 'completed' | 'failed' | 'aborted';
+    /** Optional metering metadata (filled in by `runChatTurn`). */
+    modelId?: string;
+    tokensIn?: number;
+    tokensOut?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** USD cost in micro-dollars (integer) — avoids float drift in aggregates. */
+    costUsdMicro?: number;
+    durationMs?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Host-attached extras. Kernel does not interpret. */
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface TurnStore {
+    /**
+     * Insert or update a turn by `id`. Called multiple times per turn:
+     * once on dispatch (status=pending), once on completion or failure.
+     */
+    upsert(turn: TurnRecord): Promise<void>;
+    /** Recent history for prompt assembly, oldest-first. */
+    loadHistory(threadId: string, limit?: number): Promise<TurnRecord[]>;
+    /** Terminal mark — kernel calls this when the model call rejects. */
+    markFailed(turnId: string, error: {
+        code: string;
+        message: string;
+    }): Promise<void>;
+    /** Terminal mark — kernel calls this on abort signal. */
+    markAborted(turnId: string, reason: string): Promise<void>;
+}
+//# sourceMappingURL=turn-store.d.ts.map

package/dist/ports/turn-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-store.d.ts","sourceRoot":"","sources":["../../src/ports/turn-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACvB,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC9C,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,4BAA4B;IAC5B,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;IAEtD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IAEzC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAElC,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACtB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvC,wDAAwD;IACxD,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAEpE,qEAAqE;IACrE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnF,yDAAyD;IACzD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7D"}

package/dist/ports/turn-store.js

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

package/dist/ports/turn-store.js.map

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

package/dist/safe-tool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Capture a tool-execute exception so observability tooling (Sentry,
+ * OTel, Datadog, custom) sees a uniform alert without each adapter
+ * inventing its own catch block.
+ *
+ * The kernel does NOT depend on a specific observability SDK. Hosts
+ * wire one by passing an `onError` callback to the adapter builders;
+ * the adapter calls this helper to format the tags and invoke the
+ * callback.
+ *
+ * Important: the throw is intentionally NOT swallowed by the adapter
+ * that calls this helper. AI SDK / MCP need the rejection to mark
+ * the tool result as `error` so the model sees it and can recover.
+ * Swallowing would surface as the assistant continuing as if the tool
+ * had succeeded.
+ */
+export interface ToolExceptionTags {
+    /** Tool that threw. */
+    toolName: string;
+    /** Surface invoking the tool. */
+    transport: string;
+    /** Who authorised the call. */
+    actor: string;
+    /** Tenant scope. */
+    tenantId: string;
+    /** Principal id if known, else null. */
+    principalId?: string | null;
+    /** Trace id, if any. */
+    requestId?: string | null;
+}
+export type ToolExceptionHandler = (error: unknown, tags: ToolExceptionTags) => void;
+/**
+ * Invoke the host's observability handler, if provided, with structured
+ * tags. Errors thrown by the handler itself are swallowed — observability
+ * must never break the chat turn.
+ */
+export declare function captureToolException(error: unknown, tags: ToolExceptionTags, onError?: ToolExceptionHandler): void;
+//# sourceMappingURL=safe-tool.d.ts.map

package/dist/safe-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-tool.d.ts","sourceRoot":"","sources":["../src/safe-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAC9B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAEpF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC/B,IAAI,CAON"}

package/dist/safe-tool.js

@@ -0,0 +1,16 @@
+/**
+ * Invoke the host's observability handler, if provided, with structured
+ * tags. Errors thrown by the handler itself are swallowed — observability
+ * must never break the chat turn.
+ */
+export function captureToolException(error, tags, onError) {
+    if (!onError)
+        return;
+    try {
+        onError(error, tags);
+    }
+    catch {
+        // Intentional swallow — see doc above.
+    }
+}
+//# sourceMappingURL=safe-tool.js.map

package/dist/safe-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-tool.js","sourceRoot":"","sources":["../src/safe-tool.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAChC,KAAc,EACd,IAAuB,EACvB,OAA8B;IAE9B,IAAI,CAAC,OAAO;QAAE,OAAM;IACpB,IAAI,CAAC;QACD,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACL,uCAAuC;IAC3C,CAAC;AACL,CAAC"}