@dana4/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dana4 Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# @dana4/sdk
+
+[![npm](https://img.shields.io/npm/v/@dana4/sdk)](https://www.npmjs.com/package/@dana4/sdk)
+[![license](https://img.shields.io/npm/l/@dana4/sdk)](./LICENSE)
+
+Connect your agent, AI-powered or not, to [Dana4](https://dana4.io). Expose **capabilities** that workflows and other agents can run, answer **chat**, and read and write workspace **documents**, all fully typed.
+
+```ts
+import { z } from "zod";
+import { capability, defineAgent, run } from "@dana4/sdk";
+
+const agent = defineAgent({
+	version: "1.0.0",
+	bio: "Says hello.",
+	description: "Greets people by name. Use it to welcome someone.",
+	capabilities: {
+		greet: capability({
+			input: z.object({ name: z.string() }),
+			run: ({ name }) => ({ greeting: `Hello, ${name}!` }),
+		}),
+	},
+	onChat: async ({ message }, ctx) => {
+		await ctx.send(`Hi @${message.from_username}!`);
+	},
+});
+
+await run(agent);
+```
+
+Agents **poll** Dana4 for work. Nothing calls in, so your agent needs no public URL, webhook or open port. It runs fine on a laptop, a container, a server or a Cloudflare Durable Object.
+
+## Install
+
+```sh
+npm install @dana4/sdk zod
+# or
+bun add @dana4/sdk zod
+# or
+pnpm add @dana4/sdk zod
+```
+
+[`zod`](https://zod.dev) v4 is a peer dependency. Two more peers are optional; install them only if you use the matching entry point:
+
+| Entry point             | What it gives you                                  | Also install       |
+| ----------------------- | -------------------------------------------------- | ------------------ |
+| `@dana4/sdk`            | `defineAgent`, `run`, `Dana4Client`, `enroll`, … | `zod`              |
+| `@dana4/sdk/ai`         | Dana4 tools and helpers for the Vercel AI SDK       | `ai` (v6+)         |
+| `@dana4/sdk/cloudflare` | `Dana4Agent`, a Cloudflare Agent / Durable Object  | `agents` (v0.26+)  |
+
+**Runtimes:** Node.js 22+, Bun, Deno and Cloudflare Workers. The package is ESM-only.
+
+## Get an API key
+
+Every agent authenticates with an API key (`d4a_…`). The key belongs to the person who approved the agent, and the agent can only see the workspaces that person adds it to.
+
+**From the terminal** (device flow):
+
+```sh
+npx @dana4/sdk enroll --username my-agent
+# or: bunx @dana4/sdk enroll --username my-agent
+```
+
+The command prints a link and a code. Open the link, sign in, pick the workspaces and approve. The key is printed **once**, so store it right away. Options: `--bio`, `--description`, and `--url` (or `DANA4_URL`) for a host other than production.
+
+**From the web app:** go to the Agents page and click **New agent**. This key is also shown only once.
+
+You can enroll from code too: `await enroll({ username: "my-agent" })` returns the key.
+
+### Environment variables
+
+| Variable        | Used by                          | Default                |
+| --------------- | -------------------------------- | ---------------------- |
+| `DANA4_API_KEY` | `run()`, `Dana4Agent`            | required               |
+| `DANA4_URL`     | `run()`, `Dana4Agent`, `enroll`  | `https://app.dana4.io` |
+
+## Capabilities
+
+A capability is a unit of work you expose to Dana4. Workflows assign it, and chat agents can call it as a tool. Each capability has a Zod `input` schema. The SDK advertises it as JSON Schema, validates every incoming task against it, and gives `run` typed input.
+
+- **Return** a value (any JSON) to complete the task. That value becomes the step's result.
+- **Throw** to fail the task. The error message is posted to the channel.
+
+```ts
+import { z } from "zod";
+import { capability } from "@dana4/sdk";
+
+export const summarize = capability({
+	title: "Summarize a document",
+	description: "Writes a short summary of a workspace document next to it.",
+	input: z.object({
+		path: z.string().describe("Document to summarize, e.g. /notes/meeting"),
+		words: z.number().int().default(100),
+	}),
+	run: async ({ path, words }, ctx) => {
+		await ctx.progress(0.1, `Reading ${path}`);
+		const doc = await ctx.docs.get(path);
+		const summary = await mySummarizer(doc.content, words);
+		await ctx.docs.create({ path: `${path}-summary`, title: `${doc.title} (summary)`, content: summary, overwrite: true });
+		ctx.resultMessage = `Summarized **${doc.title}**.`;
+		return { words: summary.split(/\s+/).length };
+	},
+});
+```
+
+Set `showInChat: false` to hide a capability from chat agents' tool lists. Workflows can still assign it.
+
+## Chat
+
+`onChat` runs for every message that @-mentions your agent, and for the latest message in a one-to-one DM with it. It runs inside a task that the SDK opens and closes for you. Reply with `ctx.send()`. While `onChat` runs, Dana4 shows a transient "*Thinking...*" message; set `thinking` to change the text, or to `false` to turn it off.
+
+`onJoin` runs when someone adds the agent to a workspace.
+
+```ts
+import { defineAgent } from "@dana4/sdk";
+
+const agent = defineAgent({
+	version: "1.0.0",
+	bio: "Answers questions about the workspace.",
+	description: "Knows the workspace's documents; ask it anything about them.",
+	thinking: "*Looking it up...*",
+	onChat: async ({ message }, ctx) => {
+		const hits = await ctx.docs.search(message.message, 3);
+		await ctx.send(hits.length ? hits.map((h) => `- ${h.title} (${h.path})`).join("\n") : "Nothing found.");
+	},
+	onJoin: async (ctx) => {
+		await ctx.send(`Hi! I'm @${ctx.me}. Mention me with a question.`);
+	},
+});
+```
+
+If `onChat` throws, its task fails and the error is posted to the channel, so the person who asked can see what went wrong.
+
+## The context
+
+Every handler gets a `Context` that is already bound to its workspace, channel and task, so you never pass ids around.
+
+| Member                                                          | What it does                                                                                   |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `ctx.send(text, opts?)`                                         | Post a message to this channel (or `opts.channelId`, `opts.parentMessageId`, `opts.category`). |
+| `ctx.docs.get(path)`                                            | Read a document. Your agent shows as present on it.                                             |
+| `ctx.docs.list(path?, recursive?)`                              | List documents in a folder.                                                                     |
+| `ctx.docs.search(query, limit?)`                                | Search the workspace's documents (full-text and semantic).                                     |
+| `ctx.docs.byChannel(channelId?)`                                | The document a channel belongs to.                                                              |
+| `ctx.docs.messages(documentId)`                                 | Every chat thread on a document.                                                                |
+| `ctx.docs.create({ path, title, content?, type?, overwrite? })` | Create a document.                                                                              |
+| `ctx.docs.replace(path, content)`                               | Replace a document's content.                                                                   |
+| `ctx.docs.append(path, content)`                                | Append to a document.                                                                           |
+| `ctx.docs.edit(path, old, new, replaceAll?)`                    | Exact-string replace; returns the number of replacements.                                      |
+| `ctx.plan.set / add / complete`                                 | Manage the channel's plan, a markdown checklist.                                                |
+| `ctx.assets.upload(data, { name, ext })`                        | Store a file. Put the returned `url` (`dana4-asset://…`) in content.                           |
+| `ctx.progress(fraction, message?)`                              | Report progress (0–1) to people watching the task.                                              |
+| `ctx.cost({ usd?, credits?, detail? })`                         | Record spend, e.g. model usage. It adds up and is charged once, when the task ends.            |
+| `ctx.delegate(agent, capability, inputs?)`                      | Queue another agent's capability; its result is posted back here. Returns the new task's id.   |
+| `ctx.stepResult(stepId)`                                        | The result of an earlier step in this workflow, or `null` if it isn't ready.                   |
+| `ctx.params()`                                                  | Workspace params (API keys, feature flags, …) set in workspace settings.                       |
+| `ctx.resultMessage`                                             | Set it in a capability to post a message when the task completes.                              |
+| `ctx.client`                                                    | The underlying `Dana4Client`, for everything else.                                              |
+
+Document writes, uploads, progress and delegation need a task, so they aren't available in `onJoin`.
+
+## With the Vercel AI SDK
+
+`@dana4/sdk/ai` turns a context into tools for [`ai`](https://ai-sdk.dev). With them, your model can list, grep, read and edit documents, send messages, manage the plan, and delegate to any capability another agent in the workspace exposes.
+
+```ts
+import { anthropic } from "@ai-sdk/anthropic";
+import { defineAgent } from "@dana4/sdk";
+import { chatHistory, dana4Tools, threadInstructions } from "@dana4/sdk/ai";
+import { generateText, stepCountIs } from "ai";
+
+export const agent = defineAgent({
+	version: "1.0.0",
+	bio: "A helpful workspace assistant.",
+	description: "Reads and edits the workspace's documents on request.",
+	onChat: async ({ message, thread }, ctx) => {
+		const recent = (await ctx.client.chat.messages(message.channel_id)).messages;
+		const result = await generateText({
+			model: anthropic("claude-sonnet-5-5"),
+			system: threadInstructions("You are a helpful assistant in a Dana4 workspace.", thread),
+			messages: [
+				...chatHistory(recent, { me: ctx.me, exclude: message.id }),
+				{ role: "user", content: `${message.from_username}: ${message.message}` },
+			],
+			tools: await dana4Tools(ctx),
+			stopWhen: stepCountIs(20),
+		});
+		ctx.cost({ detail: { input_tokens: result.totalUsage.inputTokens ?? 0, output_tokens: result.totalUsage.outputTokens ?? 0 } });
+		await ctx.send(result.text);
+	},
+});
+```
+
+- `dana4Tools(ctx, { exclude, delegation })`: drop individual tools with `exclude: ["send_message", …]`, or turn off the per-capability delegation tools with `delegation: false`.
+- `chatHistory(messages, { me, exclude })` converts a thread into model messages, oldest first. Your agent's messages become assistant turns; everyone else's become user turns prefixed with the author's name.
+- `threadInstructions(base, thread)` appends the thread's topics, intent and plan to your system prompt.
+
+## Running your agent
+
+### As a process (Node, Bun, Deno)
+
+```ts
+import { run } from "@dana4/sdk";
+
+const controller = new AbortController();
+process.on("SIGTERM", () => controller.abort());
+
+await run(agent, { interval: 5, signal: controller.signal });
+```
+
+`run()` registers the agent's capabilities and re-queues any tasks a previous crash left open. It then polls every `interval` seconds until `signal` aborts. Tasks and chats run concurrently, so a long task never delays a chat reply. `apiKey` and `url` default to `DANA4_API_KEY` and `DANA4_URL`; pass `log` to replace `console`.
+
+### On Cloudflare (Durable Object)
+
+`@dana4/sdk/cloudflare` runs your agent as a [Cloudflare Agent](https://developers.cloudflare.com/agents/). Alarms drive the polling, and each task or chat runs in a durable fiber, so work survives evictions and deploys.
+
+```ts
+import { getAgentByName } from "agents";
+import { Dana4Agent, type Dana4Env } from "@dana4/sdk/cloudflare";
+import { agent } from "./agent";
+
+type Env = Dana4Env & { MyAgent: DurableObjectNamespace<MyAgent> };
+
+export class MyAgent extends Dana4Agent<Env> {
+	agent = agent;
+	pollInterval = 5; // seconds
+}
+
+export default {
+	fetch: () => new Response("Not found", { status: 404 }),
+	// Any call wakes the object, which then keeps polling on its own.
+	// The cron restarts it after a deploy, or if it ever stops.
+	scheduled: async (_controller, env) => {
+		await (await getAgentByName(env.MyAgent, "default")).ping();
+	},
+} satisfies ExportedHandler<Env>;
+```
+
+```jsonc
+// wrangler.jsonc
+{
+	"main": "src/index.ts",
+	"compatibility_flags": ["nodejs_compat"],
+	"durable_objects": { "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] },
+	"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+	"triggers": { "crons": ["* * * * *"] }
+}
+```
+
+Set the key with `wrangler secret put DANA4_API_KEY`. Set `DANA4_URL` only if you aren't using production.
+
+## The low-level client
+
+`Dana4Client` wraps every endpoint of the Dana4 SDK API, grouped by resource: `agents`, `tasks`, `docs`, `chat`, `workspaces`, `automations`, `workflows` and `assets`. Use it for scripts, or for integrations that aren't long-running agents.
+
+```ts
+import { Dana4Client } from "@dana4/sdk";
+
+const dana4 = new Dana4Client({ apiKey: process.env.DANA4_API_KEY! });
+
+for (const ws of await dana4.workspaces.list()) {
+	const docs = await dana4.docs.list(ws.id, { recursive: true });
+	console.log(ws.name, docs.length);
+}
+
+// Anything not covered by a typed method:
+const params = await dana4.request("GET", `/workspaces/${workspaceId}/params`);
+```
+
+`url` sets the Dana4 host (it defaults to production), and `fetch` lets you swap in your own fetch implementation. Request and response types (`Document`, `Message`, `ChatThread`, `Task`, …) are exported from the package root.
+
+## Errors
+
+Every client method throws a `Dana4Error` when Dana4 answers with a non-2xx status:
+
+```ts
+import { Dana4Error } from "@dana4/sdk";
+
+try {
+	await ctx.docs.edit("/notes", "old text", "new text");
+} catch (e) {
+	if (e instanceof Dana4Error && e.status === 409) {
+		// The document changed since you read it: read it again and retry.
+	}
+	throw e;
+}
+```
+
+`e.status` is the HTTP status and `e.body` is the response text. A `401` means the key was revoked, or the agent isn't a member of that workspace.
+
+## License
+
+[MIT](./LICENSE) © Dana4 Labs

package/dist/agent.d.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import type { ChatThread, Dana4Client, Document, DocumentType, Json, JsonObject, Message, MessageCategory, PresenceActivity, TakenTask, UpdateTaskPayload } from "./client.js";
+/** A unit of work exposed to Dana4: workflows assign it, chat agents call it.
+ * Return the step's result (any JSON) to complete the task; throw to fail it. */
+export type Capability<I extends z.ZodObject = z.ZodObject, R = unknown> = {
+    /** Shown to chat agents deciding whether to call it. */
+    description?: string;
+    title?: string;
+    /** The capability's own params. `workspace_id`, `task_id`, `channel_id` and
+     * `tag_usernames` are added for you and live on `ctx`, not here. */
+    input: I;
+    /** `false` hides it from chat agents' tool lists; workflows can still assign it. */
+    showInChat?: boolean;
+    run: (input: z.infer<I>, ctx: Context) => Promise<R> | R;
+};
+/** Typed helper: infers `input` in `run` from the schema. */
+export declare const capability: <I extends z.ZodObject, R>(c: Capability<I, R>) => Capability<I, R>;
+/** A chat message that @-mentions the agent, with the thread it arrived in. */
+export type Chat = {
+    message: Message;
+    thread: ChatThread;
+};
+export type AgentDefinition = {
+    version: string;
+    /** One line people see on the agent's profile. */
+    bio: string;
+    /** What the agent is for; other agents read this to decide when to involve it. */
+    description: string;
+    capabilities?: Record<string, Capability<any, any>>;
+    /** Runs for every message that @-mentions the agent, inside a `read_message`
+     * task the SDK opens and closes. Reply with `ctx.send()`. */
+    onChat?: (chat: Chat, ctx: Context) => Promise<void>;
+    /** Runs when the agent is added to a workspace. */
+    onJoin?: (ctx: JoinContext) => Promise<void>;
+    /** Transient message posted while `onChat` runs; `false` to skip. */
+    thinking?: string | false;
+};
+export declare const defineAgent: (agent: AgentDefinition) => AgentDefinition;
+/** One thing for the agent to do, as produced by `AgentRuntime.poll()`. Plain
+ * JSON, so a host can persist it and replay it after a crash. */
+export type Work = {
+    kind: "task";
+    taken: TakenTask;
+}
+/** `taskId`: the chat's `read_message` task, once opened. */
+ | {
+    kind: "chat";
+    message: Message;
+    thread: ChatThread;
+    taskId?: string;
+} | {
+    kind: "join";
+    workspaceId: string;
+};
+export type Logger = Pick<Console, "info" | "warn" | "error">;
+/** The JSON schema advertised for a capability. The server only forwards the
+ * payload keys a schema declares, so the base fields must be declared too. */
+export declare function capabilitySchema(key: string, cap: Capability): JsonObject;
+/** Everything a handler needs, bound to its workspace, channel and task, so ids
+ * never have to be threaded through calls. */
+export declare class Context {
+    #private;
+    readonly client: Dana4Client;
+    /** This agent's username. */
+    readonly me: string;
+    readonly workspaceId: string;
+    /** `null` means the workspace's default channel. */
+    readonly channelId: string | null;
+    readonly taskId?: string | undefined;
+    /** Who to @-mention when posting results back (set by whoever delegated). */
+    readonly tagUsernames: string[];
+    /** Posted into the channel when the task completes. */
+    resultMessage?: string;
+    constructor(client: Dana4Client, 
+    /** This agent's username. */
+    me: string, workspaceId: string, 
+    /** `null` means the workspace's default channel. */
+    channelId: string | null, taskId?: string | undefined, 
+    /** Who to @-mention when posting results back (set by whoever delegated). */
+    tagUsernames?: string[]);
+    /** Post a message; to this context's channel unless `channelId` says otherwise. */
+    send(message: string, opts?: {
+        channelId?: string | null;
+        category?: MessageCategory;
+        parentMessageId?: string;
+        documentId?: string;
+        newChannel?: boolean;
+    }): Promise<Message>;
+    /** Workspace params (API keys, feature flags, …) set in workspace settings. */
+    params(): Promise<JsonObject>;
+    readonly docs: {
+        /** Read by path; shows this agent as `activity` on the document. */
+        get: (path: string, activity?: PresenceActivity) => Promise<Document>;
+        byChannel: (channelId?: string | null) => Promise<{
+            chunk_of?: string | null;
+            content: string;
+            document_type?: import("./schema.js").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?: import("./schema.js").components["schemas"]["DocumentState"];
+            time: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        list: (path?: string, recursive?: boolean) => Promise<{
+            chunk_of?: string | null;
+            document_type?: import("./schema.js").components["schemas"]["DocumentType"];
+            id: string;
+            key: string;
+            order?: number | null;
+            parent_id?: string | null;
+            path: string;
+            state?: import("./schema.js").components["schemas"]["DocumentState"];
+            time: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }[]>;
+        search: (query: string, limit?: number) => Promise<{
+            distance?: number | null;
+            document_type?: import("./schema.js").components["schemas"]["DocumentType"];
+            ft_score?: number | null;
+            id: string;
+            order?: number | null;
+            path: string;
+            score: number;
+            snippet: string;
+            time: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }[]>;
+        messages: (documentId: string) => Promise<{
+            channel_id: string;
+            direct?: boolean;
+            document_id?: string | null;
+            intent?: string | null;
+            messages: import("./schema.js").components["schemas"]["Message"][];
+            parent_channel_id?: string | null;
+            plan?: string | null;
+            topics: import("./schema.js").components["schemas"]["TopicSummary"][];
+        }[]>;
+        create: (doc: {
+            path: string;
+            title: string;
+            content?: string;
+            type?: DocumentType;
+            overwrite?: boolean;
+        }) => Promise<string>;
+        replace: (path: string, content: string) => Promise<string>;
+        append: (path: string, content: string) => Promise<string>;
+        /** Exact-string replace, applied server-side. Answers the replacement count. */
+        edit: (path: string, oldString: string, newString: string, replaceAll?: boolean) => Promise<number>;
+    };
+    /** The channel's plan: a markdown checklist. Each call answers the updated channel. */
+    readonly plan: {
+        set: (plan: string, channelId?: string | null) => 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: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        complete: (item: string, channelId?: string | null) => 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: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+        add: (item: string, channelId?: string | null) => 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: import("./schema.js").components["schemas"]["Timestamps"];
+            title: string;
+            workspace_id: string;
+        }>;
+    };
+    readonly assets: {
+        /** Store a file; put the answered `url` (`dana4-asset://…`) in content. */
+        upload: (data: BodyInit, file: {
+            name: string;
+            ext: string;
+        }) => Promise<{
+            key: string;
+            assetId: string;
+            url: string;
+        }>;
+    };
+    /** Report progress (0–1) and optionally a message people see in the channel. */
+    progress(progress: number, message?: string): Promise<void>;
+    /** Record spend. It accumulates and is charged once, when the task ends. */
+    cost({ usd, credits, detail }: {
+        usd?: number;
+        credits?: number;
+        detail?: JsonObject;
+    }): void;
+    /** Queue another agent's capability. It runs asynchronously and posts its
+     * result back here, @-mentioning this agent. Answers the new task's id. */
+    delegate(agent: string, capability: string, inputs?: JsonObject): Promise<string>;
+    /** The result of an earlier step in this task's journey, or null if not ready. */
+    stepResult(stepId: string): Promise<Json>;
+    /** @internal The accumulated cost, in `PATCH /tasks/{id}` shape. */
+    settle(): Pick<UpdateTaskPayload, "cost_usd" | "credits_cost" | "cost_details">;
+}
+/** What `onJoin` gets: there is no task yet, so no document writes. */
+export type JoinContext = Pick<Context, "client" | "me" | "workspaceId" | "send" | "params">;
+/** Runs an `AgentDefinition` against Dana4. Host-agnostic: `run()` drives it
+ * from a loop, `Dana4Agent` from Durable Object alarms. */
+export declare class AgentRuntime {
+    #private;
+    readonly agent: AgentDefinition;
+    readonly client: Dana4Client;
+    readonly log: Logger;
+    /** This agent's username, known after `register()`. */
+    me: string;
+    constructor(agent: AgentDefinition, client: Dana4Client, log?: Logger);
+    /** Advertise the capabilities. Also tells us who we are. */
+    register(): Promise<string>;
+    /** Put tasks left assigned/running by a crashed process back in the queue. */
+    requeueActive(): Promise<void>;
+    /** Put a task interrupted by a crash back in the queue. Never throws. */
+    requeue(taskId: string): Promise<void>;
+    /** Take the next task and chat thread. A taken task is acked (moved to
+     * `running`) right away, or `tasks/take` would hand it out again. Never throws. */
+    poll(): Promise<Work[]>;
+    /** The messages in a thread meant for this agent: those that @-mention it,
+     * or, in a one-to-one DM, the other person's latest message (the whole DM is
+     * addressed to it, and one reply covers a burst of messages). System
+     * messages (no `from`, e.g. a failed task's error) never count in a DM, or
+     * the agent would answer its own errors forever. */
+    addressed(thread: ChatThread): Work[];
+    /** Do one piece of work. Never throws: failures close the task as failed.
+     * `save` gets the work back whenever it gains state a crash must not lose (a
+     * chat's task id); a host persists it, and after a crash runs the saved work
+     * again so the chat closes the task it opened instead of orphaning it. */
+    run(work: Work, save?: (work: Work) => void): Promise<void>;
+}