@loopingai/core 0.5.0 → 0.6.0

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/budget.d.ts

@@ -44,4 +44,3 @@ export declare const newTurnBudget: (allowance: number) => TurnBudget;
  * attempt as the only one that can ever begin overdrawn.
  */
 export declare const stepAllowance: (maxTurns: number, spent: number) => number;
-//# sourceMappingURL=budget.d.ts.map

package/dist/agent/budget.js

@@ -40,4 +40,3 @@ export const newTurnBudget = (allowance) => ({
  * attempt as the only one that can ever begin overdrawn.
  */
 export const stepAllowance = (maxTurns, spent) => Math.max(1, maxTurns - spent);
-//# sourceMappingURL=budget.js.map

package/dist/agent/control.d.ts

@@ -107,4 +107,3 @@ export declare function controlTools(opts: {
 }): ControlTool[];
 /** The tools as the SDK takes them, in declaration order. */
 export declare function controlToolSet(tools: ControlTool[]): ToolSet;
-//# sourceMappingURL=control.d.ts.map

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) {
@@ -112,4 +113,3 @@ function issues(error) {
 export function controlToolSet(tools) {
     return Object.fromEntries(tools.map((c) => [c.name, c.tool]));
 }
-//# sourceMappingURL=control.js.map

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,7 +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>;
-//# sourceMappingURL=final-reply.d.ts.map
+}>;

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,8 +35,34 @@ 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
 });
-//# sourceMappingURL=final-reply.js.map

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;
 /**
@@ -95,4 +95,3 @@ export declare function sessionMessage(role: "user" | "assistant", text: string)
 export declare function sessionText(m: SessionMessage): string;
 /** Convert stored history to AI-SDK model messages (user/assistant text only). */
 export declare function toModelMessages(history: SessionMessage[]): ModelMessage[];
-//# sourceMappingURL=history.d.ts.map

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`;
@@ -131,4 +131,3 @@ export function toModelMessages(history) {
         content: sessionText(m)
     }));
 }
-//# sourceMappingURL=history.js.map

package/dist/agent/index.d.ts

@@ -19,10 +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";
-//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.js

@@ -19,10 +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";
-//# sourceMappingURL=index.js.map

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
@@ -49,4 +106,3 @@ export declare function isTransientAiError(err: unknown): boolean;
  * steps are skipped. Default `[]` (the subagent loop has no control tools).
  */
 export declare function buildIntermediateContentHandler(onContent: OnContent, terminalToolNames?: string[]): (step: StepResult<ToolSet>) => Promise<void>;
-//# sourceMappingURL=inference.d.ts.map