@cerebro-labs/agentnava-sdk 0.26.0

package/workflows.js

@@ -0,0 +1,101 @@
+// Load workflows from a directory of markdown.
+//
+// Workflows are the same shape as a Claude Code SKILL.md, so an existing skills
+// directory loads unchanged: frontmatter `name` and `description`, body is the
+// procedure. `description` maps to `when`, because it is already the one line
+// that says when the thing applies, which is exactly what `when` means.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+/**
+ * Parse one SKILL.md-shaped document.
+ *
+ * Exported because it is the part worth testing: the frontmatter, not the
+ * directory walk.
+ */
+export function parseWorkflow(source, fallbackName) {
+    const match = source.replace(/^/, '').match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/);
+    if (!match) {
+        // No frontmatter: the whole file is the procedure and the filename is the
+        // name. Rejecting it would make the helper useless for the notes people
+        // actually have, and a workflow with no `when` is caught at publish with a
+        // message that says what to add.
+        return { name: fallbackName, when: '', content: source.trim() };
+    }
+    const [, frontmatter = '', body = ''] = match;
+    const fields = {};
+    for (const line of frontmatter.split(/\r?\n/)) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        // Deliberately NOT a YAML parser. These are two scalar fields, and pulling
+        // in a YAML dependency to read them would be the larger mistake. Quotes
+        // are stripped because people write them.
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key)
+            fields[key] = value;
+    }
+    return {
+        name: fields.name || fallbackName,
+        // `description` is Claude Code's spelling of the same idea.
+        when: fields.when || fields.description || '',
+        content: body.trim(),
+    };
+}
+/** Strip the extension and any SKILL.md wrapper directory name. */
+function nameFromPath(fileName) {
+    return fileName.replace(/\.(md|markdown)$/i, '');
+}
+/**
+ * Read every workflow under `dir`.
+ *
+ * Handles both layouts without being told which: a flat directory of
+ * `*.md` files, and Claude Code's `<name>/SKILL.md` directories. Requiring the
+ * caller to say which one they have would be a question they should not have to
+ * answer about their own folder.
+ *
+ * Synchronous, because this runs at configuration time in a script, and an async
+ * version would infect every call site that builds an agent literal.
+ *
+ * NODE AND BUN ONLY. `node:fs` is a static import here, so a browser bundle that
+ * reaches this module will fail at build time rather than at run time. That is
+ * the right trade for a helper that exists to read a folder off disk: in a
+ * browser there is no folder, and the answer is to pass `workflows` directly.
+ * The `fs` parameter exists so this is testable without touching a disk.
+ */
+export function loadWorkflows(dir, fs) {
+    const io = fs ?? { readdirSync, readFileSync, statSync };
+    const out = [];
+    for (const entry of io.readdirSync(dir).sort()) {
+        if (entry.startsWith('.'))
+            continue;
+        const full = `${dir.replace(/\/+$/, '')}/${entry}`;
+        let isDir = false;
+        try {
+            isDir = io.statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            // Claude Code layout: <name>/SKILL.md. The DIRECTORY is the name, which
+            // is why the fallback is `entry` and not 'SKILL'.
+            try {
+                out.push(parseWorkflow(io.readFileSync(`${full}/SKILL.md`, 'utf8'), entry));
+            }
+            catch {
+                // A directory with no SKILL.md is not a workflow. Skipping is right:
+                // people keep other things in these folders.
+            }
+            continue;
+        }
+        if (!/\.(md|markdown)$/i.test(entry))
+            continue;
+        out.push(parseWorkflow(io.readFileSync(full, 'utf8'), nameFromPath(entry)));
+    }
+    return out;
+}
+//# sourceMappingURL=workflows.js.map

package/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"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","sourcesContent":["// Load workflows from a directory of markdown.\n//\n// Workflows are the same shape as a Claude Code SKILL.md, so an existing skills\n// directory loads unchanged: frontmatter `name` and `description`, body is the\n// procedure. `description` maps to `when`, because it is already the one line\n// that says when the thing applies, which is exactly what `when` means.\n\nimport { readdirSync, readFileSync, statSync } from 'node:fs';\n\nimport type { Workflow } from './types.ts';\n\n/** The bits of `node:fs` this needs, so it can be faked in a test and so the\n *  module does not break a browser bundle merely by being imported. */\ninterface FsLike {\n\treaddirSync(dir: string): string[];\n\treadFileSync(path: string, encoding: 'utf8'): string;\n\tstatSync(path: string): { isDirectory(): boolean };\n}\n\n/**\n * Parse one SKILL.md-shaped document.\n *\n * Exported because it is the part worth testing: the frontmatter, not the\n * directory walk.\n */\nexport function parseWorkflow(source: string, fallbackName: string): Workflow {\n\tconst match = source.replace(/^/, '').match(/^---\\s*\\r?\\n([\\s\\S]*?)\\r?\\n---\\s*(?:\\r?\\n|$)([\\s\\S]*)$/);\n\tif (!match) {\n\t\t// No frontmatter: the whole file is the procedure and the filename is the\n\t\t// name. Rejecting it would make the helper useless for the notes people\n\t\t// actually have, and a workflow with no `when` is caught at publish with a\n\t\t// message that says what to add.\n\t\treturn { name: fallbackName, when: '', content: source.trim() };\n\t}\n\n\tconst [, frontmatter = '', body = ''] = match;\n\tconst fields: Record<string, string> = {};\n\tfor (const line of frontmatter.split(/\\r?\\n/)) {\n\t\tconst colon = line.indexOf(':');\n\t\tif (colon === -1) continue;\n\t\tconst key = line.slice(0, colon).trim();\n\t\tlet value = line.slice(colon + 1).trim();\n\t\t// Deliberately NOT a YAML parser. These are two scalar fields, and pulling\n\t\t// in a YAML dependency to read them would be the larger mistake. Quotes\n\t\t// are stripped because people write them.\n\t\tif (\n\t\t\t(value.startsWith('\"') && value.endsWith('\"')) ||\n\t\t\t(value.startsWith(\"'\") && value.endsWith(\"'\"))\n\t\t) {\n\t\t\tvalue = value.slice(1, -1);\n\t\t}\n\t\tif (key) fields[key] = value;\n\t}\n\n\treturn {\n\t\tname: fields.name || fallbackName,\n\t\t// `description` is Claude Code's spelling of the same idea.\n\t\twhen: fields.when || fields.description || '',\n\t\tcontent: body.trim(),\n\t};\n}\n\n/** Strip the extension and any SKILL.md wrapper directory name. */\nfunction nameFromPath(fileName: string): string {\n\treturn fileName.replace(/\\.(md|markdown)$/i, '');\n}\n\n/**\n * Read every workflow under `dir`.\n *\n * Handles both layouts without being told which: a flat directory of\n * `*.md` files, and Claude Code's `<name>/SKILL.md` directories. Requiring the\n * caller to say which one they have would be a question they should not have to\n * answer about their own folder.\n *\n * Synchronous, because this runs at configuration time in a script, and an async\n * version would infect every call site that builds an agent literal.\n *\n * NODE AND BUN ONLY. `node:fs` is a static import here, so a browser bundle that\n * reaches this module will fail at build time rather than at run time. That is\n * the right trade for a helper that exists to read a folder off disk: in a\n * browser there is no folder, and the answer is to pass `workflows` directly.\n * The `fs` parameter exists so this is testable without touching a disk.\n */\nexport function loadWorkflows(dir: string, fs?: FsLike): Workflow[] {\n\tconst io: FsLike = fs ?? { readdirSync, readFileSync, statSync };\n\n\tconst out: Workflow[] = [];\n\tfor (const entry of io.readdirSync(dir).sort()) {\n\t\tif (entry.startsWith('.')) continue;\n\t\tconst full = `${dir.replace(/\\/+$/, '')}/${entry}`;\n\n\t\tlet isDir = false;\n\t\ttry {\n\t\t\tisDir = io.statSync(full).isDirectory();\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (isDir) {\n\t\t\t// Claude Code layout: <name>/SKILL.md. The DIRECTORY is the name, which\n\t\t\t// is why the fallback is `entry` and not 'SKILL'.\n\t\t\ttry {\n\t\t\t\tout.push(parseWorkflow(io.readFileSync(`${full}/SKILL.md`, 'utf8'), entry));\n\t\t\t} catch {\n\t\t\t\t// A directory with no SKILL.md is not a workflow. Skipping is right:\n\t\t\t\t// people keep other things in these folders.\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (!/\\.(md|markdown)$/i.test(entry)) continue;\n\t\tout.push(parseWorkflow(io.readFileSync(full, 'utf8'), nameFromPath(entry)));\n\t}\n\treturn out;\n}\n"]}

package/workspace.d.ts

@@ -0,0 +1,290 @@
+import { Agent } from './agent.ts';
+import { Connection } from './connection.ts';
+import { type ClientOptions } from './http.ts';
+import { Secret } from './secret.ts';
+import { EndUser } from './end-user.ts';
+import { KnowledgeBase } from './knowledge-base.ts';
+import { Project } from './project.ts';
+import type { AgentFields, Credits, ProjectFields, SeatPlan, WorkspaceInfo, WorkspaceMember } from './types.ts';
+/**
+ * Your workspace: the account an API key names.
+ *
+ * ```ts
+ * const ws = AgentNava.getWorkspace();             // reads AGENTNAVA_API_KEY
+ * const agent = await ws.agents.create({ … });
+ * const conversation = await agent.start({ endUserId: null });
+ * console.log(await conversation.ask('Hello'));
+ * ```
+ *
+ * Constructing it makes no request. So do `ws.agent(id)`
+ * and `ws.project(id)`: they hand you something you can call methods on, and the
+ * first request happens when you call one. Fetching an object just to send it a
+ * message would be a round trip for nothing.
+ *
+ * A returned object is not plain JSON. Store the `id`, not the object, and use
+ * `ws.agent(id)` to come back in.
+ */
+export declare class Workspace {
+    #private;
+    constructor(options?: ClientOptions);
+    /** The workspace itself: name, credits. */
+    get(): Promise<WorkspaceInfo>;
+    readonly agents: {
+        /**
+         * Create an agent.
+         *
+         * Supplying an `id` is optional; without one the server mints it. An id
+         * that already exists is a 409 rather than a quiet new version of the
+         * existing agent, so a typo cannot silently rewrite something else. Use
+         * `agent.update()` to publish a version.
+         */
+        create: (fields: AgentFields) => Promise<Agent>;
+        list: () => Promise<Agent[]>;
+    };
+    /**
+     * Secrets: values your agents USE and never see.
+     *
+     * The one way to give an agent an API key. A secret is written once, stored
+     * encrypted, and substituted into an HTTP tool's url, headers or body on the
+     * server at the moment the call goes out, so the key is never in a prompt,
+     * never in a transcript, and never in anything the model could repeat back.
+     * Reference it from a tool as `{{secrets.NAME}}`.
+     *
+     * Scope is the `agentId` argument. Left out, every agent in the workspace can
+     * use it; supplied, only that agent can, and it takes precedence over a
+     * workspace secret of the same name. Prefer the narrow one for anything that
+     * moves money.
+     *
+     * NOTHING READS A VALUE BACK, including you. `list` returns names and
+     * metadata. That is deliberate rather than an omission: a value you can read
+     * is a value that can end up in a log.
+     */
+    readonly secrets: {
+        /** Store a secret. A name that already exists at the same scope is a 409,
+         *  rather than a silent overwrite of a key something else is using. */
+        create: (input: {
+            name: string;
+            value: string;
+            description?: string;
+            agentId?: string;
+            /** One of YOUR end users, stored verbatim. Prefer
+             *  `ws.endUser(id).secrets.create(...)`, which fills this in for you.
+             *
+             *  THIS PARAMETER WAS REMOVED AND IS BACK, and the difference is that
+             *  it now does something. It used to be accepted, written to the
+             *  column, and read by nothing: a credential reached a turn only by
+             *  being ATTACHED, and a secret could not be, because binding one took
+             *  its VALUE and not an id. A parameter that accepts a write, reports
+             *  success and changes nothing an agent can use is a decoy, so it was
+             *  deleted rather than left to teach somebody that per-person secrets
+             *  worked.
+             *
+             *  `conversation.attach(secret)` is the route that was missing. */
+            endUserId?: string;
+        }) => Promise<Secret>;
+        /** Every secret this WORKSPACE holds, values excluded. Pass `agentId` to
+         *  include that agent's own secrets alongside the workspace ones.
+         *
+         *  One of your end users' secrets is NOT in here, deliberately: ask for
+         *  those with `ws.endUser(id).secrets.list()`. A listing that mixed them
+         *  would be a listing you could not act on, since deleting from it would
+         *  reach into somebody's personal credentials. */
+        list: (agentId?: string) => Promise<Secret[]>;
+    };
+    /**
+     * Connections: third-party accounts your agents act through.
+     *
+     * The account is attached in a browser by the person who owns it, so YOU
+     * NEVER HANDLE A TOKEN. `create` returns a url to send them to.
+     *
+     * OWNING AN ACCOUNT GRANTS NOTHING. Creating one records whose it is; a
+     * turn uses it only where it was ATTACHED, and the attach is a line you can
+     * see:
+     *
+     * | owner | created with | reaches a turn when |
+     * |---|---|---|
+     * | workspace | `ws.connections.create({ provider })` | attached |
+     * | agent | `ws.connections.create({ agentId })` | attached |
+     * | **end user** | `ws.connections.create({ endUserId })` | `conversation.attach(c)` or `agent.attach(c)` |
+     * | conversation | `conversation.authorize()` | that one thread |
+     *
+     * The end-user owner is what an application with its own users wants.
+     * Ananya connects Gmail ONCE and the account stays hers across every
+     * conversation, so you never send her through a sign-in again. What you do
+     * per conversation is attach it, which costs one line and makes the grant
+     * readable.
+     *
+     * An earlier version resolved her account automatically from the id on the
+     * conversation. It was wrong even when it picked correctly: nothing in the
+     * code said what the agent could reach.
+     *
+     * THE END-USER ID IS YOURS AND WE NEVER CHECK IT. It is from your database,
+     * not ours, and it is not a workspace member's id. Pass the wrong one and
+     * you file an account under the wrong person, with no error.
+     */
+    readonly connections: {
+        /**
+         * Begin connecting an account, for one of your users or for an agent.
+         *
+         * Returns a url. Send the person there; they sign in, and the account
+         * attaches when they finish. Poll `list` or use
+         * `conversation.waitUntilReady()` to know when.
+         */
+        create: (input: {
+            provider: string;
+            /** One of YOUR end users, from your own database. Omit for a shared
+             *  account. Never a `ws.members()` id: different namespace. */
+            endUserId?: string;
+            agentId?: string;
+        }) => Promise<Connection>;
+        /** What is connected. `endUserId` narrows to one end user's accounts;
+         *  without it you get the shared ones, which is the operator's view. */
+        list: (input?: {
+            endUserId?: string;
+            agentId?: string;
+        }) => Promise<Connection[]>;
+    };
+    /**
+     * Knowledge bases: named folders of files your agents read.
+     *
+     * Called `knowledgeBases`, not `knowledge`, on purpose. `agent.knowledge`
+     * already means one agent's FILES, and a `ws.knowledge.list()` returning
+     * bases rather than files would be the same word meaning two different things
+     * one level apart. The longer name is worth it.
+     */
+    readonly knowledgeBases: {
+        /**
+         * Create a base. The KEY is what agent configurations store, so pick
+         * something readable: `product-docs`, not `kb1`.
+         *
+         * A key already in use is an error rather than a silent overwrite, because
+         * the base it would replace may be one several agents already read from.
+         */
+        create: (fields: {
+            key: string;
+            name?: string;
+            description?: string;
+        }) => Promise<KnowledgeBase>;
+        /** Every base in this workspace. No pagination: bases are few, and a
+         *  workspace with hundreds of them has a naming problem rather than a
+         *  paging one. */
+        list: () => Promise<KnowledgeBase[]>;
+        /** One base, by key. Returns a HANDLE you act through: `kb.files.put(...)`,
+         *  `kb.attachments()`, `kb.delete()`. */
+        get: (key: string) => Promise<KnowledgeBase>;
+    };
+    readonly projects: {
+        create: (fields: ProjectFields) => Promise<Project>;
+        list: () => Promise<Project[]>;
+    };
+    /**
+     * Who is on this workspace, and what each of them may do.
+     *
+     * ```ts
+     * for (const m of await ws.members()) {
+     *   console.log(m.email, m.role);
+     * }
+     * ```
+     */
+    members(): Promise<WorkspaceMember[]>;
+    /**
+     * What credit is left, and roughly how many turns that buys.
+     *
+     * The turn counts are the useful half: a balance in credits is not something
+     * anybody can act on without knowing what a turn costs.
+     *
+     * ```ts
+     * const { credits, standardTurnsRemaining } = await ws.credits();
+     * if (standardTurnsRemaining < 100) await topUpSomehow();
+     * ```
+     */
+    credits(): Promise<Credits>;
+    /**
+     * Which seat plan this workspace is on.
+     *
+     * Seats and credits are separate purchases: this says how many people may
+     * share the account, not how much work they may do. Returns null when the
+     * server cannot say, rather than guessing at the free plan, because "we do
+     * not know" and "you are on the cheapest one" are different answers.
+     */
+    plan(): Promise<SeatPlan | null>;
+    /** Address an agent you already have the id of. No request. */
+    agent(agentId: string): Agent;
+    /** Address a project you already have the id of. No request. */
+    project(projectId: string): Project;
+    /**
+     * One of YOUR end users. No request.
+     *
+     * The object everything about a person hangs off: their connections, their
+     * conversations across every agent. You say who once, here, instead of
+     * threading an `endUserId` through each call and forgetting it in one of
+     * them.
+     *
+     * ```ts
+     * const ananya = ws.endUser(row.userId);
+     * await ananya.connections.create({ provider: 'gmail' });
+     * await ananya.conversations();
+     * ```
+     *
+     * A SCOPE, NOT A RECORD. Every other addresser here points at a row we
+     * store and can list back: `ws.agent(id)`, `ws.project(id)`,
+     * `ws.connection(id)`, `ws.secret(id)`, each with its own
+     * `ws.<plural>.create/list`. This one points at nothing. We do not create
+     * your end users, we cannot list them, and there is no `ws.endUsers`
+     * collection anywhere in this SDK. We only write the id you give us onto
+     * rows we already own.
+     *
+     * So this does not fetch a person. It hands you the same workspace,
+     * narrowed to one of your people. If a `ws.endUsers` ever appears here,
+     * something has started claiming to own them.
+     *
+     * It hangs off the workspace because a an end-user id is MEANINGLESS WITHOUT
+     * ONE: uniqueness is (workspace_id, end_user_id, provider), so two of our
+     * own customers can each have a person called `user_1` without colliding.
+     *
+     * NOT `ws.user()`, and not a workspace member. `ws.members()` lists the
+     * colleagues who share this account, with ids we issued and authenticate.
+     * This takes an id from YOUR database that we store verbatim and never
+     * check. Passing one where the other belongs used to be a call that could
+     * not fail, because there is nothing for an end-user id to fail against.
+     */
+    endUser(endUserId: string): EndUser;
+    /** Address a connection you already have the id of. No request.
+     *
+     *  The sibling of `ws.agent(id)`. A connection belongs to the workspace, not
+     *  to an agent: the same account can be the agent's shared one, one person's
+     *  or one conversation's, and which it is lives on the row rather than in
+     *  where you reached it from. */
+    connection(connectionId: string): Connection;
+    /** Address a secret you already have the id of. No request. */
+    secret(secretId: string): Secret;
+    /** Address a knowledge base you already know the key of. No request.
+     *
+     *  The sibling of `agent()` and `project()`, and it was the
+     *  one missing: reaching a base meant `knowledgeBases.get(key)`, which costs a
+     *  round trip to learn something the caller already knew. Use `get()` when you
+     *  want the base's RECORD; use this when you only want to put a file in it. */
+    knowledgeBase(key: string): KnowledgeBase;
+}
+/**
+ * The way in.
+ *
+ * ```ts
+ * import { AgentNava } from '@cerebro-labs/agentnava-sdk';
+ *
+ * const ws = AgentNava.getWorkspace();          // reads AGENTNAVA_API_KEY
+ * const ws = AgentNava.getWorkspace('ank_...'); // or pass the key
+ * ```
+ *
+ * IT MAKES NO REQUEST. `get` here means "hand me the workspace this key names",
+ * not "go and fetch it"; the first round trip happens on the first method you
+ * call. `ws.get()` is the one that actually reads the record.
+ *
+ * An API key belongs to exactly one workspace, so there is nothing to select
+ * and no workspace argument anywhere in this SDK. This does not CREATE a
+ * workspace either: the key already names one, and creating them is not
+ * something an API key may do (see "the account is read-only").
+ */
+export declare const AgentNava: {
+    getWorkspace(options?: string | ClientOptions): Workspace;
+};