@cerebro-labs/agentnava-sdk 0.26.0

package/knowledge-base.js

@@ -0,0 +1,274 @@
+/**
+ * A knowledge base: a named folder of files your agents read.
+ *
+ * A base lives on the WORKSPACE, not on one agent, and an agent configuration
+ * attaches it by key. Two agents attaching the same base is the point: correct a
+ * file once and both see the correction.
+ *
+ * Attached bases are mounted READ-ONLY at `/knowledge/<key>/` when a session
+ * starts, so the agent finds things the way a person would, with `ls`, `grep`
+ * and `cat`. There is no search endpoint and no embedding step, deliberately;
+ * see the NO EMBEDDINGS decision in CLAUDE.md.
+ *
+ * ```ts
+ * const kb = await ws.knowledgeBases.create({ key: 'product-docs', name: 'Docs' });
+ * await kb.files.put('/pricing/tiers.md', bytes, 'text/markdown');
+ * await ws.agents.create({ name: 'Nava', knowledge: ['product-docs'] });
+ * ```
+ */
+export class KnowledgeBase {
+    /** Workspace-unique, and what an agent configuration stores. Not editable:
+     *  renaming it would move every attachment silently. */
+    key;
+    #http;
+    snapshot;
+    constructor(http, key, snapshot) {
+        this.#http = http;
+        this.key = key;
+        if (snapshot)
+            this.snapshot = snapshot;
+    }
+    get base() {
+        return `/v1/knowledge/bases/${encodeURIComponent(this.key)}`;
+    }
+    /** The base's current record: name, description, file count, timestamps. */
+    async get() {
+        const res = await this.#http.get(this.base);
+        this.snapshot = res.base;
+        return res.base;
+    }
+    /** What was known at the time this handle was made, without a round trip.
+     *  Undefined on a handle built from a bare key. */
+    get data() {
+        return this.snapshot;
+    }
+    /** Change the display name or description. The KEY is deliberately not
+     *  changeable here: agent configurations point at it. */
+    async update(fields) {
+        const res = await this.#http.patch(this.base, fields);
+        this.snapshot = res.base;
+        return new KnowledgeBase(this.#http, this.key, res.base);
+    }
+    /**
+     * Delete the base and everything in it.
+     *
+     * REFUSES while any agent still attaches it, with an error naming them. That
+     * refusal is what makes attaching safe: an agent configuration that named a
+     * base at save time would otherwise find it missing the next morning. Call
+     * `attachments()` first if you want to know before you try.
+     */
+    async delete() {
+        await this.#http.delete(this.base);
+    }
+    /**
+     * Which agents read this base.
+     *
+     * The question worth asking before deleting or reorganising one: who breaks?
+     * Read from each agent's current configuration, so it reflects what a session
+     * would actually mount rather than what somebody typed into a draft.
+     */
+    async attachments() {
+        const res = await this.#http.get(`${this.base}/attachments`);
+        return res.agents ?? [];
+    }
+    /**
+     * The files in this base.
+     *
+     * Paths, not flat names, so `/pricing/tiers.md` is a file inside `pricing/`
+     * and the session mount reproduces that shape exactly.
+     */
+    files = {
+        /**
+         * Upload, or REPLACE what is already at this path. A path holds one file;
+         * re-uploading it is a correction, not a second copy.
+         */
+        put: async (path, bytes, contentType) => {
+            const res = await this.#http.request(`${this.base}/files`, {
+                method: 'PUT',
+                bytes,
+                query: { path },
+                ...(contentType && { contentType }),
+            });
+            return res.file;
+        },
+        /** List files, optionally under one prefix. Ordered by path, so a listing
+         *  reads like a directory rather than an upload log. */
+        list: async (prefix = '/') => {
+            const res = await this.#http.get(`${this.base}/files`, {
+                ...(prefix && prefix !== '/' ? { prefix } : {}),
+            });
+            return res.files ?? [];
+        },
+        /**
+         * Read a file's bytes back.
+         *
+         * Exists because until now you could write a file and list it but never
+         * read it, so a script had no way to verify its own upload except by
+         * asking an agent.
+         */
+        get: async (path) => {
+            // `send`, not `request`. `request` ALWAYS parses the body as JSON; the
+            // `raw` flag it used to be passed was declared in the options type and
+            // read by nothing, so this returned a parsed object (or threw "Expected
+            // JSON") and then called `.arrayBuffer()` on it. Every call failed.
+            const res = await this.#http.send(`${this.base}/files/content`, { query: { path } });
+            return new Uint8Array(await res.arrayBuffer());
+        },
+        /**
+         * Read a file back as a string.
+         *
+         * `get` returns bytes, which is right for a PDF and awkward for text: you
+         * decode, change something, and encode again. This is the same file
+         * already decoded, for the case people actually hit, which is reading a
+         * document to check it or to correct it.
+         */
+        text: async (path) => {
+            // Same fix as `get` above, and this one failed in a nastier way: for a
+            // JSON file `request` PARSED it and returned an object, so the failure
+            // was `.text is not a function`; for markdown it threw "Expected JSON
+            // from ...". Two different errors, one cause, neither mentioning it.
+            const res = await this.#http.send(`${this.base}/files/content`, { query: { path } });
+            return res.text();
+        },
+        remove: async (path) => {
+            await this.#http.delete(`${this.base}/files`, { path });
+        },
+        /**
+         * Prepare a file again.
+         *
+         * Preparation happens by itself when a file is uploaded, so this is for
+         * the times it did not work: a scan that came out blank, or a document
+         * that failed before we could read its format and can now.
+         *
+         * It also hands back a file you have edited by hand. Anything you write
+         * yourself is left alone by later runs, and calling this returns it to
+         * being generated.
+         *
+         * Returns immediately. Watch `status` on the file listing to see it
+         * finish.
+         */
+        retry: async (path) => {
+            await this.#http.post(`${this.base}/files/retry`, { path });
+        },
+        /**
+         * Upload a whole directory, preserving its structure under `prefix`.
+         *
+         * Sugar over repeated `put`, but it is the operation people actually
+         * perform, and hand-rolling the walk is where mistakes about path prefixes
+         * get made. Node and Bun only: it reads the local filesystem.
+         *
+         * Sequential on purpose. A knowledge base is uploaded once in a while, not
+         * in a hot path, and a burst of parallel writes against one base is a good
+         * way to meet a rate limit for no gain.
+         */
+        putDirectory: async (dir, options = {}) => {
+            const { readdir, readFile } = await import('node:fs/promises');
+            const { join, relative, posix, sep } = await import('node:path');
+            const prefix = (options.prefix ?? '/').replace(/\/+$/, '');
+            const matches = (rel) => {
+                if (!options.include || options.include.length === 0)
+                    return true;
+                return options.include.some((pattern) => globMatches(pattern, rel));
+            };
+            const walk = async (current) => {
+                const entries = await readdir(current, { withFileTypes: true });
+                const out = [];
+                for (const e of entries) {
+                    const full = join(current, e.name);
+                    if (e.isDirectory())
+                        out.push(...(await walk(full)));
+                    else if (e.isFile())
+                        out.push(full);
+                }
+                return out;
+            };
+            const uploaded = [];
+            for (const full of await walk(dir)) {
+                const rel = relative(dir, full).split(sep).join(posix.sep);
+                if (!matches(rel))
+                    continue;
+                const bytes = await readFile(full);
+                uploaded.push(await this.files.put(`${prefix}/${rel}`, new Uint8Array(bytes), contentTypeFor(rel)));
+            }
+            return uploaded;
+        },
+    };
+    /**
+     * The agent that looks after this base.
+     *
+     * Every base has one. It reads the documents you upload, turns the ones an
+     * agent cannot open into text, and keeps a list of what is in here. That
+     * happens by itself; these methods are for asking it to do something
+     * specific.
+     *
+     * It lives in your own workspace, so its runs cost turns like any other
+     * agent's, and you can see what it did.
+     */
+    librarian = {
+        /**
+         * Work through the whole base: read what has not been read, and rewrite
+         * the list of what is in here.
+         *
+         * The same routine every time, which is the difference between this and
+         * `ask`. Reach for it after uploading a lot at once, or when something
+         * looks out of date.
+         *
+         * RETURNS IMMEDIATELY. The work is queued and runs within about a minute,
+         * because reading a base can take several minutes and no HTTP call should
+         * be held open that long. Watch `status` on the file listing to see it
+         * finish, exactly as with `files.retry`.
+         */
+        organize: async () => {
+            await this.#http.post(`${this.base}/librarian/organize`, {});
+        },
+        /**
+         * Ask the librarian to do something to this base.
+         *
+         *   'split the handbook by chapter'
+         *   'the text from that scan came out garbled, read it again'
+         *   'what is in here about pricing?'
+         *
+         * It can add and change files, which is its job. Your documents are not
+         * sacred to it, so ask it for what you want rather than working around it.
+         */
+        ask: async (text) => {
+            return this.#http.post(`${this.base}/librarian/ask`, { text });
+        },
+    };
+}
+/**
+ * Enough glob for `**\/*.md` and `docs/*.txt`, which is what `include` is for.
+ *
+ * Deliberately not a glob library. Pulling a dependency into a published SDK so
+ * that one convenience method can match filenames is a poor trade, and the
+ * patterns people pass here are simple. Anything more complex: list the files
+ * yourself and call `put`.
+ */
+function globMatches(pattern, path) {
+    const rx = pattern
+        .split('/')
+        .map((seg) => {
+        if (seg === '**')
+            return '.*';
+        return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+    })
+        .join('/')
+        // `**/` should also match zero directories, so `**\/*.md` finds `a.md`.
+        .replace(/\.\*\//g, '(?:.*/)?');
+    return new RegExp(`^${rx}$`).test(path);
+}
+/** A content type from the extension, so uploads are not all octet-stream. */
+function contentTypeFor(path) {
+    const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+    const known = {
+        md: 'text/markdown',
+        markdown: 'text/markdown',
+        txt: 'text/plain',
+        csv: 'text/csv',
+        json: 'application/json',
+        html: 'text/html',
+        pdf: 'application/pdf',
+    };
+    return known[ext] ?? 'application/octet-stream';
+}
+//# sourceMappingURL=knowledge-base.js.map

package/knowledge-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-base.js","sourceRoot":"","sources":["../src/knowledge-base.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Http } from './http.ts';\nimport type { KnowledgeBaseData, KnowledgeFileEntry } from './types.ts';\n\n/**\n * A knowledge base: a named folder of files your agents read.\n *\n * A base lives on the WORKSPACE, not on one agent, and an agent configuration\n * attaches it by key. Two agents attaching the same base is the point: correct a\n * file once and both see the correction.\n *\n * Attached bases are mounted READ-ONLY at `/knowledge/<key>/` when a session\n * starts, so the agent finds things the way a person would, with `ls`, `grep`\n * and `cat`. There is no search endpoint and no embedding step, deliberately;\n * see the NO EMBEDDINGS decision in CLAUDE.md.\n *\n * ```ts\n * const kb = await ws.knowledgeBases.create({ key: 'product-docs', name: 'Docs' });\n * await kb.files.put('/pricing/tiers.md', bytes, 'text/markdown');\n * await ws.agents.create({ name: 'Nava', knowledge: ['product-docs'] });\n * ```\n */\nexport class KnowledgeBase {\n\t/** Workspace-unique, and what an agent configuration stores. Not editable:\n\t *  renaming it would move every attachment silently. */\n\treadonly key: string;\n\n\treadonly #http: Http;\n\tprivate snapshot?: KnowledgeBaseData;\n\n\tconstructor(http: Http, key: string, snapshot?: KnowledgeBaseData) {\n\t\tthis.#http = http;\n\t\tthis.key = key;\n\t\tif (snapshot) this.snapshot = snapshot;\n\t}\n\n\tprivate get base(): string {\n\t\treturn `/v1/knowledge/bases/${encodeURIComponent(this.key)}`;\n\t}\n\n\t/** The base's current record: name, description, file count, timestamps. */\n\tasync get(): Promise<KnowledgeBaseData> {\n\t\tconst res = await this.#http.get<{ base: KnowledgeBaseData }>(this.base);\n\t\tthis.snapshot = res.base;\n\t\treturn res.base;\n\t}\n\n\t/** What was known at the time this handle was made, without a round trip.\n\t *  Undefined on a handle built from a bare key. */\n\tget data(): KnowledgeBaseData | undefined {\n\t\treturn this.snapshot;\n\t}\n\n\t/** Change the display name or description. The KEY is deliberately not\n\t *  changeable here: agent configurations point at it. */\n\tasync update(fields: { name?: string; description?: string }): Promise<KnowledgeBase> {\n\t\tconst res = await this.#http.patch<{ base: KnowledgeBaseData }>(this.base, fields);\n\t\tthis.snapshot = res.base;\n\t\treturn new KnowledgeBase(this.#http, this.key, res.base);\n\t}\n\n\t/**\n\t * Delete the base and everything in it.\n\t *\n\t * REFUSES while any agent still attaches it, with an error naming them. That\n\t * refusal is what makes attaching safe: an agent configuration that named a\n\t * base at save time would otherwise find it missing the next morning. Call\n\t * `attachments()` first if you want to know before you try.\n\t */\n\tasync delete(): Promise<void> {\n\t\tawait this.#http.delete(this.base);\n\t}\n\n\t/**\n\t * Which agents read this base.\n\t *\n\t * The question worth asking before deleting or reorganising one: who breaks?\n\t * Read from each agent's current configuration, so it reflects what a session\n\t * would actually mount rather than what somebody typed into a draft.\n\t */\n\tasync attachments(): Promise<{ agentId: string; agentKey?: string; name?: string }[]> {\n\t\tconst res = await this.#http.get<{\n\t\t\tagents: { agentId: string; agentKey?: string; name?: string }[];\n\t\t}>(`${this.base}/attachments`);\n\t\treturn res.agents ?? [];\n\t}\n\n\t/**\n\t * The files in this base.\n\t *\n\t * Paths, not flat names, so `/pricing/tiers.md` is a file inside `pricing/`\n\t * and the session mount reproduces that shape exactly.\n\t */\n\treadonly files = {\n\t\t/**\n\t\t * Upload, or REPLACE what is already at this path. A path holds one file;\n\t\t * re-uploading it is a correction, not a second copy.\n\t\t */\n\t\tput: async (\n\t\t\tpath: string,\n\t\t\tbytes: Uint8Array | ArrayBuffer,\n\t\t\tcontentType?: string,\n\t\t): Promise<KnowledgeFileEntry> => {\n\t\t\tconst res = await this.#http.request<{ file: KnowledgeFileEntry }>(`${this.base}/files`, {\n\t\t\t\tmethod: 'PUT',\n\t\t\t\tbytes,\n\t\t\t\tquery: { path },\n\t\t\t\t...(contentType && { contentType }),\n\t\t\t});\n\t\t\treturn res.file;\n\t\t},\n\n\t\t/** List files, optionally under one prefix. Ordered by path, so a listing\n\t\t *  reads like a directory rather than an upload log. */\n\t\tlist: async (prefix = '/'): Promise<KnowledgeFileEntry[]> => {\n\t\t\tconst res = await this.#http.get<{ files: KnowledgeFileEntry[] }>(`${this.base}/files`, {\n\t\t\t\t...(prefix && prefix !== '/' ? { prefix } : {}),\n\t\t\t});\n\t\t\treturn res.files ?? [];\n\t\t},\n\n\t\t/**\n\t\t * Read a file's bytes back.\n\t\t *\n\t\t * Exists because until now you could write a file and list it but never\n\t\t * read it, so a script had no way to verify its own upload except by\n\t\t * asking an agent.\n\t\t */\n\t\tget: async (path: string): Promise<Uint8Array> => {\n\t\t\t// `send`, not `request`. `request` ALWAYS parses the body as JSON; the\n\t\t\t// `raw` flag it used to be passed was declared in the options type and\n\t\t\t// read by nothing, so this returned a parsed object (or threw \"Expected\n\t\t\t// JSON\") and then called `.arrayBuffer()` on it. Every call failed.\n\t\t\tconst res = await this.#http.send(`${this.base}/files/content`, { query: { path } });\n\t\t\treturn new Uint8Array(await res.arrayBuffer());\n\t\t},\n\n\t\t/**\n\t\t * Read a file back as a string.\n\t\t *\n\t\t * `get` returns bytes, which is right for a PDF and awkward for text: you\n\t\t * decode, change something, and encode again. This is the same file\n\t\t * already decoded, for the case people actually hit, which is reading a\n\t\t * document to check it or to correct it.\n\t\t */\n\t\ttext: async (path: string): Promise<string> => {\n\t\t\t// Same fix as `get` above, and this one failed in a nastier way: for a\n\t\t\t// JSON file `request` PARSED it and returned an object, so the failure\n\t\t\t// was `.text is not a function`; for markdown it threw \"Expected JSON\n\t\t\t// from ...\". Two different errors, one cause, neither mentioning it.\n\t\t\tconst res = await this.#http.send(`${this.base}/files/content`, { query: { path } });\n\t\t\treturn res.text();\n\t\t},\n\n\t\tremove: async (path: string): Promise<void> => {\n\t\t\tawait this.#http.delete(`${this.base}/files`, { path });\n\t\t},\n\n\t\t/**\n\t\t * Prepare a file again.\n\t\t *\n\t\t * Preparation happens by itself when a file is uploaded, so this is for\n\t\t * the times it did not work: a scan that came out blank, or a document\n\t\t * that failed before we could read its format and can now.\n\t\t *\n\t\t * It also hands back a file you have edited by hand. Anything you write\n\t\t * yourself is left alone by later runs, and calling this returns it to\n\t\t * being generated.\n\t\t *\n\t\t * Returns immediately. Watch `status` on the file listing to see it\n\t\t * finish.\n\t\t */\n\t\tretry: async (path: string): Promise<void> => {\n\t\t\tawait this.#http.post(`${this.base}/files/retry`, { path });\n\t\t},\n\n\t\t/**\n\t\t * Upload a whole directory, preserving its structure under `prefix`.\n\t\t *\n\t\t * Sugar over repeated `put`, but it is the operation people actually\n\t\t * perform, and hand-rolling the walk is where mistakes about path prefixes\n\t\t * get made. Node and Bun only: it reads the local filesystem.\n\t\t *\n\t\t * Sequential on purpose. A knowledge base is uploaded once in a while, not\n\t\t * in a hot path, and a burst of parallel writes against one base is a good\n\t\t * way to meet a rate limit for no gain.\n\t\t */\n\t\tputDirectory: async (\n\t\t\tdir: string,\n\t\t\toptions: { prefix?: string; include?: string[] } = {},\n\t\t): Promise<KnowledgeFileEntry[]> => {\n\t\t\tconst { readdir, readFile } = await import('node:fs/promises');\n\t\t\tconst { join, relative, posix, sep } = await import('node:path');\n\n\t\t\tconst prefix = (options.prefix ?? '/').replace(/\\/+$/, '');\n\t\t\tconst matches = (rel: string): boolean => {\n\t\t\t\tif (!options.include || options.include.length === 0) return true;\n\t\t\t\treturn options.include.some((pattern) => globMatches(pattern, rel));\n\t\t\t};\n\n\t\t\tconst walk = async (current: string): Promise<string[]> => {\n\t\t\t\tconst entries = await readdir(current, { withFileTypes: true });\n\t\t\t\tconst out: string[] = [];\n\t\t\t\tfor (const e of entries) {\n\t\t\t\t\tconst full = join(current, e.name);\n\t\t\t\t\tif (e.isDirectory()) out.push(...(await walk(full)));\n\t\t\t\t\telse if (e.isFile()) out.push(full);\n\t\t\t\t}\n\t\t\t\treturn out;\n\t\t\t};\n\n\t\t\tconst uploaded: KnowledgeFileEntry[] = [];\n\t\t\tfor (const full of await walk(dir)) {\n\t\t\t\tconst rel = relative(dir, full).split(sep).join(posix.sep);\n\t\t\t\tif (!matches(rel)) continue;\n\t\t\t\tconst bytes = await readFile(full);\n\t\t\t\tuploaded.push(\n\t\t\t\t\tawait this.files.put(\n\t\t\t\t\t\t`${prefix}/${rel}`,\n\t\t\t\t\t\tnew Uint8Array(bytes),\n\t\t\t\t\t\tcontentTypeFor(rel),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn uploaded;\n\t\t},\n\t};\n\n\t/**\n\t * The agent that looks after this base.\n\t *\n\t * Every base has one. It reads the documents you upload, turns the ones an\n\t * agent cannot open into text, and keeps a list of what is in here. That\n\t * happens by itself; these methods are for asking it to do something\n\t * specific.\n\t *\n\t * It lives in your own workspace, so its runs cost turns like any other\n\t * agent's, and you can see what it did.\n\t */\n\treadonly librarian = {\n\t\t/**\n\t\t * Work through the whole base: read what has not been read, and rewrite\n\t\t * the list of what is in here.\n\t\t *\n\t\t * The same routine every time, which is the difference between this and\n\t\t * `ask`. Reach for it after uploading a lot at once, or when something\n\t\t * looks out of date.\n\t\t *\n\t\t * RETURNS IMMEDIATELY. The work is queued and runs within about a minute,\n\t\t * because reading a base can take several minutes and no HTTP call should\n\t\t * be held open that long. Watch `status` on the file listing to see it\n\t\t * finish, exactly as with `files.retry`.\n\t\t */\n\t\torganize: async (): Promise<void> => {\n\t\t\tawait this.#http.post(`${this.base}/librarian/organize`, {});\n\t\t},\n\n\t\t/**\n\t\t * Ask the librarian to do something to this base.\n\t\t *\n\t\t *   'split the handbook by chapter'\n\t\t *   'the text from that scan came out garbled, read it again'\n\t\t *   'what is in here about pricing?'\n\t\t *\n\t\t * It can add and change files, which is its job. Your documents are not\n\t\t * sacred to it, so ask it for what you want rather than working around it.\n\t\t */\n\t\task: async (text: string): Promise<{ reply: string }> => {\n\t\t\treturn this.#http.post<{ reply: string }>(`${this.base}/librarian/ask`, { text });\n\t\t},\n\t};\n}\n\n/**\n * Enough glob for `**\\/*.md` and `docs/*.txt`, which is what `include` is for.\n *\n * Deliberately not a glob library. Pulling a dependency into a published SDK so\n * that one convenience method can match filenames is a poor trade, and the\n * patterns people pass here are simple. Anything more complex: list the files\n * yourself and call `put`.\n */\nfunction globMatches(pattern: string, path: string): boolean {\n\tconst rx = pattern\n\t\t.split('/')\n\t\t.map((seg) => {\n\t\t\tif (seg === '**') return '.*';\n\t\t\treturn seg.replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&').replace(/\\*/g, '[^/]*');\n\t\t})\n\t\t.join('/')\n\t\t// `**/` should also match zero directories, so `**\\/*.md` finds `a.md`.\n\t\t.replace(/\\.\\*\\//g, '(?:.*/)?');\n\treturn new RegExp(`^${rx}$`).test(path);\n}\n\n/** A content type from the extension, so uploads are not all octet-stream. */\nfunction contentTypeFor(path: string): string {\n\tconst ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();\n\tconst known: Record<string, string> = {\n\t\tmd: 'text/markdown',\n\t\tmarkdown: 'text/markdown',\n\t\ttxt: 'text/plain',\n\t\tcsv: 'text/csv',\n\t\tjson: 'application/json',\n\t\thtml: 'text/html',\n\t\tpdf: 'application/pdf',\n\t};\n\treturn known[ext] ?? 'application/octet-stream';\n}\n"]}

package/load-agent-dir.d.ts

@@ -0,0 +1,17 @@
+import type { Filesystem, SpecInput } from './types.ts';
+type AgentRole = string;
+type SpecSandbox = Filesystem;
+type SpecToolGroup = string;
+export interface LoadAgentDirOptions {
+    /** Dev-chosen, stable key, required. Used by the backend to upsert this spec. */
+    key: string;
+    /** The role this agent plays. Default `'freelancer'` is applied server-side
+     *  when omitted. See {@link AgentRole} for the full vocabulary. */
+    role?: AgentRole;
+    /** Platform tool groups to grant. Overrides `agent.json`. */
+    tools?: SpecToolGroup[];
+    /** Filesystem for this agent's turns. Overrides `agent.json`. */
+    sandbox?: SpecSandbox;
+}
+export declare function loadAgentDir(path: string, opts: LoadAgentDirOptions): SpecInput;
+export {};

package/load-agent-dir.js

@@ -0,0 +1,192 @@
+// `loadAgentDir` reads a Claude-Code-style folder and returns a SpecInput
+// suitable for `an.specs.push(...)`. Layout it expects:
+//
+//   <path>/
+//   ├── AGENT.md                        # required: core instructions (CLAUDE.md equivalent)
+//   ├── skills/<name>/SKILL.md          # optional, repeated
+//   ├── subagents/<name>.md             # optional, repeated (advanced)
+//   ├── workflows/<name>.md             # optional, repeated
+//   ├── commands/<name>.md              # IGNORED (warned): specs carry no commands
+//   ├── http-tools.json                 # optional, declarative HTTP tool array
+//   └── agent.json                      # optional, capabilities (tools, sandbox, role)
+//
+// Files inside `skills/` use the Claude Code convention: one folder per skill,
+// containing `SKILL.md` with YAML frontmatter. The folder name is the skill name.
+// `subagents/` and `workflows/` are flat directories of `<name>.md`. A
+// `commands/` directory is ignored with a warning: specs no longer carry them.
+//
+// `agent.json` is what makes a folder self-describing: it carries the spec-level
+// capabilities (`tools`, `sandbox`, `role`) alongside the markdown, so an agent
+// directory can be copied between workspaces and still be the same agent. Values
+// passed in `opts` win over the file, so a caller can still override in code.
+//
+// Knowledge base files are NOT loaded by this helper. Use `an.knowledge.upload`
+// for those. Everything else in the bundle is markdown.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export function loadAgentDir(path, opts) {
+    if (!opts.key) {
+        throw new Error('[loadAgentDir] opts.key is required');
+    }
+    if (!existsSync(path) || !statSync(path).isDirectory()) {
+        throw new Error(`[loadAgentDir] not a directory: ${path}`);
+    }
+    const agentMdPath = join(path, 'AGENT.md');
+    if (!existsSync(agentMdPath)) {
+        throw new Error(`[loadAgentDir] missing required file: ${agentMdPath}. ` +
+            `Every spec needs an AGENT.md (the CLAUDE.md equivalent: core instructions).`);
+    }
+    const instructions = readFileSync(agentMdPath, 'utf8');
+    const skills = loadSkillsDir(join(path, 'skills'));
+    const subagents = loadFlatMdDir(join(path, 'subagents'));
+    const workflows = loadFlatMdDir(join(path, 'workflows'));
+    // `commands/` is read only to WARN about it. A spec has no commands field any
+    // more: slash commands had one writer (the dedicated-vm translator) and no
+    // reader on the default runtime.
+    //
+    // Deliberately not folded into workflows, which would be the tempting
+    // one-liner. A Claude Code slash command is invoked BY A PERSON; a workflow is
+    // invoked by the model whenever it looks relevant. Folding them would make
+    // every /command fire unbidden, which is a behaviour change disguised as a
+    // migration. Warned rather than dropped in silence, and rather than thrown,
+    // so an existing agent directory still loads.
+    const commands = loadFlatMdDir(join(path, 'commands'));
+    if (commands.length > 0) {
+        console.warn(`[loadAgentDir] ignoring ${commands.length} file(s) in commands/: agent specs no longer ` +
+            'carry slash commands. Move any that should run automatically into workflows/.');
+    }
+    const out = { key: opts.key, instructions };
+    if (skills.length > 0)
+        out.skills = skills;
+    if (subagents.length > 0)
+        out.subagents = subagents;
+    if (workflows.length > 0)
+        out.workflows = workflows;
+    const httpTools = loadHttpTools(join(path, 'http-tools.json'));
+    if (httpTools && httpTools.length > 0)
+        out.httpTools = httpTools;
+    const widgets = loadWidgets(join(path, 'widgets.json'));
+    if (widgets && widgets.length > 0)
+        out.widgets = widgets;
+    const mcpServers = loadMcpServers(join(path, 'mcp-servers.json'));
+    if (mcpServers && mcpServers.length > 0)
+        out.mcpServers = mcpServers;
+    const manifest = loadManifest(join(path, 'agent.json'));
+    const tools = opts.tools ?? manifest.tools;
+    if (tools && tools.length > 0)
+        out.tools = tools;
+    const sandbox = opts.sandbox ?? manifest.sandbox;
+    if (sandbox)
+        out.sandbox = sandbox;
+    const role = opts.role ?? manifest.role;
+    if (role)
+        out.role = role;
+    return out;
+}
+/** agent.json, optional. Absent is the common case and means "all defaults". */
+function loadManifest(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return {};
+    const raw = readFileSync(filePath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`[loadAgentDir] agent.json: invalid JSON (${e.message})`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('[loadAgentDir] agent.json: must be an object');
+    }
+    const m = parsed;
+    if (m.tools !== undefined && !Array.isArray(m.tools)) {
+        throw new Error('[loadAgentDir] agent.json: "tools" must be an array');
+    }
+    if (m.sandbox !== undefined && m.sandbox !== 'drive' && m.sandbox !== 'none') {
+        throw new Error(`[loadAgentDir] agent.json: "sandbox" must be 'drive' or 'none'`);
+    }
+    // Group names are NOT validated here on purpose: the platform is the
+    // authority on which groups exist and rejects unknown ones at push time with
+    // the current list, so the SDK never goes stale against a newer platform.
+    return m;
+}
+function loadHttpTools(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return undefined;
+    const raw = readFileSync(filePath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`[loadAgentDir] http-tools.json: invalid JSON (${e.message})`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('[loadAgentDir] http-tools.json: must be an array of tool defs');
+    }
+    return parsed;
+}
+function loadWidgets(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return undefined;
+    const raw = readFileSync(filePath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`[loadAgentDir] widgets.json: invalid JSON (${e.message})`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('[loadAgentDir] widgets.json: must be an array of widget defs');
+    }
+    return parsed;
+}
+function loadMcpServers(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return undefined;
+    const raw = readFileSync(filePath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`[loadAgentDir] mcp-servers.json: invalid JSON (${e.message})`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('[loadAgentDir] mcp-servers.json: must be an array of MCP server defs');
+    }
+    return parsed;
+}
+/** skills/<name>/SKILL.md: name comes from the directory. */
+function loadSkillsDir(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir).sort()) {
+        if (name.startsWith('.'))
+            continue;
+        const skillPath = join(dir, name, 'SKILL.md');
+        if (existsSync(skillPath) && statSync(skillPath).isFile()) {
+            out.push({ name, content: readFileSync(skillPath, 'utf8') });
+        }
+    }
+    return out;
+}
+/** subagents/, workflows/: flat directories of <name>.md. */
+function loadFlatMdDir(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    const out = [];
+    for (const file of readdirSync(dir).sort()) {
+        if (!file.endsWith('.md') || file.startsWith('.'))
+            continue;
+        const filePath = join(dir, file);
+        if (!statSync(filePath).isFile())
+            continue;
+        const name = file.replace(/\.md$/, '');
+        out.push({ name, content: readFileSync(filePath, 'utf8') });
+    }
+    return out;
+}
+//# sourceMappingURL=load-agent-dir.js.map

package/load-agent-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-agent-dir.js","sourceRoot":"","sources":["../src/load-agent-dir.ts"],"names":[],"mappings":"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","sourcesContent":["// `loadAgentDir` reads a Claude-Code-style folder and returns a SpecInput\n// suitable for `an.specs.push(...)`. Layout it expects:\n//\n//   <path>/\n//   ├── AGENT.md                        # required: core instructions (CLAUDE.md equivalent)\n//   ├── skills/<name>/SKILL.md          # optional, repeated\n//   ├── subagents/<name>.md             # optional, repeated (advanced)\n//   ├── workflows/<name>.md             # optional, repeated\n//   ├── commands/<name>.md              # IGNORED (warned): specs carry no commands\n//   ├── http-tools.json                 # optional, declarative HTTP tool array\n//   └── agent.json                      # optional, capabilities (tools, sandbox, role)\n//\n// Files inside `skills/` use the Claude Code convention: one folder per skill,\n// containing `SKILL.md` with YAML frontmatter. The folder name is the skill name.\n// `subagents/` and `workflows/` are flat directories of `<name>.md`. A\n// `commands/` directory is ignored with a warning: specs no longer carry them.\n//\n// `agent.json` is what makes a folder self-describing: it carries the spec-level\n// capabilities (`tools`, `sandbox`, `role`) alongside the markdown, so an agent\n// directory can be copied between workspaces and still be the same agent. Values\n// passed in `opts` win over the file, so a caller can still override in code.\n//\n// Knowledge base files are NOT loaded by this helper. Use `an.knowledge.upload`\n// for those. Everything else in the bundle is markdown.\n\nimport { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { Filesystem, HttpTool, McpServer, SpecFile, SpecInput } from './types.ts';\n\n// Local aliases, so the body of this file reads the way it was written against\n// the retired package's names. Nothing outside this module uses them.\ntype HttpToolDef = HttpTool;\ntype McpServerSpec = McpServer;\ntype AgentRole = string;\ntype SpecSandbox = Filesystem;\ntype SpecToolGroup = string;\ntype WidgetDef = { name: string; [k: string]: unknown };\n\nexport interface LoadAgentDirOptions {\n\t/** Dev-chosen, stable key, required. Used by the backend to upsert this spec. */\n\tkey: string;\n\t/** The role this agent plays. Default `'freelancer'` is applied server-side\n\t *  when omitted. See {@link AgentRole} for the full vocabulary. */\n\trole?: AgentRole;\n\t/** Platform tool groups to grant. Overrides `agent.json`. */\n\ttools?: SpecToolGroup[];\n\t/** Filesystem for this agent's turns. Overrides `agent.json`. */\n\tsandbox?: SpecSandbox;\n}\n\n/** The optional `agent.json` manifest, spec-level capabilities that belong with\n *  the markdown rather than in whatever script happens to push it. */\ninterface AgentManifest {\n\ttools?: SpecToolGroup[];\n\tsandbox?: SpecSandbox;\n\trole?: AgentRole;\n}\n\nexport function loadAgentDir(path: string, opts: LoadAgentDirOptions): SpecInput {\n\tif (!opts.key) {\n\t\tthrow new Error('[loadAgentDir] opts.key is required');\n\t}\n\tif (!existsSync(path) || !statSync(path).isDirectory()) {\n\t\tthrow new Error(`[loadAgentDir] not a directory: ${path}`);\n\t}\n\n\tconst agentMdPath = join(path, 'AGENT.md');\n\tif (!existsSync(agentMdPath)) {\n\t\tthrow new Error(\n\t\t\t`[loadAgentDir] missing required file: ${agentMdPath}. ` +\n\t\t\t\t`Every spec needs an AGENT.md (the CLAUDE.md equivalent: core instructions).`,\n\t\t);\n\t}\n\tconst instructions = readFileSync(agentMdPath, 'utf8');\n\n\tconst skills = loadSkillsDir(join(path, 'skills'));\n\tconst subagents = loadFlatMdDir(join(path, 'subagents'));\n\tconst workflows = loadFlatMdDir(join(path, 'workflows'));\n\t// `commands/` is read only to WARN about it. A spec has no commands field any\n\t// more: slash commands had one writer (the dedicated-vm translator) and no\n\t// reader on the default runtime.\n\t//\n\t// Deliberately not folded into workflows, which would be the tempting\n\t// one-liner. A Claude Code slash command is invoked BY A PERSON; a workflow is\n\t// invoked by the model whenever it looks relevant. Folding them would make\n\t// every /command fire unbidden, which is a behaviour change disguised as a\n\t// migration. Warned rather than dropped in silence, and rather than thrown,\n\t// so an existing agent directory still loads.\n\tconst commands = loadFlatMdDir(join(path, 'commands'));\n\tif (commands.length > 0) {\n\t\tconsole.warn(\n\t\t\t`[loadAgentDir] ignoring ${commands.length} file(s) in commands/: agent specs no longer ` +\n\t\t\t\t'carry slash commands. Move any that should run automatically into workflows/.',\n\t\t);\n\t}\n\n\tconst out: SpecInput = { key: opts.key, instructions };\n\tif (skills.length > 0) out.skills = skills;\n\tif (subagents.length > 0) out.subagents = subagents;\n\tif (workflows.length > 0) out.workflows = workflows;\n\tconst httpTools = loadHttpTools(join(path, 'http-tools.json'));\n\tif (httpTools && httpTools.length > 0) out.httpTools = httpTools;\n\tconst widgets = loadWidgets(join(path, 'widgets.json'));\n\tif (widgets && widgets.length > 0) out.widgets = widgets;\n\tconst mcpServers = loadMcpServers(join(path, 'mcp-servers.json'));\n\tif (mcpServers && mcpServers.length > 0) out.mcpServers = mcpServers;\n\n\tconst manifest = loadManifest(join(path, 'agent.json'));\n\tconst tools = opts.tools ?? manifest.tools;\n\tif (tools && tools.length > 0) out.tools = tools;\n\tconst sandbox = opts.sandbox ?? manifest.sandbox;\n\tif (sandbox) out.sandbox = sandbox;\n\tconst role = opts.role ?? manifest.role;\n\tif (role) out.role = role;\n\treturn out;\n}\n\n/** agent.json, optional. Absent is the common case and means \"all defaults\". */\nfunction loadManifest(filePath: string): AgentManifest {\n\tif (!existsSync(filePath) || !statSync(filePath).isFile()) return {};\n\tconst raw = readFileSync(filePath, 'utf8');\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (e) {\n\t\tthrow new Error(`[loadAgentDir] agent.json: invalid JSON (${(e as Error).message})`);\n\t}\n\tif (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n\t\tthrow new Error('[loadAgentDir] agent.json: must be an object');\n\t}\n\tconst m = parsed as Record<string, unknown>;\n\tif (m.tools !== undefined && !Array.isArray(m.tools)) {\n\t\tthrow new Error('[loadAgentDir] agent.json: \"tools\" must be an array');\n\t}\n\tif (m.sandbox !== undefined && m.sandbox !== 'drive' && m.sandbox !== 'none') {\n\t\tthrow new Error(`[loadAgentDir] agent.json: \"sandbox\" must be 'drive' or 'none'`);\n\t}\n\t// Group names are NOT validated here on purpose: the platform is the\n\t// authority on which groups exist and rejects unknown ones at push time with\n\t// the current list, so the SDK never goes stale against a newer platform.\n\treturn m as AgentManifest;\n}\n\nfunction loadHttpTools(filePath: string): HttpToolDef[] | undefined {\n\tif (!existsSync(filePath) || !statSync(filePath).isFile()) return undefined;\n\tconst raw = readFileSync(filePath, 'utf8');\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (e) {\n\t\tthrow new Error(`[loadAgentDir] http-tools.json: invalid JSON (${(e as Error).message})`);\n\t}\n\tif (!Array.isArray(parsed)) {\n\t\tthrow new Error('[loadAgentDir] http-tools.json: must be an array of tool defs');\n\t}\n\treturn parsed as HttpToolDef[];\n}\n\nfunction loadWidgets(filePath: string): WidgetDef[] | undefined {\n\tif (!existsSync(filePath) || !statSync(filePath).isFile()) return undefined;\n\tconst raw = readFileSync(filePath, 'utf8');\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (e) {\n\t\tthrow new Error(`[loadAgentDir] widgets.json: invalid JSON (${(e as Error).message})`);\n\t}\n\tif (!Array.isArray(parsed)) {\n\t\tthrow new Error('[loadAgentDir] widgets.json: must be an array of widget defs');\n\t}\n\treturn parsed as WidgetDef[];\n}\n\nfunction loadMcpServers(filePath: string): McpServerSpec[] | undefined {\n\tif (!existsSync(filePath) || !statSync(filePath).isFile()) return undefined;\n\tconst raw = readFileSync(filePath, 'utf8');\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (e) {\n\t\tthrow new Error(`[loadAgentDir] mcp-servers.json: invalid JSON (${(e as Error).message})`);\n\t}\n\tif (!Array.isArray(parsed)) {\n\t\tthrow new Error('[loadAgentDir] mcp-servers.json: must be an array of MCP server defs');\n\t}\n\treturn parsed as McpServerSpec[];\n}\n\n/** skills/<name>/SKILL.md: name comes from the directory. */\nfunction loadSkillsDir(dir: string): SpecFile[] {\n\tif (!existsSync(dir) || !statSync(dir).isDirectory()) return [];\n\tconst out: SpecFile[] = [];\n\tfor (const name of readdirSync(dir).sort()) {\n\t\tif (name.startsWith('.')) continue;\n\t\tconst skillPath = join(dir, name, 'SKILL.md');\n\t\tif (existsSync(skillPath) && statSync(skillPath).isFile()) {\n\t\t\tout.push({ name, content: readFileSync(skillPath, 'utf8') });\n\t\t}\n\t}\n\treturn out;\n}\n\n/** subagents/, workflows/: flat directories of <name>.md. */\nfunction loadFlatMdDir(dir: string): SpecFile[] {\n\tif (!existsSync(dir) || !statSync(dir).isDirectory()) return [];\n\tconst out: SpecFile[] = [];\n\tfor (const file of readdirSync(dir).sort()) {\n\t\tif (!file.endsWith('.md') || file.startsWith('.')) continue;\n\t\tconst filePath = join(dir, file);\n\t\tif (!statSync(filePath).isFile()) continue;\n\t\tconst name = file.replace(/\\.md$/, '');\n\t\tout.push({ name, content: readFileSync(filePath, 'utf8') });\n\t}\n\treturn out;\n}\n"]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cerebro-labs/agentnava-sdk",
+  "version": "0.26.0",
+  "description": "The AgentNava SDK. Configure an agent, start a conversation, and work with it.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cerebro-labs/agentnava.git",
+    "directory": "packages/agentnava-sdk"
+  },
+  "homepage": "https://docs.agentnava.com",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./templates": {
+      "types": "./templates.d.ts",
+      "default": "./templates.js"
+    }
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}