genaicode 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 2.1.0 — 2026-07-25
+
+Publishes the Phase 3–4 work already on `master`. npm `2.0.0` shipped the 2.0
+kernel and provider adapters only; this minor adds the remaining public surface
+documented in the README and [semver policy](docs/semver.md).
+
+### Added
+
+- Provider-neutral streaming (`StreamEvent`, `.stream()` / `.streamText()`,
+  native streams for OpenAI / Anthropic / Google with generate→stream fallback)
+- Built-in middleware: `timingPlugin`, `rateLimitPlugin`, `cachePlugin`,
+  `fallbackPlugin`, `fallbackProvider`
+- Retry helpers: `classifyError`, `isRetryable`, `withRetry` (+ [docs/retry.md](docs/retry.md))
+- `ProviderCapabilities` on `ModelProvider`
+- Compatibility fixtures for multimodal and tool-call round trips
+- Framework examples under `examples/` (HTTP handler, queue worker, cron job)
+- Written guidance: [docs/semver.md](docs/semver.md),
+  [docs/provider-packages.md](docs/provider-packages.md)
+
+### Notes
+
+- Additive API only; no breaking changes from `2.0.0`.
+- Retries remain opt-in application policy (no hidden retries in core).
+- Provider SDKs stay bundled behind `genaicode/providers` for 2.x.
+
+## 2.0.0 — 2026-07-24
+
+Major pivot from coding agent to backend LLM toolkit.
+
+- `genaicode()` client, immutable request builders, conversation chains
+- `PromptItem` IR and prompt/result helpers
+- OpenAI, OpenAI-compatible, Anthropic, Gemini, and Vertex adapters
+- `GenAIPlugin` middleware contract
+- Coding-agent CLI/UI/tools removed; `npx genaicode` prints migration guidance
+  (1.x remains on the `1.x` branch / `genaicode@1`)

package/README.md

@@ -129,6 +129,22 @@ for (let attempt = 1; attempt <= 3; attempt += 1) {
 
 The application owns validation, attempt limits, and failure policy.
 
+## Schema adapters
+
+`json(...)` and `parseJsonResult(...)` accept either a parser function or a schema adapter
+with a `parse(value)` method. This keeps schema validation library-agnostic:
+
+```ts
+const value = await ai('Return {"count": 3}.').json({
+  parse(input) {
+    if (typeof input !== 'object' || input === null || typeof input.count !== 'number') {
+      throw new Error('Invalid shape');
+    }
+    return input;
+  },
+});
+```
+
 ## PromptItem: the portable prompt IR
 
 `PromptItem` is GenAIcode's provider-neutral intermediate representation:
@@ -184,6 +200,68 @@ const calls = await ai('What is the weather in Warsaw?')
 GenAIcode normalizes tool calls but deliberately does not execute them. The application
 owns permissions, retries, and side effects.
 
+## Streaming
+
+Providers that support native streaming expose a provider-neutral `StreamEvent` IR.
+Request builders and chains offer `.stream()` and `.streamText()`. If a provider has no
+`stream` method, GenAIcode synthesizes a short stream from `generate`.
+
+```ts
+for await (const event of ai('Write a haiku about queues.').stream()) {
+  if (event.type === 'text-delta') process.stdout.write(event.text);
+  if (event.type === 'done') console.log('\n', event.result.usage);
+}
+```
+
+Built-in adapters declare capability metadata:
+
+```ts
+ai.provider.capabilities;
+// { streaming: true, tools: true, images: 'input', systemPrompt: true }
+```
+
+## Middleware
+
+Hook-style plugins remain the extension point. Built-in helpers cover common backend
+needs without restoring a global registry:
+
+```ts
+import {
+  cachePlugin,
+  fallbackPlugin,
+  genaicode,
+  rateLimitPlugin,
+  timingPlugin,
+} from 'genaicode';
+import { anthropic, openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }), {
+  plugins: [
+    timingPlugin(),
+    rateLimitPlugin({ concurrency: 2, minIntervalMs: 50 }),
+    cachePlugin({ maxEntries: 64 }),
+    fallbackPlugin({ providers: [anthropic({ model: 'your-claude-model' })] }),
+  ],
+});
+```
+
+## Retries
+
+Retries stay in application code. Use `classifyError`, `isRetryable`, and `withRetry`
+when you want shared classification without hidden policy:
+
+```ts
+import { withRetry } from 'genaicode';
+
+const text = await withRetry(() => ai('Summarize the deploy notes.').text(), {
+  attempts: 3,
+  delayMs: 250,
+});
+```
+
+See [retry guidance](docs/retry.md), [semver policy](docs/semver.md), and the
+[provider package evaluation](docs/provider-packages.md).
+
 ## Providers
 
 Models are provided in the adapter, through `.model(...)`, or with environment variables:
@@ -248,6 +326,24 @@ const provider: ModelProvider = {
 All Anthropic, Google, and OpenAI conversion functions are public from
 `genaicode/providers`, so gateways and tests can reuse them without instantiating clients.
 
+## Provider E2E tests
+
+Run real-provider E2E tests locally with:
+
+```bash
+npm run test:e2e
+```
+
+These tests are credential-gated and run only when provider-specific environment variables
+are set:
+
+- OpenAI: `OPENAI_API_KEY`, `OPENAI_MODEL`
+- Anthropic: `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`
+- Gemini: `GEMINI_API_KEY`, `GEMINI_MODEL`
+
+CI/CD is configured in `.github/workflows/provider-e2e.yaml`. Each provider runs in its own
+job and only starts when both required secrets are configured in GitHub Actions.
+
 ## Plugins and hooks
 
 A provider plugin no longer needs registration in global configuration. It exports the
@@ -259,6 +355,7 @@ import type { ModelProvider } from 'genaicode';
 
 export const bedrock = (options: BedrockOptions): ModelProvider => ({
   name: 'bedrock',
+  capabilities: { streaming: false, tools: true, systemPrompt: true },
   async generate(request) {
     // Convert PromptItem[], call Bedrock, and return GenerationResult.
     return { parts: [{ type: 'text', text: 'response' }] };
@@ -267,7 +364,8 @@ export const bedrock = (options: BedrockOptions): ModelProvider => ({
 ```
 
 Hook-style plugins use middleware. They can observe or rewrite requests and results,
-handle errors, implement caches or fallbacks, and intentionally short-circuit a call:
+handle errors, implement caches or fallbacks, and intentionally short-circuit a call.
+Optional `stream` middleware follows the same registration order.
 
 ```ts
 import { definePlugin, genaicode } from 'genaicode';
@@ -294,6 +392,9 @@ Plugins run in registration order, and each plugin may call `next()` once. This
 extension mechanism compatible with npm packages and ordinary imports without restoring
 the 1.x runtime TypeScript loader or process-global plugin registry.
 
+Framework-shaped examples live under `examples/` (`http-handler`, `queue-worker`,
+`cron-job`).
+
 ## Design boundaries
 
 - Backend library, not a coding agent.

package/dist/core/client.d.ts

@@ -1,5 +1,5 @@
 import { type GenAIPlugin } from './plugins.js';
-import type { GenerationDefaults, GenerationRequest, GenerationResult, ModelProvider, PromptInput, PromptItem, ToolCall, ToolChoice, ToolDefinition } from './types.js';
+import type { GenerationDefaults, GenerationRequest, GenerationResult, JsonResultParser, ModelProvider, PromptInput, PromptItem, StreamEvent, ToolCall, ToolChoice, ToolDefinition } from './types.js';
 export interface RequestBuilder {
     system(text: string): RequestBuilder;
     user(input: PromptInput): RequestBuilder;
@@ -11,16 +11,22 @@ export interface RequestBuilder {
     signal(signal: AbortSignal): RequestBuilder;
     run(): Promise<GenerationResult>;
     text(): Promise<string>;
-    json<T = unknown>(parse?: (value: unknown) => T): Promise<T>;
+    json<T = unknown>(parse?: JsonResultParser<T>): Promise<T>;
     toolCalls(): Promise<ToolCall[]>;
+    /** Provider-neutral streaming events (native when available, synthesized otherwise). */
+    stream(): AsyncIterable<StreamEvent>;
+    /** Convenience: yield only text deltas. */
+    streamText(): AsyncIterable<string>;
     inspect(): GenerationRequest;
 }
 export type ConfigureRequest = (request: RequestBuilder) => RequestBuilder;
 export interface Conversation {
     ask(input: PromptInput, configure?: ConfigureRequest): Promise<GenerationResult>;
     text(input: PromptInput, configure?: ConfigureRequest): Promise<string>;
-    json<T = unknown>(input: PromptInput, parse?: (value: unknown) => T, configure?: ConfigureRequest): Promise<T>;
+    json<T = unknown>(input: PromptInput, parse?: JsonResultParser<T>, configure?: ConfigureRequest): Promise<T>;
     toolCalls(input: PromptInput, configure?: ConfigureRequest): Promise<ToolCall[]>;
+    stream(input: PromptInput, configure?: ConfigureRequest): AsyncIterable<StreamEvent>;
+    streamText(input: PromptInput, configure?: ConfigureRequest): AsyncIterable<string>;
     history(): PromptItem[];
     reset(...initial: PromptInput[]): void;
 }

package/dist/core/client.js

@@ -1,6 +1,7 @@
 import { assistant, prompt, system, toPromptItems } from './prompt.js';
 import { withPlugins } from './plugins.js';
 import { parseJsonResult, resultText, resultToPromptItem, resultToolCalls } from './result.js';
+import { providerStream, streamTextDeltas } from './stream.js';
 class RequestBuilderImpl {
     provider;
     state;
@@ -67,6 +68,12 @@ class RequestBuilderImpl {
     async toolCalls() {
         return resultToolCalls(await this.run());
     }
+    stream() {
+        return providerStream(this.provider, this.inspect());
+    }
+    streamText() {
+        return streamTextDeltas(this.stream());
+    }
 }
 class ConversationImpl {
     createRequest;
@@ -100,6 +107,68 @@ class ConversationImpl {
     async toolCalls(input, configure) {
         return resultToolCalls(await this.ask(input, configure));
     }
+    stream(input, configure = (request) => request) {
+        return this.iterateStream(input, configure);
+    }
+    async *iterateStream(input, configure) {
+        let release = () => undefined;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = this.queue;
+        this.queue = previous.then(() => gate);
+        await previous;
+        try {
+            const additions = toPromptItems(input);
+            const generation = this.generation;
+            const events = configure(this.createRequest(this.items, additions)).stream();
+            let text = '';
+            const toolCalls = [];
+            const images = [];
+            let usage;
+            let doneResult;
+            for await (const event of events) {
+                yield event;
+                switch (event.type) {
+                    case 'text-delta':
+                        text += event.text;
+                        break;
+                    case 'tool-call':
+                        toolCalls.push(event.toolCall);
+                        break;
+                    case 'image':
+                        images.push({ type: 'image', image: event.image });
+                        break;
+                    case 'usage':
+                        usage = event.usage;
+                        break;
+                    case 'done':
+                        doneResult = event.result;
+                        break;
+                    default:
+                        break;
+                }
+            }
+            const result = doneResult ??
+                {
+                    parts: [
+                        ...(text ? [{ type: 'text', text }] : []),
+                        ...toolCalls.map((toolCall) => ({ type: 'toolCall', toolCall })),
+                        ...images,
+                    ],
+                    usage,
+                };
+            if (generation === this.generation) {
+                this.items = [...this.items, ...additions, resultToPromptItem(result)];
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    streamText(input, configure) {
+        return streamTextDeltas(this.stream(input, configure));
+    }
     history() {
         return this.items.map((item) => ({ ...item }));
     }

package/dist/core/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAgE/D,MAAM,kBAAkB;IAEH;IACA;IAFnB,YACmB,QAAuB,EACvB,KAAmB;QADnB,aAAQ,GAAR,QAAQ,CAAe;QACvB,UAAK,GAAL,KAAK,CAAc;IACnC,CAAC;IAEI,IAAI,CAAC,MAA6B;QACxC,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC3C,GAAG,IAAI,CAAC,KAAK;YACb,GAAG,MAAM;YACT,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC;QACpF,UAAU,CAAC,MAAM,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/F,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,YAAwB,EAAE;QAChD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,KAAK,CAAC,KAAa;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,WAAW,CAAC,WAAmB;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,eAAe,CAAC,eAAuB;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAuB,EAAE,aAAyB,MAAM;QAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,CAAC,MAAmB;QACxB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;YACtD,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK;YACvB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW;YACnC,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe;YAC3C,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK;YACvB,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU;YACjC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YACzB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ;SAC9B,CAAC;IACJ,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,UAAU,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,IAAI,CAAc,KAA2B;QACjD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,OAAO,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,eAAe,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM;QACJ,OAAO,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,UAAU;QACR,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;CACF;AAED,MAAM,gBAAgB;IAOD;IANX,KAAK,CAAe;IACpB,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IACzC,UAAU,GAAG,CAAC,CAAC;IAEvB,YACE,OAAqB,EACJ,aAA2D;QAA3D,kBAAa,GAAb,aAAa,CAA8C;QAE5E,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,CAAC;IAED,GAAG,CAAC,KAAkB,EAAE,YAA8B,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO;QACxE,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;YACzB,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACvC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YAChF,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,SAAS,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;YACzE,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,IAAI,CACzB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB,EAAE,SAA4B;QACzD,OAAO,UAAU,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,IAAI,CAAc,KAAkB,EAAE,KAA2B,EAAE,SAA4B;QACnG,OAAO,eAAe,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAkB,EAAE,SAA4B;QAC9D,OAAO,eAAe,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,CAAC,KAAkB,EAAE,YAA8B,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO;QAC3E,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAEO,KAAK,CAAC,CAAC,aAAa,CAC1B,KAAkB,EAClB,SAA2B;QAE3B,IAAI,OAAO,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACzC,OAAO,GAAG,OAAO,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,QAAQ,CAAC;QAEf,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACvC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;YACnC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC7E,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,MAAM,SAAS,GAAe,EAAE,CAAC;YACjC,MAAM,MAAM,GAA8B,EAAE,CAAC;YAC7C,IAAI,KAAgC,CAAC;YACrC,IAAI,UAAwC,CAAC;YAE7C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBACjC,MAAM,KAAK,CAAC;gBACZ,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACnB,KAAK,YAAY;wBACf,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC;wBACnB,MAAM;oBACR,KAAK,WAAW;wBACd,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;wBAC/B,MAAM;oBACR,KAAK,OAAO;wBACV,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;wBACnD,MAAM;oBACR,KAAK,OAAO;wBACV,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;wBACpB,MAAM;oBACR,KAAK,MAAM;wBACT,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;wBAC1B,MAAM;oBACR;wBACE,MAAM;gBACV,CAAC;YACH,CAAC;YAED,MAAM,MAAM,GACV,UAAU;gBACT;oBACC,KAAK,EAAE;wBACL,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;wBAClD,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAmB,EAAE,QAAQ,EAAE,CAAC,CAAC;wBACzE,GAAG,MAAM;qBACV;oBACD,KAAK;iBACsB,CAAC;YAEhC,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,SAAS,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,UAAU,CAAC,KAAkB,EAAE,SAA4B;QACzD,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,GAAG,OAAsB;QAC7B,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,SAAS,CAAC,QAAuB,EAAE,UAA8B,EAAE;IACjF,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC9C,MAAM,iBAAiB,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,CAAC,GAAG,MAAqB,EAAkB,EAAE,CACjE,IAAI,kBAAkB,CAAC,iBAAiB,EAAE,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACxF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAkB,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE;QACjE,MAAM,EAAE,aAAa;QACrB,KAAK,EAAE,CAAC,GAAG,OAAsB,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,EAAE,aAAa,CAAC;QAC7F,QAAQ,EAAE,iBAAiB;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,38 @@
+export type ErrorClass = 'transient' | 'permanent' | 'unknown';
+export interface ClassifiedError {
+    class: ErrorClass;
+    retryable: boolean;
+    reason: string;
+    status?: number;
+    code?: string;
+    cause: unknown;
+}
+/**
+ * Classify a provider/SDK error for application-owned retry loops.
+ *
+ * GenAIcode does not retry automatically. Use this helper (or your own policy)
+ * inside ordinary application control flow. See docs/retry.md.
+ */
+export declare function classifyError(error: unknown): ClassifiedError;
+export declare function isRetryable(error: unknown): boolean;
+export interface RetryOptions {
+    attempts?: number;
+    /** Base delay in ms; doubles each attempt. Defaults to 250. */
+    delayMs?: number;
+    /** Max delay cap in ms. Defaults to 5000. */
+    maxDelayMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (info: {
+        attempt: number;
+        error: unknown;
+        delayMs: number;
+    }) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Explicit retry helper for application code. Not wired into the client by default.
+ *
+ * Idempotency: only wrap operations that are safe to repeat (most pure generation
+ * calls are; tool side effects are not unless the application makes them idempotent).
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/core/errors.js

@@ -0,0 +1,118 @@
+function readStatus(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidate = error;
+    for (const value of [candidate.status, candidate.statusCode, candidate.response?.status]) {
+        if (typeof value === 'number')
+            return value;
+    }
+    return undefined;
+}
+function readCode(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/**
+ * Classify a provider/SDK error for application-owned retry loops.
+ *
+ * GenAIcode does not retry automatically. Use this helper (or your own policy)
+ * inside ordinary application control flow. See docs/retry.md.
+ */
+export function classifyError(error) {
+    const status = readStatus(error);
+    const code = readCode(error);
+    const message = messageOf(error).toLowerCase();
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return { class: 'permanent', retryable: false, reason: 'aborted', cause: error };
+    }
+    if (code === 'ECONNRESET' || code === 'ETIMEDOUT' || code === 'ECONNREFUSED' || code === 'ENOTFOUND') {
+        return { class: 'transient', retryable: true, reason: `network:${code}`, code, cause: error };
+    }
+    if (status === 408 || status === 425 || status === 429 || (status !== undefined && status >= 500)) {
+        return {
+            class: 'transient',
+            retryable: true,
+            reason: `http:${status}`,
+            status,
+            code,
+            cause: error,
+        };
+    }
+    if (status !== undefined && status >= 400 && status < 500) {
+        return {
+            class: 'permanent',
+            retryable: false,
+            reason: `http:${status}`,
+            status,
+            code,
+            cause: error,
+        };
+    }
+    if (message.includes('rate limit') ||
+        message.includes('timeout') ||
+        message.includes('temporar') ||
+        message.includes('unavailable') ||
+        message.includes('overloaded')) {
+        return { class: 'transient', retryable: true, reason: 'message-heuristic', status, code, cause: error };
+    }
+    if (message.includes('invalid') ||
+        message.includes('authentication') ||
+        message.includes('unauthorized') ||
+        message.includes('permission') ||
+        message.includes('not found')) {
+        return { class: 'permanent', retryable: false, reason: 'message-heuristic', status, code, cause: error };
+    }
+    return { class: 'unknown', retryable: false, reason: 'unclassified', status, code, cause: error };
+}
+export function isRetryable(error) {
+    return classifyError(error).retryable;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason instanceof Error ? signal.reason : new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+/**
+ * Explicit retry helper for application code. Not wired into the client by default.
+ *
+ * Idempotency: only wrap operations that are safe to repeat (most pure generation
+ * calls are; tool side effects are not unless the application makes them idempotent).
+ */
+export async function withRetry(operation, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 3);
+    const delayMs = options.delayMs ?? 250;
+    const maxDelayMs = options.maxDelayMs ?? 5000;
+    const shouldRetry = options.shouldRetry ?? ((error) => isRetryable(error));
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= attempts || !shouldRetry(error, attempt)) {
+                throw error;
+            }
+            const wait = Math.min(maxDelayMs, delayMs * 2 ** (attempt - 1));
+            options.onRetry?.({ attempt, error, delayMs: wait });
+            await sleep(wait, options.signal);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/middleware.d.ts

@@ -0,0 +1,43 @@
+import type { GenerationRequest, ModelProvider } from './types.js';
+import { type GenAIPlugin } from './plugins.js';
+export interface TimingPluginOptions {
+    onTiming?: (info: {
+        plugin: string;
+        provider?: string;
+        durationMs: number;
+        ok: boolean;
+    }) => void;
+}
+/** Observability middleware: records wall-clock duration around each generate call. */
+export declare function timingPlugin(options?: TimingPluginOptions): GenAIPlugin;
+export interface RateLimitPluginOptions {
+    /** Maximum concurrent in-flight generate calls. Defaults to 1. */
+    concurrency?: number;
+    /** Minimum delay between starting successive calls, in milliseconds. */
+    minIntervalMs?: number;
+}
+/** Simple concurrency / interval limiter. Does not talk to external rate-limit stores. */
+export declare function rateLimitPlugin(options?: RateLimitPluginOptions): GenAIPlugin;
+export interface CachePluginOptions {
+    /** Stable cache key. Defaults to a JSON serialization of the request (excluding signal). */
+    key?: (request: GenerationRequest) => string;
+    maxEntries?: number;
+}
+/** In-memory response cache. Intentionally short-circuits `next` on hit. */
+export declare function cachePlugin(options?: CachePluginOptions): GenAIPlugin;
+export interface FallbackPluginOptions {
+    /** Additional providers tried after the primary provider fails. */
+    providers: readonly ModelProvider[];
+    /** Decide whether an error should trigger fallback. Defaults to always. */
+    shouldFallback?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Fallback middleware: on primary failure, try alternate providers in order.
+ * Each alternate receives the same GenerationRequest.
+ */
+export declare function fallbackPlugin(options: FallbackPluginOptions): GenAIPlugin;
+/**
+ * Compose multiple providers into one ModelProvider that tries each until one succeeds.
+ * Prefer this when there is no single "primary" provider wired through plugins.
+ */
+export declare function fallbackProvider(providers: readonly ModelProvider[], name?: string): ModelProvider;