@retinue/agentkit 0.1.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * MCP — outbound server consumption. `@proposed`: no specification section covers this
+ * yet, so these contracts are the open proposal, not settled design.
+ *
+ * Direction matters. The repository already ships an *inbound* MCP server
+ * (`web/src/lib/mcp/server.ts`) that exposes Chorus tools to external clients. This
+ * module is the other direction: a tenant registers their own MCP server and the
+ * assistant gains its tools.
+ *
+ * An imported tool is a `ToolProvider` like any other, which means it inherits the
+ * whole authorization and approval path rather than sitting beside it.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { TenantId } from "../core/ids.js";
+import type { ToolDescriptor, ToolEffect, ToolProvider } from "../tools/index.js";
+export declare const MCP_TRANSPORTS: readonly ["stdio", "streamable-http", "sse"];
+export type McpTransport = (typeof MCP_TRANSPORTS)[number];
+export type McpAuth = {
+    readonly kind: "none";
+} | {
+    readonly kind: "bearer";
+    readonly credentialRef: string;
+} | {
+    readonly kind: "oauth";
+    readonly credentialRef: string;
+};
+/**
+ * Credentials are referenced, never inlined — `credentialRef` points at secret storage.
+ * Nothing in this record may reach model context.
+ */
+export type McpServerConnection = {
+    readonly id: string;
+    readonly tenantId: TenantId;
+    readonly label: string;
+    readonly transport: McpTransport;
+    /** URL for HTTP transports, command for stdio. Validated against the egress policy. */
+    readonly endpoint: string;
+    readonly auth: McpAuth;
+    readonly enabled: boolean;
+    readonly createdAt: string;
+    readonly lastHandshakeAt?: string;
+    readonly lastError?: string;
+};
+/**
+ * MCP does not classify side effects the way the platform does. `readOnlyHint` and
+ * `destructiveHint` are advisory and come from the remote server, which is untrusted.
+ * So classification defaults to the safe end and only an administrator can relax it.
+ */
+export type McpToolHints = {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly openWorldHint?: boolean;
+};
+export type McpToolClassification = {
+    readonly effect: ToolEffect;
+    readonly source: "hint" | "administrator" | "default";
+};
+/**
+ * Safe default: anything not explicitly classified by an administrator is treated as an
+ * external write and requires approval. A remote server cannot talk its way down to
+ * `read` — a `readOnlyHint` alone is not enough, because the hint is attacker-controlled
+ * when the server is.
+ */
+export declare const classifyMcpTool: (hints: McpToolHints, administratorEffect?: ToolEffect) => McpToolClassification;
+/** Namespaced so two servers exposing `search` cannot collide. */
+export declare const mcpToolName: (serverId: string, toolName: string) => string;
+/**
+ * MCP servers may change their tool list between calls. The run records a hash of what
+ * it discovered, so a catalog that shifted mid-run is detectable after the fact.
+ */
+export type McpCatalogSnapshot = {
+    readonly connectionId: string;
+    readonly toolListHash: string;
+    readonly discoveredAt: string;
+    readonly tools: readonly ToolDescriptor[];
+};
+/** Bridges one connection into the ordinary tool pipeline. */
+export interface McpToolProvider extends ToolProvider {
+    readonly connectionId: string;
+    snapshot(context: ExecutionContext): Promise<McpCatalogSnapshot>;
+}
+/**
+ * MCP resources and prompts are context, not tools. They belong on the context-provider
+ * path so they are budgeted and pruned like every other section.
+ */
+export type McpResourceRef = {
+    readonly connectionId: string;
+    readonly uri: string;
+    readonly mimeType?: string;
+};
+export * from "./egress.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.js

@@ -0,0 +1,33 @@
+/**
+ * MCP — outbound server consumption. `@proposed`: no specification section covers this
+ * yet, so these contracts are the open proposal, not settled design.
+ *
+ * Direction matters. The repository already ships an *inbound* MCP server
+ * (`web/src/lib/mcp/server.ts`) that exposes Chorus tools to external clients. This
+ * module is the other direction: a tenant registers their own MCP server and the
+ * assistant gains its tools.
+ *
+ * An imported tool is a `ToolProvider` like any other, which means it inherits the
+ * whole authorization and approval path rather than sitting beside it.
+ */
+export const MCP_TRANSPORTS = ["stdio", "streamable-http", "sse"];
+/**
+ * Safe default: anything not explicitly classified by an administrator is treated as an
+ * external write and requires approval. A remote server cannot talk its way down to
+ * `read` — a `readOnlyHint` alone is not enough, because the hint is attacker-controlled
+ * when the server is.
+ */
+export const classifyMcpTool = (hints, administratorEffect) => {
+    if (administratorEffect !== undefined) {
+        return { effect: administratorEffect, source: "administrator" };
+    }
+    if (hints.destructiveHint === true) {
+        return { effect: "destructive", source: "hint" };
+    }
+    return { effect: "external-write", source: "default" };
+};
+/** Namespaced so two servers exposing `search` cannot collide. */
+export const mcpToolName = (serverId, toolName) => `mcp__${serverId}__${toolName}`;
+export * from "./egress.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/provider.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MCP tool provider & connection store — `docs/10-mcp-integration.md`.
+ *
+ * Bridges a tenant's MCP server into the ordinary tool pipeline: each remote tool becomes a `Tool`
+ * with a platform-classified effect, an `mcp__<server>__<tool>` namespaced name, and an approval
+ * policy derived from that effect — so imported tools inherit the whole authorization + approval
+ * path instead of sitting beside it. Effects are classified safe-by-default (untrusted hints cannot
+ * reach `read`; only an administrator can relax). A per-run catalog snapshot hash makes a tool list
+ * that shifted mid-run detectable after the fact. Connections are tenant-scoped and never expose
+ * credentials — auth carries only a `credentialRef`, and the model-facing view is redacted.
+ */
+import type { TenantId } from "../core/ids.js";
+import type { ToolEffect } from "../tools/index.js";
+import { type McpCatalogSnapshot, type McpServerConnection, type McpToolHints, type McpToolProvider } from "./index.js";
+/** A remote tool as reported by an MCP server. Untrusted — descriptions/schemas are attacker data. */
+export type McpRemoteTool = {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: unknown;
+    readonly outputSchema?: unknown;
+    readonly hints?: McpToolHints;
+};
+/** The MCP client the host wires to a real transport. Kept minimal and injectable for tests. */
+export interface McpClient {
+    listTools(): Promise<readonly McpRemoteTool[]>;
+    callTool(name: string, input: unknown): Promise<unknown>;
+}
+/** Deterministic, order-independent hash of a tool list, for catalog-drift detection. */
+export declare const hashToolList: (tools: readonly {
+    name: string;
+}[]) => string;
+/** True when the two snapshots describe different tool lists — i.e. the catalog drifted. */
+export declare const detectCatalogDrift: (a: McpCatalogSnapshot, b: McpCatalogSnapshot) => boolean;
+export declare const createMcpToolProvider: (config: {
+    readonly connection: McpServerConnection;
+    readonly client: McpClient;
+    /** Administrator effect classifications by remote tool name (relaxes the safe default). */
+    readonly adminEffects?: Readonly<Record<string, ToolEffect>>;
+    readonly clock?: () => string;
+}) => McpToolProvider;
+/** The model/log-safe view of a connection: no endpoint, no credential reference at all. */
+export declare const redactConnection: (connection: McpServerConnection) => Pick<McpServerConnection, "id" | "tenantId" | "label" | "transport" | "enabled">;
+/** Tenant-scoped connection registry. Endpoints are egress-validated before storage. */
+export interface McpConnectionStore {
+    register(input: {
+        tenantId: TenantId;
+        connection: McpServerConnection;
+    }): Promise<void>;
+    get(input: {
+        tenantId: TenantId;
+        id: string;
+    }): Promise<McpServerConnection | null>;
+    list(input: {
+        tenantId: TenantId;
+    }): Promise<readonly McpServerConnection[]>;
+    setEnabled(input: {
+        tenantId: TenantId;
+        id: string;
+        enabled: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/models/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Model platform — `docs/03-intelligence-runtime.md`.
+ *
+ * Provider-neutral. Agents state a policy and a role; they never hardcode model IDs.
+ */
+export declare const MODEL_PROVIDERS: readonly ["openai", "anthropic", "google", "mistral", "azure-openai", "bedrock", "openai-compatible"];
+export type ModelProvider = (typeof MODEL_PROVIDERS)[number];
+export type ModelLifecycle = "preview" | "generally-available" | "deprecated" | "retired";
+export type InputModality = "text" | "image" | "audio" | "video" | "pdf";
+export type ModelCapabilities = {
+    readonly tools: boolean;
+    readonly structuredOutput: boolean;
+    readonly reasoning: boolean;
+    readonly nativeSearch: boolean;
+};
+export type ModelLimits = {
+    readonly contextTokens: number;
+    readonly maxOutputTokens: number;
+};
+/** Prices are per million tokens, in minor currency units, to avoid float drift. */
+export type ModelPricing = {
+    readonly currency: string;
+    readonly inputPerMillion: number;
+    readonly outputPerMillion: number;
+    readonly cacheReadPerMillion?: number;
+    readonly cacheWritePerMillion?: number;
+    /**
+     * How this provider charges for non-text input — REQ-036 (#185), AC-4.
+     *
+     * The field exists because getting it wrong is a wrong bill in **either** direction, and the two conventions
+     * are indistinguishable from the token counts alone:
+     *
+     * - `"in-input-tokens"` (the default, and what OpenAI does): an image is converted to input tokens by the
+     *   provider and already counted in `inputTokens`. Adding a per-image charge on top **double-bills**.
+     * - `"per-unit"`: images and audio are billed separately, per image or per second, *in addition* to the text
+     *   tokens. Not adding the charge **under-bills**, silently, and the shortfall scales with usage.
+     *
+     * Defaulting to `"in-input-tokens"` is the safe direction for the model catalogue we ship, and it means every
+     * existing pricing record keeps costing exactly what it did.
+     */
+    readonly nonTextInput?: "in-input-tokens" | "per-unit";
+    /** Minor units per image sent. Only consulted when `nonTextInput` is `"per-unit"`. */
+    readonly perImageMinorUnits?: number;
+    /** Minor units per second of audio input. Only consulted when `nonTextInput` is `"per-unit"`. */
+    readonly perAudioSecondMinorUnits?: number;
+};
+export type ModelDefinition = {
+    readonly provider: ModelProvider;
+    readonly modelId: string;
+    readonly label: string;
+    readonly lifecycle: ModelLifecycle;
+    readonly inputModalities: readonly InputModality[];
+    readonly capabilities: ModelCapabilities;
+    readonly limits: ModelLimits;
+    readonly pricing: ModelPricing;
+    /** ISO 3166 regions the provider will process this model's data in. */
+    readonly dataResidency: readonly string[];
+};
+/** `fast` and `smart` let an agent express intent without naming a model. */
+export type ModelRole = "fast" | "smart";
+export type ModelPolicy = {
+    readonly role: ModelRole;
+    readonly requiredCapabilities?: Partial<ModelCapabilities>;
+    readonly requiredModalities?: readonly InputModality[];
+    readonly allowedProviders?: readonly ModelProvider[];
+    readonly dataResidency?: readonly string[];
+    /** Ceiling per run, in the pricing currency's minor units. */
+    readonly costCeilingMinorUnits?: number;
+};
+/**
+ * Resolution considers administrator policy, tenant policy, required capabilities,
+ * data residency, availability, cost ceiling and deprecation state.
+ */
+export interface ModelRegistry {
+    list(): readonly ModelDefinition[];
+    resolve(policy: ModelPolicy): ModelDefinition;
+}
+/** Administrator/tenant policy: ordered candidate model IDs per role (most preferred first). */
+export type ModelRoleAssignments = Readonly<Record<ModelRole, readonly string[]>>;
+export type ModelRegistryConfig = {
+    readonly models: readonly ModelDefinition[];
+    readonly roles: ModelRoleAssignments;
+};
+/**
+ * Resolves a role + constraints to a concrete model using the administrator's role assignments.
+ * Agents never name a model, so re-pointing a role here changes no agent code.
+ */
+export declare const createModelRegistry: (config: ModelRegistryConfig) => ModelRegistry;
+/**
+ * `provider-factory` is **not** re-exported here — #196.
+ *
+ * It statically imports six `@ai-sdk/*` packages, so anything that pulls this barrel pulled all six. Since they
+ * are optional peers now, a root import must not reach them: a consumer using OpenAI would get a resolution
+ * failure for Anthropic. It lives behind the `./providers` subpath instead.
+ */
+export { computeModelCostMinorUnits } from "./pricing.js";
+export * from "./streaming.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/models/index.js

@@ -0,0 +1,74 @@
+/**
+ * Model platform — `docs/03-intelligence-runtime.md`.
+ *
+ * Provider-neutral. Agents state a policy and a role; they never hardcode model IDs.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+export const MODEL_PROVIDERS = [
+    "openai",
+    "anthropic",
+    "google",
+    "mistral",
+    "azure-openai",
+    "bedrock",
+    "openai-compatible",
+];
+const covers = (have, need) => need.every((n) => have.includes(n));
+/** A model is eligible when it clears every hard constraint in the policy. */
+const eligible = (m, p) => {
+    if (m.lifecycle === "retired")
+        return false;
+    if (p.allowedProviders && !p.allowedProviders.includes(m.provider))
+        return false;
+    if (p.requiredModalities && !covers(m.inputModalities, p.requiredModalities))
+        return false;
+    if (p.dataResidency && !covers(m.dataResidency, p.dataResidency))
+        return false;
+    if (p.requiredCapabilities) {
+        for (const key of Object.keys(p.requiredCapabilities)) {
+            if (p.requiredCapabilities[key] && !m.capabilities[key])
+                return false;
+        }
+    }
+    // Cost ceiling is honored at resolution as an output-price ceiling; the per-run budget is
+    // separately enforced at execution by the usage recorder.
+    if (p.costCeilingMinorUnits !== undefined && m.pricing.outputPerMillion > p.costCeilingMinorUnits) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Resolves a role + constraints to a concrete model using the administrator's role assignments.
+ * Agents never name a model, so re-pointing a role here changes no agent code.
+ */
+export const createModelRegistry = (config) => {
+    const byId = new Map(config.models.map((m) => [m.modelId, m]));
+    return {
+        list: () => config.models,
+        resolve: (policy) => {
+            for (const id of config.roles[policy.role] ?? []) {
+                const m = byId.get(id);
+                if (m && eligible(m, policy))
+                    return m;
+            }
+            throw new AgentPlatformError({
+                code: "capability_unavailable",
+                message: `No model satisfies role '${policy.role}' with the requested constraints`,
+                retryable: false,
+            });
+        },
+    };
+};
+/**
+ * `provider-factory` is **not** re-exported here — #196.
+ *
+ * It statically imports six `@ai-sdk/*` packages, so anything that pulls this barrel pulled all six. Since they
+ * are optional peers now, a root import must not reach them: a consumer using OpenAI would get a resolution
+ * failure for Anthropic. It lives behind the `./providers` subpath instead.
+ */
+// `computeModelCostMinorUnits` moved to `./pricing.ts` (#199): reaching it through this barrel pulled
+// `streaming.js`, and with it the AI SDK, into the in-memory usage adapter. Re-exported here so the models
+// subpath still offers it in one place.
+export { computeModelCostMinorUnits } from "./pricing.js";
+export * from "./streaming.js";
+//# sourceMappingURL=index.js.map

package/dist/models/pricing.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a unit of usage costs — extracted from the models barrel (#199).
+ *
+ * Its own module because of what importing it used to drag in. `usage/recorder.ts` needs this one function, and
+ * reaching it through `models/index.js` pulled `streaming.js` with it — and `streaming.js` imports `ai`. So the
+ * in-memory usage adapter, which needs no model SDK and no network, transitively reached the AI SDK: a consumer
+ * importing `@retinue/agentkit/persistence` for an in-memory prototype loaded a provider library to do it.
+ *
+ * Nothing about the pricing arithmetic connects it to streaming. The barrel was the only thing joining them.
+ */
+import type { ModelPricing } from "./index.js";
+/**
+ * Cost of a unit of usage, in the pricing currency's minor units. Prices are per-million tokens.
+ * Cached input is billed at the cache-read rate when present. This is what feeds usage accounting.
+ */
+export declare const computeModelCostMinorUnits: (pricing: ModelPricing, usage: {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens?: number;
+    /** Images sent with the turn — counted from the parts, not from the provider. See `NeutralUsage`. */
+    readonly imageCount?: number;
+    readonly audioSeconds?: number;
+}) => number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/models/pricing.js

@@ -0,0 +1,37 @@
+/**
+ * What a unit of usage costs — extracted from the models barrel (#199).
+ *
+ * Its own module because of what importing it used to drag in. `usage/recorder.ts` needs this one function, and
+ * reaching it through `models/index.js` pulled `streaming.js` with it — and `streaming.js` imports `ai`. So the
+ * in-memory usage adapter, which needs no model SDK and no network, transitively reached the AI SDK: a consumer
+ * importing `@retinue/agentkit/persistence` for an in-memory prototype loaded a provider library to do it.
+ *
+ * Nothing about the pricing arithmetic connects it to streaming. The barrel was the only thing joining them.
+ */
+/**
+ * Cost of a unit of usage, in the pricing currency's minor units. Prices are per-million tokens.
+ * Cached input is billed at the cache-read rate when present. This is what feeds usage accounting.
+ */
+export const computeModelCostMinorUnits = (pricing, usage) => {
+    const cachedIn = usage.cachedInputTokens ?? 0;
+    const freshIn = Math.max(0, usage.inputTokens - cachedIn);
+    const perMillion = (tokens, price) => (tokens * price) / 1_000_000;
+    const tokenCost = perMillion(freshIn, pricing.inputPerMillion) +
+        perMillion(cachedIn, pricing.cacheReadPerMillion ?? pricing.inputPerMillion) +
+        perMillion(usage.outputTokens, pricing.outputPerMillion);
+    /**
+     * Non-text input, charged **only** where the provider prices it separately — #185 AC-4.
+     *
+     * The default is `"in-input-tokens"`, which means the image is already inside `inputTokens` and there is
+     * nothing to add. Adding it anyway is the double-bill this branch exists to prevent, and it would not show up
+     * in any test that only ever passes text.
+     */
+    if (pricing.nonTextInput !== "per-unit")
+        return Math.round(tokenCost);
+    const images = Math.max(0, usage.imageCount ?? 0);
+    const seconds = Math.max(0, usage.audioSeconds ?? 0);
+    return Math.round(tokenCost +
+        images * (pricing.perImageMinorUnits ?? 0) +
+        seconds * (pricing.perAudioSecondMinorUnits ?? 0));
+};
+//# sourceMappingURL=pricing.js.map

package/dist/models/provider-factory.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Provider factory — `docs/03-intelligence-runtime.md`.
+ *
+ * Turns a resolved `ModelDefinition` into a concrete Vercel AI SDK language model. The AI SDK
+ * imports are confined to this `models` layer (enforced by the dependency-boundary check); the
+ * rest of the platform speaks the neutral `ModelDefinition`/`ModelPolicy` contracts.
+ *
+ * Credentials are supplied per provider (supporting a tenant's BYO keys) and never inlined into
+ * a model definition.
+ */
+import type { LanguageModel } from "ai";
+import type { ModelDefinition, ModelProvider } from "./index.js";
+/** Per-provider credentials. `apiKey`/`baseURL` fall back to the SDK's env defaults when unset. */
+export type ProviderCredentials = {
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+    /** Azure only. */
+    readonly resourceName?: string;
+    readonly apiVersion?: string;
+    /** A display name for OpenAI-compatible endpoints. */
+    readonly name?: string;
+};
+export type ProviderFactoryConfig = {
+    readonly credentials?: Partial<Record<ModelProvider, ProviderCredentials>>;
+};
+export interface ProviderFactory {
+    /** The AI SDK language model for a resolved definition, ready for generate/stream. */
+    languageModel(model: ModelDefinition): LanguageModel;
+}
+export declare const createProviderFactory: (config?: ProviderFactoryConfig) => ProviderFactory;
+//# sourceMappingURL=provider-factory.d.ts.map

package/dist/models/provider-factory.js

@@ -0,0 +1,67 @@
+/**
+ * Provider factory — `docs/03-intelligence-runtime.md`.
+ *
+ * Turns a resolved `ModelDefinition` into a concrete Vercel AI SDK language model. The AI SDK
+ * imports are confined to this `models` layer (enforced by the dependency-boundary check); the
+ * rest of the platform speaks the neutral `ModelDefinition`/`ModelPolicy` contracts.
+ *
+ * Credentials are supplied per provider (supporting a tenant's BYO keys) and never inlined into
+ * a model definition.
+ */
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createAzure } from "@ai-sdk/azure";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createMistral } from "@ai-sdk/mistral";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { AgentPlatformError } from "../core/errors.js";
+export const createProviderFactory = (config = {}) => {
+    const cred = (p) => config.credentials?.[p] ?? {};
+    return {
+        languageModel(model) {
+            const c = cred(model.provider);
+            switch (model.provider) {
+                case "openai":
+                    return createOpenAI({ apiKey: c.apiKey, baseURL: c.baseURL })(model.modelId);
+                case "anthropic":
+                    return createAnthropic({ apiKey: c.apiKey, baseURL: c.baseURL })(model.modelId);
+                case "google":
+                    return createGoogleGenerativeAI({ apiKey: c.apiKey, baseURL: c.baseURL })(model.modelId);
+                case "mistral":
+                    return createMistral({ apiKey: c.apiKey, baseURL: c.baseURL })(model.modelId);
+                case "azure-openai":
+                    return createAzure({
+                        apiKey: c.apiKey,
+                        resourceName: c.resourceName,
+                        baseURL: c.baseURL,
+                        apiVersion: c.apiVersion,
+                    })(model.modelId);
+                case "openai-compatible":
+                    if (!c.baseURL) {
+                        throw new AgentPlatformError({
+                            code: "capability_unavailable",
+                            message: "openai-compatible provider requires a baseURL credential",
+                            retryable: false,
+                        });
+                    }
+                    return createOpenAICompatible({ name: c.name ?? "openai-compatible", baseURL: c.baseURL, apiKey: c.apiKey })(model.modelId);
+                case "bedrock":
+                    // Bedrock wiring (@ai-sdk/amazon-bedrock + AWS credentials) is a follow-up.
+                    throw new AgentPlatformError({
+                        code: "capability_unavailable",
+                        message: "Amazon Bedrock provider is not wired yet",
+                        retryable: false,
+                    });
+                default: {
+                    const exhaustive = model.provider;
+                    throw new AgentPlatformError({
+                        code: "capability_unavailable",
+                        message: `Unknown provider ${String(exhaustive)}`,
+                        retryable: false,
+                    });
+                }
+            }
+        },
+    };
+};
+//# sourceMappingURL=provider-factory.js.map