@loopingai/core 0.5.1 → 0.7.0

package/README.md

@@ -188,8 +188,8 @@ probed for), and hand-rolling it is how two agents in one repo drift apart.
 
 ### 4. Delegate, if your agent delegates
 
-`@loopingai/core/round` adds the other half: a durable Subtask DAG, wave
-scheduling, isolated subagent execution, and the round loop over them.
+`@loopingai/core/round` adds the other half: durable Subtasks, concurrent
+execution, isolated subagents, and the round loop over them.
 
 ```ts
 import { RoundAgentBase, type RoundPolicy } from "@loopingai/core/round";
@@ -225,10 +225,11 @@ not drag in the A2A adapter, and the test harness cannot reach a production bund
 | `@loopingai/core`              | `createAgentRuntime`, the plugin contract, config shapes, platform facts    |
 | `@loopingai/core/a2a`          | card signing, JWKS, gateway-JWT verify, push notify, task store, executor   |
 | `@loopingai/core/worker`       | `createA2AWorker()` — the whole zero-trust edge                             |
-| `@loopingai/core/agent`        | session, history, model runtime, inference, budget, control tools           |
+| `@loopingai/core/agent`        | session, history, models + Workers AI, inference, budget, control tools     |
 | `@loopingai/core/host`         | `LoopingAgent` — the Durable Object body — and `PluginHost`                 |
 | `@loopingai/core/round`        | the delegating round loop: `RoundAgentBase`, `runHandleTask`, `runTurn`     |
-| `@loopingai/core/subtasks`     | delegation types, decomposition, the `delegate` tool, wave scheduler        |
+| `@loopingai/core/anthropic`    | Claude as a second provider — _optional peer on `@anthropic-ai/sdk`_        |
+| `@loopingai/core/subtasks`     | delegation types, decomposition, the `delegate` tool                        |
 | `@loopingai/core/subagent`     | `RecipeSubagentBase`, resumable runs, fingerprinting, workspace             |
 | `@loopingai/core/db`           | `AgentDB`, `notify_tasks` + `subtasks` schema, migrations, `PluginStore`    |
 | `@loopingai/core/testing`      | VCR, `FakeSession`, `mockModel`, DO helpers, JWK fixtures — _workerd realm_ |
@@ -465,6 +466,7 @@ await withDb("accepts a turn once", async (db) => {
 - **Bindings:** `AI`, one Durable Object, one Workflow
 - **Secrets:** `A2A_SIGNING_KEY`, `GATEWAY_ORIGINS`
 - **Peers, never bundled:** `agents`, `ai`, `workers-ai-provider`
+- **Optional peer:** `@anthropic-ai/sdk`, needed only by `@loopingai/core/anthropic`
 
 That last point is not stylistic: two copies of `agents` in one Worker breaks the
 `Session` / `SessionMessage` types and every `instanceof`. For local development

package/dist/a2a/caller-token.d.ts

@@ -0,0 +1,38 @@
+export interface CallerTokenOptions {
+    /** This agent's raw private JWK JSON — the same `A2A_SIGNING_KEY` its card is signed with. */
+    signingKey: string;
+    /**
+     * This agent's own origin. It becomes `iss`, and `jku` is derived from it, and
+     * the two must agree: a verifier that accepts a `jku` on a different origin
+     * than `iss` lets one allowlisted origin impersonate another.
+     */
+    issuer: string;
+    /**
+     * Who the token is for. Normalized to a bare origin, because a verifier
+     * typically derives what it expects from `new URL(request.url).origin` and
+     * `jose` compares `aud` byte-for-byte — a trailing slash or a stray path is a
+     * 401 on every request with nothing to catch it. Throws on a value that is not
+     * an absolute URL, which is the right moment for that to fail.
+     */
+    audience: string;
+    /** The identity this agent asserts. */
+    identity: Record<string, unknown>;
+    /** Which tenant of this deployment the token speaks for. */
+    tenant: string;
+    /** Lifetime in seconds. Defaults to 120. */
+    ttlSeconds?: number;
+}
+/**
+ * Sign a short-lived token identifying **this agent as a caller** to another
+ * service that trusts its card key.
+ *
+ * The production sibling of `makeGatewayToken`, which core previously shipped
+ * only from `/testing` — so an agent that had to call out mint-signed had to
+ * hand-write this shape, and every deployment that did so wrote its own subtly
+ * different version of the `iss`/`jku` agreement above.
+ *
+ * Distinct from {@link signCallbackJwt}, which carries **no** claims: that one
+ * proves "the agent you called is calling you back about this task", where this
+ * proves "this is who I am and which tenant I speak for".
+ */
+export declare function signCallerToken(options: CallerTokenOptions): Promise<string>;

package/dist/a2a/caller-token.js

@@ -0,0 +1,61 @@
+import { importJWK, SignJWT } from "jose";
+import { A2A_JWS_ALG, IDENTITY_CLAIM, TENANT_CLAIM, jwksUrl } from "@loopingai/a2a-protocol";
+import { parsePrivateJwk } from "./card.js";
+/** Default lifetime: long enough for clock skew, short enough to be worthless from a log. */
+const DEFAULT_TTL_SECONDS = 120;
+/**
+ * `importJWK` does real work and this is on the per-request path.
+ *
+ * Keyed by the raw secret so a rotated key invalidates the entry rather than
+ * being ignored for the life of the isolate.
+ */
+let cached;
+async function signingKeyFor(raw) {
+    if (cached?.raw === raw)
+        return cached;
+    const jwk = parsePrivateJwk(raw);
+    // Not cast to `CryptoKey`: `importJWK` returns a union, and asserting the
+    // branch would be a lie the day this key is anything but Ed25519.
+    const key = await importJWK(jwk, A2A_JWS_ALG);
+    cached = { raw, key, kid: jwk.kid };
+    return cached;
+}
+/**
+ * Sign a short-lived token identifying **this agent as a caller** to another
+ * service that trusts its card key.
+ *
+ * The production sibling of `makeGatewayToken`, which core previously shipped
+ * only from `/testing` — so an agent that had to call out mint-signed had to
+ * hand-write this shape, and every deployment that did so wrote its own subtly
+ * different version of the `iss`/`jku` agreement above.
+ *
+ * Distinct from {@link signCallbackJwt}, which carries **no** claims: that one
+ * proves "the agent you called is calling you back about this task", where this
+ * proves "this is who I am and which tenant I speak for".
+ */
+export async function signCallerToken(options) {
+    const { key, kid } = await signingKeyFor(options.signingKey);
+    // Normalized for the same reason `audience` is, and it has to happen before
+    // both uses: `jku` names only the origin, so an `issuer` carrying a trailing
+    // slash or a path would sign an `iss` that disagrees with it — and a verifier
+    // comparing `iss` byte-for-byte against a normalized origin allowlist rejects
+    // the token even though the two URLs share an origin.
+    const issuer = new URL(options.issuer).origin;
+    return new SignJWT({
+        [IDENTITY_CLAIM]: options.identity,
+        [TENANT_CLAIM]: options.tenant
+    })
+        .setProtectedHeader({
+        alg: A2A_JWS_ALG,
+        kid,
+        // Where the far side fetches the public half. A verifier must check this
+        // origin against its own allowlist *before* fetching, which is what stops
+        // a forged token nominating an attacker-controlled JWKS.
+        jku: jwksUrl(issuer)
+    })
+        .setIssuer(issuer)
+        .setAudience(new URL(options.audience).origin)
+        .setIssuedAt()
+        .setExpirationTime(`${options.ttlSeconds ?? DEFAULT_TTL_SECONDS}s`)
+        .sign(key);
+}

package/dist/a2a/deliver.d.ts

@@ -0,0 +1,49 @@
+import type { WorkflowStep } from "cloudflare:workers";
+import { type TurnPushContext } from "./push.js";
+import type { PlainTask } from "./task.js";
+/** What {@link deliverTerminalTask} needs to finish a turn. */
+export interface DeliverTerminalOptions {
+    /** Which Task this is about, and where its callback goes. */
+    push: TurnPushContext;
+    /** The agent's card-signing key, for the callback JWT. */
+    signingKey: string;
+    /**
+     * The guarded write, and **the cancellation check**. Return whether it
+     * applied: `false` must mean the row was already terminal (canceled), which is
+     * what suppresses the callback.
+     *
+     * Resolve any Durable Object stub *inside* this function, never above it — a
+     * stub hoisted out of a step body is a live connection that a replay cannot
+     * reconnect.
+     */
+    saveTask: (task: PlainTask) => Promise<boolean>;
+    /**
+     * Build the terminal Task. Called **inside** the `complete` step so that what
+     * gets notified is exactly what was persisted: building it outside would
+     * re-stamp `new Date()` on every replay and post a Task that differs from the
+     * stored one.
+     */
+    terminal: () => PlainTask;
+    /**
+     * Optional best-effort cleanup, run after the write and before the callback.
+     * An agent with no managed children omits it and no `sweep` step appears.
+     */
+    sweep?: () => Promise<void>;
+}
+/**
+ * Persist a turn's terminal Task, then notify the gateway.
+ *
+ * **The guarded write is the cancellation check.** `saveTask` refuses to write a
+ * terminal state over a `canceled` row and says so, doing that read and write in
+ * one synchronous pass inside the Durable Object. Probing first and saving
+ * second would leave a window — between the two calls, and again between this
+ * step and `notify` — in which a `tasks/cancel` lands and the gateway still
+ * receives a `completed` callback. Keying the notify on "did the write apply"
+ * closes it, and that has already been got wrong once.
+ *
+ * In `/a2a` rather than `/round` because the shape is not a round's: an agent
+ * whose turn is a single inference ends it the same way, and importing this from
+ * `/round` would put the whole delegation engine in a bundle that must not carry
+ * it. Everything it calls already lives here.
+ */
+export declare function deliverTerminalTask(step: WorkflowStep, options: DeliverTerminalOptions): Promise<void>;

package/dist/a2a/deliver.js

@@ -0,0 +1,49 @@
+import { createPushChannel } from "./push.js";
+/**
+ * Persist a turn's terminal Task, then notify the gateway.
+ *
+ * **The guarded write is the cancellation check.** `saveTask` refuses to write a
+ * terminal state over a `canceled` row and says so, doing that read and write in
+ * one synchronous pass inside the Durable Object. Probing first and saving
+ * second would leave a window — between the two calls, and again between this
+ * step and `notify` — in which a `tasks/cancel` lands and the gateway still
+ * receives a `completed` callback. Keying the notify on "did the write apply"
+ * closes it, and that has already been got wrong once.
+ *
+ * In `/a2a` rather than `/round` because the shape is not a round's: an agent
+ * whose turn is a single inference ends it the same way, and importing this from
+ * `/round` would put the whole delegation engine in a bundle that must not carry
+ * it. Everything it calls already lives here.
+ */
+export async function deliverTerminalTask(step, options) {
+    const task = await step.do("complete", async () => {
+        const terminal = options.terminal();
+        return (await options.saveTask(terminal)) ? terminal : null;
+    });
+    if (!task)
+        return;
+    // Caught, not left to propagate: the terminal Task is already durably saved,
+    // so a sweep that still fails once the step's own retries are exhausted must
+    // not block the callback — the gateway is owed its result either way.
+    if (options.sweep) {
+        const sweep = options.sweep;
+        try {
+            await step.do("sweep", async () => {
+                await sweep();
+            });
+        }
+        catch (err) {
+            console.error("[deliver] sweep failed after retries", {
+                taskId: options.push.taskId,
+                err: String(err)
+            });
+        }
+    }
+    // A card-key-signed callback POST. Retried by the step on a non-2xx; the
+    // terminal messageId is deterministic and the gateway is idempotent and
+    // single-use, so retries are safe. If it ultimately fails, the gateway's own
+    // reaction backstop clears the pending marker.
+    await step.do("notify", async () => {
+        await createPushChannel(options.signingKey, options.push).deliver(task);
+    });
+}

package/dist/a2a/index.d.ts

@@ -22,6 +22,8 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken, type GatewayIdentity, type VerifyOptions } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks, type AgentManifest, type BuildCardOptions, type CardSigningConfig, type WireAgentCard } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
+export { deliverTerminalTask, type DeliverTerminalOptions } from "./deliver.js";
+export { signCallerToken, type CallerTokenOptions } from "./caller-token.js";
 export { callerContext } from "./caller.js";
 export { createPushChannel, type PushChannel, type TurnPushContext } from "./push.js";
 export { taskStateLabel, type PlainArtifact, type PlainMessage, type PlainPart, type PlainStatus, type PlainTask } from "./task.js";

package/dist/a2a/index.js

@@ -22,6 +22,8 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
+export { deliverTerminalTask } from "./deliver.js";
+export { signCallerToken } from "./caller-token.js";
 export { callerContext } from "./caller.js";
 export { createPushChannel } from "./push.js";
 export { taskStateLabel } from "./task.js";

package/dist/a2a/notify.d.ts

@@ -37,9 +37,10 @@ export { NOTIFICATION_TOKEN_HEADER } from "@loopingai/a2a-protocol";
  */
 export declare function buildSubmittedTask(taskId: string, contextId: string): PlainTask;
 /**
- * The terminal `completed` Task for a turn the agent deliberately did not answer
- * (it called the `no_reply` tool — see the agent loop). Same
- * shape as {@link buildSubmittedTask}: **no `status.message` at all**.
+ * The terminal `completed` Task for a turn the agent deliberately did not
+ * answer — a turn an `AgentPlugin.shouldHandleTurn` gate declined, or whatever
+ * else a host treats as "nothing to say". Same shape as
+ * {@link buildSubmittedTask}: **no `status.message` at all**.
  *
  * The callback is still POSTed. The gateway's pending row has to resolve — we
  * simply hand it nothing to post to Slack. There is no `messageId` because there

package/dist/a2a/notify.js

@@ -69,9 +69,10 @@ export function buildSubmittedTask(taskId, contextId) {
     return buildBareTask(taskId, contextId, TaskState.TASK_STATE_SUBMITTED);
 }
 /**
- * The terminal `completed` Task for a turn the agent deliberately did not answer
- * (it called the `no_reply` tool — see the agent loop). Same
- * shape as {@link buildSubmittedTask}: **no `status.message` at all**.
+ * The terminal `completed` Task for a turn the agent deliberately did not
+ * answer — a turn an `AgentPlugin.shouldHandleTurn` gate declined, or whatever
+ * else a host treats as "nothing to say". Same shape as
+ * {@link buildSubmittedTask}: **no `status.message` at all**.
  *
  * The callback is still POSTed. The gateway's pending row has to resolve — we
  * simply hand it nothing to post to Slack. There is no `messageId` because there

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

@@ -0,0 +1,15 @@
+/**
+ * `@loopingai/core/anthropic` — Claude as a second model provider.
+ *
+ * Its own subpath, and an **optional** peer dependency on `@anthropic-ai/sdk`,
+ * for the same reason `/round` is not re-exported from the root barrel: an agent
+ * that runs on Workers AI should not pay — in install size, in bundle bytes, or
+ * in a dependency it must keep current — for a provider it never calls.
+ *
+ * What lives here is a provider, not a capability. It ships no tools, no prompt
+ * copy and no policy; it satisfies {@link ModelRuntime} and stops.
+ */
+export { CredentialRejectedError, type CredentialRejectedBy } from "../errors.js";
+export { createAnthropicLanguageModel, type AnthropicModelDeps } from "./language-model.js";
+export { createAnthropicModelRuntime, type AnthropicRuntimeDeps } from "./runtime.js";
+export { ANTHROPIC_PROVIDER, type CacheTtl } from "./prompt.js";

package/dist/agent/anthropic/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@loopingai/core/anthropic` — Claude as a second model provider.
+ *
+ * Its own subpath, and an **optional** peer dependency on `@anthropic-ai/sdk`,
+ * for the same reason `/round` is not re-exported from the root barrel: an agent
+ * that runs on Workers AI should not pay — in install size, in bundle bytes, or
+ * in a dependency it must keep current — for a provider it never calls.
+ *
+ * What lives here is a provider, not a capability. It ships no tools, no prompt
+ * copy and no policy; it satisfies {@link ModelRuntime} and stops.
+ */
+// Re-exported, not owned: a rejected credential is a fact about the path to a
+// model, not about Anthropic, so the error lives with the rest of the provider
+// contract in {@link file://../errors.ts}. An agent that only imports this
+// subpath still gets it from one place.
+export { CredentialRejectedError } from "../errors.js";
+export { createAnthropicLanguageModel } from "./language-model.js";
+export { createAnthropicModelRuntime } from "./runtime.js";
+export { ANTHROPIC_PROVIDER } from "./prompt.js";

package/dist/agent/anthropic/language-model.d.ts

@@ -0,0 +1,59 @@
+import type Anthropic from "@anthropic-ai/sdk";
+import type { LanguageModelV4 } from "@ai-sdk/provider";
+import { type CredentialRejectedBy } from "../errors.js";
+import { type CacheTtl } from "./prompt.js";
+/**
+ * A `LanguageModelV4` over `@anthropic-ai/sdk`, so core's loops can call Claude
+ * without knowing they are.
+ *
+ * Every loop in core is written against `generateText` from `ai` and a
+ * `LanguageModel` — {@link file://../../round/turn.ts turn.ts},
+ * {@link file://../../subagent/run.ts run.ts} and
+ * {@link file://../session.ts session.ts}. Satisfying that interface is what
+ * keeps the round loop, the control-tool repair ladder, subtask execution and
+ * the Workflow untouched by a second provider. The alternative — a bespoke
+ * Messages-API loop for one agent — would have given all of that up.
+ *
+ * `ai@7` accepts `LanguageModelV2 | V3 | V4`; this targets **v4**, the newest
+ * the installed `@ai-sdk/provider` defines.
+ */
+/** How the adapter reaches the API. Everything is injected so nothing reads env. */
+export interface AnthropicModelDeps {
+    /**
+     * Constructed lazily by the runtime — see the note in
+     * {@link file://./runtime.ts}. Awaited, because building it has to resolve
+     * `env.AI.gateway(id).getUrl()`, which is async.
+     */
+    client: () => Anthropic | Promise<Anthropic>;
+    /** Anthropic model id, e.g. `claude-opus-5`. */
+    modelId: string;
+    /** `max_tokens` when a caller supplies none. Anthropic requires the field. */
+    defaultMaxTokens: number;
+    /** Prompt-cache TTL, or `false` to place no breakpoints. Defaults to `"5m"`. */
+    cache?: CacheTtl | false;
+    /**
+     * Reasoning effort, when the caller does not set one per-call.
+     *
+     * Maps to `output_config.effort`. Coding and agentic work wants `"xhigh"`;
+     * `"high"` is the API default. Core never picks this — an agent does.
+     */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /** Extra headers merged into every request (AI Gateway metadata lives here). */
+    headers?: Record<string, string>;
+    /**
+     * Recognise a deployment-specific authority in a `401`/`403` body.
+     *
+     * Consulted before the built-in shapes; return `undefined` to fall through to
+     * them. It exists because a deployment may put an authenticated intermediary
+     * between the gateway and Anthropic, and only that deployment knows what its
+     * refusal looks like — core recognising one particular proxy's error body
+     * would be exactly the deployment policy this package does not ship.
+     *
+     * The remedy is what makes it worth distinguishing at all: a proxy that mints
+     * its caller credential per request has no secret to rotate, so reporting its
+     * `401` as `credential` sends an operator to replace a working token. See
+     * {@link file://../errors.ts CredentialRejectedBy}.
+     */
+    classifyAuthFailure?: (body: unknown) => CredentialRejectedBy | undefined;
+}
+export declare function createAnthropicLanguageModel(deps: AnthropicModelDeps): LanguageModelV4;