@dana4/sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,498 @@
+import type { components } from "./schema.js";
+type S = components["schemas"];
+export type Agent = S["Agent"];
+export type AgentDescription = S["AgentDescription"];
+export type Automation = S["Automation"];
+export type Channel = S["Channel"];
+export type ChatThread = S["ChatThread"];
+export type CreateAutomationBody = S["CreateAutomationBody"];
+export type CreateWorkflowPayload = S["CreateWorkflowPayload"];
+export type Document = S["Document"];
+export type DocumentHeader = S["DocumentHeader"];
+export type DocumentType = S["DocumentType"];
+export type EnrollAgentResponse = S["EnrollAgentResponse"];
+export type Message = S["Message"];
+export type MessageCategory = S["MessageCategory"];
+export type Pipe = S["Pipe"];
+export type PresenceActivity = S["PresenceActivity"];
+export type SearchResult = S["SearchResult"];
+export type Task = S["Task"];
+export type TaskStatus = S["TaskStatus"];
+/** `cost_details` is optional on the wire; utoipa marks it required. */
+export type UpdateTaskPayload = Omit<S["UpdateTaskPayload"], "cost_details"> & {
+    cost_details?: JsonObject[] | null;
+};
+export type Workflow = S["Workflow"];
+export type WorkflowRef = S["WorkflowRef"];
+export type WorkspaceRef = S["WorkspaceRef"];
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export type JsonObject = {
+    [key: string]: Json;
+};
+/** What `POST /tasks/take` hands out (the spec types it as a bare `Value`). */
+export type TakenTask = {
+    task: Task;
+    payload: JsonObject;
+};
+export declare const DEFAULT_URL = "https://app.dana4.io";
+/** A non-2xx answer from Dana4. `status` 401 means a revoked key or a workspace
+ * the agent is not a member of; 409 on a document edit means a stale read. */
+export declare class Dana4Error extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string, what: string);
+}
+export type ClientOptions = {
+    /** The agent's key (`d4a_…`). Get one with `npx @dana4/sdk enroll`. */
+    apiKey: string;
+    /** Dana4 host, e.g. `http://localhost:8000`. Defaults to production. */
+    url?: string;
+    fetch?: typeof fetch;
+};
+type Query = Record<string, string | number | boolean | Date | null | undefined>;
+/** Typed access to every `/api-sdk/v1` endpoint, grouped by resource. Every
+ * method throws `Dana4Error` on failure; none returns a silent `false`. */
+export declare class Dana4Client {
+    #private;
+    readonly url: string;
+    constructor({ apiKey, url, fetch: f }: ClientOptions);
+    /** Raw call, for anything the grouped methods don't cover. JSON responses are
+     * parsed; text ones (ids, paths) come back as strings. */
+    request<T>(method: string, path: string, opts?: {
+        body?: unknown;
+        query?: Query;
+    }): Promise<T>;
+    readonly agents: {
+        /** Advertise the schema/bio/description; answers who this key belongs to. */
+        updateMe: (body: S["UpdateAgentPayload"]) => Promise<{
+            bio?: string | null;
+            description?: string | null;
+            last_seen_at?: string | null;
+            schema?: null | components["schemas"]["AgentSchema"];
+            status: components["schemas"]["AgentStatus"];
+            user_id: string;
+            username: string;
+        }>;
+        /** Queue another agent's capability; answers the new task's id. */
+        execute: (username: string, body: {
+            tool_key: string;
+            task_id: string;
+            channel_id?: string | null;
+            inputs?: JsonObject;
+            metadata?: JsonObject;
+        }) => Promise<string>;
+    };
+    readonly tasks: {
+        take: () => Promise<TakenTask | null>;
+        active: () => Promise<{
+            channel_id: string;
+            cost_detail?: {
+                [key: string]: unknown;
+            }[];
+            cost_usd?: number | null;
+            execution_duration?: number | null;
+            id: string;
+            journey_id: string;
+            order: number;
+            params?: {
+                [key: string]: unknown;
+            };
+            progress: number;
+            result?: null | components["schemas"]["JourneyStepResult"];
+            started_at?: number | null;
+            status: components["schemas"]["TaskStatus"];
+            step_id: string;
+            step_type: components["schemas"]["JourneyStepType"];
+            time: components["schemas"]["Timestamps"];
+        }[]>;
+        assigned: () => Promise<{
+            channel_id: string;
+            cost_detail?: {
+                [key: string]: unknown;
+            }[];
+            cost_usd?: number | null;
+            execution_duration?: number | null;
+            id: string;
+            journey_id: string;
+            order: number;
+            params?: {
+                [key: string]: unknown;
+            };
+            progress: number;
+            result?: null | components["schemas"]["JourneyStepResult"];
+            started_at?: number | null;
+            status: components["schemas"]["TaskStatus"];
+            step_id: string;
+            step_type: components["schemas"]["JourneyStepType"];
+            time: components["schemas"]["Timestamps"];
+        }[]>;
+        unassigned: () => Promise<{
+            channel_id: string;
+            cost_detail?: {
+                [key: string]: unknown;
+            }[];
+            cost_usd?: number | null;
+            execution_duration?: number | null;
+            id: string;
+            journey_id: string;
+            order: number;
+            params?: {
+                [key: string]: unknown;
+            };
+            progress: number;
+            result?: null | components["schemas"]["JourneyStepResult"];
+            started_at?: number | null;
+            status: components["schemas"]["TaskStatus"];
+            step_id: string;
+            step_type: components["schemas"]["JourneyStepType"];
+            time: components["schemas"]["Timestamps"];
+        }[]>;
+        claim: (taskId: string, capability: string) => Promise<{
+            channel_id: string;
+            cost_detail?: {
+                [key: string]: unknown;
+            }[];
+            cost_usd?: number | null;
+            execution_duration?: number | null;
+            id: string;
+            journey_id: string;
+            order: number;
+            params?: {
+                [key: string]: unknown;
+            };
+            progress: number;
+            result?: null | components["schemas"]["JourneyStepResult"];
+            started_at?: number | null;
+            status: components["schemas"]["TaskStatus"];
+            step_id: string;
+            step_type: components["schemas"]["JourneyStepType"];
+            time: components["schemas"]["Timestamps"];
+        }>;
+        /** Start a one-step journey (e.g. `read_message`); answers its task id. */
+        start: (body: {
+            step_name: string;
+            workspace_id: string;
+            channel_id: string;
+            params?: JsonObject | null;
+        }) => Promise<string>;
+        update: (taskId: string, body: UpdateTaskPayload) => Promise<string>;
+        /** Workspace params merged with the journey's params. */
+        params: (taskId: string) => Promise<JsonObject>;
+        stepResult: (taskId: string, stepId: string) => Promise<Json>;
+    };
+    readonly docs: {
+        list: (workspaceId: string, opts?: {
+            path?: string;
+            recursive?: boolean;
+        }) => Promise<{
+            chunk_of?: string | null;
+            document_type?: components["schemas"]["DocumentType"];
+            id: string;
+            key: string;
+            order?: number | null;
+            parent_id?: string | null;
+            path: string;
+            state?: components["schemas"]["DocumentState"];
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }[]>;
+        getByPath: (workspaceId: string, path: string) => Promise<{
+            chunk_of?: string | null;
+            content: string;
+            document_type?: components["schemas"]["DocumentType"];
+            hash: string;
+            id: string;
+            key: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            order?: number | null;
+            origin_channel_id?: string | null;
+            parent_id?: string | null;
+            path: string;
+            public?: boolean;
+            source_asset_id?: string | null;
+            state?: components["schemas"]["DocumentState"];
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        get: (documentId: string) => Promise<{
+            chunk_of?: string | null;
+            content: string;
+            document_type?: components["schemas"]["DocumentType"];
+            hash: string;
+            id: string;
+            key: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            order?: number | null;
+            origin_channel_id?: string | null;
+            parent_id?: string | null;
+            path: string;
+            public?: boolean;
+            source_asset_id?: string | null;
+            state?: components["schemas"]["DocumentState"];
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        byChannel: (channelId: string) => Promise<{
+            chunk_of?: string | null;
+            content: string;
+            document_type?: components["schemas"]["DocumentType"];
+            hash: string;
+            id: string;
+            key: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            order?: number | null;
+            origin_channel_id?: string | null;
+            parent_id?: string | null;
+            path: string;
+            public?: boolean;
+            source_asset_id?: string | null;
+            state?: components["schemas"]["DocumentState"];
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        source: (documentId: string) => Promise<{
+            asset_id: string;
+            s3_key: string;
+            url: string;
+        }>;
+        search: (workspaceId: string, q: string, limit?: number) => Promise<{
+            distance?: number | null;
+            document_type?: components["schemas"]["DocumentType"];
+            ft_score?: number | null;
+            id: string;
+            order?: number | null;
+            path: string;
+            score: number;
+            snippet: string;
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }[]>;
+        /** Every thread on a document; the root discussion has no `parent_channel_id`. */
+        messages: (documentId: string, range?: {
+            since?: Date;
+            until?: Date;
+        }) => Promise<{
+            channel_id: string;
+            direct?: boolean;
+            document_id?: string | null;
+            intent?: string | null;
+            messages: components["schemas"]["Message"][];
+            parent_channel_id?: string | null;
+            plan?: string | null;
+            topics: components["schemas"]["TopicSummary"][];
+        }[]>;
+        create: (body: S["CreateDocumentPayload"]) => Promise<string>;
+        replace: (body: S["UpdateDocumentPayload"]) => Promise<string>;
+        append: (body: S["AppendDocumentPayload"]) => Promise<string>;
+        edit: (body: S["EditDocumentPayload"]) => Promise<{
+            path: string;
+            replacements: number;
+        }>;
+        presence: (documentId: string, activity: PresenceActivity) => Promise<string>;
+    };
+    readonly chat: {
+        /** The next channel with unread messages for this agent. Marks them read:
+         * delivery is at-most-once. `channel_id` is "" when there is nothing. */
+        take: () => Promise<{
+            channel_id: string;
+            direct?: boolean;
+            document_id?: string | null;
+            intent?: string | null;
+            messages: components["schemas"]["Message"][];
+            parent_channel_id?: string | null;
+            plan?: string | null;
+            topics: components["schemas"]["TopicSummary"][];
+        }>;
+        messages: (channelId: string, range?: {
+            since?: Date;
+            until?: Date;
+        }) => Promise<{
+            channel_id: string;
+            direct?: boolean;
+            document_id?: string | null;
+            intent?: string | null;
+            messages: components["schemas"]["Message"][];
+            parent_channel_id?: string | null;
+            plan?: string | null;
+            topics: components["schemas"]["TopicSummary"][];
+        }>;
+        send: (body: S["SendMessagePayload"]) => Promise<{
+            category: components["schemas"]["MessageCategory"];
+            channel_id: string;
+            from?: string | null;
+            from_username: string;
+            id: string;
+            message: string;
+            time: components["schemas"]["Timestamps"];
+            workspace_id: string;
+        }>;
+        privateChannels: (workspaceId: string) => Promise<{
+            document_id: string;
+            id: string;
+            intent?: string | null;
+            owners: string[];
+            parent_channel_id?: string | null;
+            parent_message_id?: string | null;
+            plan?: string | null;
+            plan_completed: boolean;
+            private: boolean;
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }[]>;
+        setPlan: (channelId: string, plan: string) => Promise<{
+            document_id: string;
+            id: string;
+            intent?: string | null;
+            owners: string[];
+            parent_channel_id?: string | null;
+            parent_message_id?: string | null;
+            plan?: string | null;
+            plan_completed: boolean;
+            private: boolean;
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        completePlanItem: (channelId: string, item: string) => Promise<{
+            document_id: string;
+            id: string;
+            intent?: string | null;
+            owners: string[];
+            parent_channel_id?: string | null;
+            parent_message_id?: string | null;
+            plan?: string | null;
+            plan_completed: boolean;
+            private: boolean;
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        addPlanItem: (channelId: string, item: string) => Promise<{
+            document_id: string;
+            id: string;
+            intent?: string | null;
+            owners: string[];
+            parent_channel_id?: string | null;
+            parent_message_id?: string | null;
+            plan?: string | null;
+            plan_completed: boolean;
+            private: boolean;
+            time: components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+    };
+    readonly workspaces: {
+        list: () => Promise<{
+            id: string;
+            name: string;
+        }[]>;
+        params: (workspaceId: string) => Promise<JsonObject>;
+        blockers: (workspaceId: string) => Promise<{
+            always: boolean;
+            blocked_at?: string | null;
+            id: string;
+            output: components["schemas"]["Requirement"];
+            source?: null | components["schemas"]["Resource"];
+            task_id: string;
+            workspace_id: string;
+        }[]>;
+        /** Every agent in the workspace with its chat-visible capabilities. */
+        agents: (workspaceId: string) => Promise<{
+            capabilities: components["schemas"]["AgentCapability"][];
+            description?: string | null;
+            metadata?: Record<string, never> | null;
+            name: string;
+            username: string;
+        }[]>;
+        automations: (workspaceId: string) => Promise<{
+            created_by: string;
+            enabled: boolean;
+            id: string;
+            last_run_at?: string | null;
+            name: string;
+            next_run_at?: string | null;
+            params?: {
+                [key: string]: unknown;
+            };
+            run_count: number;
+            schedule_day?: number | null;
+            schedule_frequency: components["schemas"]["ScheduleFrequency"];
+            schedule_time: string;
+            schedule_timezone: string;
+            time: components["schemas"]["Timestamps"];
+            workflow_id?: string | null;
+            workspace_id: string;
+            yaml_definition?: string | null;
+        }[]>;
+        workflows: (workspaceId: string) => Promise<{
+            description: string;
+            id: string;
+            name: string;
+            workspace: string;
+        }[]>;
+    };
+    readonly automations: {
+        create: (body: CreateAutomationBody) => Promise<{
+            created_by: string;
+            enabled: boolean;
+            id: string;
+            last_run_at?: string | null;
+            name: string;
+            next_run_at?: string | null;
+            params?: {
+                [key: string]: unknown;
+            };
+            run_count: number;
+            schedule_day?: number | null;
+            schedule_frequency: components["schemas"]["ScheduleFrequency"];
+            schedule_time: string;
+            schedule_timezone: string;
+            time: components["schemas"]["Timestamps"];
+            workflow_id?: string | null;
+            workspace_id: string;
+            yaml_definition?: string | null;
+        }>;
+        delete: (automationId: string) => Promise<string>;
+    };
+    readonly workflows: {
+        create: (body: CreateWorkflowPayload) => Promise<{
+            definition: string;
+            description: string;
+            id: string;
+            name: string;
+            params: {
+                [key: string]: components["schemas"]["WorkflowParamDef"];
+            };
+            time: components["schemas"]["Timestamps"];
+            workspace: string;
+        }>;
+    };
+    readonly assets: {
+        /** Upload bytes to the workspace's bucket and register the asset. Reference
+         * it in content as `url` (`dana4-asset://…`); Dana4 signs it on read. */
+        upload: (taskId: string, data: BodyInit, { name, ext }: {
+            name: string;
+            ext: string;
+        }) => Promise<{
+            key: string;
+            assetId: string;
+            url: string;
+        }>;
+    };
+}
+export {};

package/dist/client.js

@@ -0,0 +1,124 @@
+export const DEFAULT_URL = "https://app.dana4.io";
+/** A non-2xx answer from Dana4. `status` 401 means a revoked key or a workspace
+ * the agent is not a member of; 409 on a document edit means a stale read. */
+export class Dana4Error extends Error {
+    status;
+    body;
+    constructor(status, body, what) {
+        super(`${what} failed: ${status} ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "Dana4Error";
+    }
+}
+/** Typed access to every `/api-sdk/v1` endpoint, grouped by resource. Every
+ * method throws `Dana4Error` on failure; none returns a silent `false`. */
+export class Dana4Client {
+    url;
+    #apiKey;
+    #fetch;
+    constructor({ apiKey, url = DEFAULT_URL, fetch: f = fetch }) {
+        if (!apiKey)
+            throw new Error("No Dana4 API key. Get one with `npx @dana4/sdk enroll --username <name>`.");
+        this.url = url.replace(/\/+$/, "");
+        this.#apiKey = apiKey;
+        // Called detached: Workers' fetch throws "Illegal invocation" when `this` is the client.
+        this.#fetch = (input, init) => f(input, init);
+    }
+    /** Raw call, for anything the grouped methods don't cover. JSON responses are
+     * parsed; text ones (ids, paths) come back as strings. */
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.url}/api-sdk/v1${path}`);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v != null)
+                url.searchParams.set(k, v instanceof Date ? v.toISOString() : String(v));
+        }
+        const res = await this.#fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                ...(opts.body !== undefined && { "Content-Type": "application/json" }),
+            },
+            body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+        });
+        if (!res.ok)
+            throw new Dana4Error(res.status, await res.text(), `${method} ${path}`);
+        const isJson = res.headers.get("content-type")?.includes("json");
+        return (isJson ? await res.json() : await res.text());
+    }
+    agents = {
+        /** Advertise the schema/bio/description; answers who this key belongs to. */
+        updateMe: (body) => this.request("PATCH", "/agents/me", { body }),
+        /** Queue another agent's capability; answers the new task's id. */
+        execute: (username, body) => this.request("POST", `/agents/${encodeURIComponent(username)}/execute`, { body }).then((r) => r.task_id),
+    };
+    tasks = {
+        take: () => this.request("POST", "/tasks/take"),
+        active: () => this.request("GET", "/tasks/active"),
+        assigned: () => this.request("GET", "/tasks/assigned"),
+        unassigned: () => this.request("GET", "/tasks/unassigned"),
+        claim: (taskId, capability) => this.request("POST", `/tasks/${taskId}/claim`, { body: { capability } }),
+        /** Start a one-step journey (e.g. `read_message`); answers its task id. */
+        start: (body) => this.request("POST", "/tasks", { body: { params: null, ...body } }),
+        update: (taskId, body) => this.request("PATCH", `/tasks/${taskId}`, { body }),
+        /** Workspace params merged with the journey's params. */
+        params: (taskId) => this.request("GET", `/tasks/${taskId}/params`),
+        stepResult: (taskId, stepId) => this.request("GET", `/tasks/${taskId}/steps/${stepId}/result`),
+    };
+    docs = {
+        list: (workspaceId, opts = {}) => this.request("GET", `/workspaces/${workspaceId}/documents`, { query: { path: "/", recursive: false, ...opts } }),
+        getByPath: (workspaceId, path) => this.request("GET", `/workspaces/${workspaceId}/documents/by-path`, { query: { path } }),
+        get: (documentId) => this.request("GET", `/documents/${documentId}`),
+        byChannel: (channelId) => this.request("GET", `/channels/${channelId}/document`),
+        source: (documentId) => this.request("GET", `/documents/${documentId}/source`),
+        search: (workspaceId, q, limit) => this.request("GET", `/workspaces/${workspaceId}/documents/search`, { query: { q, limit } }),
+        /** Every thread on a document; the root discussion has no `parent_channel_id`. */
+        messages: (documentId, range = {}) => this.request("GET", `/documents/${documentId}/messages`, { query: range }),
+        create: (body) => this.request("POST", "/documents", { body }),
+        replace: (body) => this.request("POST", "/documents/replace", { body }),
+        append: (body) => this.request("POST", "/documents/append", { body }),
+        edit: (body) => this.request("POST", "/documents/edit", { body }),
+        presence: (documentId, activity) => this.request("PUT", `/documents/${documentId}/presence`, { body: { activity } }),
+    };
+    chat = {
+        /** The next channel with unread messages for this agent. Marks them read:
+         * delivery is at-most-once. `channel_id` is "" when there is nothing. */
+        take: () => this.request("POST", "/chats/take"),
+        messages: (channelId, range = {}) => this.request("GET", `/channels/${channelId}/messages`, { query: range }),
+        send: (body) => this.request("POST", "/messages", { body }),
+        privateChannels: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/private-channels`),
+        setPlan: (channelId, plan) => this.request("PUT", `/channels/${channelId}/plan`, { body: { plan } }),
+        completePlanItem: (channelId, item) => this.request("POST", `/channels/${channelId}/plan/complete`, { body: { item } }),
+        addPlanItem: (channelId, item) => this.request("POST", `/channels/${channelId}/plan/items`, { body: { item } }),
+    };
+    workspaces = {
+        list: () => this.request("GET", "/workspaces"),
+        params: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/params`),
+        blockers: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/blockers`),
+        /** Every agent in the workspace with its chat-visible capabilities. */
+        agents: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/agents`),
+        automations: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/automations`),
+        workflows: (workspaceId) => this.request("GET", `/workspaces/${workspaceId}/workflows`),
+    };
+    automations = {
+        create: (body) => this.request("POST", "/automations", { body }),
+        delete: (automationId) => this.request("DELETE", `/automations/${automationId}`),
+    };
+    workflows = {
+        create: (body) => this.request("POST", "/workflows", { body }),
+    };
+    assets = {
+        /** Upload bytes to the workspace's bucket and register the asset. Reference
+         * it in content as `url` (`dana4-asset://…`); Dana4 signs it on read. */
+        upload: async (taskId, data, { name, ext }) => {
+            const { url, key } = await this.request("POST", "/uploads", {
+                body: { task_id: taskId, asset_name: name, file_ext: ext },
+            });
+            const put = await this.#fetch(url, { method: "PUT", body: data });
+            if (!put.ok)
+                throw new Dana4Error(put.status, await put.text(), "asset upload");
+            const assetId = await this.request("POST", "/assets", { body: { task_id: taskId, key } });
+            return { key, assetId, url: `dana4-asset://${key}` };
+        },
+    };
+}

package/dist/cloudflare.d.ts

@@ -0,0 +1,39 @@
+/** 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, type FiberRecoveryContext } from "agents";
+import { type AgentDefinition, AgentRuntime } from "./agent.js";
+export type Dana4Env = {
+    DANA4_API_KEY: string;
+    DANA4_URL?: string;
+};
+export declare abstract class Dana4Agent<Env extends Dana4Env = Dana4Env, State = unknown> extends Agent<Env, State> {
+    #private;
+    abstract readonly agent: AgentDefinition;
+    /** Seconds between polls. */
+    pollInterval: number;
+    get runtime(): AgentRuntime;
+    onStart(): Promise<void>;
+    /** 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. */
+    poll(): Promise<void>;
+    /** 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. */
+    onFiberRecovered(ctx: FiberRecoveryContext): Promise<void>;
+    /** Does nothing; calling it wakes the object (and so starts polling). */
+    ping(): Promise<void>;
+}