@dana4/sdk 0.1.0 → 0.6.0

package/README.md

@@ -147,6 +147,7 @@ Every handler gets a `Context` that is already bound to its workspace, channel a
 | `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.memory.set(memory)`                                        | Replace the channel's memory, markdown notes shared by its agents and people.                   |
 | `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.            |
@@ -175,7 +176,7 @@ export const agent = defineAgent({
 	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"),
+			model: anthropic("claude-haiku-5-5"),
 			system: threadInstructions("You are a helpful assistant in a Dana4 workspace.", thread),
 			messages: [
 				...chatHistory(recent, { me: ctx.me, exclude: message.id }),
@@ -190,9 +191,10 @@ export const agent = defineAgent({
 });
 ```
 
+- `ctx.tickets.create({ title, description?, status?, blocked_by? })` (and the `create_ticket` tool) puts a ticket on the board; tickets are referred to by their per-workspace number, so `blocked_by: [12]` means #12.
 - `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.
+- `threadInstructions(base, thread)` appends the thread's topics, intent, plan and memory to your system prompt.
 
 ## Running your agent
 
@@ -250,7 +252,7 @@ Set the key with `wrangler secret put DANA4_API_KEY`. Set `DANA4_URL` only if yo
 
 ## 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.
+`Dana4Client` wraps every endpoint of the Dana4 SDK API, grouped by resource: `agents`, `tasks`, `docs`, `chat`, `workspaces`, `tickets`, `automations`, `workflows` and `assets`. Use it for scripts, or for integrations that aren't long-running agents.
 
 ```ts
 import { Dana4Client } from "@dana4/sdk";

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ChatThread, Dana4Client, Document, DocumentType, Json, JsonObject, Message, MessageCategory, PresenceActivity, TakenTask, UpdateTaskPayload } from "./client.js";
+import type { ChatThread, CreateTicketBody, 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> = {
@@ -56,6 +56,8 @@ 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;
+/** Usernames @-mentioned in `body`, lowercased; the server's `extract_tagged_usernames`. */
+export declare const taggedUsernames: (body: string) => string[];
 /** Everything a handler needs, bound to its workspace, channel and task, so ids
  * never have to be threaded through calls. */
 export declare class Context {
@@ -88,6 +90,16 @@ export declare class Context {
     }): Promise<Message>;
     /** Workspace params (API keys, feature flags, …) set in workspace settings. */
     params(): Promise<JsonObject>;
+    readonly tickets: {
+        /** Put a ticket on this workspace's board; `blocked_by` takes ticket numbers. */
+        create: (ticket: Omit<CreateTicketBody, "workspace_id">) => Promise<{
+            blocked_by: number[];
+            number: number;
+            status: import("./schema.js").components["schemas"]["BoardStatus"];
+            title: string;
+            workspace_id: string;
+        }>;
+    };
     readonly docs: {
         /** Read by path; shows this agent as `activity` on the document. */
         get: (path: string, activity?: PresenceActivity) => Promise<Document>;
@@ -143,9 +155,11 @@ export declare class Context {
             direct?: boolean;
             document_id?: string | null;
             intent?: string | null;
+            memory?: string | null;
             messages: import("./schema.js").components["schemas"]["Message"][];
             parent_channel_id?: string | null;
             plan?: string | null;
+            tickets?: import("./schema.js").components["schemas"]["TicketSummary"][];
             topics: import("./schema.js").components["schemas"]["TopicSummary"][];
         }[]>;
         create: (doc: {
@@ -166,6 +180,7 @@ export declare class Context {
             document_id: string;
             id: string;
             intent?: string | null;
+            memory?: string | null;
             owners: string[];
             parent_channel_id?: string | null;
             parent_message_id?: string | null;
@@ -180,6 +195,7 @@ export declare class Context {
             document_id: string;
             id: string;
             intent?: string | null;
+            memory?: string | null;
             owners: string[];
             parent_channel_id?: string | null;
             parent_message_id?: string | null;
@@ -194,6 +210,25 @@ export declare class Context {
             document_id: string;
             id: string;
             intent?: string | null;
+            memory?: 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;
+        }>;
+    };
+    /** The channel's memory: markdown notes shared by its agents and people. Answers the updated channel. */
+    readonly memory: {
+        set: (memory: string, channelId?: string | null) => Promise<{
+            document_id: string;
+            id: string;
+            intent?: string | null;
+            memory?: string | null;
             owners: string[];
             parent_channel_id?: string | null;
             parent_message_id?: string | null;
@@ -219,18 +254,21 @@ export declare class Context {
     /** 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 }: {
+    cost({ usd, credits, detail, }: {
         usd?: number;
         credits?: number;
         detail?: JsonObject;
     }): void;
+    /** Record tools the LLM called, for debugging. Saved on the task when it
+     * ends. By convention `{ name, args }`, plus `error` when one failed. */
+    toolCalls(...calls: 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">;
+    /** @internal The accumulated cost and tool calls, in `PATCH /tasks/{id}` shape. */
+    settle(): Pick<UpdateTaskPayload, "cost_usd" | "credits_cost" | "cost_details" | "tool_calls">;
 }
 /** What `onJoin` gets: there is no task yet, so no document writes. */
 export type JoinContext = Pick<Context, "client" | "me" | "workspaceId" | "send" | "params">;

package/dist/agent.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { skippedFromHistory } from "./client.js";
 /** Typed helper: infers `input` in `run` from the schema. */
 export const capability = (c) => c;
 export const defineAgent = (agent) => agent;
@@ -7,7 +8,9 @@ const BASE_FIELDS = ["workspace_id", "task_id", "channel_id", "tag_usernames"];
  * 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" });
+    const { $schema: _, ...schema } = z.toJSONSchema(cap.input, {
+        io: "input",
+    });
     return {
         ...schema,
         title: cap.title ?? key,
@@ -22,9 +25,9 @@ export function capabilitySchema(key, cap) {
         required: [...(schema.required ?? []), "workspace_id", "task_id"],
     };
 }
-const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+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
+export 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("@"))
@@ -43,6 +46,7 @@ export class Context {
     #usd = 0;
     #credits = 0;
     #costDetails = [];
+    #toolCalls = [];
     constructor(client, 
     /** This agent's username. */
     me, workspaceId, 
@@ -78,6 +82,10 @@ export class Context {
     params() {
         return this.client.workspaces.params(this.workspaceId);
     }
+    tickets = {
+        /** Put a ticket on this workspace's board; `blocked_by` takes ticket numbers. */
+        create: (ticket) => this.client.tickets.create({ ...ticket, workspace_id: this.workspaceId }),
+    };
     docs = {
         /** Read by path; shows this agent as `activity` on the document. */
         get: async (path, activity = "reading") => {
@@ -101,8 +109,13 @@ export class Context {
         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,
+        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 = {
@@ -110,6 +123,10 @@ export class Context {
         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),
     };
+    /** The channel's memory: markdown notes shared by its agents and people. Answers the updated channel. */
+    memory = {
+        set: (memory, channelId = this.channelId) => this.client.chat.setMemory(this.#channel(channelId), memory),
+    };
     #channel(channelId) {
         if (!channelId)
             throw new Error("No channel: pass channelId explicitly");
@@ -121,15 +138,24 @@ export class Context {
     };
     /** 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 });
+        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 }) {
+    cost({ usd = 0, credits = 0, detail, }) {
         this.#usd += usd;
         this.#credits += credits;
         if (detail)
             this.#costDetails.push(detail);
     }
+    /** Record tools the LLM called, for debugging. Saved on the task when it
+     * ends. By convention `{ name, args }`, plus `error` when one failed. */
+    toolCalls(...calls) {
+        this.#toolCalls.push(...calls);
+    }
     /** 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 = {}) {
@@ -138,19 +164,24 @@ export class Context {
             task_id: this.#task(),
             channel_id: this.channelId,
             inputs,
-            metadata: { triggered_by: this.me, triggered_from: "chat", tag_usernames: [this.me] },
+            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. */
+    /** @internal The accumulated cost and tool calls, 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,
+            tool_calls: this.#toolCalls.length ? this.#toolCalls : undefined,
         };
     }
 }
@@ -177,7 +208,10 @@ export class AgentRuntime {
                 version,
                 capabilities: Object.fromEntries(Object.entries(capabilities).map(([key, cap]) => [
                     key,
-                    { input_schema: capabilitySchema(key, cap), show_in_chat: cap.showInChat ?? true },
+                    {
+                        input_schema: capabilitySchema(key, cap),
+                        show_in_chat: cap.showInChat ?? true,
+                    },
                 ])),
             },
         });
@@ -192,7 +226,11 @@ export class AgentRuntime {
     /** 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" })
+            .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
@@ -202,7 +240,10 @@ export class AgentRuntime {
         try {
             const taken = await this.client.tasks.take();
             if (taken) {
-                await this.client.tasks.update(taken.task.id, { status: "running", progress: 0 });
+                await this.client.tasks.update(taken.task.id, {
+                    status: "running",
+                    progress: 0,
+                });
                 work.push({ kind: "task", taken });
             }
         }
@@ -223,14 +264,16 @@ export class AgentRuntime {
      * 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 theirs = thread.messages.filter((m) => m.from_username !== this.me && !skippedFromHistory(m));
         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 });
+            .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
@@ -250,7 +293,11 @@ export class AgentRuntime {
         }
     }
     async #runTask({ task, payload }) {
-        const fail = (message, ctx) => this.client.tasks.update(task.id, { status: "failed", message, ...ctx?.settle() });
+        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)
@@ -262,12 +309,17 @@ export class AgentRuntime {
         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) : []);
+        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) {
+            this.log.error(`dana4: ${spec.capability} failed:`, e);
             return void (await fail(errorMessage(e), ctx));
         }
         await this.client.tasks.update(task.id, {
@@ -284,21 +336,34 @@ export class AgentRuntime {
         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 });
+            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 ctx.send(thinking, { category: "skip_from_history" });
             await this.agent.onChat({ message, thread }, ctx);
-            await this.client.tasks.update(taskId, { status: "completed", progress: 1, ...ctx.settle() });
+            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() });
+            // person who asked sees it. Log it too, with the stack, for the host.
+            this.log.error("dana4: chat failed:", e);
+            await this.client.tasks.update(taskId, {
+                status: "failed",
+                message: errorMessage(e),
+                ...ctx.settle(),
+            });
         }
     }
 }

package/dist/ai.d.ts

@@ -1,7 +1,7 @@
 /** 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 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;
@@ -16,7 +16,7 @@ export declare function insertAt(document: string, line: number, content: 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";
+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" | "set_memory" | "create_ticket";
 /** 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
@@ -27,11 +27,12 @@ export declare function dana4Tools(ctx: Context, opts?: {
 }): 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. */
+ * the author. Only conversation is kept; orchestrator notices and errors only
+ * when they @-tag the agent, and status lines never. */
 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;
+/** `base` followed by the thread's topics, the board, intent, plan and memory, so the
+ * model knows what the conversation is for. */
+export declare function threadInstructions(base: string, thread: Pick<ChatThread, "topics" | "tickets" | "intent" | "plan" | "memory">): string;