@cat-factory/agents 0.6.0

package/dist/providers/instrumented.d.ts

@@ -0,0 +1,28 @@
+import type { LanguageModel } from 'ai';
+import type { InlineObservabilityContext, LlmTraceSink, ModelProvider, ModelRef } from '@cat-factory/kernel';
+import { catFactoryObservability } from '@cat-factory/kernel';
+export { catFactoryObservability };
+export type { InlineObservabilityContext };
+/**
+ * A {@link ModelProvider} that wraps every resolved model so inline LLM calls surface
+ * on the trace sink. Build it only when a sink is wired AND the deployment opts in; an
+ * unwrapped provider behaves exactly as before.
+ */
+export declare class InstrumentedModelProvider implements ModelProvider {
+    private readonly inner;
+    private readonly traceSink;
+    private readonly recordPrompts;
+    private readonly now;
+    constructor(deps: {
+        inner: ModelProvider;
+        traceSink: LlmTraceSink;
+        /** Honour the same `LLM_RECORD_PROMPTS` switch as the local store; default true. */
+        recordPrompts?: boolean;
+        /** Injectable clock (tests); defaults to `Date.now`. */
+        now?: () => number;
+    });
+    resolve(ref: ModelRef): LanguageModel;
+    private middlewareFor;
+    private emit;
+}
+//# sourceMappingURL=instrumented.d.ts.map

package/dist/providers/instrumented.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumented.d.ts","sourceRoot":"","sources":["../../src/providers/instrumented.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AACvC,OAAO,KAAK,EACV,0BAA0B,EAE1B,YAAY,EACZ,aAAa,EACb,QAAQ,EACT,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,uBAAuB,EAAkC,MAAM,qBAAqB,CAAA;AAK7F,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAClC,YAAY,EAAE,0BAA0B,EAAE,CAAA;AAwD1C;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,aAAa;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC,YAAY,IAAI,EAAE;QAChB,KAAK,EAAE,aAAa,CAAA;QACpB,SAAS,EAAE,YAAY,CAAA;QACvB,oFAAoF;QACpF,aAAa,CAAC,EAAE,OAAO,CAAA;QACvB,wDAAwD;QACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KACnB,EAKA;IAED,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAWpC;IAED,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,IAAI;CAoCb"}

package/dist/providers/instrumented.js

@@ -0,0 +1,147 @@
+import { wrapLanguageModel } from 'ai';
+import { catFactoryObservability, readInlineObservabilityContext } from '@cat-factory/kernel';
+// Re-exported so existing `@cat-factory/agents` consumers keep importing the inline
+// observability tag from here; the canonical, dependency-free definition lives in the
+// kernel so any caller layer can build the tag without depending on this package.
+export { catFactoryObservability };
+// Instruments the INLINE (non-proxied) LLM calls so they reach the SAME trace sink as
+// the container-agent calls. Container calls go through the LLM proxy, which the
+// orchestration `LlmObservabilityService` fans out to the sink; inline calls
+// (requirements review/rework, the document planner, the fragment selector, the inline
+// agent executor) call the AI SDK directly. This decorator wraps every resolved model
+// with an AI SDK middleware that, after each generate, builds the SAME
+// {@link LlmGenerationEvent} and calls the SAME `sink.recordGeneration` — so adding the
+// inline feeder never means a second sink.
+//
+// The middleware is transparent: callers keep calling `generateText({ model })`
+// unchanged. To group a call under its run's trace and label it, a caller passes
+// `providerOptions: catFactoryObservability({ agentKind, workspaceId, executionId })`
+// (the kernel helper); absent ⇒ the call still emits, as its own standalone trace
+// named `inline`. The instrumentation never changes the model's behaviour and never
+// throws into the call.
+/** Read token counts defensively across the AI SDK's flat (v2) and nested (v3) usage shapes. */
+function readUsage(usage) {
+    const u = usage;
+    if (!u)
+        return { prompt: 0, completion: 0, total: 0 };
+    const inputTokens = u.inputTokens;
+    const outputTokens = u.outputTokens;
+    // v3: nested { total, … }
+    if (inputTokens && typeof inputTokens === 'object') {
+        const prompt = Number(inputTokens.total ?? 0);
+        const completion = Number(outputTokens?.total ?? 0);
+        const total = typeof u.totalTokens === 'number' ? u.totalTokens : prompt + completion;
+        return { prompt, completion, total };
+    }
+    // v2 / legacy flat
+    const prompt = Number(inputTokens ?? u.promptTokens ?? 0);
+    const completion = Number(outputTokens ?? u.completionTokens ?? 0);
+    const total = typeof u.totalTokens === 'number' ? u.totalTokens : prompt + completion;
+    return { prompt, completion, total };
+}
+/** Extract the assistant text from a generate result, across result shapes. */
+function readOutputText(result) {
+    const r = result;
+    if (typeof r?.text === 'string')
+        return r.text;
+    if (Array.isArray(r?.content)) {
+        return r.content
+            .filter((part) => part?.type === 'text')
+            .map((part) => String(part.text ?? ''))
+            .join('');
+    }
+    return '';
+}
+function readFinishReason(result) {
+    const reason = result?.finishReason;
+    return typeof reason === 'string' ? reason : null;
+}
+/**
+ * A {@link ModelProvider} that wraps every resolved model so inline LLM calls surface
+ * on the trace sink. Build it only when a sink is wired AND the deployment opts in; an
+ * unwrapped provider behaves exactly as before.
+ */
+export class InstrumentedModelProvider {
+    inner;
+    traceSink;
+    recordPrompts;
+    now;
+    constructor(deps) {
+        this.inner = deps.inner;
+        this.traceSink = deps.traceSink;
+        this.recordPrompts = deps.recordPrompts ?? true;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    resolve(ref) {
+        const model = this.inner.resolve(ref);
+        // wrapLanguageModel only accepts a model instance (not a model-id string). A bare
+        // string ref would be unusual for inline kinds, but pass it through untouched. The
+        // base resolvers return current-spec (v3) models; the cast bridges the broader
+        // `LanguageModel` union to wrapLanguageModel's exact model param.
+        if (typeof model === 'string')
+            return model;
+        return wrapLanguageModel({
+            model: model,
+            middleware: this.middlewareFor(ref),
+        });
+    }
+    middlewareFor(ref) {
+        return {
+            specificationVersion: 'v3',
+            wrapGenerate: async ({ doGenerate, params }) => {
+                const startedAt = this.now();
+                try {
+                    const result = await doGenerate();
+                    this.emit(ref, params, result, startedAt, true, null);
+                    return result;
+                }
+                catch (err) {
+                    this.emit(ref, params, undefined, startedAt, false, errorMessage(err));
+                    throw err;
+                }
+            },
+        };
+    }
+    emit(ref, params, result, startedAt, ok, errMessage) {
+        const endedAt = this.now();
+        const context = readInlineObservabilityContext(params);
+        const usage = readUsage(result?.usage);
+        const event = {
+            workspaceId: context.workspaceId ?? null,
+            executionId: context.executionId ?? null,
+            agentKind: context.agentKind,
+            provider: ref.provider,
+            model: ref.model,
+            startedAt,
+            endedAt,
+            promptTokens: usage.prompt,
+            completionTokens: usage.completion,
+            totalTokens: usage.total,
+            finishReason: ok ? readFinishReason(result) : null,
+            ok,
+            errorMessage: errMessage,
+            input: this.recordPrompts ? safeJson(params?.prompt) : '',
+            output: this.recordPrompts && ok ? readOutputText(result) : '',
+        };
+        // Best-effort and fully isolated: the sink itself swallows + logs, but guard the
+        // synchronous build/dispatch too so instrumentation can never break the LLM call.
+        try {
+            void Promise.resolve(this.traceSink.recordGeneration(event)).catch(() => { });
+        }
+        catch {
+            // ignored
+        }
+    }
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value ?? []);
+    }
+    catch {
+        return '';
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=instrumented.js.map

package/dist/providers/instrumented.js.map

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

package/dist/providers/registry.d.ts

@@ -0,0 +1,26 @@
+import type { ModelProvider, ModelRef } from '@cat-factory/kernel';
+import type { LanguageModel } from 'ai';
+/** Resolves one provider's {@link ModelRef} into a model the AI SDK can call. */
+export type ModelResolver = (ref: ModelRef) => LanguageModel;
+/**
+ * A set of resolvers keyed by provider id (`openai`, `anthropic`, `bedrock`, …).
+ * An entry may be `undefined` so callers can register conditionally (e.g. only when
+ * a credential is configured) without filtering first.
+ */
+export type ProviderRegistry = Record<string, ModelResolver | undefined>;
+/**
+ * A {@link ModelProvider} composed from one or more {@link ProviderRegistry registries}.
+ * `resolve` dispatches on `ref.provider` and throws a clear error for any provider that
+ * was not registered. Later registrations win for the same provider id, so a deployment
+ * can override a base resolver by mixing in its own registry afterwards.
+ */
+export declare class CompositeModelProvider implements ModelProvider {
+    private readonly resolvers;
+    constructor(...registries: ProviderRegistry[]);
+    /** Mix in a registry; returns `this` for fluent chaining. */
+    register(registry: ProviderRegistry): this;
+    /** Provider ids currently registered (useful for diagnostics / a /models gate). */
+    providers(): string[];
+    resolve(ref: ModelRef): LanguageModel;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/providers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAcvC,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAA;AAE5D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAA;AAExE;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAE7D,YAAY,GAAG,UAAU,EAAE,gBAAgB,EAAE,EAE5C;IAED,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAKzC;IAED,mFAAmF;IACnF,SAAS,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAIpC;CACF"}

package/dist/providers/registry.js

@@ -0,0 +1,32 @@
+/**
+ * A {@link ModelProvider} composed from one or more {@link ProviderRegistry registries}.
+ * `resolve` dispatches on `ref.provider` and throws a clear error for any provider that
+ * was not registered. Later registrations win for the same provider id, so a deployment
+ * can override a base resolver by mixing in its own registry afterwards.
+ */
+export class CompositeModelProvider {
+    resolvers = new Map();
+    constructor(...registries) {
+        for (const registry of registries)
+            this.register(registry);
+    }
+    /** Mix in a registry; returns `this` for fluent chaining. */
+    register(registry) {
+        for (const [provider, resolver] of Object.entries(registry)) {
+            if (resolver)
+                this.resolvers.set(provider, resolver);
+        }
+        return this;
+    }
+    /** Provider ids currently registered (useful for diagnostics / a /models gate). */
+    providers() {
+        return [...this.resolvers.keys()];
+    }
+    resolve(ref) {
+        const resolver = this.resolvers.get(ref.provider);
+        if (!resolver)
+            throw new Error(`Unsupported model provider: ${ref.provider}`);
+        return resolver(ref);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,MAAM,OAAO,sBAAsB;IAChB,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAA;IAE7D,YAAY,GAAG,UAA8B;QAC3C,KAAK,MAAM,QAAQ,IAAI,UAAU;YAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC5D,CAAC;IAED,6DAA6D;IAC7D,QAAQ,CAAC,QAA0B;QACjC,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5D,IAAI,QAAQ;gBAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QACtD,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,mFAAmF;IACnF,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,CAAC,GAAa;QACnB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACjD,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC7E,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IACtB,CAAC;CACF"}

package/dist/providers/resolvers.d.ts

@@ -0,0 +1,58 @@
+import type { ModelResolver, ProviderRegistry } from './registry.js';
+/** Resolver for OpenAI (or any drop-in compatible base URL using the OpenAI SDK). */
+export declare function openAiResolver(opts: {
+    apiKey?: string;
+    baseURL?: string;
+}): ModelResolver;
+/** Resolver for Anthropic. */
+export declare function anthropicResolver(opts: {
+    apiKey?: string;
+    baseURL?: string;
+}): ModelResolver;
+/**
+ * Resolver for an OpenAI-compatible vendor (DashScope/Qwen, DeepSeek, Moonshot, or a
+ * self-hosted gateway). `name` is only used by the SDK for telemetry/labels.
+ */
+export declare function openAiCompatibleResolver(opts: {
+    name: string;
+    apiKey: string;
+    baseURL: string;
+}): ModelResolver;
+/**
+ * Resolver for Cloudflare-hosted models reached over HTTP (no Workers `AI` binding):
+ * either the Workers AI OpenAI-compatible REST endpoint (account id + API token) or an
+ * AI Gateway. This is how the Node service uses Cloudflare models; the Worker uses the
+ * in-process binding instead. Registered under the `workers-ai` provider id by default so
+ * a model pinned `workers-ai` resolves on both deployments (binding vs REST).
+ */
+export declare function cloudflareRestResolver(opts: {
+    accountId: string;
+    apiToken: string;
+    /** AI Gateway slug; when set, routes through the gateway instead of the direct REST API. */
+    gateway?: string;
+    /** Full override of the base URL (wins over accountId/gateway). */
+    baseURL?: string;
+}): ModelResolver;
+/**
+ * Build the base provider registry from a deployment's credentials. Each provider is
+ * registered only when its credential is present, so an unconfigured provider resolves
+ * to a clear "Unsupported model provider" error rather than a deep SDK failure. Mix
+ * extra registries (e.g. Bedrock, the Workers AI binding) in afterwards.
+ */
+export declare function baseProviderRegistry(opts: {
+    openaiApiKey?: string;
+    openaiBaseURL?: string;
+    anthropicApiKey?: string;
+    /** Per-provider OpenAI-compatible upstreams (base URL + key), keyed by provider id. */
+    openAiCompatible?: Record<string, {
+        apiKey?: string;
+        baseURL: string;
+    } | undefined>;
+    cloudflareRest?: {
+        accountId: string;
+        apiToken: string;
+        gateway?: string;
+        baseURL?: string;
+    };
+}): ProviderRegistry;
+//# sourceMappingURL=resolvers.d.ts.map

package/dist/providers/resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../../src/providers/resolvers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAOpE,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAMzF;AAED,8BAA8B;AAC9B,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAM5F;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,aAAa,CAOhB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,aAAa,CAOhB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;IACnF,cAAc,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7F,GAAG,gBAAgB,CAoBnB"}

package/dist/providers/resolvers.js

@@ -0,0 +1,78 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+// The base, runtime-neutral resolvers. They depend only on `ai` + the `@ai-sdk/*`
+// vendor packages (no Cloudflare bindings, no Node built-ins), so they run on both
+// the Worker and the Node service. Heavier/optional backends (e.g. AWS Bedrock) ship
+// as their own packages and are mixed in as extra registries.
+/** Resolver for OpenAI (or any drop-in compatible base URL using the OpenAI SDK). */
+export function openAiResolver(opts) {
+    const provider = createOpenAI({
+        apiKey: opts.apiKey,
+        ...(opts.baseURL ? { baseURL: opts.baseURL } : {}),
+    });
+    return (ref) => provider(ref.model);
+}
+/** Resolver for Anthropic. */
+export function anthropicResolver(opts) {
+    const provider = createAnthropic({
+        apiKey: opts.apiKey,
+        ...(opts.baseURL ? { baseURL: opts.baseURL } : {}),
+    });
+    return (ref) => provider(ref.model);
+}
+/**
+ * Resolver for an OpenAI-compatible vendor (DashScope/Qwen, DeepSeek, Moonshot, or a
+ * self-hosted gateway). `name` is only used by the SDK for telemetry/labels.
+ */
+export function openAiCompatibleResolver(opts) {
+    const provider = createOpenAICompatible({
+        name: opts.name,
+        apiKey: opts.apiKey,
+        baseURL: opts.baseURL,
+    });
+    return (ref) => provider(ref.model);
+}
+/**
+ * Resolver for Cloudflare-hosted models reached over HTTP (no Workers `AI` binding):
+ * either the Workers AI OpenAI-compatible REST endpoint (account id + API token) or an
+ * AI Gateway. This is how the Node service uses Cloudflare models; the Worker uses the
+ * in-process binding instead. Registered under the `workers-ai` provider id by default so
+ * a model pinned `workers-ai` resolves on both deployments (binding vs REST).
+ */
+export function cloudflareRestResolver(opts) {
+    const baseURL = opts.baseURL ??
+        (opts.gateway
+            ? `https://gateway.ai.cloudflare.com/v1/${opts.accountId}/${opts.gateway}/workers-ai/v1`
+            : `https://api.cloudflare.com/client/v4/accounts/${opts.accountId}/ai/v1`);
+    return openAiCompatibleResolver({ name: 'cloudflare', apiKey: opts.apiToken, baseURL });
+}
+/**
+ * Build the base provider registry from a deployment's credentials. Each provider is
+ * registered only when its credential is present, so an unconfigured provider resolves
+ * to a clear "Unsupported model provider" error rather than a deep SDK failure. Mix
+ * extra registries (e.g. Bedrock, the Workers AI binding) in afterwards.
+ */
+export function baseProviderRegistry(opts) {
+    const registry = {
+        openai: opts.openaiApiKey
+            ? openAiResolver({ apiKey: opts.openaiApiKey, baseURL: opts.openaiBaseURL })
+            : undefined,
+        anthropic: opts.anthropicApiKey
+            ? anthropicResolver({ apiKey: opts.anthropicApiKey })
+            : undefined,
+    };
+    for (const [provider, upstream] of Object.entries(opts.openAiCompatible ?? {})) {
+        if (upstream?.apiKey) {
+            registry[provider] = openAiCompatibleResolver({
+                name: provider,
+                apiKey: upstream.apiKey,
+                baseURL: upstream.baseURL,
+            });
+        }
+    }
+    if (opts.cloudflareRest)
+        registry['workers-ai'] = cloudflareRestResolver(opts.cloudflareRest);
+    return registry;
+}
+//# sourceMappingURL=resolvers.js.map

package/dist/providers/resolvers.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cat-factory/agents",
+  "version": "0.6.0",
+  "description": "Agent catalog, routing, prompts and fragment library for the Agent Architecture Board.",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
+    "@ai-sdk/openai": "^3.0.73",
+    "@ai-sdk/openai-compatible": "^2.0.51",
+    "ai": "^6.0.208",
+    "handlebars": "^4.7.9",
+    "@cat-factory/contracts": "0.6.0",
+    "@cat-factory/kernel": "0.6.0",
+    "@cat-factory/prompt-fragments": "0.6.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.1-rc"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "precompile:templates": "node scripts/precompile-prompts.mjs"
+  }
+}