@ank1015/agents-provider-anthropic-spec 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@ank1015/agents-provider-anthropic-spec` will be documented in this file.
+
+## 0.1.0 - Initial Release
+
+- Added direct-value API key secret references to the provider config schema.
+- Added the `anthropic` provider identifier and config schema.
+- Added Anthropic native message and provider option type augmentation for `@ank1015/agents-contracts`.
+- Added a static Anthropic model catalog with literal model-id narrowing.
+- Added `getAnthropicModel` for catalog lookup.
+- Added grouped package exports for `config` and `models`.
+- Added unit and type-contract coverage for config validation, catalog shape, lookup behavior, and model-id narrowing.

package/README.md

@@ -0,0 +1,105 @@
+# @ank1015/agents-provider-anthropic-spec
+
+Static Anthropic provider metadata for the `@ank1015/agents` packages.
+
+This package contains no live Anthropic client. It provides provider identity, config types, provider-specific type augmentation, and a static model catalog that other packages can consume without depending on the Anthropic runtime adapter.
+
+## Install
+
+```sh
+pnpm add @ank1015/agents-provider-anthropic-spec
+```
+
+## What This Package Provides
+
+- `ANTHROPIC_PROVIDER` provider id.
+- `anthropicProviderConfigSchema` for provider config validation.
+- `AnthropicProviderOptions` based on Anthropic Messages API request options.
+- `AnthropicNativeMessage` based on Anthropic SDK message responses.
+- `ANTHROPIC_MODELS` static model catalog.
+- `AnthropicModelId` literal union derived from the catalog.
+- Contract augmentation for `@ank1015/agents-contracts`.
+
+## Import Paths
+
+```ts
+import {
+  ANTHROPIC_MODELS,
+  ANTHROPIC_PROVIDER,
+  getAnthropicModel,
+} from '@ank1015/agents-provider-anthropic-spec';
+
+import { anthropicProviderConfigSchema } from '@ank1015/agents-provider-anthropic-spec/config';
+import type { AnthropicModelId } from '@ank1015/agents-provider-anthropic-spec/models';
+```
+
+## Provider Config
+
+Anthropic provider config uses a secret reference for the API key. Environment references keep keys out of config:
+
+```ts
+import {
+  ANTHROPIC_PROVIDER,
+  anthropicProviderConfigSchema,
+} from '@ank1015/agents-provider-anthropic-spec';
+
+const config = anthropicProviderConfigSchema.parse({
+  provider: ANTHROPIC_PROVIDER,
+  apiKey: {
+    type: 'env',
+    name: 'ANTHROPIC_API_KEY',
+  },
+});
+```
+
+The live adapter resolves the referenced environment variable when it creates the Anthropic SDK client. Callers that already have a key from another secret source can pass a direct value reference:
+
+```ts
+const config = anthropicProviderConfigSchema.parse({
+  provider: ANTHROPIC_PROVIDER,
+  apiKey: {
+    type: 'value',
+    value: anthropicKey,
+  },
+});
+```
+
+## Model Catalog
+
+`ANTHROPIC_MODELS` is a static snapshot used for model lookup, UI metadata, defaults, and compile-time model-id narrowing:
+
+```ts
+import {
+  ANTHROPIC_MODELS,
+  getAnthropicModel,
+} from '@ank1015/agents-provider-anthropic-spec';
+
+const model = getAnthropicModel('claude-sonnet-4-6');
+```
+
+The catalog currently includes:
+
+- `claude-opus-4-8`
+- `claude-sonnet-4-6`
+- `claude-haiku-4-5`
+
+Static model metadata can age as providers release or retire models. Treat pricing, context windows, and max-token metadata as package-versioned snapshot data.
+
+## Type Augmentation
+
+Importing this package augments `@ank1015/agents-contracts` so Anthropic requests can narrow provider-specific fields:
+
+```ts
+import type { LLMRequest } from '@ank1015/agents-contracts';
+import type { AnthropicProvider } from '@ank1015/agents-provider-anthropic-spec';
+
+const request: LLMRequest<AnthropicProvider> = {
+  provider: 'anthropic',
+  modelId: 'claude-sonnet-4-6',
+  messages: [],
+};
+```
+
+## Versioning
+
+This package is currently `0.1.0`. Until `1.0.0`, model metadata and provider option types may evolve as the surrounding agent runtime settles.

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import type { Message, MessageCreateParamsBase } from '@anthropic-ai/sdk/resources/messages.js';
+import { z } from 'zod';
+export declare const ANTHROPIC_PROVIDER: "anthropic";
+export type AnthropicProvider = typeof ANTHROPIC_PROVIDER;
+export type AnthropicNativeMessage = Message;
+export declare const anthropicProviderConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    provider: z.ZodLiteral<"anthropic">;
+    apiKey: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"env">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"value">;
+        value: z.ZodString;
+    }, z.core.$strict>], "type">;
+}, z.core.$strict>;
+export type AnthropicProviderConfig = z.infer<typeof anthropicProviderConfigSchema>;
+/**
+ * Per-call Anthropic request options.
+ * Model, messages, streaming, system prompt, and tools are owned by the generic LLM layer.
+ * `max_tokens` is required by the Anthropic API but absent from the generic request, so it
+ * stays here as an optional override; the adapter defaults it to the model's `maxTokens`.
+ */
+export type AnthropicProviderOptions = Omit<MessageCreateParamsBase, 'model' | 'messages' | 'stream' | 'system' | 'tools' | 'max_tokens'> & {
+    max_tokens?: number;
+};
+declare module '@ank1015/agents-contracts' {
+    interface ProviderNativeMessageMap {
+        anthropic: AnthropicNativeMessage;
+    }
+    interface ProviderOptionsMap {
+        anthropic: AnthropicProviderOptions;
+    }
+    interface ProviderConfigMap {
+        anthropic: AnthropicProviderConfig;
+    }
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,kBAAkB,EAAG,WAAoB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG,OAAO,kBAAkB,CAAC;AAE1D,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE7C,eAAO,MAAM,6BAA6B;;;;;;;;;;;kBAK/B,CAAC;AAEZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CACzC,uBAAuB,EACvB,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CACpE,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,wBAAwB;QAChC,SAAS,EAAE,sBAAsB,CAAC;KACnC;IAED,UAAU,kBAAkB;QAC1B,SAAS,EAAE,wBAAwB,CAAC;KACrC;IAED,UAAU,iBAAiB;QACzB,SAAS,EAAE,uBAAuB,CAAC;KACpC;CACF"}

package/dist/config.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { baseProviderConfigSchema, secretRefSchema, } from '@ank1015/agents-contracts';
+export const ANTHROPIC_PROVIDER = 'anthropic';
+export const anthropicProviderConfigSchema = baseProviderConfigSchema
+    .extend({
+    provider: z.literal(ANTHROPIC_PROVIDER),
+    apiKey: secretRefSchema,
+})
+    .strict();
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,wBAAwB,EACxB,eAAe,GAChB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAoB,CAAC;AAMvD,MAAM,CAAC,MAAM,6BAA6B,GAAG,wBAAwB;KAClE,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACvC,MAAM,EAAE,eAAe;CACxB,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './models.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './models.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":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,56 @@
+export declare const ANTHROPIC_MODEL_AVATAR = "https://avatars.githubusercontent.com/u/81847?s=64&v=4";
+export declare const ANTHROPIC_MODELS: readonly [{
+    readonly id: "claude-opus-4-8";
+    readonly name: "Claude Opus 4.8";
+    readonly avatar: "https://avatars.githubusercontent.com/u/81847?s=64&v=4";
+    readonly provider: "anthropic";
+    readonly reasoning: true;
+    readonly input: ["text", "image"];
+    readonly cost: {
+        readonly input: 5;
+        readonly output: 25;
+        readonly cacheRead: 0.5;
+        readonly cacheWrite: 6.25;
+    };
+    readonly contextWindow: 1000000;
+    readonly maxTokens: 128000;
+}, {
+    readonly id: "claude-sonnet-4-6";
+    readonly name: "Claude Sonnet 4.6";
+    readonly avatar: "https://avatars.githubusercontent.com/u/81847?s=64&v=4";
+    readonly provider: "anthropic";
+    readonly reasoning: true;
+    readonly input: ["text", "image"];
+    readonly cost: {
+        readonly input: 3;
+        readonly output: 15;
+        readonly cacheRead: 0.3;
+        readonly cacheWrite: 3.75;
+    };
+    readonly contextWindow: 1000000;
+    readonly maxTokens: 64000;
+}, {
+    readonly id: "claude-haiku-4-5";
+    readonly name: "Claude Haiku 4.5";
+    readonly avatar: "https://avatars.githubusercontent.com/u/81847?s=64&v=4";
+    readonly provider: "anthropic";
+    readonly reasoning: true;
+    readonly input: ["text", "image"];
+    readonly cost: {
+        readonly input: 1;
+        readonly output: 5;
+        readonly cacheRead: 0.1;
+        readonly cacheWrite: 1.25;
+    };
+    readonly contextWindow: 200000;
+    readonly maxTokens: 64000;
+}];
+export type AnthropicModel = (typeof ANTHROPIC_MODELS)[number];
+export type AnthropicModelId = AnthropicModel['id'];
+export declare function getAnthropicModel(id: string): AnthropicModel | undefined;
+declare module '@ank1015/agents-contracts' {
+    interface ProviderModelIdMap {
+        anthropic: AnthropicModelId;
+    }
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB,2DAA2D,CAAC;AAE/F,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiD2B,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;AAMpD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAExE;AAED,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,kBAAkB;QAC1B,SAAS,EAAE,gBAAgB,CAAC;KAC7B;CACF"}

package/dist/models.js

@@ -0,0 +1,56 @@
+import { ANTHROPIC_PROVIDER } from './config.js';
+export const ANTHROPIC_MODEL_AVATAR = 'https://avatars.githubusercontent.com/u/81847?s=64&v=4';
+export const ANTHROPIC_MODELS = [
+    {
+        id: 'claude-opus-4-8',
+        name: 'Claude Opus 4.8',
+        avatar: ANTHROPIC_MODEL_AVATAR,
+        provider: ANTHROPIC_PROVIDER,
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: {
+            input: 5,
+            output: 25,
+            cacheRead: 0.5,
+            cacheWrite: 6.25,
+        },
+        contextWindow: 1000000,
+        maxTokens: 128000,
+    },
+    {
+        id: 'claude-sonnet-4-6',
+        name: 'Claude Sonnet 4.6',
+        avatar: ANTHROPIC_MODEL_AVATAR,
+        provider: ANTHROPIC_PROVIDER,
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: {
+            input: 3,
+            output: 15,
+            cacheRead: 0.3,
+            cacheWrite: 3.75,
+        },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+    },
+    {
+        id: 'claude-haiku-4-5',
+        name: 'Claude Haiku 4.5',
+        avatar: ANTHROPIC_MODEL_AVATAR,
+        provider: ANTHROPIC_PROVIDER,
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: {
+            input: 1,
+            output: 5,
+            cacheRead: 0.1,
+            cacheWrite: 1.25,
+        },
+        contextWindow: 200000,
+        maxTokens: 64000,
+    },
+];
+export function getAnthropicModel(id) {
+    return ANTHROPIC_MODELS.find((model) => model.id === id);
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wDAAwD,CAAC;AAE/F,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;QACE,EAAE,EAAE,iBAAiB;QACrB,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,sBAAsB;QAC9B,QAAQ,EAAE,kBAAkB;QAC5B,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QACxB,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,IAAI;SACjB;QACD,aAAa,EAAE,OAAO;QACtB,SAAS,EAAE,MAAM;KAClB;IACD;QACE,EAAE,EAAE,mBAAmB;QACvB,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,sBAAsB;QAC9B,QAAQ,EAAE,kBAAkB;QAC5B,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QACxB,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,IAAI;SACjB;QACD,aAAa,EAAE,OAAO;QACtB,SAAS,EAAE,KAAK;KACjB;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,kBAAkB;QACxB,MAAM,EAAE,sBAAsB;QAC9B,QAAQ,EAAE,kBAAkB;QAC5B,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QACxB,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,CAAC;YACT,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,IAAI;SACjB;QACD,aAAa,EAAE,MAAM;QACrB,SAAS,EAAE,KAAK;KACjB;CACqD,CAAC;AAUzD,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ank1015/agents-provider-anthropic-spec",
+  "version": "0.1.0",
+  "description": "Anthropic provider static spec (model catalog, config + per-call option types) for @ank1015/agents.",
+  "keywords": [
+    "agents",
+    "anthropic",
+    "claude",
+    "llm",
+    "typescript"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ank1015/agent.git",
+    "directory": "packages/provider-anthropic-spec"
+  },
+  "bugs": {
+    "url": "https://github.com/ank1015/agent/issues"
+  },
+  "homepage": "https://github.com/ank1015/agent#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "import": "./dist/models.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b",
+    "build": "tsc -b",
+    "check": "tsc -b --pretty false",
+    "test": "vitest run && tsc --noEmit --strict --skipLibCheck --module NodeNext --moduleResolution NodeNext --target ES2022 --ignoreConfig tests/*.test.ts",
+    "clean": "rm -rf dist ../../.tsbuildinfo/provider-anthropic-spec.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ank1015/agents-contracts": "^0.1.1",
+    "@anthropic-ai/sdk": "^0.104.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  }
+}