@loopingai/core 0.3.0 → 0.4.0

package/dist/host/agent.d.ts

@@ -0,0 +1,217 @@
+import { Agent, type Schedule } from "agents";
+import { type Task } from "@a2a-js/sdk";
+import { type AgentRuntime } from "../runtime/index.js";
+import type { AgentPlugin } from "../contract/plugin.js";
+import { type CoreConfig, type CoreConfigOverrides } from "../config.js";
+import type { A2ASecretsEnv, AiEnv } from "../env.js";
+import { AgentDB } from "../db/index.js";
+import type { GatewayIdentity } from "../a2a/verify.js";
+import type { PlainTask } from "../a2a/task.js";
+import type { TaskListQuery } from "../a2a/agent-stub.js";
+import { type PushChannel, type TurnPushContext } from "../a2a/push.js";
+import { type SessionLike } from "../agent/session.js";
+import { type GatewayMetadata, type ModelPair, type ModelRuntime } from "../agent/model.js";
+import type { PluginHost } from "./plugin-host.js";
+/**
+ * The Durable Object body every Looping agent has, whatever loop it runs.
+ *
+ * ## Why this is core's and not the app's
+ *
+ * It was the app's, in the starter, and it was written twice — once for the
+ * delegating round agent, once for the single-turn proactive one. The two copies
+ * were identical for ~180 lines: the memoized runtime/db/models getters, the
+ * `onStart` that must await migrations before the SDK dispatches any RPC, the
+ * cron registration guard, the session with its displacement fan-out, the
+ * `identityKey` timing, and the task RPC surface.
+ *
+ * They did not stay identical. The second copy dropped `markWorking`'s
+ * cancellation verdict on the floor and probed with a separate `getTask` before
+ * writing a terminal Task — so a canceled task still burned a model call, and the
+ * gateway could still receive a `completed` callback for a task the caller had
+ * abandoned. Both are lifecycle invariants, both were documented in the first
+ * copy, and neither is visible to a type checker or a linter.
+ *
+ * That is the argument for this class. **None of it is policy.** How a turn is
+ * shaped, what ends it, what the model is told — all of that stays with the
+ * agent, and an agent that wants a different loop simply does not extend
+ * {@link file://../round/agent.ts RoundAgentBase}. What is here is the part where
+ * being different is only ever a bug.
+ *
+ * ## The three seams
+ *
+ * ```ts
+ * export class MyAgent extends LoopingAgent<Env> {
+ *   protected agentConfig() { return MY_CONFIG; }
+ *   protected agentPlugins(host: PluginHost<Env>) { return plugins(host); }
+ *   protected agentSoul(capabilities: string) { return soulPrompt(capabilities); }
+ * }
+ * ```
+ *
+ * One Durable Object instance per verified caller (keyed by the gateway JWT's
+ * `identity.key`), each owning **one continuous Session** — durable history plus
+ * a self-edited `memory` block, backed by `this.sql`. All of a caller's turns, in
+ * any channel or thread, accumulate into that one conversation.
+ */
+export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv & A2ASecretsEnv = Cloudflare.Env & AiEnv & A2ASecretsEnv> extends Agent<TEnv> {
+    private session?;
+    private _runtime?;
+    private _models?;
+    private _pair?;
+    private _db?;
+    /**
+     * The verified caller this instance belongs to, set on the first turn.
+     *
+     * `onStart` runs before any request, so it is not known when `agentPlugins()`
+     * is built — which is why anything per-caller takes a thunk. The DO is keyed
+     * 1:1 by this value, so it is constant once set.
+     */
+    private identityKey?;
+    /**
+     * Test-only model injection. A **field**, not a constructor argument or an RPC
+     * parameter, so it never appears on the generated DO stub: production callers
+     * cannot reach it, and no model configuration crosses the RPC boundary.
+     */
+    modelsOverride?: ModelPair;
+    /** This agent's config overrides. Merged onto core's baseline once, at start. */
+    protected abstract agentConfig(): CoreConfigOverrides;
+    /** This agent's installed capabilities. Conventionally its `./plugins.ts`. */
+    protected abstract agentPlugins(host: PluginHost<TEnv>): AgentPlugin[];
+    /**
+     * This agent's identity, with the installed plugins' capability blocks already
+     * rendered in. Core ships no prompt copy — this is yours to write.
+     */
+    protected abstract agentSoul(capabilities: string): string;
+    /**
+     * Everything that would otherwise be a module-level constant, resolved once
+     * per DO instance from this agent's config and its installed plugins.
+     *
+     * Resolving a registry at *import* time is the one thing the package split
+     * exists to prevent: it freezes the registry before `env` exists (which on
+     * Workers is always), defeats tree-shaking, and makes per-agent plugin
+     * selection impossible.
+     */
+    protected get runtime(): AgentRuntime;
+    /** The resolved config. */
+    protected get config(): CoreConfig;
+    /** The agent's database (drizzle + migrations), built once per DO instance. */
+    protected get db(): AgentDB;
+    /** The model runtime for this instance, built lazily over the `AI` binding. */
+    protected get models(): ModelRuntime;
+    /**
+     * What this agent's plugins are handed. Built from
+     * {@link resolvedModelIds} rather than `this.config`, which would be a cycle —
+     * building the runtime is what needs these.
+     */
+    protected pluginHost(): PluginHost<TEnv>;
+    /**
+     * The model settings a locally-declared recipe runs on, resolved *before* the
+     * runtime exists.
+     *
+     * Deliberately not `this.config` — that would be a cycle. `resolveConfig` is
+     * cheap and pure and fills in core's defaults, so this is the same result the
+     * runtime lands on; that matters because a recipe's models are checked against
+     * `policy.modelAllowlist`, which is built from these very values.
+     */
+    private resolvedModelIds;
+    onStart(): Promise<void>;
+    /**
+     * Cron handler: delete task rows older than 30 days. Runs Sunday 01:00 UTC.
+     *
+     * A plugin's own tables are its business — core's journal does not reach them,
+     * and neither does this sweep. A subclass with more durable state of its own
+     * overrides {@link cleanupAgentState}.
+     */
+    cleanupOldTasks(_payload: Record<string, never>, _schedule: Schedule): Promise<void>;
+    /** Extra durable state to age out alongside the task rows. Default: none. */
+    protected cleanupAgentState(): void;
+    /**
+     * The main agent's primary/fallback pair. With `metadata` it builds a fresh
+     * pair carrying that AI Gateway correlation tag (so a gateway log ties the call
+     * to its task and round); without it — the Session's own compaction model — it
+     * reuses a memoized default. A test `modelsOverride` always wins.
+     */
+    protected modelPair(metadata?: GatewayMetadata): ModelPair;
+    /**
+     * The one continuous Session for this caller (rebuilt from `this.sql` after
+     * eviction). Memoized — `identity` is constant for the DO's life, since the DO
+     * is keyed 1:1 by `identity.key`.
+     *
+     * `onMessagesDisplaced` is the whole integration for anything that wants the
+     * messages a compaction folds away: core performs the compaction, so core
+     * announces the loss, and the runtime fans it out to every plugin that asked.
+     */
+    getSession(identity: GatewayIdentity): SessionLike;
+    /** The caller key, which is present on every path that can reach a plugin. */
+    protected requireIdentityKey(): string;
+    /** The gateway callback channel for one turn. See {@link PushChannel}. */
+    protected push(context: TurnPushContext): PushChannel;
+    /**
+     * The per-request system-prompt suffix describing the verified caller.
+     *
+     * A rendering of a protocol fact rather than prompt copy, so core supplies one
+     * — see {@link callerContext}. Override it to name what a workspace id means in
+     * your deployment; do not use it to say who the *user* is, which this is not.
+     */
+    protected callerContext(identity: GatewayIdentity): string;
+    beginTask(input: {
+        messageId: string;
+        taskId: string;
+        contextId: string;
+    }): Promise<PlainTask>;
+    getTask(taskId: string): Promise<PlainTask | null>;
+    listTasks(query: TaskListQuery): Promise<{
+        tasks: PlainTask[];
+        totalSize: number;
+    }>;
+    /**
+     * Persist a Task, returning **whether the guarded write applied**.
+     *
+     * That boolean is the cancellation check, and a caller must key its callback on
+     * it: `AgentDB` refuses to write a terminal state over a `canceled` row and
+     * does that read and write in one synchronous pass inside the DO. Probing with
+     * {@link getTask} first and saving second leaves a window — between the two
+     * calls, and again between the save and the notify — in which a cancel lands
+     * and the gateway still receives a `completed` callback.
+     *
+     * A `canceled` state routes to {@link markCanceled} instead of a plain write,
+     * so a `tasks/cancel` arriving through the a2a-js TaskStore and one arriving
+     * through {@link cancelTask} converge on the same interruption path.
+     */
+    saveTask(task: Task): Promise<boolean>;
+    /**
+     * Move the Task to `working`. Returns `"canceled"` when the caller cancelled
+     * first — read it and stop, rather than probing with a separate
+     * {@link getTask}, which reopens the gap between asking and acting.
+     *
+     * Anything else is `"ok"`, including an unknown row and a row already `working`
+     * (a replayed step): only an actual cancellation stops the pipeline.
+     */
+    markWorking(taskId: string): Promise<"ok" | "canceled">;
+    cancelTask(taskId: string): Promise<PlainTask | null>;
+    /**
+     * The one place a Task becomes canceled: flip the row — terminal, so every
+     * non-canceled write is refused afterwards — then interrupt whatever is still
+     * running for it.
+     *
+     * `task` is supplied when the caller already built the canceled Task (the
+     * a2a-js cancel branch attaches its own status message); otherwise the row's
+     * own guarded flip produces it. Both paths are guarded against the same race:
+     * a task that already reached `completed`/`failed` refuses the write, and its
+     * verdict — not a `get` read straight after, which would return that
+     * unchanged terminal row and be mistaken for a successful cancellation — is
+     * what decides whether {@link onTaskCanceled} runs at all.
+     */
+    private markCanceled;
+    /**
+     * Interrupt work still in flight for a task that has just been canceled.
+     *
+     * Default: nothing, which is right for an agent whose turn is a single
+     * inference — the row is terminal and the next guarded write refuses. An agent
+     * with children overrides this to abort them.
+     *
+     * **Must be best-effort.** Cancellation has already been recorded by the time
+     * this runs, and it must not fail because cleanup did.
+     */
+    protected onTaskCanceled(_taskId: string): Promise<void>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/host/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/host/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,OAAO,EAAW,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,8BAAsB,YAAY,CAChC,IAAI,SAAS,UAAU,CAAC,GAAG,GAAG,KAAK,GAAG,aAAa,GAAG,UAAU,CAAC,GAAG,GAClE,KAAK,GACL,aAAa,CACf,SAAQ,KAAK,CAAC,IAAI,CAAC;IACnB,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,KAAK,CAAC,CAAY;IAC1B,OAAO,CAAC,GAAG,CAAC,CAAU;IAEtB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAC,CAAS;IAE7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,CAAC;IAI3B,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,WAAW,IAAI,mBAAmB;IAErD,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,WAAW,EAAE;IAEtE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAI1D;;;;;;;;OAQG;IACH,SAAS,KAAK,OAAO,IAAI,YAAY,CASpC;IAED,2BAA2B;IAC3B,SAAS,KAAK,MAAM,IAAI,UAAU,CAEjC;IAED,+EAA+E;IAC/E,SAAS,KAAK,EAAE,IAAI,OAAO,CAQ1B;IAED,+EAA+E;IAC/E,SAAS,KAAK,MAAM,IAAI,YAAY,CAKnC;IAED;;;;OAIG;IACH,SAAS,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,CAAC;IAaxC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IAIlB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B;;;;;;OAMG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC/B,SAAS,EAAE,QAAQ,GAClB,OAAO,CAAC,IAAI,CAAC;IAKhB,6EAA6E;IAC7E,SAAS,CAAC,iBAAiB,IAAI,IAAI;IAEnC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS;IAM1D;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,WAAW;IAkBlD,8EAA8E;IAC9E,SAAS,CAAC,kBAAkB,IAAI,MAAM;IAOtC,0EAA0E;IAC1E,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW;IAIrD;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IAepD,SAAS,CAAC,KAAK,EAAE;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,SAAS,CAAC;IAIhB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAIlD,SAAS,CACb,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrD;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAO5C;;;;;;;OAOG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,UAAU,CAAC;IAIvD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAI3D;;;;;;;;;;;;OAYG;YACW,YAAY;IAY1B;;;;;;;;;OASG;cACa,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAC/D"}

package/dist/host/agent.js

@@ -0,0 +1,306 @@
+import { Agent } from "agents";
+import { TaskState } from "@a2a-js/sdk";
+import { createAgentRuntime } from "../runtime/index.js";
+import { resolveConfig } from "../config.js";
+import { AgentDB, stateOf } from "../db/index.js";
+import { callerContext } from "../a2a/caller.js";
+import { createPushChannel } from "../a2a/push.js";
+import { buildAgentSession } from "../agent/session.js";
+import { createModelRuntime } from "../agent/model.js";
+/**
+ * The Durable Object body every Looping agent has, whatever loop it runs.
+ *
+ * ## Why this is core's and not the app's
+ *
+ * It was the app's, in the starter, and it was written twice — once for the
+ * delegating round agent, once for the single-turn proactive one. The two copies
+ * were identical for ~180 lines: the memoized runtime/db/models getters, the
+ * `onStart` that must await migrations before the SDK dispatches any RPC, the
+ * cron registration guard, the session with its displacement fan-out, the
+ * `identityKey` timing, and the task RPC surface.
+ *
+ * They did not stay identical. The second copy dropped `markWorking`'s
+ * cancellation verdict on the floor and probed with a separate `getTask` before
+ * writing a terminal Task — so a canceled task still burned a model call, and the
+ * gateway could still receive a `completed` callback for a task the caller had
+ * abandoned. Both are lifecycle invariants, both were documented in the first
+ * copy, and neither is visible to a type checker or a linter.
+ *
+ * That is the argument for this class. **None of it is policy.** How a turn is
+ * shaped, what ends it, what the model is told — all of that stays with the
+ * agent, and an agent that wants a different loop simply does not extend
+ * {@link file://../round/agent.ts RoundAgentBase}. What is here is the part where
+ * being different is only ever a bug.
+ *
+ * ## The three seams
+ *
+ * ```ts
+ * export class MyAgent extends LoopingAgent<Env> {
+ *   protected agentConfig() { return MY_CONFIG; }
+ *   protected agentPlugins(host: PluginHost<Env>) { return plugins(host); }
+ *   protected agentSoul(capabilities: string) { return soulPrompt(capabilities); }
+ * }
+ * ```
+ *
+ * One Durable Object instance per verified caller (keyed by the gateway JWT's
+ * `identity.key`), each owning **one continuous Session** — durable history plus
+ * a self-edited `memory` block, backed by `this.sql`. All of a caller's turns, in
+ * any channel or thread, accumulate into that one conversation.
+ */
+export class LoopingAgent extends Agent {
+    session;
+    _runtime;
+    _models;
+    _pair;
+    _db;
+    /**
+     * The verified caller this instance belongs to, set on the first turn.
+     *
+     * `onStart` runs before any request, so it is not known when `agentPlugins()`
+     * is built — which is why anything per-caller takes a thunk. The DO is keyed
+     * 1:1 by this value, so it is constant once set.
+     */
+    identityKey;
+    /**
+     * Test-only model injection. A **field**, not a constructor argument or an RPC
+     * parameter, so it never appears on the generated DO stub: production callers
+     * cannot reach it, and no model configuration crosses the RPC boundary.
+     */
+    modelsOverride;
+    // --- assembly -------------------------------------------------------------
+    /**
+     * Everything that would otherwise be a module-level constant, resolved once
+     * per DO instance from this agent's config and its installed plugins.
+     *
+     * Resolving a registry at *import* time is the one thing the package split
+     * exists to prevent: it freezes the registry before `env` exists (which on
+     * Workers is always), defeats tree-shaking, and makes per-agent plugin
+     * selection impossible.
+     */
+    get runtime() {
+        return (this._runtime ??= createAgentRuntime({
+            config: this.agentConfig(),
+            plugins: this.agentPlugins(this.pluginHost()),
+            // Opt in to verifying every plugin's declared bindings exist. Fails at DO
+            // start with a sentence naming the plugin, rather than at the first tool
+            // call inside a request someone is waiting on.
+            env: this.env
+        }));
+    }
+    /** The resolved config. */
+    get config() {
+        return this.runtime.config;
+    }
+    /** The agent's database (drizzle + migrations), built once per DO instance. */
+    get db() {
+        return (this._db ??= new AgentDB(this.ctx.storage, {
+            maxSubtasks: this.config.maxSubtasks,
+            // Plugin-owned tables, applied after core's own migrations. A store that
+            // throws fails DO start rather than being skipped — a plugin whose tables
+            // are missing would otherwise fail at its first tool call.
+            stores: this.runtime.stores
+        }));
+    }
+    /** The model runtime for this instance, built lazily over the `AI` binding. */
+    get models() {
+        return (this._models ??= createModelRuntime({
+            ai: this.env.AI,
+            config: this.config.model
+        }));
+    }
+    /**
+     * What this agent's plugins are handed. Built from
+     * {@link resolvedModelIds} rather than `this.config`, which would be a cycle —
+     * building the runtime is what needs these.
+     */
+    pluginHost() {
+        const model = this.resolvedModelIds();
+        return {
+            env: this.env,
+            storage: this.ctx.storage,
+            // A thunk, not a value — see `identityKey`.
+            callerKey: () => this.requireIdentityKey(),
+            primaryModelId: model.chatModelId,
+            fallbackModelId: model.fallbackChatModelId,
+            aiGatewayId: model.aiGatewayId
+        };
+    }
+    /**
+     * The model settings a locally-declared recipe runs on, resolved *before* the
+     * runtime exists.
+     *
+     * Deliberately not `this.config` — that would be a cycle. `resolveConfig` is
+     * cheap and pure and fills in core's defaults, so this is the same result the
+     * runtime lands on; that matters because a recipe's models are checked against
+     * `policy.modelAllowlist`, which is built from these very values.
+     */
+    resolvedModelIds() {
+        return resolveConfig(this.agentConfig()).model;
+    }
+    async onStart() {
+        // Await migrations before the SDK dispatches any RPC — eliminates the race
+        // between schema creation and first query on cold start / hibernation wake-up.
+        await this.db.ensureReady();
+        // Register the weekly cleanup cron once per DO instance (idempotent guard).
+        const existing = await this.listSchedules({ type: "cron" });
+        if (!existing.some((s) => s.callback === "cleanupOldTasks")) {
+            await this.schedule("0 1 * * 0", "cleanupOldTasks", {});
+        }
+    }
+    /**
+     * Cron handler: delete task rows older than 30 days. Runs Sunday 01:00 UTC.
+     *
+     * A plugin's own tables are its business — core's journal does not reach them,
+     * and neither does this sweep. A subclass with more durable state of its own
+     * overrides {@link cleanupAgentState}.
+     */
+    async cleanupOldTasks(_payload, _schedule) {
+        this.db.tasks.cleanup();
+        this.cleanupAgentState();
+    }
+    /** Extra durable state to age out alongside the task rows. Default: none. */
+    cleanupAgentState() { }
+    /**
+     * The main agent's primary/fallback pair. With `metadata` it builds a fresh
+     * pair carrying that AI Gateway correlation tag (so a gateway log ties the call
+     * to its task and round); without it — the Session's own compaction model — it
+     * reuses a memoized default. A test `modelsOverride` always wins.
+     */
+    modelPair(metadata) {
+        if (this.modelsOverride)
+            return this.modelsOverride;
+        if (!metadata)
+            return (this._pair ??= this.models.createModelPair());
+        return this.models.createModelPair({ metadata });
+    }
+    /**
+     * The one continuous Session for this caller (rebuilt from `this.sql` after
+     * eviction). Memoized — `identity` is constant for the DO's life, since the DO
+     * is keyed 1:1 by `identity.key`.
+     *
+     * `onMessagesDisplaced` is the whole integration for anything that wants the
+     * messages a compaction folds away: core performs the compaction, so core
+     * announces the loss, and the runtime fans it out to every plugin that asked.
+     */
+    getSession(identity) {
+        this.identityKey ??= identity.key ?? undefined;
+        const { session, model } = this.config;
+        return (this.session ??= buildAgentSession(this, this.modelPair().primary(), {
+            soul: () => this.agentSoul(this.runtime.renderCapabilities()),
+            memoryDescription: session.memoryDescription,
+            memoryMaxTokens: session.memoryMaxTokens,
+            compactAfterTokens: session.compactAfterTokens,
+            compactTailTokens: session.compactTailTokens,
+            maxOutputTokens: model.maxOutputTokens,
+            onMessagesDisplaced: this.runtime.onMessagesDisplaced
+        }));
+    }
+    /** The caller key, which is present on every path that can reach a plugin. */
+    requireIdentityKey() {
+        if (!this.identityKey) {
+            throw new Error("identity.key is required for per-caller isolation");
+        }
+        return this.identityKey;
+    }
+    /** The gateway callback channel for one turn. See {@link PushChannel}. */
+    push(context) {
+        return createPushChannel(this.env.A2A_SIGNING_KEY, context);
+    }
+    /**
+     * The per-request system-prompt suffix describing the verified caller.
+     *
+     * A rendering of a protocol fact rather than prompt copy, so core supplies one
+     * — see {@link callerContext}. Override it to name what a workspace id means in
+     * your deployment; do not use it to say who the *user* is, which this is not.
+     */
+    callerContext(identity) {
+        return callerContext(identity);
+    }
+    // --- Async task state (accept + notify) ----------------------------------
+    //
+    // A thin RPC surface over `AgentDB`'s `tasks` table. Native RPC methods — the
+    // DO is never a network-reachable server — called by the Workflow, which
+    // cannot touch this SQLite directly.
+    //
+    // The Task-returning methods return `PlainTask`: the SDK `Task` narrowed to
+    // what survives Cloudflare's RPC types. Returning the raw SDK `Task` breaks
+    // the generated DO-stub types (under v1.0 it blows past TypeScript's
+    // instantiation-depth limit).
+    async beginTask(input) {
+        return this.db.tasks.begin(input);
+    }
+    async getTask(taskId) {
+        return this.db.tasks.get(taskId);
+    }
+    async listTasks(query) {
+        return this.db.tasks.list(query);
+    }
+    /**
+     * Persist a Task, returning **whether the guarded write applied**.
+     *
+     * That boolean is the cancellation check, and a caller must key its callback on
+     * it: `AgentDB` refuses to write a terminal state over a `canceled` row and
+     * does that read and write in one synchronous pass inside the DO. Probing with
+     * {@link getTask} first and saving second leaves a window — between the two
+     * calls, and again between the save and the notify — in which a cancel lands
+     * and the gateway still receives a `completed` callback.
+     *
+     * A `canceled` state routes to {@link markCanceled} instead of a plain write,
+     * so a `tasks/cancel` arriving through the a2a-js TaskStore and one arriving
+     * through {@link cancelTask} converge on the same interruption path.
+     */
+    async saveTask(task) {
+        if (stateOf(task) === TaskState.TASK_STATE_CANCELED) {
+            return (await this.markCanceled(task.id, task)) !== null;
+        }
+        return this.db.tasks.save(task);
+    }
+    /**
+     * Move the Task to `working`. Returns `"canceled"` when the caller cancelled
+     * first — read it and stop, rather than probing with a separate
+     * {@link getTask}, which reopens the gap between asking and acting.
+     *
+     * Anything else is `"ok"`, including an unknown row and a row already `working`
+     * (a replayed step): only an actual cancellation stops the pipeline.
+     */
+    async markWorking(taskId) {
+        return this.db.tasks.markWorking(taskId);
+    }
+    async cancelTask(taskId) {
+        return this.markCanceled(taskId);
+    }
+    /**
+     * The one place a Task becomes canceled: flip the row — terminal, so every
+     * non-canceled write is refused afterwards — then interrupt whatever is still
+     * running for it.
+     *
+     * `task` is supplied when the caller already built the canceled Task (the
+     * a2a-js cancel branch attaches its own status message); otherwise the row's
+     * own guarded flip produces it. Both paths are guarded against the same race:
+     * a task that already reached `completed`/`failed` refuses the write, and its
+     * verdict — not a `get` read straight after, which would return that
+     * unchanged terminal row and be mistaken for a successful cancellation — is
+     * what decides whether {@link onTaskCanceled} runs at all.
+     */
+    async markCanceled(taskId, task) {
+        const canceled = task
+            ? this.db.tasks.save(task) && this.db.tasks.get(taskId)
+            : this.db.tasks.cancel(taskId);
+        if (!canceled)
+            return null;
+        await this.onTaskCanceled(taskId);
+        return canceled;
+    }
+    /**
+     * Interrupt work still in flight for a task that has just been canceled.
+     *
+     * Default: nothing, which is right for an agent whose turn is a single
+     * inference — the row is terminal and the next guarded write refuses. An agent
+     * with children overrides this to abort them.
+     *
+     * **Must be best-effort.** Cancellation has already been recorded by the time
+     * this runs, and it must not fail because cleanup did.
+     */
+    async onTaskCanceled(_taskId) { }
+}
+//# sourceMappingURL=agent.js.map

package/dist/host/agent.js.map

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

package/dist/host/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/host` — the Durable Object half of an agent.
+ *
+ * {@link LoopingAgent} is the DO body every Looping agent has whatever loop it
+ * runs: the runtime and database built once per instance, the one continuous
+ * Session per verified caller, the gateway callback channel, and the task
+ * lifecycle RPC surface a Workflow drives. {@link PluginHost} is what it hands
+ * the plugins.
+ *
+ * Its own subpath rather than part of `/agent` on purpose. `/agent` is the
+ * primitives a *loop* is built from — session, model pair, budget, control tools
+ * — and a loop module should be able to import those without pulling a Durable
+ * Object base class and drizzle into its graph.
+ *
+ * Core still ships **no loop and no prompt copy**. Nothing here decides how a
+ * turn is shaped or what ends it; see `@loopingai/core/round` for the delegating
+ * round loop, which is opt-in and takes its prompt copy from the agent.
+ */
+export { LoopingAgent } from "./agent.js";
+export type { PluginHost } from "./plugin-host.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/host/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@loopingai/core/host` — the Durable Object half of an agent.
+ *
+ * {@link LoopingAgent} is the DO body every Looping agent has whatever loop it
+ * runs: the runtime and database built once per instance, the one continuous
+ * Session per verified caller, the gateway callback channel, and the task
+ * lifecycle RPC surface a Workflow drives. {@link PluginHost} is what it hands
+ * the plugins.
+ *
+ * Its own subpath rather than part of `/agent` on purpose. `/agent` is the
+ * primitives a *loop* is built from — session, model pair, budget, control tools
+ * — and a loop module should be able to import those without pulling a Durable
+ * Object base class and drizzle into its graph.
+ *
+ * Core still ships **no loop and no prompt copy**. Nothing here decides how a
+ * turn is shaped or what ends it; see `@loopingai/core/round` for the delegating
+ * round loop, which is opt-in and takes its prompt copy from the agent.
+ */
+export { LoopingAgent } from "./agent.js";
+//# sourceMappingURL=index.js.map

package/dist/host/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/host/plugin-host.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Everything a plugin may need from its host, resolved once per Durable Object
+ * instance.
+ *
+ * This is **contract, not application code**, which is why it lives in core. A
+ * published plugin's config is written against this shape — `arcAgi` takes
+ * `storage`, `recall` takes `callerKey` — so a plugin that could not name the
+ * type was writing its signature against a structural guess at an interface
+ * declared in an app it has never seen.
+ *
+ * Not just `env`, and each field is load-bearing:
+ *
+ * - `env` — bindings and secrets. Typed `object` for the same reason
+ *   {@link file://../runtime/index.ts CreateAgentRuntimeOptions.env} is: `Env` is
+ *   the ambient interface `wrangler types` generates into a consumer's
+ *   `worker-configuration.d.ts`, it has no index signature, and requiring a cast
+ *   to pass one's own `this.env` is how a seam goes unused. A host narrows it.
+ * - `storage` — a plugin that owns tables needs the DO's storage to build a query
+ *   handle over. `this.ctx.storage`.
+ * - `callerKey` — **a thunk, deliberately.** It derives from the verified
+ *   caller's identity, which does not exist yet when `plugins()` runs at DO
+ *   start. The DO is keyed 1:1 by that caller, so the value is constant once
+ *   known; a thunk is what lets the host supply it late while every hook reads
+ *   the same one. On a subagent facet there is no caller at all, and the honest
+ *   encoding is a thunk that throws.
+ * - the model ids — what a locally-declared recipe runs on. A recipe may only
+ *   name models in the host's allowlist, so a plugin that ships one is handed the
+ *   host's pair rather than guessing.
+ * - `aiGatewayId` — the **resolved** AI Gateway slug, so a plugin making its own
+ *   model calls is correlated with the agent's. Resolved, not read off the
+ *   overrides object: reaching into `MY_CONFIG.model?.aiGatewayId` at a call site
+ *   silently yields `undefined` the moment that override is dropped in favour of
+ *   core's default, and the plugin's calls quietly stop being correlated.
+ */
+export interface PluginHost<TEnv extends object = object> {
+    env: TEnv;
+    storage: DurableObjectStorage;
+    /** The verified caller. A thunk — it does not exist when `onStart` runs. */
+    callerKey: () => string;
+    /** `config.model.chatModelId` — what a locally-declared recipe runs on. */
+    primaryModelId: string;
+    /** `config.model.fallbackChatModelId`. */
+    fallbackModelId: string;
+    /** `config.model.aiGatewayId`, already resolved over core's defaults. */
+    aiGatewayId: string;
+}
+//# sourceMappingURL=plugin-host.d.ts.map

package/dist/host/plugin-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.d.ts","sourceRoot":"","sources":["../../src/host/plugin-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,UAAU,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACtD,GAAG,EAAE,IAAI,CAAC;IACV,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/host/plugin-host.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-host.js.map

package/dist/host/plugin-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.js","sourceRoot":"","sources":["../../src/host/plugin-host.ts"],"names":[],"mappings":""}