@loopingai/core 0.5.1 → 0.6.0

package/dist/agent/anthropic/runtime.d.ts

@@ -0,0 +1,79 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { ModelConfig } from "../../config.js";
+import type { CredentialRejectedBy } from "../errors.js";
+import type { ModelRuntime } from "../model.js";
+import type { CacheTtl } from "./prompt.js";
+/**
+ * A {@link ModelRuntime} backed by Claude, for agents whose work justifies it.
+ *
+ * `ModelRuntime` / `ModelPair` were already the right interface — the Workers AI
+ * implementation in {@link file://../model.ts model.ts} is one implementation of
+ * it, not the definition. This is a sibling, so an agent switches providers by
+ * overriding `modelRuntime()` and changes nothing else.
+ *
+ * Provider choice is per **agent**, not per deployment: the fleet keeps running
+ * on Workers AI and one tenant opts into Claude.
+ */
+export interface AnthropicRuntimeDeps {
+    /**
+     * Base URL for the Messages API.
+     *
+     * A thunk because the useful value — `env.AI.gateway(id).getUrl("anthropic")`
+     * — is only obtainable once bindings exist. Routing through AI Gateway is what
+     * keeps Claude calls in the same logs as every Workers AI call; point it at
+     * `https://api.anthropic.com` to bypass the gateway.
+     */
+    baseUrl: () => string | Promise<string>;
+    /**
+     * The bearer credential, resolved lazily so a rotated secret is picked up by
+     * the next isolate without a redeploy.
+     *
+     * Async-capable, like {@link baseUrl}, because the credential is not always a
+     * stored secret. A deployment that puts an authenticated intermediary in
+     * front of Anthropic mints a short-lived token per request instead — signing
+     * is asynchronous, and a token with a lifetime measured in minutes cannot be
+     * captured once and reused, which is why the client is rebuilt per call
+     * rather than memoized. See the note above `clientFor`.
+     */
+    authToken: () => string | Promise<string>;
+    /**
+     * AI Gateway token, when the gateway has **Authenticated Gateway** enabled.
+     *
+     * Required in that case and only that case, which is why it is optional:
+     * pointing `baseUrl` at `api.anthropic.com`, or at a gateway with
+     * authentication off, must keep working with no token at all.
+     *
+     * Easy to miss, because the agents on Workers AI never need it — `env.AI.run()`
+     * reaches the gateway through the binding, which the platform authenticates.
+     * Only a client calling the **provider-native URL** presents credentials of
+     * its own, and a gateway with authentication on rejects it at the door: a
+     * `401` that never reaches Anthropic and never appears in the gateway's own
+     * call log, which makes it look like the model credential was refused.
+     */
+    gatewayToken?: () => string | undefined;
+    /** Model ids, gateway slug and output ceiling — the agent's resolved config. */
+    config: ModelConfig;
+    /**
+     * `output_config.effort`. Coding and agentic work wants `"xhigh"`; the API
+     * default is `"high"`. Core does not choose this — the agent does.
+     */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /**
+     * Prompt-cache TTL. `"1h"` costs 2x on write instead of 1.25x and is the right
+     * call for an agent whose rounds are separated by minutes of tool work — a
+     * container boot, an install, a test suite — because a 5-minute entry has
+     * expired by the next round and the whole prefix is re-billed at full price.
+     */
+    cache?: CacheTtl | false;
+    /**
+     * Recognise a deployment-specific authority in a rejected-credential body —
+     * notably the intermediary {@link gatewayToken}'s note describes, which fails
+     * with the same `401` as the gateway and the provider and has a completely
+     * different remedy. See
+     * {@link file://./language-model.ts AnthropicModelDeps.classifyAuthFailure}.
+     */
+    classifyAuthFailure?: (body: unknown) => CredentialRejectedBy | undefined;
+    /** Escape hatch for tests: use this instead of constructing a real client. */
+    clientOverride?: Anthropic;
+}
+export declare function createAnthropicModelRuntime(deps: AnthropicRuntimeDeps): ModelRuntime;

package/dist/agent/anthropic/runtime.js

@@ -0,0 +1,130 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { createAnthropicLanguageModel } from "./language-model.js";
+/**
+ * The beta Anthropic requires to accept a bearer credential rather than an
+ * `x-api-key`.
+ */
+const OAUTH_BETA = "oauth-2025-04-20";
+/**
+ * AI Gateway's per-request log metadata header.
+ *
+ * Core already stamps `{taskId, round}` on a turn and `{taskId, subtaskId}` on a
+ * subagent chunk so a model call can be tied back to the work that made it; the
+ * Workers AI provider carries that in its settings object. Anthropic has no such
+ * field, so it rides as a header instead — same correlation, different envelope.
+ * Capped at five entries by the gateway; extra keys are dropped there, so trim
+ * here rather than sending something that silently truncates.
+ */
+const GATEWAY_METADATA_HEADER = "cf-aig-metadata";
+const GATEWAY_METADATA_MAX_ENTRIES = 5;
+/**
+ * AI Gateway's own authorization header — deliberately *not* `Authorization`,
+ * which already carries the model provider's credential on the same request.
+ * Two independent authorities, two headers.
+ *
+ * A client header rather than a per-pair one: it authenticates the caller to the
+ * gateway, which does not vary by task or round, unlike
+ * {@link GATEWAY_METADATA_HEADER}.
+ */
+const GATEWAY_AUTH_HEADER = "cf-aig-authorization";
+function metadataHeaders(metadata) {
+    if (!metadata)
+        return {};
+    const entries = Object.entries(metadata).slice(0, GATEWAY_METADATA_MAX_ENTRIES);
+    if (entries.length === 0)
+        return {};
+    return {
+        [GATEWAY_METADATA_HEADER]: JSON.stringify(Object.fromEntries(entries))
+    };
+}
+export function createAnthropicModelRuntime(deps) {
+    const { config } = deps;
+    /**
+     * The resolved base URL, memoized — **not** the client.
+     *
+     * Resolving is what is expensive and what must not happen at module scope:
+     * `wrangler deploy` evaluates module scope to validate the new version and
+     * bindings are unpopulated at that point, so an eager `baseUrl()` would throw
+     * during deploy. That argument is about the *URL*, which is why it is the URL
+     * that is cached.
+     *
+     * Assigned only on success, so a failed gateway lookup is retried on the next
+     * round rather than cached as a rejected promise for the life of the isolate.
+     * Two concurrent first calls may each resolve one; they are identical, and
+     * the cost is a spare string.
+     */
+    let resolvedBaseUrl;
+    /**
+     * A client per call, deliberately.
+     *
+     * This used to memoize the `Anthropic` instance, which bakes the credential
+     * in at construction. That is correct only while the credential outlives the
+     * isolate. It does not when {@link AnthropicRuntimeDeps.authToken} mints a
+     * short-lived token per request: the first call succeeds, and every call
+     * after the token's lifetime gets a `401` — intermittently, only under
+     * sustained load, and pointing at the wrong secret.
+     *
+     * Rebuilding is close to free. `new Anthropic({...})` is pure config
+     * assembly — no network, no handshake — so the per-call cost is an object
+     * allocation, against a correctness bug that only appears in production.
+     * The per-pair headers ride on the request rather than the client, so nothing
+     * else depended on the instance being shared.
+     */
+    const clientFor = async () => {
+        if (deps.clientOverride)
+            return deps.clientOverride;
+        // Awaited, not cast. `env.AI.gateway(id).getUrl()` returns a PROMISE:
+        // handing it to `baseURL` unresolved type-checks only behind an `as
+        // string`, then fails deep inside the SDK on `baseURL.endsWith is not a
+        // function`, on every request, with nothing naming the gateway. The await
+        // is why this thunk is async and why `client` is awaited at the call site.
+        resolvedBaseUrl ??= await deps.baseUrl();
+        const gatewayToken = deps.gatewayToken?.();
+        return new Anthropic({
+            authToken: await deps.authToken(),
+            // Explicitly null, or the SDK falls back to resolving credentials from
+            // config files and env vars — which on Workers means a confusing failure
+            // far from the actual misconfiguration.
+            apiKey: null,
+            baseURL: resolvedBaseUrl,
+            defaultHeaders: {
+                "anthropic-beta": OAUTH_BETA,
+                ...(gatewayToken
+                    ? { [GATEWAY_AUTH_HEADER]: `Bearer ${gatewayToken}` }
+                    : {})
+            },
+            // Retry lives one layer up, in the AI SDK, which is the only layer that
+            // honours the provider's own `retry-after` — see `ModelConfig.maxRetries`
+            // and the `APICallError` mapping that feeds it. A second layer here would
+            // multiply that wait and defeat the fallback's timing.
+            maxRetries: 0
+        });
+    };
+    return {
+        createModelPair(overrides = {}) {
+            const primaryId = overrides.primaryModelId ?? config.chatModelId;
+            const fallbackId = overrides.fallbackModelId ?? config.fallbackChatModelId;
+            const headers = metadataHeaders(overrides.metadata);
+            const build = (modelId) => createAnthropicLanguageModel({
+                client: clientFor,
+                modelId,
+                defaultMaxTokens: config.maxOutputTokens,
+                ...(deps.effort ? { effort: deps.effort } : {}),
+                ...(deps.cache !== undefined ? { cache: deps.cache } : {}),
+                ...(deps.classifyAuthFailure
+                    ? { classifyAuthFailure: deps.classifyAuthFailure }
+                    : {}),
+                headers
+            });
+            let primary;
+            let fallback;
+            return {
+                primary: () => (primary ??= overrides.model ?? build(primaryId)),
+                fallback: () => (fallback ??=
+                    overrides.fallbackModel ?? overrides.model ?? build(fallbackId)),
+                primaryId: () => primaryId,
+                fallbackId: () => fallbackId
+            };
+        }
+    };
+}

package/dist/agent/control.js

@@ -64,9 +64,8 @@ export function controlTools(opts) {
                 if (!parsed.success) {
                     throw new ControlCallError(`${DELEGATE_TOOL_NAME} input is invalid — ${issues(parsed.error)}`);
                 }
-                // Everything past the schema — unknown reference indexes, dependency
-                // cycles, a type's required params — throws its own error, already worded
-                // for the model.
+                // Everything past the schema — unknown reference indexes, a type's
+                // required params — throws its own error, already worded for the model.
                 const { reply, drafts } = resolveDecomposition({
                     ...parsed.data,
                     subtasks: parsed.data.subtasks.map((s) => ({
@@ -84,11 +83,12 @@ export function controlTools(opts) {
  * Drop params the model sent as an explicit `undefined`.
  *
  * The delegate schema declares the union of every type's param keys, all optional,
- * so one tool schema can serve every type (see `subtaskParamProperties`). A model
- * that names a key and leaves it empty has sent no param, and forwarding the key
- * with an `undefined` value would only make a missing required param report itself
- * as a *present* one. Whether what survives satisfies the type is still
- * `validateSubtaskParams`'s call, downstream.
+ * so one tool schema can serve every type (see
+ * `SubtaskTypeRegistry.paramProperties`). A model that names a key and leaves it
+ * empty has sent no param, and forwarding the key with an `undefined` value would
+ * only make a missing required param report itself as a *present* one. Whether
+ * what survives satisfies the type is still
+ * `SubtaskTypeRegistry.validateParams`'s call, downstream.
  */
 function definedParams(params) {
     if (!params)
@@ -100,7 +100,8 @@ function definedParams(params) {
 }
 /**
  * A zod failure as one line the model can act on: which field, and what was wrong.
- * The same rendering {@link file://./subtasks/subtask-types.ts validateSubtaskParams}
+ * The same rendering
+ * {@link file://../subtasks/subtask-types.ts SubtaskTypeRegistry.validateParams}
  * uses, so every rejection a control call can produce reads the same way.
  */
 function issues(error) {

package/dist/agent/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Failures the loops must treat specially, whichever provider raised them.
+ *
+ * A sibling of {@link file://./model.ts model.ts} and neutral for the same
+ * reason: a provider directory may throw these, and nothing here may know that
+ * any particular one exists. `nonRecoverableKind` in
+ * {@link file://./inference.ts inference.ts} keys on this file, so a provider
+ * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
+ * gets the same handling as `agent/anthropic` with no change to core.
+ *
+ * ## Why a third classification was needed at all
+ *
+ * Core's attempt ladder splits every failure two ways — transient conditions
+ * throw out so the Workflow step retries the whole round, everything else burns
+ * the model slot and hands over to the fallback (see
+ * {@link file://./inference.ts isTransientAiError}). An expired credential fits
+ * neither: retrying spends the Workflow's budget on a request that can never
+ * succeed, and falling back spends the second slot on the *same* rejected token.
+ * It has to stop the round and say what a human must do.
+ *
+ * Note that being non-transient is not enough on its own — "not transient" is
+ * precisely the signal that means "try the fallback".
+ */
+/**
+ * Who refused the request, when a `401` came back.
+ *
+ * There can be up to three authorities on the path, each with its own
+ * credential: the AI Gateway (`cf-aig-authorization`), an optional intermediary
+ * a deployment puts between the gateway and the provider (`"proxy"`), and the
+ * model provider itself (`Authorization`). They fail with the same status code
+ * and completely different remedies, so a rejection that does not say which one
+ * it was sends an operator to rotate the wrong secret — which is exactly what
+ * happened before this existed.
+ *
+ * `"proxy"` is the odd one out: it is generally *not* a secret to rotate. An
+ * intermediary that mints its caller credential per request fails for reasons
+ * upstream of any stored secret — configuration drift, a rotated signing key,
+ * clock skew — so the remedy is to look, not to rotate. Core recognises no
+ * particular intermediary; a deployment that has one supplies its own classifier
+ * (see `AnthropicModelDeps.classifyAuthFailure`).
+ *
+ * `"unknown"` is a real answer and the default. Guessing `"provider"` for an
+ * unrecognised body is how the misdiagnosis happens; saying "one of these, here
+ * is how to check each" is worse copy and better information.
+ */
+export type CredentialRejectedBy = "provider" | "gateway" | "proxy" | "unknown";
+/**
+ * A credential on the path to the model was rejected (HTTP 401 / 403).
+ *
+ * Deliberately not an `APICallError`: the AI SDK's classifier treats those as
+ * potentially retryable, and this never is.
+ * {@link file://./inference.ts nonRecoverableKind} maps it to one of the
+ * credential kinds — which one depends on {@link source} — and that is what
+ * stops the round before the fallback slot; `isTransientAiError` additionally
+ * returns `false` so the message text can never be mistaken for a rate limit.
+ *
+ * The round then fails carrying that kind, and the host supplies the
+ * operator-facing copy through `HandleTaskDeps.failureCopy` — core owns the
+ * signal and the delivery, never the wording.
+ */
+export declare class CredentialRejectedError extends Error {
+    readonly name = "CredentialRejectedError";
+    /** The upstream status, when one was available. */
+    readonly status: number | undefined;
+    /** Which authority rejected it. See {@link CredentialRejectedBy}. */
+    readonly source: CredentialRejectedBy;
+    constructor(message: string, options?: {
+        status?: number;
+        source?: CredentialRejectedBy;
+        cause?: unknown;
+    });
+    /**
+     * Structural check rather than `instanceof`.
+     *
+     * A Worker bundle can end up with two copies of this module (core linked as a
+     * tarball while a plugin resolves its own), and `instanceof` fails across
+     * them — the same realm hazard `AGENTS.md` calls out for `agents`. The name is
+     * a readonly literal, so this is as strong in practice and survives bundling.
+     *
+     * It is also what lets a provider outside core raise one: anything named
+     * `CredentialRejectedError` with a `source` is honoured, no shared class
+     * identity required.
+     */
+    static isInstance(err: unknown): err is CredentialRejectedError;
+}

package/dist/agent/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Failures the loops must treat specially, whichever provider raised them.
+ *
+ * A sibling of {@link file://./model.ts model.ts} and neutral for the same
+ * reason: a provider directory may throw these, and nothing here may know that
+ * any particular one exists. `nonRecoverableKind` in
+ * {@link file://./inference.ts inference.ts} keys on this file, so a provider
+ * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
+ * gets the same handling as `agent/anthropic` with no change to core.
+ *
+ * ## Why a third classification was needed at all
+ *
+ * Core's attempt ladder splits every failure two ways — transient conditions
+ * throw out so the Workflow step retries the whole round, everything else burns
+ * the model slot and hands over to the fallback (see
+ * {@link file://./inference.ts isTransientAiError}). An expired credential fits
+ * neither: retrying spends the Workflow's budget on a request that can never
+ * succeed, and falling back spends the second slot on the *same* rejected token.
+ * It has to stop the round and say what a human must do.
+ *
+ * Note that being non-transient is not enough on its own — "not transient" is
+ * precisely the signal that means "try the fallback".
+ */
+/**
+ * A credential on the path to the model was rejected (HTTP 401 / 403).
+ *
+ * Deliberately not an `APICallError`: the AI SDK's classifier treats those as
+ * potentially retryable, and this never is.
+ * {@link file://./inference.ts nonRecoverableKind} maps it to one of the
+ * credential kinds — which one depends on {@link source} — and that is what
+ * stops the round before the fallback slot; `isTransientAiError` additionally
+ * returns `false` so the message text can never be mistaken for a rate limit.
+ *
+ * The round then fails carrying that kind, and the host supplies the
+ * operator-facing copy through `HandleTaskDeps.failureCopy` — core owns the
+ * signal and the delivery, never the wording.
+ */
+export class CredentialRejectedError extends Error {
+    name = "CredentialRejectedError";
+    /** The upstream status, when one was available. */
+    status;
+    /** Which authority rejected it. See {@link CredentialRejectedBy}. */
+    source;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.status = options?.status;
+        this.source = options?.source ?? "unknown";
+    }
+    /**
+     * Structural check rather than `instanceof`.
+     *
+     * A Worker bundle can end up with two copies of this module (core linked as a
+     * tarball while a plugin resolves its own), and `instanceof` fails across
+     * them — the same realm hazard `AGENTS.md` calls out for `agents`. The name is
+     * a readonly literal, so this is as strong in practice and survives bundling.
+     *
+     * It is also what lets a provider outside core raise one: anything named
+     * `CredentialRejectedError` with a `source` is honoured, no shared class
+     * identity required.
+     */
+    static isInstance(err) {
+        return err instanceof Error && err.name === "CredentialRejectedError";
+    }
+}

package/dist/agent/final-reply.d.ts

@@ -1,3 +1,4 @@
+import { type Tool } from "ai";
 import { z } from "zod";
 /**
  * The `final_reply` tool — the main agent answering the user itself, and the other
@@ -12,7 +13,7 @@ import { z } from "zod";
  * So prose is no longer an outcome. Both endings are now named tools, the round runs
  * with `toolChoice: "required"`, and a round that ends any other way has failed its
  * attempt. The *choice* is still entirely the model's — the point of the design (see
- * {@link file://./turn.ts turn.ts}) was never that the model be steered toward
+ * {@link file://../round/turn.ts turn.ts}) was never that the model be steered toward
  * delegating, only that it not be forced. Picking between two named tools is also a
  * far easier discrimination for a small model than picking between prose and a tool,
  * which is what the weaker fallback models kept getting wrong.
@@ -20,16 +21,6 @@ import { z } from "zod";
  * This lives outside `subtasks/` deliberately: replying is not a subtask concept.
  */
 export declare const FINAL_REPLY_TOOL_NAME = "final_reply";
-/**
- * The tool as the model sees it. **Without `execute`**, exactly like
- * {@link file://./subtasks/delegate.ts delegateTool}: the call *is* the round's
- * output, so there is nothing for the SDK to run and the loop halts on it.
- *
- * Unlike `delegate`, this call is never reconstructed in a later round's history —
- * a past reply is stored as, and replayed as, ordinary assistant text (history is
- * text-only by design). The tool exists to constrain *generation*, not to become a
- * new shape in the transcript.
- */
 /**
  * The call's input, exported as the zod schema rather than only as the tool's
  * `inputSchema`, because the round has to run it itself.
@@ -43,6 +34,16 @@ export declare const FINAL_REPLY_TOOL_NAME = "final_reply";
 export declare const finalReplyInputSchema: z.ZodObject<{
     text: z.ZodString;
 }, z.core.$strip>;
-export declare const finalReplyTool: import("ai").Tool<{
+/**
+ * The tool as the model sees it. **Without `execute`**, exactly like
+ * {@link file://../subtasks/delegate.ts delegateTool}: the call *is* the round's
+ * output, so there is nothing for the SDK to run and the loop halts on it.
+ *
+ * Unlike `delegate`, this call is never reconstructed in a later round's history —
+ * a past reply is stored as, and replayed as, ordinary assistant text (history is
+ * text-only by design). The tool exists to constrain *generation*, not to become a
+ * new shape in the transcript.
+ */
+export declare const finalReplyTool: Tool<{
     text: string;
-}, never, import("@ai-sdk/provider-utils").Context>;
+}>;

package/dist/agent/final-reply.js

@@ -14,7 +14,7 @@ import { nonBlank } from "../subtasks/decomposition.js";
  * So prose is no longer an outcome. Both endings are now named tools, the round runs
  * with `toolChoice: "required"`, and a round that ends any other way has failed its
  * attempt. The *choice* is still entirely the model's — the point of the design (see
- * {@link file://./turn.ts turn.ts}) was never that the model be steered toward
+ * {@link file://../round/turn.ts turn.ts}) was never that the model be steered toward
  * delegating, only that it not be forced. Picking between two named tools is also a
  * far easier discrimination for a small model than picking between prose and a tool,
  * which is what the weaker fallback models kept getting wrong.
@@ -22,16 +22,6 @@ import { nonBlank } from "../subtasks/decomposition.js";
  * This lives outside `subtasks/` deliberately: replying is not a subtask concept.
  */
 export const FINAL_REPLY_TOOL_NAME = "final_reply";
-/**
- * The tool as the model sees it. **Without `execute`**, exactly like
- * {@link file://./subtasks/delegate.ts delegateTool}: the call *is* the round's
- * output, so there is nothing for the SDK to run and the loop halts on it.
- *
- * Unlike `delegate`, this call is never reconstructed in a later round's history —
- * a past reply is stored as, and replayed as, ordinary assistant text (history is
- * text-only by design). The tool exists to constrain *generation*, not to become a
- * new shape in the transcript.
- */
 /**
  * The call's input, exported as the zod schema rather than only as the tool's
  * `inputSchema`, because the round has to run it itself.
@@ -45,6 +35,33 @@ export const FINAL_REPLY_TOOL_NAME = "final_reply";
 export const finalReplyInputSchema = z.object({
     text: nonBlank("text").describe("Your reply, in your own voice. This is shown to the user verbatim, so it must be the complete answer and must not be blank.")
 });
+/**
+ * The tool as the model sees it. **Without `execute`**, exactly like
+ * {@link file://../subtasks/delegate.ts delegateTool}: the call *is* the round's
+ * output, so there is nothing for the SDK to run and the loop halts on it.
+ *
+ * Unlike `delegate`, this call is never reconstructed in a later round's history —
+ * a past reply is stored as, and replayed as, ordinary assistant text (history is
+ * text-only by design). The tool exists to constrain *generation*, not to become a
+ * new shape in the transcript.
+ */
+/*
+ * Annotated, not inferred, and the annotation is a **packaging** constraint
+ * rather than a style choice.
+ *
+ * `tool()` returns `Tool<Input, Output, Context>`, and `Context` lives in
+ * `@ai-sdk/provider-utils` — an internal of `ai`, which resolves it as a nested
+ * copy. Left inferred, `tsc` emits `import("@ai-sdk/provider-utils").Context`
+ * into this module's `.d.ts`, so every consumer typechecking
+ * `@loopingai/core/agent` needs a package this one does not declare and cannot
+ * usefully declare: pinning it here installs a *second*, different major
+ * alongside `ai`'s own, and TypeScript then refuses the reference outright as
+ * unportable.
+ *
+ * Naming the type through `ai`'s own re-export keeps the emitted declaration
+ * pointing at a package that is already a required peer. `verify:exports` walks
+ * the declaration graph for exactly this.
+ */
 export const finalReplyTool = tool({
     description: "Answer the user and end this round. Use this whenever the request is yours to answer — anything about this conversation, your own history, memory, or tools, and anything you can settle with the tools available to you here, including work that has already come back to you.",
     inputSchema: finalReplyInputSchema

package/dist/agent/history.d.ts

@@ -3,7 +3,7 @@ import type { SessionMessage } from "agents/experimental/memory/session";
 /**
  * Session-history glue for the agent runtime: parse the gateway-authored `<turn>`
  * provenance wrapper, and bridge between plain text and the Agents-SDK Sessions
- * store. No A2A types cross this boundary — the {@link file://../a2a/inbound.ts
+ * store. No A2A types cross this boundary — the {@link file://../a2a/parts.ts
  * A2A adapter} has already reduced the inbound message to a plain string.
  *
  * The gateway inlines a `<turn from="…" id="…" channel="…" at="…">…</turn>` tag
@@ -53,8 +53,8 @@ export declare function taskUserMessageId(taskId: string): string;
  * Id of the acknowledgment a **delegating** round publishes — the message the
  * user sees while that round's Subtasks run. Also the anchor a later round finds
  * to reattach the round's `delegate` call to (see
- * {@link file://./turn.ts renderTurnMessages}), which is why it is derived from
- * the round rather than stored.
+ * {@link file://../round/turn.ts renderTurnMessages}), which is why it is
+ * derived from the round rather than stored.
  */
 export declare function roundAckMessageId(taskId: string, round: number): string;
 /**

package/dist/agent/history.js

@@ -61,8 +61,8 @@ export function taskUserMessageId(taskId) {
  * Id of the acknowledgment a **delegating** round publishes — the message the
  * user sees while that round's Subtasks run. Also the anchor a later round finds
  * to reattach the round's `delegate` call to (see
- * {@link file://./turn.ts renderTurnMessages}), which is why it is derived from
- * the round rather than stored.
+ * {@link file://../round/turn.ts renderTurnMessages}), which is why it is
+ * derived from the round rather than stored.
  */
 export function roundAckMessageId(taskId, round) {
     return `task:${taskId}:round:${round}:ack`;

package/dist/agent/index.d.ts

@@ -19,9 +19,11 @@
  * exactly what is here.
  */
 export { newTurnBudget, stepAllowance, type TurnBudget } from "./budget.js";
-export { createModelRuntime, type GatewayMetadata, type ModelOverrides, type ModelPair, type ModelRuntime, type ModelRuntimeDeps } from "./model.js";
+export { type GatewayMetadata, type ModelOverrides, type ModelPair, type ModelRuntime, type ModelRuntimeFactory } from "./model.js";
+export { CredentialRejectedError, type CredentialRejectedBy } from "./errors.js";
+export { createWorkersAIModelRuntime, workersAIModels, type WorkersAIRuntimeDeps } from "./workers-ai/index.js";
 export { appendOnce, buildAgentSession, notifyingCompaction, type AgentSessionOptions, type SessionHost, type SessionLike } from "./session.js";
 export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionMessage, sessionText, taskUserMessageId, toModelMessages, type ParsedTurn } from "./history.js";
-export { buildIntermediateContentHandler, isTransientAiError, type OnContent } from "./inference.js";
+export { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind, type NonRecoverableKind, type OnContent, type RoundFailureKind } from "./inference.js";
 export { ControlCallError, controlTools, controlToolSet, type ControlTool, type TurnDecision } from "./control.js";
 export { FINAL_REPLY_TOOL_NAME, finalReplyInputSchema, finalReplyTool } from "./final-reply.js";

package/dist/agent/index.js

@@ -19,9 +19,11 @@
  * exactly what is here.
  */
 export { newTurnBudget, stepAllowance } from "./budget.js";
-export { createModelRuntime } from "./model.js";
+export {} from "./model.js";
+export { CredentialRejectedError } from "./errors.js";
+export { createWorkersAIModelRuntime, workersAIModels } from "./workers-ai/index.js";
 export { appendOnce, buildAgentSession, notifyingCompaction } from "./session.js";
 export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionMessage, sessionText, taskUserMessageId, toModelMessages } from "./history.js";
-export { buildIntermediateContentHandler, isTransientAiError } from "./inference.js";
+export { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind } from "./inference.js";
 export { ControlCallError, controlTools, controlToolSet } from "./control.js";
 export { FINAL_REPLY_TOOL_NAME, finalReplyInputSchema, finalReplyTool } from "./final-reply.js";

package/dist/agent/inference.d.ts

@@ -5,7 +5,7 @@ import type { StepResult, ToolSet } from "ai";
  *
  * The two loops themselves are deliberately separate, not layered on a common
  * one: the main agent's Session-coupled round lives in
- * {@link file://./turn.ts turn.ts}, and the Session-less subagent loop in
+ * {@link file://../round/turn.ts turn.ts}, and the Session-less subagent loop in
  * {@link file://../subagent/run.ts run.ts}. They share error classification and
  * progress streaming; their control flow has nothing in common worth abstracting.
  */
@@ -34,6 +34,63 @@ export type OnContent = (text: string, stepIndex: number) => void | Promise<void
  * error codes, which arrive as prose on a plain `Error`.
  */
 export declare function isTransientAiError(err: unknown): boolean;
+/**
+ * Why a round stopped without a second attempt being worth making.
+ *
+ * A stable string rather than the error itself, because this value crosses two
+ * serialization boundaries — the DO's RPC return and a Workflow step result —
+ * and an `Error` survives neither reliably. The host maps it to operator-facing
+ * copy; core never owns that wording.
+ *
+ * The credential kinds are separate strings rather than one, because they have
+ * different remedies and the host cannot tell them apart afterwards:
+ *
+ * - `credential` — the model provider rejected the token. Rotate that one.
+ * - `gateway-credential` — the gateway *in front of* the provider rejected the
+ *   request, which the provider therefore never saw. Rotate the gateway's token
+ *   instead; the model credential is very likely fine.
+ * - `proxy-credential` — an intermediary between the gateway and the provider
+ *   rejected the caller. Notably **not** a token to rotate: the credential it
+ *   refused is minted per request, so the fault is upstream of the secret —
+ *   configuration drift, a rotated signing key, or clock skew.
+ * - `unknown-credential` — a `401`/`403` matching none of the shapes. Says so,
+ *   rather than picking one and sending an operator to rotate a working secret.
+ */
+export type NonRecoverableKind = "credential" | "gateway-credential" | "proxy-credential" | "unknown-credential";
+/**
+ * Why a round ended with no answer — one terminal status, two situations.
+ *
+ * `exhausted` is the ladder run to the end: both slots tried, every repair
+ * spent, nothing usable produced. Every other member is the ladder stopping
+ * early, because nothing further could have cleared the fault — see
+ * {@link nonRecoverableKind}.
+ *
+ * The distinction is a *reason*, not an outcome: both deliver a failed Task with
+ * the same shape. What it decides is the words, and only the host has those (see
+ * `HandleTaskDeps.failureCopy`) — which is why this is a total union rather than
+ * an optional field. A consumer that maps kinds to copy is then a `Record` the
+ * compiler checks, and a new kind cannot be silently ignored by any of them.
+ */
+export type RoundFailureKind = "exhausted" | NonRecoverableKind;
+/**
+ * Whether an error is one that **no** further attempt can clear, and the reason.
+ *
+ * This is the third classification, and the one the other two cannot express.
+ * {@link isTransientAiError} splits failures into "retry the step" (`true`) and
+ * "burn this slot, try the fallback" (`false`) — and for a rejected credential
+ * *both* are wrong. Retrying spends the Workflow's budget on a request that can
+ * never succeed; falling back spends the second slot presenting the *same* dead
+ * token. Returning `false` from the transient check only avoids the first.
+ *
+ * So the attempt ladders check this **before** entering the fallback slot and
+ * stop there, and `runHandleTask` ends the Task with copy the host supplies.
+ * Nothing is retried and nothing is spent proving the obvious twice.
+ *
+ * Keyed on {@link file://./errors.ts CredentialRejectedError}, which is neutral
+ * and structurally matched — so a provider outside core raises one and gets this
+ * handling with nothing here to change.
+ */
+export declare function nonRecoverableKind(err: unknown): NonRecoverableKind | undefined;
 /**
  * Returns a fresh `onStepEnd` callback for one `generateText` attempt.
  * Fires `onContent` for each intermediate step (text that accompanies tool