@cerebro-labs/agentnava-sdk 0.26.0

package/types.d.ts

@@ -0,0 +1,485 @@
+export type Grade = 'standard' | 'premium';
+export type Filesystem = 'drive' | 'none';
+/** Where a credential is supplied.
+ *
+ *  'fixed' is set once on the agent and used by every conversation. 'conversation'
+ *  is asked for when a conversation starts, so each user brings their own. The
+ *  two DO NOT substitute for each other: an account connected on the agent does
+ *  not satisfy a declaration scoped 'conversation'. */
+export type Scope = 'fixed' | 'conversation';
+/** WHOSE credential a stored account or value is, which is a different question
+ *  from `Scope` above. `Scope` is what an agent DECLARES it needs; this is who
+ *  a row that exists actually belongs to.
+ *
+ *  'endUser' is one of YOUR end users: the person your application serves,
+ *  never a member of this workspace. The two are separate populations with
+ *  separate id namespaces: see `EndUser`. */
+export type CredentialOwner = 'workspace' | 'agent' | 'endUser' | 'conversation';
+export interface WorkspaceInfo {
+    id: string;
+    name: string;
+    credits: number;
+    createdAt: string;
+}
+/** One procedure the agent follows when its `when` matches what is in front of
+ *  it. `when` is one line and is not optional: it is what the agent reads to
+ *  decide the workflow applies, so a vague one makes a good workflow invisible. */
+export interface Workflow {
+    name: string;
+    when: string;
+    content: string;
+}
+export type Trigger = {
+    kind: 'chat';
+} | {
+    kind: 'schedule';
+    cron: string;
+    timezone?: string;
+    message: string;
+} | {
+    kind: 'interval';
+    seconds: number;
+    maxRuns?: number;
+    message: string;
+} | {
+    kind: 'webhook';
+    message?: string;
+    url?: string;
+};
+/**
+ * What an agent NEEDS, not what it has.
+ *
+ * Named `Connection` until the actual account became an object you hold. Two
+ * different things cannot share one name: this one says "this agent requires
+ * Gmail, supplied per conversation", and says nothing about whether anybody has
+ * connected. `Connection` is the account itself, with tokens behind it.
+ *
+ * The distinction is the one `ConnectionStatus.declared` versus `.connected`
+ * already draws, now in the type names too.
+ */
+export interface ConnectionRequirement {
+    provider: string;
+    scope: Scope;
+    required?: boolean;
+}
+/** What an agent NEEDS, not the stored value. `Secret` is the value. */
+export interface SecretRequirement {
+    name: string;
+    scope: Scope;
+    required?: boolean;
+}
+export interface Parameter {
+    name: string;
+    type: 'string' | 'number' | 'date' | 'choice';
+    required?: boolean;
+    default?: string;
+    choices?: string[];
+}
+export interface McpServer {
+    name: string;
+    url: string;
+    transport?: 'http' | 'sse';
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface HttpToolParam {
+    type: 'string' | 'number' | 'boolean';
+    description?: string;
+    required?: boolean;
+    choices?: (string | number)[];
+}
+export interface HttpTool {
+    name: string;
+    description: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    params?: Record<string, HttpToolParam>;
+    secrets?: string[];
+    timeoutMs?: number;
+}
+export interface AgentData {
+    id: string;
+    name: string;
+    instructions: string;
+    greeting?: string;
+    grade: Grade;
+    filesystem: Filesystem;
+    tools: string[];
+    workflows: Workflow[];
+    connections: ConnectionRequirement[];
+    secrets: SecretRequirement[];
+    parameters: Parameter[];
+    triggers: Trigger[];
+    mcpServers: McpServer[];
+    httpTools: HttpTool[];
+    /** Workspace knowledge bases this agent reads, by key. Always present, empty
+     *  when none are attached, so a caller never has to distinguish "none" from
+     *  "an older server that did not send the field". */
+    knowledgeBases: string[];
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Whether a provider is actually usable right now, as opposed to declared.
+ *
+ *  `declared` and `connected` are separate on purpose: an agent can declare
+ *  HubSpot and have nobody connected, which is the state worth showing on a
+ *  setup checklist. */
+export interface ConnectionStatus {
+    /** The connection row's id, which `disconnect()` revokes by. */
+    id?: string;
+    provider: string;
+    /** 'connected' once the account is attached; anything else means it is not
+     *  usable yet. `connected` below is the boolean form of this. */
+    status?: string;
+    /** The conversation this account belongs to, or null for the agent's shared
+     *  account. `scope` and `suppliedBy` are both derived from it. */
+    conversationId?: string | null;
+    /** The agent this account belongs to. */
+    agentId?: string | null;
+    /** One of YOUR end users, when the account is theirs. Their id, from your
+     *  database, never a workspace member's. Null on a shared account. */
+    endUserId?: string | null;
+    /** Whether the AGENT DECLARES it needs this provider, and whether it is
+     *  mandatory.
+     *
+     *  OPTIONAL because only one of the two endpoints can answer. `agent
+     *  .connections()` reads the MERGED view (`/v1/agents/<id>/connections`),
+     *  where the server has joined the agent's declarations against the live
+     *  rows, and both are real there. `ws.connections.list()` and
+     *  `endUser(id).connections.list()` read raw rows (`/v1/connections`), which
+     *  know nothing about any agent's configuration, so both are absent.
+     *
+     *  They used to be declared as required booleans, which meant the raw-row
+     *  paths had to invent them. They were filled with the constants `true` and
+     *  `false`, so every row claimed to be declared and none claimed to be
+     *  required. Absent is the honest answer, and undefined reads as "this
+     *  endpoint cannot tell you" rather than as "no". */
+    declared?: boolean;
+    required?: boolean;
+    /** What the agent DECLARED it needs. Whose account this actually is, is
+     *  `owner`, and the two are not the same question. */
+    scope?: Scope;
+    /** Whose account this is. Derived from which of the three id fields above
+     *  is set, so it is correct even on a server that does not send it. */
+    owner?: CredentialOwner;
+    connected: boolean;
+    /** Which of the three scopes supplied the account. 'endUser' is one of YOUR
+     *  users, whose account outlives any single conversation. */
+    suppliedBy?: 'conversation' | 'agent' | 'endUser' | 'workspace';
+    accountLabel?: string;
+    error?: string;
+}
+/** Something a conversation is still missing before it can work. */
+export interface Requirement {
+    kind: 'secret' | 'connection';
+    name: string;
+    required: boolean;
+}
+export interface AgentConversationData {
+    id: string;
+    agentId: string;
+    version: number;
+    startedAt: string;
+    title?: string;
+    /** True when nothing REQUIRED is outstanding. An optional gap leaves this
+     *  true, because the conversation genuinely does work without it. */
+    ready: boolean;
+    requires: Requirement[];
+}
+export interface ProjectConversationData {
+    id: string;
+    projectId: string;
+    startedAt: string;
+    title?: string;
+    ready: boolean;
+    requires: Requirement[];
+}
+/** An AGENT on a project, not a person.
+ *
+ *  Called `ProjectAgent` and not `Member`, which is what it was. `Member` is
+ *  the word this product uses for a HUMAN on the account, so a public type of
+ *  that name holding an `agentId` was the same trap as `userId` meaning two
+ *  populations: `import { Member }` handed you the agent one, and the human one
+ *  had to carry a prefix to get out of its way.
+ *
+ *  The people are `WorkspaceMember`, from `ws.members()`. Nothing here is a
+ *  person. */
+export interface ProjectAgent {
+    agentId: string;
+    name: string;
+    addedAt: string;
+}
+export interface ProjectData {
+    id: string;
+    name: string;
+    goal: string | null;
+    managerInstructions: string | null;
+    grade: Grade;
+    status: 'active' | 'archived';
+    agents: ProjectAgent[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Step {
+    id: string;
+    label: string;
+    kind: 'read' | 'write' | 'edit' | 'search' | 'shell' | 'web' | 'data' | 'task' | 'plan' | 'other';
+    status: 'active' | 'done' | 'error';
+}
+export type TurnEvent = {
+    type: 'start';
+    turnId: string;
+}
+/** Carries the WHOLE step list every time, not a change to it. Replace what
+ *  you are showing rather than merging; that is what makes reconnecting
+ *  safe. */
+ | {
+    type: 'progress';
+    steps: Step[];
+} | {
+    type: 'tool';
+    name: string;
+    state: 'start' | 'end';
+    ok?: boolean;
+}
+/** A fragment, not a line. Append; do not assemble. */
+ | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'file';
+    path: string;
+} | {
+    type: 'done';
+    reply: string;
+} | {
+    type: 'error';
+    message: string;
+    retryable: boolean;
+};
+export interface Message {
+    role: 'user' | 'assistant';
+    content: string;
+    at: string;
+}
+/** An image goes to the model as an image. Anything else is written into the
+ *  conversation's drive before the turn starts, so the agent can parse it,
+ *  compute over it, and still have it next turn. */
+export interface Attachment {
+    kind: 'image' | 'file';
+    name?: string;
+    mimeType: string;
+    /** base64, without a data: prefix. */
+    data: string;
+}
+/** A knowledge base: a named folder of files at WORKSPACE scope that an agent
+ *  configuration attaches by key. */
+export interface KnowledgeBaseData {
+    /** Workspace-unique. This is what an agent configuration stores, and it is
+     *  not editable, because renaming it would move every attachment silently. */
+    key: string;
+    name: string;
+    description?: string;
+    /** Counted when read, so it never disagrees with the files it counts. */
+    fileCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One file in a knowledge base. PATH, not a flat name: a base is a folder, and
+ *  the session mount reproduces the shape verbatim. */
+/**
+ * Whether an agent can read a file in a knowledge base.
+ *
+ * Text and markdown are readable as they stand. A PDF, a scan or a spreadsheet
+ * has to be turned into text first, which happens when the file is uploaded
+ * rather than when a question is asked, so an agent never waits on it.
+ *
+ *   'readable'    an agent can read this now
+ *   'processing'  being prepared, check back shortly
+ *   'unreadable'  cannot be read, and `reason` says why
+ */
+export type KnowledgeFileStatus = 'readable' | 'processing' | 'unreadable';
+export interface KnowledgeFileEntry {
+    path: string;
+    mimeType: string;
+    size: number;
+    createdAt: string;
+    updatedAt: string;
+    /** Whether an agent can read this file. */
+    status: KnowledgeFileStatus;
+    /** Why it cannot be read, as a sentence you could show someone.
+     *
+     *  The same text reaches the agent in place of the file, so a developer
+     *  reading this and a model reading the base get one explanation rather than
+     *  two that can drift apart. Absent unless `status` is 'unreadable'. */
+    reason?: string;
+}
+export interface FileEntry {
+    path: string;
+    kind: 'file' | 'directory';
+    mimeType: string;
+    size: number;
+    modifiedAt: string;
+}
+/** Fields accepted when creating or updating an agent. Everything is optional on
+ *  an update: what you do not send is inherited from the current version, which
+ *  is the whole reason updating is safe. */
+export interface AgentFields {
+    id?: string;
+    name?: string;
+    instructions?: string;
+    greeting?: string;
+    grade?: Grade;
+    filesystem?: Filesystem;
+    /**
+     * Knowledge bases this agent reads, by workspace-unique key.
+     *
+     * Mounted READ-ONLY at `/knowledge/<key>/` when a session starts, so the
+     * agent finds things with `ls`, `grep` and `cat` rather than a retrieval API.
+     *
+     * Which bases an agent reads is part of its CONFIGURATION, so changing this
+     * publishes a version you can diff and roll back. The CONTENTS of a base are
+     * not versioned: correcting a file changes what every attached agent sees on
+     * its next turn, which is the same by-reference promise `agent.knowledge`
+     * already makes.
+     *
+     * A key that names no base is refused when the configuration is saved, and
+     * deleting a base is refused while any agent attaches it, so an attachment
+     * that was valid stays valid.
+     */
+    knowledgeBases?: string[];
+    tools?: string[];
+    workflows?: Workflow[];
+    connections?: ConnectionRequirement[];
+    secrets?: SecretRequirement[];
+    parameters?: Parameter[];
+    triggers?: Trigger[];
+    mcpServers?: McpServer[];
+    httpTools?: HttpTool[];
+}
+export interface ProjectFields {
+    name?: string;
+    goal?: string;
+    managerInstructions?: string;
+    grade?: Grade;
+    agents?: string[];
+}
+/** Values supplied when a conversation starts: the credentials its agent
+ *  declared at 'conversation' scope, plus any parameters. */
+export interface Bindings {
+    secrets?: Record<string, string>;
+    connections?: Record<string, string>;
+}
+/** One markdown file read off disk: a workflow, a subagent, an imported skill.
+ *
+ *  `when` is OPTIONAL here and required at publish. A file on disk has no `when`
+ *  until someone writes one, and refusing to read it would be the wrong place to
+ *  say so; the API says it at publish, with a message naming the file. */
+export interface SpecFile {
+    name: string;
+    content: string;
+    when?: string;
+}
+/** What a loaded agent directory produces: the fields `ws.agents.create()` takes,
+ *  plus the id the caller chose and the few legacy names the loader still reads
+ *  off an existing directory. */
+export interface SpecInput extends Omit<AgentFields, 'workflows'> {
+    key: string;
+    workflows?: SpecFile[];
+    skills?: SpecFile[];
+    subagents?: SpecFile[];
+    widgets?: {
+        name: string;
+        [k: string]: unknown;
+    }[];
+    sandbox?: Filesystem;
+    role?: string;
+    /** Retired in favour of `tools: ['web_search']`, still read off an existing
+     *  agent directory so one written before the rename still loads. */
+    webSearch?: boolean;
+}
+/** A PERSON with access to this workspace: your colleague, on a seat.
+ *
+ *  NOT one of your end users, and the difference is the sharpest naming trap in
+ *  this SDK. A workspace member signs in here, we issued their id, and we
+ *  authenticate it. A `EndUser` is the person YOUR application serves, never
+ *  signs in here, and carries an id from YOUR database that we store verbatim
+ *  and never check.
+ *
+ *  `userId` below is therefore a PLATFORM id and is not interchangeable with
+ *  `agent.start({ endUserId })`. Both fields were once spelled `userId`, which
+ *  made passing one where the other belonged a call that could not fail: a
+  *  end-user id is never validated against anything, so it silently labelled a
+ *  conversation with a colleague's internal id. The two names now differ.
+ *
+ *  Named WorkspaceMember rather than Member because a public `Member` type used
+ *  to mean an AGENT attached to a project. That one is now `ProjectAgent`, so
+ *  the prefix here is no longer load-bearing; it stays because it says which of
+ *  the two populations this is at every call site, and that is worth four
+ *  characters.
+ *
+ *  Read-only, like everything else on the account surface: the SDK can see who
+ *  is on the account and what they may do, and cannot add, remove or re-role
+ *  anyone. Those are decisions a person makes while signed in, not something a
+ *  key should be able to do on their behalf. */
+export interface WorkspaceMember {
+    /** A PLATFORM user id (`usr_...`), issued by us. Never pass this to
+     *  `agent.start({ endUserId })` or `ws.endUser()`. */
+    userId: string;
+    email: string;
+    name: string | null;
+    /** 'owner' is the account's creator; 'admin' can manage it; 'member' cannot. */
+    role: 'owner' | 'admin' | 'member';
+    /** Unix seconds. */
+    joinedAt: number;
+}
+/** What is left to spend.
+ *
+ *  `credits` is the balance in credits, where one credit is one US dollar. The
+ *  turn counts are the same balance expressed in the unit people actually
+ *  reason with, because "12.5 credits" answers nothing on its own. */
+export interface Credits {
+    credits: number;
+    standardTurnsRemaining: number;
+    premiumTurnsRemaining: number;
+}
+/** The seat plan this workspace is on.
+ *
+ *  Seats are a SEPARATE purchase from credits: a plan says how many people may
+ *  share the account, credits pay for the work their agents do. Being on the
+ *  free plan does not make turns free. */
+export interface SeatPlan {
+    key: string;
+    label: string;
+    /** People allowed. `null` means negotiated, which is NOT unlimited and
+     *  should never be shown to anyone as a number. */
+    seats: number | null;
+    /** Monthly price in US cents. `null` means there is no published price and
+     *  the answer is a conversation, which is the opposite fact from 0 (free). */
+    usdCentsPerMonth: number | null;
+}
+/** A stored secret, WITHOUT its value.
+ *
+ *  The value is never returned by any read. It is written once, encrypted at
+ *  rest, and substituted into an HTTP tool's url, headers or body server-side at
+ *  call time, so it is never part of anything the model can see or repeat. To
+ *  change one, write it again; to be sure of one, replace it. */
+export interface SecretMeta {
+    id: string;
+    name: string;
+    description?: string | null;
+    /** The agent this secret is scoped to, or null when the whole workspace
+     *  reads it. An agent-scoped secret of the same name wins. */
+    agentId?: string | null;
+    /** The end user this secret belongs to, or null when it is the workspace's.
+     *  One of YOUR user ids, stored verbatim: we never resolve or authenticate
+     *  it. A secret with one can only be attached to a conversation launched for
+     *  that same person. */
+    endUserId?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    lastUsedAt?: string | null;
+}

package/types.js

@@ -0,0 +1,4 @@
+// The shapes this SDK hands back. Transcribed from design/sdk-design.md's own
+// Types section so the reference and the code cannot drift.
+export {};
+//# sourceMappingURL=types.js.map

package/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D","sourcesContent":["// The shapes this SDK hands back. Transcribed from design/sdk-design.md's own\n// Types section so the reference and the code cannot drift.\n\nexport type Grade = 'standard' | 'premium';\nexport type Filesystem = 'drive' | 'none';\n\n/** Where a credential is supplied.\n *\n *  'fixed' is set once on the agent and used by every conversation. 'conversation'\n *  is asked for when a conversation starts, so each user brings their own. The\n *  two DO NOT substitute for each other: an account connected on the agent does\n *  not satisfy a declaration scoped 'conversation'. */\nexport type Scope = 'fixed' | 'conversation';\n\n/** WHOSE credential a stored account or value is, which is a different question\n *  from `Scope` above. `Scope` is what an agent DECLARES it needs; this is who\n *  a row that exists actually belongs to.\n *\n *  'endUser' is one of YOUR end users: the person your application serves,\n *  never a member of this workspace. The two are separate populations with\n *  separate id namespaces: see `EndUser`. */\nexport type CredentialOwner = 'workspace' | 'agent' | 'endUser' | 'conversation';\n\nexport interface WorkspaceInfo {\n\tid: string;\n\tname: string;\n\tcredits: number;\n\tcreatedAt: string;\n}\n\n/** One procedure the agent follows when its `when` matches what is in front of\n *  it. `when` is one line and is not optional: it is what the agent reads to\n *  decide the workflow applies, so a vague one makes a good workflow invisible. */\nexport interface Workflow {\n\tname: string;\n\twhen: string;\n\tcontent: string;\n}\n\n// `SessionMode` is deliberately NOT exposed.\n//\n// The API has one ('per-user' | 'per-call') and 'per-user' makes the server\n// resume a person's most recent conversation. That is the behaviour `start`\n// refuses to have: a verb that sometimes returns something you already had, and\n// which has to guess which one the moment a person has two.\n//\n// Its other effect, fanning a scheduled firing out across the people who have\n// conversations with an agent, is real and worth exposing one day. It should\n// arrive under a name that says THAT, not under a mode that also silently\n// changes what `start` returns.\n\nexport type Trigger =\n\t| { kind: 'chat' }\n\t| { kind: 'schedule'; cron: string; timezone?: string; message: string }\n\t| { kind: 'interval'; seconds: number; maxRuns?: number; message: string }\n\t| { kind: 'webhook'; message?: string; url?: string };\n\n/**\n * What an agent NEEDS, not what it has.\n *\n * Named `Connection` until the actual account became an object you hold. Two\n * different things cannot share one name: this one says \"this agent requires\n * Gmail, supplied per conversation\", and says nothing about whether anybody has\n * connected. `Connection` is the account itself, with tokens behind it.\n *\n * The distinction is the one `ConnectionStatus.declared` versus `.connected`\n * already draws, now in the type names too.\n */\nexport interface ConnectionRequirement {\n\tprovider: string;\n\tscope: Scope;\n\trequired?: boolean;\n}\n\n/** What an agent NEEDS, not the stored value. `Secret` is the value. */\nexport interface SecretRequirement {\n\tname: string;\n\tscope: Scope;\n\trequired?: boolean;\n}\n\nexport interface Parameter {\n\tname: string;\n\ttype: 'string' | 'number' | 'date' | 'choice';\n\trequired?: boolean;\n\tdefault?: string;\n\tchoices?: string[];\n}\n\nexport interface McpServer {\n\tname: string;\n\turl: string;\n\ttransport?: 'http' | 'sse';\n\theaders?: Record<string, string>;\n\ttimeoutMs?: number;\n}\n\nexport interface HttpToolParam {\n\ttype: 'string' | 'number' | 'boolean';\n\tdescription?: string;\n\trequired?: boolean;\n\tchoices?: (string | number)[];\n}\n\nexport interface HttpTool {\n\tname: string;\n\tdescription: string;\n\tmethod: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';\n\turl: string;\n\theaders?: Record<string, string>;\n\tbody?: string;\n\tparams?: Record<string, HttpToolParam>;\n\tsecrets?: string[];\n\ttimeoutMs?: number;\n}\n\nexport interface AgentData {\n\tid: string;\n\tname: string;\n\tinstructions: string;\n\tgreeting?: string;\n\tgrade: Grade;\n\tfilesystem: Filesystem;\n\ttools: string[];\n\tworkflows: Workflow[];\n\tconnections: ConnectionRequirement[];\n\tsecrets: SecretRequirement[];\n\tparameters: Parameter[];\n\ttriggers: Trigger[];\n\tmcpServers: McpServer[];\n\thttpTools: HttpTool[];\n\t/** Workspace knowledge bases this agent reads, by key. Always present, empty\n\t *  when none are attached, so a caller never has to distinguish \"none\" from\n\t *  \"an older server that did not send the field\". */\n\tknowledgeBases: string[];\n\tversion: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\n/** Whether a provider is actually usable right now, as opposed to declared.\n *\n *  `declared` and `connected` are separate on purpose: an agent can declare\n *  HubSpot and have nobody connected, which is the state worth showing on a\n *  setup checklist. */\nexport interface ConnectionStatus {\n\t/** The connection row's id, which `disconnect()` revokes by. */\n\tid?: string;\n\tprovider: string;\n\t/** 'connected' once the account is attached; anything else means it is not\n\t *  usable yet. `connected` below is the boolean form of this. */\n\tstatus?: string;\n\t/** The conversation this account belongs to, or null for the agent's shared\n\t *  account. `scope` and `suppliedBy` are both derived from it. */\n\tconversationId?: string | null;\n\t/** The agent this account belongs to. */\n\tagentId?: string | null;\n\t/** One of YOUR end users, when the account is theirs. Their id, from your\n\t *  database, never a workspace member's. Null on a shared account. */\n\tendUserId?: string | null;\n\t/** Whether the AGENT DECLARES it needs this provider, and whether it is\n\t *  mandatory.\n\t *\n\t *  OPTIONAL because only one of the two endpoints can answer. `agent\n\t *  .connections()` reads the MERGED view (`/v1/agents/<id>/connections`),\n\t *  where the server has joined the agent's declarations against the live\n\t *  rows, and both are real there. `ws.connections.list()` and\n\t *  `endUser(id).connections.list()` read raw rows (`/v1/connections`), which\n\t *  know nothing about any agent's configuration, so both are absent.\n\t *\n\t *  They used to be declared as required booleans, which meant the raw-row\n\t *  paths had to invent them. They were filled with the constants `true` and\n\t *  `false`, so every row claimed to be declared and none claimed to be\n\t *  required. Absent is the honest answer, and undefined reads as \"this\n\t *  endpoint cannot tell you\" rather than as \"no\". */\n\tdeclared?: boolean;\n\trequired?: boolean;\n\t/** What the agent DECLARED it needs. Whose account this actually is, is\n\t *  `owner`, and the two are not the same question. */\n\tscope?: Scope;\n\t/** Whose account this is. Derived from which of the three id fields above\n\t *  is set, so it is correct even on a server that does not send it. */\n\towner?: CredentialOwner;\n\tconnected: boolean;\n\t/** Which of the three scopes supplied the account. 'endUser' is one of YOUR\n\t *  users, whose account outlives any single conversation. */\n\tsuppliedBy?: 'conversation' | 'agent' | 'endUser' | 'workspace';\n\taccountLabel?: string;\n\terror?: string;\n}\n\n/** Something a conversation is still missing before it can work. */\nexport interface Requirement {\n\tkind: 'secret' | 'connection';\n\tname: string;\n\trequired: boolean;\n}\n\nexport interface AgentConversationData {\n\tid: string;\n\tagentId: string;\n\tversion: number;\n\tstartedAt: string;\n\ttitle?: string;\n\t/** True when nothing REQUIRED is outstanding. An optional gap leaves this\n\t *  true, because the conversation genuinely does work without it. */\n\tready: boolean;\n\trequires: Requirement[];\n}\n\nexport interface ProjectConversationData {\n\tid: string;\n\tprojectId: string;\n\tstartedAt: string;\n\ttitle?: string;\n\tready: boolean;\n\trequires: Requirement[];\n}\n\n/** An AGENT on a project, not a person.\n *\n *  Called `ProjectAgent` and not `Member`, which is what it was. `Member` is\n *  the word this product uses for a HUMAN on the account, so a public type of\n *  that name holding an `agentId` was the same trap as `userId` meaning two\n *  populations: `import { Member }` handed you the agent one, and the human one\n *  had to carry a prefix to get out of its way.\n *\n *  The people are `WorkspaceMember`, from `ws.members()`. Nothing here is a\n *  person. */\nexport interface ProjectAgent {\n\tagentId: string;\n\tname: string;\n\taddedAt: string;\n}\n\nexport interface ProjectData {\n\tid: string;\n\tname: string;\n\tgoal: string | null;\n\tmanagerInstructions: string | null;\n\tgrade: Grade;\n\tstatus: 'active' | 'archived';\n\tagents: ProjectAgent[];\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\nexport interface Step {\n\tid: string;\n\tlabel: string;\n\tkind: 'read' | 'write' | 'edit' | 'search' | 'shell' | 'web' | 'data' | 'task' | 'plan' | 'other';\n\tstatus: 'active' | 'done' | 'error';\n}\n\nexport type TurnEvent =\n\t| { type: 'start'; turnId: string }\n\t/** Carries the WHOLE step list every time, not a change to it. Replace what\n\t *  you are showing rather than merging; that is what makes reconnecting\n\t *  safe. */\n\t| { type: 'progress'; steps: Step[] }\n\t| { type: 'tool'; name: string; state: 'start' | 'end'; ok?: boolean }\n\t/** A fragment, not a line. Append; do not assemble. */\n\t| { type: 'text'; text: string }\n\t| { type: 'file'; path: string }\n\t| { type: 'done'; reply: string }\n\t| { type: 'error'; message: string; retryable: boolean };\n\nexport interface Message {\n\trole: 'user' | 'assistant';\n\tcontent: string;\n\tat: string;\n}\n\n/** An image goes to the model as an image. Anything else is written into the\n *  conversation's drive before the turn starts, so the agent can parse it,\n *  compute over it, and still have it next turn. */\nexport interface Attachment {\n\tkind: 'image' | 'file';\n\tname?: string;\n\tmimeType: string;\n\t/** base64, without a data: prefix. */\n\tdata: string;\n}\n\n/** A knowledge base: a named folder of files at WORKSPACE scope that an agent\n *  configuration attaches by key. */\nexport interface KnowledgeBaseData {\n\t/** Workspace-unique. This is what an agent configuration stores, and it is\n\t *  not editable, because renaming it would move every attachment silently. */\n\tkey: string;\n\tname: string;\n\tdescription?: string;\n\t/** Counted when read, so it never disagrees with the files it counts. */\n\tfileCount: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\n/** One file in a knowledge base. PATH, not a flat name: a base is a folder, and\n *  the session mount reproduces the shape verbatim. */\n/**\n * Whether an agent can read a file in a knowledge base.\n *\n * Text and markdown are readable as they stand. A PDF, a scan or a spreadsheet\n * has to be turned into text first, which happens when the file is uploaded\n * rather than when a question is asked, so an agent never waits on it.\n *\n *   'readable'    an agent can read this now\n *   'processing'  being prepared, check back shortly\n *   'unreadable'  cannot be read, and `reason` says why\n */\nexport type KnowledgeFileStatus = 'readable' | 'processing' | 'unreadable';\n\nexport interface KnowledgeFileEntry {\n\tpath: string;\n\tmimeType: string;\n\tsize: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/** Whether an agent can read this file. */\n\tstatus: KnowledgeFileStatus;\n\t/** Why it cannot be read, as a sentence you could show someone.\n\t *\n\t *  The same text reaches the agent in place of the file, so a developer\n\t *  reading this and a model reading the base get one explanation rather than\n\t *  two that can drift apart. Absent unless `status` is 'unreadable'. */\n\treason?: string;\n}\n\nexport interface FileEntry {\n\tpath: string;\n\tkind: 'file' | 'directory';\n\tmimeType: string;\n\tsize: number;\n\tmodifiedAt: string;\n}\n\n/** Fields accepted when creating or updating an agent. Everything is optional on\n *  an update: what you do not send is inherited from the current version, which\n *  is the whole reason updating is safe. */\nexport interface AgentFields {\n\tid?: string;\n\tname?: string;\n\tinstructions?: string;\n\tgreeting?: string;\n\tgrade?: Grade;\n\tfilesystem?: Filesystem;\n\t/**\n\t * Knowledge bases this agent reads, by workspace-unique key.\n\t *\n\t * Mounted READ-ONLY at `/knowledge/<key>/` when a session starts, so the\n\t * agent finds things with `ls`, `grep` and `cat` rather than a retrieval API.\n\t *\n\t * Which bases an agent reads is part of its CONFIGURATION, so changing this\n\t * publishes a version you can diff and roll back. The CONTENTS of a base are\n\t * not versioned: correcting a file changes what every attached agent sees on\n\t * its next turn, which is the same by-reference promise `agent.knowledge`\n\t * already makes.\n\t *\n\t * A key that names no base is refused when the configuration is saved, and\n\t * deleting a base is refused while any agent attaches it, so an attachment\n\t * that was valid stays valid.\n\t */\n\tknowledgeBases?: string[];\n\ttools?: string[];\n\tworkflows?: Workflow[];\n\tconnections?: ConnectionRequirement[];\n\tsecrets?: SecretRequirement[];\n\tparameters?: Parameter[];\n\ttriggers?: Trigger[];\n\tmcpServers?: McpServer[];\n\thttpTools?: HttpTool[];\n}\n\nexport interface ProjectFields {\n\tname?: string;\n\tgoal?: string;\n\tmanagerInstructions?: string;\n\tgrade?: Grade;\n\tagents?: string[];\n}\n\n/** Values supplied when a conversation starts: the credentials its agent\n *  declared at 'conversation' scope, plus any parameters. */\nexport interface Bindings {\n\tsecrets?: Record<string, string>;\n\tconnections?: Record<string, string>;\n}\n\n/** One markdown file read off disk: a workflow, a subagent, an imported skill.\n *\n *  `when` is OPTIONAL here and required at publish. A file on disk has no `when`\n *  until someone writes one, and refusing to read it would be the wrong place to\n *  say so; the API says it at publish, with a message naming the file. */\nexport interface SpecFile {\n\tname: string;\n\tcontent: string;\n\twhen?: string;\n}\n\n/** What a loaded agent directory produces: the fields `ws.agents.create()` takes,\n *  plus the id the caller chose and the few legacy names the loader still reads\n *  off an existing directory. */\nexport interface SpecInput extends Omit<AgentFields, 'workflows'> {\n\tkey: string;\n\tworkflows?: SpecFile[];\n\tskills?: SpecFile[];\n\tsubagents?: SpecFile[];\n\twidgets?: { name: string; [k: string]: unknown }[];\n\tsandbox?: Filesystem;\n\trole?: string;\n\t/** Retired in favour of `tools: ['web_search']`, still read off an existing\n\t *  agent directory so one written before the rename still loads. */\n\twebSearch?: boolean;\n}\n\n/** A PERSON with access to this workspace: your colleague, on a seat.\n *\n *  NOT one of your end users, and the difference is the sharpest naming trap in\n *  this SDK. A workspace member signs in here, we issued their id, and we\n *  authenticate it. A `EndUser` is the person YOUR application serves, never\n *  signs in here, and carries an id from YOUR database that we store verbatim\n *  and never check.\n *\n *  `userId` below is therefore a PLATFORM id and is not interchangeable with\n *  `agent.start({ endUserId })`. Both fields were once spelled `userId`, which\n *  made passing one where the other belonged a call that could not fail: a\n  *  end-user id is never validated against anything, so it silently labelled a\n *  conversation with a colleague's internal id. The two names now differ.\n *\n *  Named WorkspaceMember rather than Member because a public `Member` type used\n *  to mean an AGENT attached to a project. That one is now `ProjectAgent`, so\n *  the prefix here is no longer load-bearing; it stays because it says which of\n *  the two populations this is at every call site, and that is worth four\n *  characters.\n *\n *  Read-only, like everything else on the account surface: the SDK can see who\n *  is on the account and what they may do, and cannot add, remove or re-role\n *  anyone. Those are decisions a person makes while signed in, not something a\n *  key should be able to do on their behalf. */\nexport interface WorkspaceMember {\n\t/** A PLATFORM user id (`usr_...`), issued by us. Never pass this to\n\t *  `agent.start({ endUserId })` or `ws.endUser()`. */\n\tuserId: string;\n\temail: string;\n\tname: string | null;\n\t/** 'owner' is the account's creator; 'admin' can manage it; 'member' cannot. */\n\trole: 'owner' | 'admin' | 'member';\n\t/** Unix seconds. */\n\tjoinedAt: number;\n}\n\n/** What is left to spend.\n *\n *  `credits` is the balance in credits, where one credit is one US dollar. The\n *  turn counts are the same balance expressed in the unit people actually\n *  reason with, because \"12.5 credits\" answers nothing on its own. */\nexport interface Credits {\n\tcredits: number;\n\tstandardTurnsRemaining: number;\n\tpremiumTurnsRemaining: number;\n}\n\n/** The seat plan this workspace is on.\n *\n *  Seats are a SEPARATE purchase from credits: a plan says how many people may\n *  share the account, credits pay for the work their agents do. Being on the\n *  free plan does not make turns free. */\nexport interface SeatPlan {\n\tkey: string;\n\tlabel: string;\n\t/** People allowed. `null` means negotiated, which is NOT unlimited and\n\t *  should never be shown to anyone as a number. */\n\tseats: number | null;\n\t/** Monthly price in US cents. `null` means there is no published price and\n\t *  the answer is a conversation, which is the opposite fact from 0 (free). */\n\tusdCentsPerMonth: number | null;\n}\n\n/** A stored secret, WITHOUT its value.\n *\n *  The value is never returned by any read. It is written once, encrypted at\n *  rest, and substituted into an HTTP tool's url, headers or body server-side at\n *  call time, so it is never part of anything the model can see or repeat. To\n *  change one, write it again; to be sure of one, replace it. */\nexport interface SecretMeta {\n\tid: string;\n\tname: string;\n\tdescription?: string | null;\n\t/** The agent this secret is scoped to, or null when the whole workspace\n\t *  reads it. An agent-scoped secret of the same name wins. */\n\tagentId?: string | null;\n\t/** The end user this secret belongs to, or null when it is the workspace's.\n\t *  One of YOUR user ids, stored verbatim: we never resolve or authenticate\n\t *  it. A secret with one can only be attached to a conversation launched for\n\t *  that same person. */\n\tendUserId?: string | null;\n\tcreatedAt?: string;\n\tupdatedAt?: string;\n\tlastUsedAt?: string | null;\n}\n"]}

package/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.26.0";

package/version.js

@@ -0,0 +1,5 @@
+// GENERATED by scripts/regen-version.mjs. Do not edit: run `bun run regen:version`
+// after bumping the version in package.json. tests/version.test.ts fails if
+// this drifts.
+export const SDK_VERSION = '0.26.0';
+//# sourceMappingURL=version.js.map

package/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,4EAA4E;AAC5E,eAAe;AACf,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC","sourcesContent":["// GENERATED by scripts/regen-version.mjs. Do not edit: run `bun run regen:version`\n// after bumping the version in package.json. tests/version.test.ts fails if\n// this drifts.\nexport const SDK_VERSION = '0.26.0';\n"]}

package/workflows.d.ts

@@ -0,0 +1,36 @@
+import type { Workflow } from './types.ts';
+/** The bits of `node:fs` this needs, so it can be faked in a test and so the
+ *  module does not break a browser bundle merely by being imported. */
+interface FsLike {
+    readdirSync(dir: string): string[];
+    readFileSync(path: string, encoding: 'utf8'): string;
+    statSync(path: string): {
+        isDirectory(): boolean;
+    };
+}
+/**
+ * Parse one SKILL.md-shaped document.
+ *
+ * Exported because it is the part worth testing: the frontmatter, not the
+ * directory walk.
+ */
+export declare function parseWorkflow(source: string, fallbackName: string): Workflow;
+/**
+ * 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 declare function loadWorkflows(dir: string, fs?: FsLike): Workflow[];
+export {};