@frockbot/plugin-provider-frock-ai 0.3.14 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-provider-frock-ai",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,11 +20,12 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/configuration-core": "0.3.14",
-    "@frockbot/connection-core": "0.3.14",
-    "@frockbot/kernel-contracts": "0.3.14",
-    "@frockbot/plugin-models": "0.3.14",
-    "@frockbot/provider-openai-compatible": "0.3.14",
+    "@frockbot/configuration-core": "0.3.15",
+    "@frockbot/connection-core": "0.3.15",
+    "@frockbot/kernel-agent-loop": "0.3.15",
+    "@frockbot/kernel-contracts": "0.3.15",
+    "@frockbot/plugin-models": "0.3.15",
+    "@frockbot/provider-openai-compatible": "0.3.15",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/runtime.test.ts

@@ -1,21 +1,26 @@
 import { describe, expect, test } from "bun:test";
 import {
-  LlmEffectNotStartedError,
   MODEL_FIRST_BYTE_DEADLINE_MS_V1,
   MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
   MODEL_IDLE_DEADLINE_MS_V1,
   MODEL_IDLE_DEADLINE_REASON_V1,
   ModelRequestDeadlineError,
+  ModelProviderFailureError,
   type NormalizedModelRequest,
 } from "@frockbot/kernel-contracts";
 import { LlmRegistry } from "@frockbot/plugin-models";
+import type { Agent } from "@frockbot/kernel-agent-loop/agent";
 import { Context } from "cordis";
 import {
   FROCK_AI_CONNECTION_GENERATION,
   FROCK_AI_CONNECTION_ID,
   FROCK_AI_DEFAULT_MODEL,
 } from "./catalog.js";
-import { createFrockAiRuntimePlugin } from "./runtime.js";
+import {
+  classifyFrockAiFailureV1,
+  createFrockAiRuntimePlugin,
+  FrockAiTransportErrorV1,
+} from "./runtime.js";
 
 const request: NormalizedModelRequest = {
   requestId: "effect-1",
@@ -105,6 +110,135 @@ function pushableSse(): {
 }
 
 describe("Frock AI runtime Contribution", () => {
+  test("maps AI Gateway and Workers AI error envelopes", () => {
+    expect(
+      classifyFrockAiFailureV1(new FrockAiTransportErrorV1("busy", 503, 2_000)),
+    ).toMatchObject({
+      classification: "transient",
+      providerReason: "busy",
+      retryAfterMs: 2_000,
+    });
+    expect(
+      classifyFrockAiFailureV1({
+        error: { message: "model not found", code: "invalid_model" },
+      }),
+    ).toMatchObject({
+      classification: "permanent",
+      providerReason: "model not found",
+    });
+    expect(
+      classifyFrockAiFailureV1({ error: { message: "opaque", code: 7999 } }),
+    ).toMatchObject({ classification: "unknown", providerReason: "opaque" });
+  });
+
+  test("falls from a permanently rejected manual model to Auto immediately", async () => {
+    const calls: string[] = [];
+    const root = new Context();
+    await root.plugin(LlmRegistry);
+    await root.plugin(
+      createFrockAiRuntimePlugin(
+        runtimeConfig((gatewayModel) => {
+          calls.push(gatewayModel);
+          return gatewayModel.startsWith("workers-ai/")
+            ? Promise.reject(new FrockAiTransportErrorV1("model missing", 404))
+            : Promise.resolve(
+                sse(
+                  'data: {"choices":[{"delta":{"content":"auto"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n',
+                ),
+              );
+        }),
+      ),
+    );
+    const agent = {} as Agent;
+    const manual = {
+      ...request,
+      model: "@frock/deepseek-ai/deepseek-v4-flash-0731",
+    };
+    let failure: unknown;
+    try {
+      for await (const event of root.llm.stream(
+        manual,
+        new AbortController().signal,
+      )) {
+        void event;
+      }
+    } catch (error) {
+      failure = error;
+    }
+
+    const action = await root.waterfall(
+      "agent/request-error",
+      agent,
+      failure,
+      new AbortController().signal,
+      () => Promise.resolve({ kind: "fail" as const }),
+    );
+    expect(action).toEqual({ kind: "fallback" });
+    const fallback = await root.waterfall(
+      "agent/request",
+      agent,
+      manual,
+      new AbortController().signal,
+      () => Promise.resolve(manual),
+    );
+    expect(fallback.model).toBe(FROCK_AI_DEFAULT_MODEL);
+    for await (const event of root.llm.stream(
+      fallback,
+      new AbortController().signal,
+    )) {
+      void event;
+    }
+    expect(calls).toEqual([
+      "workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731",
+      "dynamic/configured-auto",
+    ]);
+    await root.fiber.dispose();
+  });
+
+  test("leaves a transient manual-model failure on the retry path", async () => {
+    const root = new Context();
+    await root.plugin(LlmRegistry);
+    await root.plugin(
+      createFrockAiRuntimePlugin(
+        runtimeConfig(() =>
+          Promise.reject(new FrockAiTransportErrorV1("busy", 503)),
+        ),
+      ),
+    );
+    const agent = {} as Agent;
+    const manual = {
+      ...request,
+      model: "@frock/deepseek-ai/deepseek-v4-flash-0731",
+    };
+    let failure: unknown;
+    try {
+      for await (const event of root.llm.stream(
+        manual,
+        new AbortController().signal,
+      )) {
+        void event;
+      }
+    } catch (error) {
+      failure = error;
+    }
+    const action = await root.waterfall(
+      "agent/request-error",
+      agent,
+      failure,
+      new AbortController().signal,
+      () => Promise.resolve({ kind: "retry" as const }),
+    );
+    expect(action).toEqual({ kind: "retry" });
+    const retried = await root.waterfall(
+      "agent/request",
+      agent,
+      manual,
+      new AbortController().signal,
+      () => Promise.resolve(manual),
+    );
+    expect(retried.model).toBe(manual.model);
+    await root.fiber.dispose();
+  });
   test.each([
     [FROCK_AI_DEFAULT_MODEL, "dynamic/configured-auto"],
     [
@@ -241,7 +375,7 @@ describe("Frock AI runtime Contribution", () => {
           void event;
         }
       })(),
-    ).rejects.toBeInstanceOf(LlmEffectNotStartedError);
+    ).rejects.toBeInstanceOf(ModelProviderFailureError);
     expect(calls).toBe(0);
     await root.fiber.dispose();
   });
@@ -273,7 +407,7 @@ describe("Frock AI runtime Contribution", () => {
 
     // Uncertain here would park the run on a reconciliation this Package
     // cannot perform, wedging the Bot on a transient gateway error.
-    expect(failure).toBeInstanceOf(LlmEffectNotStartedError);
+    expect(failure).toBeInstanceOf(ModelProviderFailureError);
     expect((failure as Error).message).toBe(
       "AI Gateway rejected the request (429): slow down",
     );
@@ -399,8 +533,10 @@ describe("Frock AI deadlines", () => {
       () => undefined,
       (error: unknown) => error,
     );
-    expect(failure).toBeInstanceOf(ModelRequestDeadlineError);
-    expect((failure as ModelRequestDeadlineError).phase).toBe("first-byte");
+    expect(failure).toBeInstanceOf(ModelProviderFailureError);
+    expect((failure as ModelProviderFailureError).classification).toBe(
+      "transient",
+    );
     expect((failure as Error).message).toBe(
       MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
     );

package/src/runtime.ts

@@ -1,19 +1,104 @@
 import {
-  LlmEffectNotStartedError,
+  boundedModelProviderReasonV1,
   type LlmProvider,
   type LlmReconciliationCapability,
+  ModelProviderFailureError,
+  type ModelProviderFailureClassV1,
+  ModelRequestDeadlineError,
   type NormalizedModelRequest,
 } from "@frockbot/kernel-contracts";
 import {
+  classifyOpenAICompatibleFailureV1,
   type ModelRequestDeadlineOptionsV1,
   requestToWire,
   streamWithModelRequestDeadlinesV1,
 } from "@frockbot/provider-openai-compatible";
+import type { Agent } from "@frockbot/kernel-agent-loop/agent";
 import type { Plugin } from "cordis";
-import { FROCK_AI_PROVIDER_TYPE, gatewayModelForFrockIdV1 } from "./catalog.js";
+import {
+  FROCK_AI_DEFAULT_MODEL,
+  FROCK_AI_PROVIDER_TYPE,
+  gatewayModelForFrockIdV1,
+} from "./catalog.js";
 
 export type OpenAICompatibleChatCompletionBodyV1 = Record<string, unknown>;
 
+/** The small error shape the Cloudflare host carries across this seam. */
+export class FrockAiTransportErrorV1 extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly retryAfterMs?: number,
+    readonly code?: string | number,
+  ) {
+    super(boundedModelProviderReasonV1(message));
+    this.name = "FrockAiTransportErrorV1";
+  }
+}
+
+function errorRecordV1(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Map both AI Gateway and Workers AI error envelopes to the model contract. */
+export function classifyFrockAiFailureV1(
+  error: unknown,
+): ModelProviderFailureError {
+  if (error instanceof ModelProviderFailureError) return error;
+  const outer = errorRecordV1(error);
+  const nested = errorRecordV1(outer?.error);
+  const status =
+    error instanceof FrockAiTransportErrorV1
+      ? error.status
+      : typeof outer?.status === "number"
+        ? outer.status
+        : undefined;
+  const code =
+    error instanceof FrockAiTransportErrorV1
+      ? error.code
+      : (nested?.code ?? outer?.code);
+  const reason =
+    error instanceof Error
+      ? error.message
+      : typeof nested?.message === "string"
+        ? nested.message
+        : typeof outer?.message === "string"
+          ? outer.message
+          : "Frock AI request did not reach the provider";
+  const words = `${String(code ?? "")} ${reason}`;
+  let classification: ModelProviderFailureClassV1;
+  if (status !== undefined) {
+    classification = classifyOpenAICompatibleFailureV1(
+      status,
+      typeof code === "string" ? code : undefined,
+    );
+  } else if (
+    /rate|overload|temporar|unavailable|timeout|timed out|gateway|reset/i.test(
+      words,
+    )
+  ) {
+    classification = "transient";
+  } else if (
+    /invalid|unauthor|forbidden|credential|not found|unknown model|content|safety|policy/i.test(
+      words,
+    )
+  ) {
+    classification = "permanent";
+  } else {
+    classification = "unknown";
+  }
+  return new ModelProviderFailureError({
+    classification,
+    reason,
+    ...(error instanceof FrockAiTransportErrorV1 &&
+    error.retryAfterMs !== undefined
+      ? { retryAfterMs: error.retryAfterMs }
+      : {}),
+  });
+}
+
 /**
  * The narrow native host seam. Cloudflare's generated `Ai` type remains in
  * apps/cloudflare; the Package consumes one streaming gateway operation.
@@ -40,6 +125,7 @@ export interface FrockAiRuntimeConfig {
 
 class FrockAiProvider implements LlmProvider {
   readonly id = FROCK_AI_PROVIDER_TYPE;
+  readonly autoFallbackFailures = new WeakSet<ModelProviderFailureError>();
 
   /**
    * The Gateway keeps no addressable copy of a completion, so an interrupted
@@ -63,9 +149,10 @@ class FrockAiProvider implements LlmProvider {
       binding?.connectionId !== this.config.connectionId ||
       binding.connectionGeneration !== this.config.connectionGeneration
     ) {
-      throw new LlmEffectNotStartedError(
-        "Frock AI request has invalid Connection authority",
-      );
+      throw new ModelProviderFailureError({
+        classification: "permanent",
+        reason: "Frock AI request has invalid Connection authority",
+      });
     }
     signal.throwIfAborted();
     const wire = requestToWire(request);
@@ -87,34 +174,73 @@ class FrockAiProvider implements LlmProvider {
     // otherwise bounded by nothing short of the fifteen-minute Turn deadline.
     // The seam's signal is derived from the caller's, so passing it down keeps
     // the cancellation and adds the deadline.
-    yield* streamWithModelRequestDeadlinesV1(
-      async (deadlineSignal) => {
-        try {
-          return await this.config.runChatCompletion(
-            gatewayModel,
-            body,
-            deadlineSignal,
-          );
-        } catch (error) {
-          deadlineSignal.throwIfAborted();
-          throw new LlmEffectNotStartedError(
-            error instanceof Error
-              ? error.message
-              : "Frock AI request did not reach the gateway",
-          );
-        }
-      },
-      signal,
-      this.config.deadlines ?? {},
-    );
+    try {
+      yield* streamWithModelRequestDeadlinesV1(
+        (deadlineSignal) =>
+          this.config.runChatCompletion(gatewayModel, body, deadlineSignal),
+        signal,
+        this.config.deadlines ?? {},
+      );
+    } catch (error) {
+      if (signal.aborted) throw error;
+      if (error instanceof ModelRequestDeadlineError) {
+        if (error.phase === "idle") throw error;
+        throw new ModelProviderFailureError({
+          classification: "transient",
+          reason: error.message,
+        });
+      }
+      const failure = classifyFrockAiFailureV1(error);
+      if (
+        failure.classification === "permanent" &&
+        request.model !== FROCK_AI_DEFAULT_MODEL
+      ) {
+        this.autoFallbackFailures.add(failure);
+      }
+      throw failure;
+    }
   }
 }
 
 export function createFrockAiRuntimePlugin(
   config: FrockAiRuntimeConfig,
 ): Plugin.Function {
-  const plugin: Plugin.Function = (ctx) =>
-    ctx.llm.register(new FrockAiProvider(config));
+  const plugin: Plugin.Function = (ctx) => {
+    const provider = new FrockAiProvider(config);
+    const fallbackAgents = new WeakSet<Agent>();
+    const disposeProvider = ctx.llm.register(provider);
+    const disposeFailure = ctx.on(
+      "agent/request-error",
+      async (agent, error, _signal, next) => {
+        if (
+          !(error instanceof ModelProviderFailureError) ||
+          !provider.autoFallbackFailures.has(error)
+        ) {
+          return next();
+        }
+        fallbackAgents.add(agent);
+        return { kind: "fallback" } as const;
+      },
+    );
+    const disposeRequest = ctx.on(
+      "agent/request",
+      async (agent, _request, _signal, next) => {
+        const request = await next();
+        return fallbackAgents.has(agent)
+          ? { ...request, model: FROCK_AI_DEFAULT_MODEL }
+          : request;
+      },
+    );
+    const disposeTurn = ctx.on("agent/turn-stopping", async (agent) => {
+      fallbackAgents.delete(agent);
+    });
+    return () => {
+      disposeTurn();
+      disposeRequest();
+      disposeFailure();
+      disposeProvider();
+    };
+  };
   plugin.inject = ["llm"];
   return plugin;
 }