@dana4/sdk 0.1.0

package/dist/agent.js

@@ -0,0 +1,304 @@
+import { z } from "zod";
+/** Typed helper: infers `input` in `run` from the schema. */
+export const capability = (c) => c;
+export const defineAgent = (agent) => agent;
+const BASE_FIELDS = ["workspace_id", "task_id", "channel_id", "tag_usernames"];
+/** 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 function capabilitySchema(key, cap) {
+    // Input mode: a field with a default is optional to whoever calls it.
+    const { $schema: _, ...schema } = z.toJSONSchema(cap.input, { io: "input" });
+    return {
+        ...schema,
+        title: cap.title ?? key,
+        ...(cap.description && { description: cap.description }),
+        properties: {
+            ...schema.properties,
+            workspace_id: { type: "string" },
+            task_id: { type: "string" },
+            channel_id: { type: ["string", "null"] },
+            tag_usernames: { type: ["array", "null"], items: { type: "string" } },
+        },
+        required: [...(schema.required ?? []), "workspace_id", "task_id"],
+    };
+}
+const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+/** Usernames @-mentioned in `body`, lowercased; the server's `extract_tagged_usernames`. */
+const taggedUsernames = (body) => body
+    .split(/\s+/)
+    .map((w) => w.replace(/^[^\p{L}\p{N}@._-]+|[^\p{L}\p{N}@._-]+$/gu, ""))
+    .filter((w) => w.length > 1 && w.startsWith("@"))
+    .map((w) => w.slice(1).toLowerCase());
+/** Everything a handler needs, bound to its workspace, channel and task, so ids
+ * never have to be threaded through calls. */
+export class Context {
+    client;
+    me;
+    workspaceId;
+    channelId;
+    taskId;
+    tagUsernames;
+    /** Posted into the channel when the task completes. */
+    resultMessage;
+    #usd = 0;
+    #credits = 0;
+    #costDetails = [];
+    constructor(client, 
+    /** This agent's username. */
+    me, workspaceId, 
+    /** `null` means the workspace's default channel. */
+    channelId, taskId, 
+    /** Who to @-mention when posting results back (set by whoever delegated). */
+    tagUsernames = []) {
+        this.client = client;
+        this.me = me;
+        this.workspaceId = workspaceId;
+        this.channelId = channelId;
+        this.taskId = taskId;
+        this.tagUsernames = tagUsernames;
+    }
+    #task() {
+        if (!this.taskId)
+            throw new Error("No task in this context: document writes and uploads need one");
+        return this.taskId;
+    }
+    /** Post a message; to this context's channel unless `channelId` says otherwise. */
+    send(message, opts = {}) {
+        return this.client.chat.send({
+            workspace_id: this.workspaceId,
+            channel_id: opts.channelId === undefined ? this.channelId : opts.channelId,
+            message,
+            category: opts.category,
+            parent_message_id: opts.parentMessageId,
+            document_id: opts.documentId,
+            new_channel: opts.newChannel,
+        });
+    }
+    /** Workspace params (API keys, feature flags, …) set in workspace settings. */
+    params() {
+        return this.client.workspaces.params(this.workspaceId);
+    }
+    docs = {
+        /** Read by path; shows this agent as `activity` on the document. */
+        get: async (path, activity = "reading") => {
+            const doc = await this.client.docs.getByPath(this.workspaceId, path);
+            this.client.docs.presence(doc.id, activity).catch(() => { });
+            return doc;
+        },
+        byChannel: (channelId = this.channelId) => this.client.docs.byChannel(channelId ?? ""),
+        list: (path = "/", recursive = false) => this.client.docs.list(this.workspaceId, { path, recursive }),
+        search: (query, limit) => this.client.docs.search(this.workspaceId, query, limit),
+        messages: (documentId) => this.client.docs.messages(documentId),
+        create: (doc) => this.client.docs.create({
+            path: doc.path,
+            title: doc.title,
+            content: doc.content ?? "",
+            document_type: doc.type,
+            overwrite: doc.overwrite,
+            workspace_id: this.workspaceId,
+            task_id: this.taskId,
+        }),
+        replace: (path, content) => this.client.docs.replace({ path, content, task_id: this.#task() }),
+        append: (path, content) => this.client.docs.append({ path, content, task_id: this.#task() }),
+        /** Exact-string replace, applied server-side. Answers the replacement count. */
+        edit: async (path, oldString, newString, replaceAll = false) => (await this.client.docs.edit({ path, old_string: oldString, new_string: newString, replace_all: replaceAll, task_id: this.#task() }))
+            .replacements,
+    };
+    /** The channel's plan: a markdown checklist. Each call answers the updated channel. */
+    plan = {
+        set: (plan, channelId = this.channelId) => this.client.chat.setPlan(this.#channel(channelId), plan),
+        complete: (item, channelId = this.channelId) => this.client.chat.completePlanItem(this.#channel(channelId), item),
+        add: (item, channelId = this.channelId) => this.client.chat.addPlanItem(this.#channel(channelId), item),
+    };
+    #channel(channelId) {
+        if (!channelId)
+            throw new Error("No channel: pass channelId explicitly");
+        return channelId;
+    }
+    assets = {
+        /** Store a file; put the answered `url` (`dana4-asset://…`) in content. */
+        upload: (data, file) => this.client.assets.upload(this.#task(), data, file),
+    };
+    /** Report progress (0–1) and optionally a message people see in the channel. */
+    async progress(progress, message) {
+        await this.client.tasks.update(this.#task(), { status: "running", progress, message });
+    }
+    /** Record spend. It accumulates and is charged once, when the task ends. */
+    cost({ usd = 0, credits = 0, detail }) {
+        this.#usd += usd;
+        this.#credits += credits;
+        if (detail)
+            this.#costDetails.push(detail);
+    }
+    /** 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, capability, inputs = {}) {
+        return this.client.agents.execute(agent, {
+            tool_key: capability,
+            task_id: this.#task(),
+            channel_id: this.channelId,
+            inputs,
+            metadata: { triggered_by: this.me, triggered_from: "chat", tag_usernames: [this.me] },
+        });
+    }
+    /** The result of an earlier step in this task's journey, or null if not ready. */
+    stepResult(stepId) {
+        return this.client.tasks.stepResult(this.#task(), stepId);
+    }
+    /** @internal The accumulated cost, in `PATCH /tasks/{id}` shape. */
+    settle() {
+        return {
+            cost_usd: this.#usd || undefined,
+            credits_cost: this.#credits || undefined,
+            cost_details: this.#costDetails.length ? this.#costDetails : undefined,
+        };
+    }
+}
+/** Runs an `AgentDefinition` against Dana4. Host-agnostic: `run()` drives it
+ * from a loop, `Dana4Agent` from Durable Object alarms. */
+export class AgentRuntime {
+    agent;
+    client;
+    log;
+    /** This agent's username, known after `register()`. */
+    me = "";
+    constructor(agent, client, log = console) {
+        this.agent = agent;
+        this.client = client;
+        this.log = log;
+    }
+    /** Advertise the capabilities. Also tells us who we are. */
+    async register() {
+        const { version, bio, description, capabilities = {} } = this.agent;
+        const me = await this.client.agents.updateMe({
+            bio,
+            description,
+            schema: {
+                version,
+                capabilities: Object.fromEntries(Object.entries(capabilities).map(([key, cap]) => [
+                    key,
+                    { input_schema: capabilitySchema(key, cap), show_in_chat: cap.showInChat ?? true },
+                ])),
+            },
+        });
+        this.me = me.username;
+        return this.me;
+    }
+    /** Put tasks left assigned/running by a crashed process back in the queue. */
+    async requeueActive() {
+        for (const task of await this.client.tasks.active())
+            await this.requeue(task.id);
+    }
+    /** Put a task interrupted by a crash back in the queue. Never throws. */
+    async requeue(taskId) {
+        await this.client.tasks
+            .update(taskId, { status: "retry", progress: 0, message: "Agent restarted; re-queuing task" })
+            .catch((e) => this.log.error("dana4: re-queuing failed:", errorMessage(e)));
+    }
+    /** 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. */
+    async poll() {
+        const work = [];
+        try {
+            const taken = await this.client.tasks.take();
+            if (taken) {
+                await this.client.tasks.update(taken.task.id, { status: "running", progress: 0 });
+                work.push({ kind: "task", taken });
+            }
+        }
+        catch (e) {
+            this.log.warn("dana4: taking a task failed:", errorMessage(e));
+        }
+        try {
+            work.push(...this.addressed(await this.client.chat.take()));
+        }
+        catch (e) {
+            this.log.warn("dana4: taking chat failed:", errorMessage(e));
+        }
+        return 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) {
+        const theirs = thread.messages.filter((m) => m.from_username !== this.me);
+        const last = theirs.filter((m) => m.from).at(-1);
+        if (thread.direct && last)
+            return [{ kind: "chat", message: last, thread }];
+        const me = this.me.toLowerCase();
+        return theirs
+            .filter((m) => taggedUsernames(m.message).includes(me))
+            .map((m) => m.category === "invited_to_workspace" ? { kind: "join", workspaceId: m.workspace_id } : { kind: "chat", message: m, thread });
+    }
+    /** 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. */
+    async run(work, save) {
+        try {
+            if (work.kind === "task")
+                await this.#runTask(work.taken);
+            else if (work.kind === "chat")
+                await this.#runChat(work, save);
+            else
+                await this.agent.onJoin?.(new Context(this.client, this.me, work.workspaceId, null));
+        }
+        catch (e) {
+            this.log.error(`dana4: ${work.kind} failed:`, errorMessage(e));
+        }
+    }
+    async #runTask({ task, payload }) {
+        const fail = (message, ctx) => this.client.tasks.update(task.id, { status: "failed", message, ...ctx?.settle() });
+        const step = task.step_type;
+        const spec = typeof step === "object" && "agent" in step ? step.agent : null;
+        if (!spec || spec.name !== this.me)
+            return void (await fail(`Not a task for @${this.me}`));
+        const cap = this.agent.capabilities?.[spec.capability];
+        if (!cap)
+            return void (await fail(`Capability not registered: ${spec.capability}`));
+        const own = Object.fromEntries(Object.entries(payload).filter(([k]) => !BASE_FIELDS.includes(k)));
+        const parsed = cap.input.safeParse(own);
+        if (!parsed.success)
+            return void (await fail(`Invalid input for ${spec.capability}: ${z.prettifyError(parsed.error)}`));
+        const ctx = new Context(this.client, this.me, String(payload.workspace_id), typeof payload.channel_id === "string" ? payload.channel_id : task.channel_id, task.id, Array.isArray(payload.tag_usernames) ? payload.tag_usernames.map(String) : []);
+        let result;
+        try {
+            result = await cap.run(parsed.data, ctx);
+        }
+        catch (e) {
+            return void (await fail(errorMessage(e), ctx));
+        }
+        await this.client.tasks.update(task.id, {
+            status: "completed",
+            progress: 1,
+            message: ctx.resultMessage,
+            result_json: result === undefined ? undefined : JSON.stringify(result),
+            ...ctx.settle(),
+        });
+    }
+    async #runChat(work, save) {
+        if (!this.agent.onChat)
+            return;
+        const { message, thread } = work;
+        let taskId = work.taskId;
+        if (!taskId) {
+            taskId = await this.client.tasks.start({ step_name: "read_message", workspace_id: message.workspace_id, channel_id: message.channel_id });
+            save?.({ ...work, taskId });
+        }
+        const ctx = new Context(this.client, this.me, message.workspace_id, message.channel_id, taskId, [this.me]);
+        try {
+            const thinking = this.agent.thinking ?? "*Thinking...*";
+            if (thinking)
+                await ctx.send(thinking, { category: "transient" });
+            await this.agent.onChat({ message, thread }, ctx);
+            await this.client.tasks.update(taskId, { status: "completed", progress: 1, ...ctx.settle() });
+        }
+        catch (e) {
+            // The server posts a failed task's message into its channel, so the
+            // person who asked sees it.
+            await this.client.tasks.update(taskId, { status: "failed", message: errorMessage(e), ...ctx.settle() });
+        }
+    }
+}

package/dist/ai.d.ts

@@ -0,0 +1,37 @@
+/** Glue for the Vercel AI SDK (`ai`): Dana4 tools ready for `generateText`,
+ * and chat threads turned into model messages. */
+import { type ModelMessage, type ToolSet } from "ai";
+import type { Context } from "./agent.js";
+import type { ChatThread, DocumentHeader, JsonObject, Message } from "./client.js";
+/** `ls -R`-style listing: grouped per directory, folders first, titles aligned. */
+export declare function formatDocumentList(documents: DocumentHeader[]): string;
+/** Matching lines (`>`) with `context` lines around them, blocks split by `---`. */
+export declare function grep(content: string, pattern: string, context?: number): {
+    matches: number;
+    lines: number;
+    text: string;
+};
+/** Insert `content` before 1-based `line` (0 = start; past the end appends). */
+export declare function insertAt(document: string, line: number, content: string): string;
+/** A capability's input schema as a tool schema: only primitive params (the
+ * platform resolves documents and the like), and never the ids it injects. */
+export declare function capabilityToolSchema(schema: JsonObject | null | undefined): JsonObject;
+export type Dana4ToolName = "list_documents" | "grep_document" | "search_documents" | "read_document" | "get_step_result" | "create_document" | "write_document" | "append_document" | "edit_document" | "insert_in_document" | "send_message" | "set_plan" | "complete_plan_item" | "add_plan_item";
+/** Tools for reading and writing the workspace's documents, messaging, and the
+ * thread's plan — plus, unless `delegation: false`, one `<agent>__<capability>`
+ * tool per capability other agents in the workspace expose. Tool errors go back
+ * to the model, which can correct itself. */
+export declare function dana4Tools(ctx: Context, opts?: {
+    exclude?: Dana4ToolName[];
+    delegation?: boolean;
+}): Promise<ToolSet>;
+/** A thread's messages as model messages, oldest first: this agent's own
+ * messages become assistant turns, everyone else's user turns prefixed with
+ * the author. Only conversational messages (and errors) are kept. */
+export declare function chatHistory(messages: Message[], { me, exclude }: {
+    me: string;
+    exclude?: string;
+}): ModelMessage[];
+/** `base` followed by the thread's topics, intent and plan, so the model knows
+ * what the conversation is for. */
+export declare function threadInstructions(base: string, thread: Pick<ChatThread, "topics" | "intent" | "plan">): string;