@dana4/sdk 0.1.0

package/dist/ai.js

@@ -0,0 +1,337 @@
+/** Glue for the Vercel AI SDK (`ai`): Dana4 tools ready for `generateText`,
+ * and chat threads turned into model messages. */
+import { jsonSchema, tool } from "ai";
+import { z } from "zod";
+const MAX_LINES_PER_READ = 500;
+const MAX_LINES_PER_WRITE = 400;
+/** `ls -R`-style listing: grouped per directory, folders first, titles aligned. */
+export function formatDocumentList(documents) {
+    const groups = new Map();
+    for (const d of documents) {
+        const dir = d.path.slice(0, d.path.lastIndexOf("/")) || "/";
+        groups.set(dir, [...(groups.get(dir) ?? []), d]);
+    }
+    const leaf = (d) => d.path.slice(d.path.lastIndexOf("/") + 1);
+    const isFolder = (d) => d.document_type === "folder";
+    return [...groups.keys()]
+        .sort()
+        .map((dir) => {
+        const entries = groups
+            .get(dir)
+            .sort((a, b) => Number(isFolder(b)) - Number(isFolder(a)) || leaf(a).localeCompare(leaf(b)));
+        const names = entries.map((d) => leaf(d) + (isFolder(d) ? "/" : ""));
+        const width = Math.max(...names.map((n) => n.length));
+        return [`${dir}:`, ...entries.map((d, i) => `  ${names[i].padEnd(width)}  ${d.title}`)].join("\n");
+    })
+        .join("\n\n");
+}
+/** Matching lines (`>`) with `context` lines around them, blocks split by `---`. */
+export function grep(content, pattern, context = 3) {
+    const lines = content.split(/\r?\n/);
+    let regex;
+    try {
+        regex = new RegExp(pattern, "i");
+    }
+    catch {
+        regex = new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i");
+    }
+    const hits = lines.flatMap((line, i) => (regex.test(line) ? [i] : []));
+    const shown = new Set(hits.flatMap((i) => Array.from({ length: 2 * context + 1 }, (_, k) => i - context + k)));
+    const out = [];
+    let prev = -2;
+    for (const i of [...shown].filter((i) => i >= 0 && i < lines.length).sort((a, b) => a - b)) {
+        if (i !== prev + 1 && out.length)
+            out.push("---");
+        out.push(`${regex.test(lines[i]) ? ">" : " "} ${i + 1}: ${lines[i]}`);
+        prev = i;
+    }
+    return { matches: hits.length, lines: lines.length, text: out.join("\n") };
+}
+/** Insert `content` before 1-based `line` (0 = start; past the end appends). */
+export function insertAt(document, line, content) {
+    const lines = document.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    const at = Math.max(0, Math.min(line - 1, lines.length));
+    // Appending after an unterminated last line: end it first, or the two join.
+    if (at === lines.length && at > 0 && !lines[at - 1].endsWith("\n"))
+        lines[at - 1] += "\n";
+    lines.splice(at, 0, content.endsWith("\n") ? content : `${content}\n`);
+    return lines.join("");
+}
+const planStatus = (channelId, done) => `Plan updated for channel ${channelId}. ${done ? "All items are checked; the plan is complete." : "Some items are still unchecked."}`;
+const PRIMITIVE = new Set(["string", "number", "integer", "boolean", "null"]);
+/** 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 function capabilityToolSchema(schema) {
+    const props = (schema?.properties ?? {});
+    const keep = Object.entries(props).filter(([name, p]) => {
+        if (["workspace_id", "task_id"].includes(name))
+            return false;
+        const t = p?.type;
+        return typeof t === "string" ? PRIMITIVE.has(t) : Array.isArray(t) && t.every((x) => typeof x === "string" && PRIMITIVE.has(x));
+    });
+    const kept = new Set(keep.map(([n]) => n));
+    const required = Array.isArray(schema?.required) ? schema.required.filter((r) => typeof r === "string" && kept.has(r)) : [];
+    return { type: "object", additionalProperties: false, properties: Object.fromEntries(keep), required };
+}
+/** 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 async function dana4Tools(ctx, opts = {}) {
+    const tools = {
+        list_documents: tool({
+            description: "List documents in a folder with their paths and titles. Optionally recurse into subfolders.",
+            inputSchema: z.object({
+                path: z.string().default("/").describe("Folder to list, as a path (e.g. '/foo/bar'). Defaults to the root."),
+                recursive: z
+                    .boolean()
+                    .default(false)
+                    .describe("List every descendant recursively (ls -R) instead of just the folder's immediate children."),
+            }),
+            execute: async ({ path, recursive }) => formatDocumentList(await ctx.docs.list(path, recursive)),
+        }),
+        grep_document: tool({
+            description: "Search for a text pattern within a document. Returns matching lines with line numbers and surrounding context. Use this BEFORE read_document to find relevant sections without reading the entire file.",
+            inputSchema: z.object({
+                path: z.string().describe("Path of the document to search in."),
+                pattern: z.string().describe("Text or regex pattern to search for. Case-insensitive."),
+                context_lines: z.number().int().default(3).describe("Number of lines to show before and after each match."),
+            }),
+            execute: async ({ path, pattern, context_lines }) => {
+                const r = grep((await ctx.docs.get(path)).content, pattern, context_lines);
+                return r.matches ? `Found ${r.matches} match(es) in ${path} (${r.lines} lines total):\n${r.text}` : `No matches for '${pattern}' in ${path}`;
+            },
+        }),
+        search_documents: tool({
+            description: "Search across ALL documents in the workspace by meaning or keyword, returning the most relevant documents with a snippet and relevance score. Use this when you don't know which document holds the content you need. Use grep_document instead to search within a single known document.",
+            inputSchema: z.object({
+                query: z.string().describe("Natural-language or keyword query to search across all documents in the workspace."),
+                limit: z.number().int().optional().describe("Max number of results to return. Defaults to the server default."),
+            }),
+            execute: async ({ query, limit }) => {
+                const results = await ctx.docs.search(query, limit);
+                if (!results.length)
+                    return `No documents matched '${query}'.`;
+                return [
+                    `Found ${results.length} result(s) for '${query}':\n`,
+                    ...results.flatMap((r) => [`- ${r.path} — ${r.title} (score: ${r.score.toFixed(3)})`, ...(r.snippet ? [`    ${r.snippet}`] : [])]),
+                ].join("\n");
+            },
+        }),
+        read_document: tool({
+            description: `Read a document's content with line numbers. Returns up to ${MAX_LINES_PER_READ} lines.\n\nUsage:\n- Use grep_document first to find relevant line numbers, then read targeted ranges.\n- Use offset and limit to read specific sections. Avoid reading entire large documents.\n- Lines are prefixed with line numbers: \`42: content here\`.\n- Call this tool in parallel when reading multiple documents.`,
+            inputSchema: z.object({
+                path: z.string().describe("The path to the document to read."),
+                offset: z.number().int().optional().describe("Line number to start reading from (1-indexed). Defaults to 1."),
+                limit: z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe(`Max lines to read. Defaults to ${MAX_LINES_PER_READ}. Use grep_document first to find relevant sections, then read targeted ranges.`),
+            }),
+            execute: async ({ path, offset = 1, limit = MAX_LINES_PER_READ }) => {
+                const doc = await ctx.docs.get(path);
+                const lines = doc.content.split(/\r?\n/);
+                const start = offset - 1;
+                const end = Math.min(start + limit, lines.length);
+                const body = lines
+                    .slice(start, end)
+                    .map((l, i) => `${start + i + 1}: ${l}`)
+                    .join("\n");
+                const more = end < lines.length ? `\n\n[Showing lines ${start + 1}-${end} of ${lines.length}. Use offset=${end + 1} to read more.]` : "";
+                return `Title: ${doc.title}\nPath: ${path}\nTotal lines: ${lines.length}\nContent:\n\n${body}${more}\n`;
+            },
+        }),
+        get_step_result: tool({
+            description: "Fetch the result produced by an earlier step in the current journey, by its step id. Returns the result as JSON, or a note if the step has not produced a result yet.",
+            inputSchema: z.object({
+                step_id: z.string().describe("The id of the step whose result to fetch (e.g. 'step_brand_questions')."),
+            }),
+            execute: async ({ step_id }) => {
+                const result = await ctx.stepResult(step_id);
+                return result == null ? `No result available for step '${step_id}' yet (it may not have run or completed).` : JSON.stringify(result, null, 2);
+            },
+        }),
+        create_document: tool({
+            description: "Create a new document at the given path.\n\nFor large documents (HTML, reports): include only the opening structure in content (e.g. head/CSS/boilerplate), then call append_document for each section.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Path for the new document, including filename. Extension is optional, defaults to markdown. Example: `/projects/pitch-deck`."),
+                title: z.string().describe("The title of the document."),
+                content: z
+                    .string()
+                    .default("")
+                    .describe("Initial content. For large documents, put only the opening structure here (e.g. HTML head + CSS), then use append_document for each section."),
+            }),
+            execute: async ({ path, title, content }) => {
+                await ctx.docs.create({ path, title, content });
+                return `Document ${path} created in workspace ${ctx.workspaceId}`;
+            },
+        }),
+        write_document: tool({
+            description: `Overwrite a document's entire content. Max ~${MAX_LINES_PER_WRITE} lines.\n\nONLY use for small documents. For anything larger, use create_document + append_document.\nFor targeted changes, prefer edit_document or insert_in_document instead.`,
+            inputSchema: z.object({
+                path: z.string().describe("Path to the document to overwrite."),
+                content: z.string().default("").describe("Full replacement content. Must be under ~200 lines."),
+            }),
+            execute: async ({ path, content }) => {
+                if (!content)
+                    return "FAILED: content was empty (likely truncated — document too large for one call). Do NOT retry. Use create_document for the skeleton, then append_document for each section.";
+                const n = content.split("\n").length;
+                if (n > MAX_LINES_PER_WRITE)
+                    return `FAILED: content is ${n} lines (max ${MAX_LINES_PER_WRITE}). Split into create_document + multiple append_document calls.`;
+                await ctx.docs.replace(path, content);
+                return `Document ${path} updated (${n} lines)`;
+            },
+        }),
+        append_document: tool({
+            description: "Append content to the end of an existing document.\n\nUse this for building large documents incrementally:\n1. create_document with opening structure\n2. append_document for each section\nKeep each append under ~300 lines.",
+            inputSchema: z.object({
+                path: z.string().describe("Path of the document to append to."),
+                content: z.string().describe("Content to append to the end of the document."),
+            }),
+            execute: async ({ path, content }) => {
+                await ctx.docs.append(path, content);
+                return `Content appended to ${path}`;
+            },
+        }),
+        edit_document: tool({
+            description: "Find and replace exact text in a document.\n\nUsage:\n- You MUST read_document or grep_document first to see the exact text.\n- old_str must match exactly (whitespace, indentation, line breaks).\n- old_str must be unique in the document. Include surrounding lines if needed, or set replace_all to change every occurrence.\n- Do NOT include line number prefixes (e.g. `42: `) in old_str/new_str.",
+            inputSchema: z.object({
+                path: z.string().describe("Path to the document to modify."),
+                old_str: z.string().describe("Exact text to find and replace. Must match uniquely. Include surrounding lines for context if needed."),
+                new_str: z.string().describe("Replacement text. Must differ from old_str."),
+                replace_all: z.boolean().default(false).describe("Replace every occurrence instead of requiring a unique match."),
+            }),
+            execute: async ({ path, old_str, new_str, replace_all }) => {
+                try {
+                    const n = await ctx.docs.edit(path, old_str, new_str, replace_all);
+                    return `Document ${path} updated successfully (${n} replacement${n !== 1 ? "s" : ""})`;
+                }
+                catch (e) {
+                    throw new Error(`Failed to edit document ${path}: ${e instanceof Error ? e.message : e}. If old_str was not found, re-read the document with read_document to get its current content; if the match was ambiguous, include more surrounding context or set replace_all.`);
+                }
+            },
+        }),
+        insert_in_document: tool({
+            description: "Insert content at a specific line number without removing existing content.\n\nUsage:\n- Use read_document or grep_document first to find the right line number.\n- Content is inserted BEFORE the specified line.\n- Use line=0 to insert at the very beginning.\n- Prefer this over edit_document when adding new sections between existing ones.",
+            inputSchema: z.object({
+                path: z.string().describe("Path to the document to insert into."),
+                line: z
+                    .number()
+                    .int()
+                    .describe("Line number to insert BEFORE (1-indexed). Use 0 to insert at the very beginning. Use a line number beyond the end to append."),
+                content: z.string().describe("Content to insert at the specified line."),
+            }),
+            execute: async ({ path, line, content }) => {
+                const doc = await ctx.docs.get(path, "editing");
+                await ctx.docs.replace(path, insertAt(doc.content, line, content));
+                const n = (content.endsWith("\n") ? content : `${content}\n`).split("\n").length - 1;
+                return `Inserted ${n} line(s) at line ${line} in ${path}`;
+            },
+        }),
+        send_message: tool({
+            description: "Send a message to a channel. Uses the current channel if channel_id is omitted.",
+            inputSchema: z.object({
+                message: z.string().describe("The message to send."),
+                channel_id: z.string().optional().describe("The id of the channel."),
+            }),
+            execute: async ({ message, channel_id }) => {
+                const sent = await ctx.send(message, channel_id ? { channelId: channel_id } : {});
+                return `Message delivered to channel ${sent.channel_id} in workspace ${ctx.workspaceId}`;
+            },
+        }),
+        set_plan: tool({
+            description: "Author or overwrite this message thread's ENTIRE plan (a markdown checklist) in one call.\n\nUse this only to write the initial plan or restructure it wholesale. For everyday edits — checking items off or adding one — use complete_plan_item / add_plan_item instead, which are cheaper and won't clobber concurrent changes.",
+            inputSchema: z.object({
+                plan: z
+                    .string()
+                    .describe("The full plan as a markdown checklist, e.g. `- [x] research\n- [ ] draft`. This REPLACES the existing plan, so include every item, not just the changed ones. Use this to author the initial plan; prefer complete_plan_item / add_plan_item for incremental edits."),
+                channel_id: z.string().optional().describe("The id of the channel. Defaults to the current channel."),
+            }),
+            execute: async ({ plan, channel_id }) => {
+                const ch = await ctx.plan.set(plan, channel_id ?? ctx.channelId);
+                return planStatus(ch.id, ch.plan_completed);
+            },
+        }),
+        complete_plan_item: tool({
+            description: "Check off one item in this message thread's plan as you finish it.\n\nUsage:\n- The current plan (a markdown checklist) is in your instructions.\n- Pass the item's exact label text — just that one item, not the whole plan.\n- If the text matches no item or several, you'll get an error; retry with more of the item's wording.\n- The thread is complete once every item is checked.",
+            inputSchema: z.object({
+                item: z
+                    .string()
+                    .describe("The exact label text of the checklist item to check off (the words after the `[ ]`), as shown in the current plan in your instructions. Matched ignoring case and extra spaces; it must be unambiguous."),
+                channel_id: z.string().optional().describe("The id of the channel. Defaults to the current channel."),
+            }),
+            execute: async ({ item, channel_id }) => {
+                try {
+                    const ch = await ctx.plan.complete(item, channel_id ?? ctx.channelId);
+                    return planStatus(ch.id, ch.plan_completed);
+                }
+                catch (e) {
+                    throw new Error(`Could not complete '${item}': ${e instanceof Error ? e.message : e}. Check the current plan and pass the item's exact wording.`);
+                }
+            },
+        }),
+        add_plan_item: tool({
+            description: "Append a new unchecked item to this message thread's plan.\n\nUse this to record a step you've discovered; pass just the new item's text, not the whole plan.",
+            inputSchema: z.object({
+                item: z.string().describe("The text of the new unchecked checklist item to append."),
+                channel_id: z.string().optional().describe("The id of the channel. Defaults to the current channel."),
+            }),
+            execute: async ({ item, channel_id }) => {
+                const ch = await ctx.plan.add(item, channel_id ?? ctx.channelId);
+                return planStatus(ch.id, ch.plan_completed);
+            },
+        }),
+    };
+    for (const name of opts.exclude ?? [])
+        delete tools[name];
+    if (opts.delegation === false)
+        return tools;
+    // Without the lookup the chat still has every other tool, so don't fail it.
+    const agents = await ctx.client.workspaces.agents(ctx.workspaceId).catch((e) => {
+        console.warn("dana4: listing agents failed; no delegation tools:", e instanceof Error ? e.message : e);
+        return [];
+    });
+    for (const agent of agents) {
+        for (const cap of agent.capabilities) {
+            // Providers cap tool names at 64 chars; sanitizing can make two equal.
+            const base = `${agent.username}__${cap.key}`.replace(/[^A-Za-z0-9_-]/g, "_");
+            let name = base.slice(0, 64);
+            for (let i = 2; name in tools; i++)
+                name = `${base.slice(0, 63 - String(i).length)}_${i}`;
+            tools[name] = tool({
+                description: cap.description || `Trigger \`${cap.key}\` from agent \`${agent.username}\`.`,
+                inputSchema: jsonSchema(capabilityToolSchema(cap.input_schema)),
+                execute: async (inputs) => {
+                    const taskId = await ctx.delegate(agent.username, cap.key, inputs);
+                    return `Queued \`${cap.key}\` (agent \`${agent.username}\`) for workspace \`${ctx.workspaceId}\` as task \`${taskId}\`. It will run asynchronously—tell the user the results will be posted when the task finishes.`;
+                },
+            });
+        }
+    }
+    return tools;
+}
+/** 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 function chatHistory(messages, { me, exclude }) {
+    return messages
+        .filter((m) => (m.category === "default" || m.category === "error") && m.id !== exclude)
+        .sort((a, b) => a.time.created_at.localeCompare(b.time.created_at))
+        .map((m) => {
+        const content = `${m.from_username}: ${m.category === "error" ? "ERROR: " : ""}${m.message}`;
+        return m.from_username === me ? { role: "assistant", content } : { role: "user", content };
+    });
+}
+/** `base` followed by the thread's topics, intent and plan, so the model knows
+ * what the conversation is for. */
+export function threadInstructions(base, thread) {
+    const context = [
+        ...thread.topics.map((t) => `Thread topic: ${t.title} — ${t.summary}`),
+        ...(thread.intent ? [`Thread intent: ${thread.intent}`] : []),
+        ...(thread.plan ? [`Thread plan:\n${thread.plan}`] : []),
+    ].join("\n");
+    return [base, context].filter(Boolean).join("\n\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { enroll } from "./enroll.js";
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: { username: { type: "string" }, bio: { type: "string" }, description: { type: "string" }, url: { type: "string" } },
+});
+const username = values.username;
+if (positionals[0] !== "enroll" || !username) {
+    console.error("usage: dana4 enroll --username <name> [--url https://app.dana4.io] [--bio …] [--description …]");
+    process.exitCode = 2;
+}
+else {
+    const key = await enroll({ ...values, username, url: values.url ?? process.env.DANA4_URL });
+    console.log(`\nApproved. Your API key (shown once), e.g. for DANA4_API_KEY:\n\n${key}`);
+}