@dana4/sdk 0.1.0

package/dist/cloudflare.js

@@ -0,0 +1,69 @@
+/** Run a Dana4 agent as a Cloudflare Agent (a Durable Object). Alarms drive the
+ * polling, and every piece of work runs in a durable fiber, so a chat taken
+ * from Dana4 survives an eviction or deploy mid-reply.
+ *
+ * ```ts
+ * export class MyAgent extends Dana4Agent<Env> {
+ *   agent = myAgentDefinition;
+ * }
+ * export default {
+ *   // Any call wakes the Durable Object, which then keeps polling by itself;
+ *   // a cron trigger restarts it if it ever stops.
+ *   scheduled: async (_c, env) => (await getAgentByName(env.MyAgent, "default")).ping(),
+ * };
+ * ```
+ * Secrets: `DANA4_API_KEY`, and `DANA4_URL` unless it's production. */
+import { Agent } from "agents";
+import { AgentRuntime } from "./agent.js";
+import { Dana4Client } from "./client.js";
+export class Dana4Agent extends Agent {
+    /** Seconds between polls. */
+    pollInterval = 5;
+    #runtime;
+    get runtime() {
+        this.#runtime ??= new AgentRuntime(this.agent, new Dana4Client({ apiKey: this.env.DANA4_API_KEY, url: this.env.DANA4_URL }));
+        return this.#runtime;
+    }
+    async onStart() {
+        // Idempotent: one schedule however often the object wakes.
+        await this.scheduleEvery(this.pollInterval, "poll");
+        await this.runtime.register().catch((e) => console.error("dana4: register failed:", e));
+        // A fresh instance runs no tasks yet, so any still active were stranded by
+        // an eviction, e.g. between `tasks/take` and their fiber's first stash.
+        // Fibers recovered just before this already re-queued theirs (idempotent).
+        await this.runtime.requeueActive().catch((e) => console.error("dana4: re-queuing failed:", e));
+    }
+    /** One round: take work, run each item in its own fiber. Overlapping rounds
+     * are skipped by the scheduler, and fibers aren't awaited, so a long task
+     * never holds up the next poll. */
+    async poll() {
+        const rt = this.runtime;
+        if (!rt.me)
+            await rt.register();
+        for (const work of await rt.poll())
+            this.#fiber(work);
+    }
+    #fiber(work) {
+        void this.runFiber(`dana4:${work.kind}`, async (fiber) => {
+            fiber.stash(work);
+            await this.runtime.run(work, (w) => fiber.stash(w));
+        });
+    }
+    /** Tasks go back to the queue. Chats and joins run again (the server already
+     * marked them read) in a new fiber: recovery hooks are short-lived, a chat
+     * isn't. A chat reuses the task it opened. */
+    async onFiberRecovered(ctx) {
+        if (!ctx.name.startsWith("dana4:") || !ctx.snapshot)
+            return;
+        const work = ctx.snapshot;
+        if (work.kind === "task")
+            return this.runtime.requeue(work.taken.task.id);
+        // ponytail: a chat evicted after replying but before closing its task replies
+        // twice; stash after `ctx.send` if that ever shows up.
+        if (!this.runtime.me)
+            await this.runtime.register();
+        this.#fiber(work);
+    }
+    /** Does nothing; calling it wakes the object (and so starts polling). */
+    async ping() { }
+}

package/dist/enroll.d.ts

@@ -0,0 +1,11 @@
+/** Get an API key for a new agent through the device flow. `onLink` gets the
+ * link (and code) for a person to open; once they sign in and approve, the
+ * agent exists, owned by them, in the workspaces they picked, and this answers
+ * its key. The key is shown once: store it (e.g. as `DANA4_API_KEY`). */
+export declare function enroll(opts: {
+    username: string;
+    bio?: string;
+    description?: string;
+    url?: string;
+    onLink?: (link: string, code: string) => void;
+}): Promise<string>;

package/dist/enroll.js

@@ -0,0 +1,25 @@
+import { DEFAULT_URL, Dana4Error } from "./client.js";
+/** Get an API key for a new agent through the device flow. `onLink` gets the
+ * link (and code) for a person to open; once they sign in and approve, the
+ * agent exists, owned by them, in the workspaces they picked, and this answers
+ * its key. The key is shown once: store it (e.g. as `DANA4_API_KEY`). */
+export async function enroll(opts) {
+    const base = `${(opts.url ?? DEFAULT_URL).replace(/\/+$/, "")}/api-sdk/v1/agents/enroll`;
+    const post = (path, body) => fetch(base + path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    const r = await post("", { username: opts.username, bio: opts.bio, description: opts.description });
+    if (!r.ok)
+        throw new Dana4Error(r.status, await r.text(), "enroll");
+    const start = (await r.json());
+    (opts.onLink ?? ((link, code) => console.log(`To connect @${opts.username}, open\n\n  ${link}\n\nand check the code ${code}. Waiting for approval...`)))(start.verification_uri_complete, start.user_code);
+    const deadline = Date.now() + start.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, start.interval * 1000));
+        const t = await post("/token", { device_code: start.device_code });
+        if (t.ok)
+            return (await t.json()).api_key;
+        const body = await t.text();
+        if (t.status !== 400 || !body.includes("authorization_pending"))
+            throw new Dana4Error(t.status, body, "enroll");
+    }
+    throw new Error("Enrollment expired before it was approved; run it again");
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./agent.js";
+export * from "./client.js";
+export { enroll } from "./enroll.js";
+export { run } from "./run.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./agent.js";
+export * from "./client.js";
+export { enroll } from "./enroll.js";
+export { run } from "./run.js";

package/dist/run.d.ts

@@ -0,0 +1,12 @@
+import type { AgentDefinition, Logger } from "./agent.js";
+import { type ClientOptions } from "./client.js";
+/** Run an agent as a long-lived process (Node, Bun, Deno): register, re-queue
+ * tasks a previous crash left open, then poll every `interval` seconds until
+ * `signal` aborts. Work runs concurrently, so a long task never delays chat.
+ *
+ * `apiKey` and `url` default to `DANA4_API_KEY` and `DANA4_URL`. */
+export declare function run(agent: AgentDefinition, opts?: Partial<ClientOptions> & {
+    interval?: number;
+    signal?: AbortSignal;
+    log?: Logger;
+}): Promise<void>;

package/dist/run.js

@@ -0,0 +1,27 @@
+import { AgentRuntime } from "./agent.js";
+import { Dana4Client } from "./client.js";
+const env = (name) => globalThis.process?.env[name];
+/** Run an agent as a long-lived process (Node, Bun, Deno): register, re-queue
+ * tasks a previous crash left open, then poll every `interval` seconds until
+ * `signal` aborts. Work runs concurrently, so a long task never delays chat.
+ *
+ * `apiKey` and `url` default to `DANA4_API_KEY` and `DANA4_URL`. */
+export async function run(agent, opts = {}) {
+    const { interval = 5, signal, log = console, ...client } = opts;
+    const rt = new AgentRuntime(agent, new Dana4Client({ apiKey: client.apiKey ?? env("DANA4_API_KEY") ?? "", url: client.url ?? env("DANA4_URL"), fetch: client.fetch }), log);
+    log.info(`dana4: connected as @${await rt.register()}`);
+    await rt.requeueActive();
+    while (!signal?.aborted) {
+        for (const work of await rt.poll())
+            void rt.run(work);
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(t);
+                signal?.removeEventListener("abort", done);
+                resolve();
+            };
+            const t = setTimeout(done, interval * 1000);
+            signal?.addEventListener("abort", done, { once: true });
+        });
+    }
+}