@proteos/sdk 0.18.1

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@proteos/sdk",
+  "version": "0.18.1",
+  "license": "Apache-2.0",
+  "description": "TypeScript SDK for the Proteos platform",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proteos-ai/go-sdk.git"
+  },
+  "homepage": "https://github.com/proteos-ai/go-sdk",
+  "bugs": "https://github.com/proteos-ai/go-sdk/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./meta": {
+      "import": {
+        "types": "./dist/meta/index.d.ts",
+        "default": "./dist/meta/index.js"
+      },
+      "require": {
+        "types": "./dist/meta/index.d.cts",
+        "default": "./dist/meta/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "proteos",
+    "sdk",
+    "api",
+    "client",
+    "typescript"
+  ],
+  "author": "Tonio Knuth",
+  "dependencies": {
+    "@microsoft/fetch-event-source": "^2.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "msw": "^2.7.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@proteos/biome-config": "0.0.0",
+    "@proteos/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:integration:watch": "vitest --config vitest.integration.config.ts",
+    "test:all": "pnpm test && pnpm test:integration",
+    "typecheck": "tsc -b",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "clean": "rm -rf dist"
+  }
+}

package/src/agent/agents.ts

@@ -0,0 +1,53 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { Agent, CreateAgentRequest, ListAgentsOptions, UpdateAgentRequest } from './types.js'
+
+const AGENTS_BASE_PATH = '/agents/v1/agents'
+
+/**
+ * Service for managing Agents — configured personas (system prompt + model
+ * config + the skills/tools/sub-agents they can use). Keyed by immutable `key`.
+ */
+export interface AgentService {
+  /** Lists agents, auto-paginating. */
+  list(options?: ListAgentsOptions): PageIterator<Agent, ListAgentsOptions>
+  /** Fetches a single page of agents with pagination metadata. */
+  listPage(options?: ListAgentsOptions): Promise<ListResult<Agent>>
+  /** Gets a single agent by key. @throws {ProteosError} 404 if not found. */
+  get(key: string): Promise<Agent>
+  /** Creates a new agent. @throws {ProteosError} 400/409. */
+  create(request: CreateAgentRequest): Promise<Agent>
+  /** Patches an existing agent (partial). @throws {ProteosError} 404/400. */
+  update(key: string, request: UpdateAgentRequest): Promise<Agent>
+  /** Deletes an agent. @throws {ProteosError} 404 if not found. */
+  delete(key: string): Promise<void>
+}
+
+export class AgentServiceImpl implements AgentService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListAgentsOptions = {}): PageIterator<Agent, ListAgentsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListAgentsOptions = {}): Promise<ListResult<Agent>> {
+    return this.client.requestWithQuery<ListResult<Agent>>('GET', AGENTS_BASE_PATH, options)
+  }
+
+  async get(key: string): Promise<Agent> {
+    return this.client.request<Agent>('GET', `${AGENTS_BASE_PATH}/${key}`)
+  }
+
+  async create(request: CreateAgentRequest): Promise<Agent> {
+    return this.client.request<Agent>('POST', AGENTS_BASE_PATH, request)
+  }
+
+  async update(key: string, request: UpdateAgentRequest): Promise<Agent> {
+    return this.client.request<Agent>('PATCH', `${AGENTS_BASE_PATH}/${key}`, request)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${AGENTS_BASE_PATH}/${key}`)
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,134 @@
+import type { ProteosClient } from '../client.js'
+import { type AgentService, AgentServiceImpl } from './agents.js'
+import { type McpServerService, McpServerServiceImpl } from './mcp-servers.js'
+import { type PromptService, PromptServiceImpl } from './prompts.js'
+import { type SessionService, SessionServiceImpl } from './sessions.js'
+import { type SkillService, SkillServiceImpl } from './skills.js'
+import { type ToolService, ToolServiceImpl } from './tools.js'
+
+/**
+ * Client for the Proteos Agent Service API.
+ *
+ * Manages the AI-agent configuration domain: Agents, Prompts (versioned),
+ * Skills (versioned bundles), Tools, and MCP Servers — all org-scoped and keyed
+ * by an immutable kebab-case `key`.
+ *
+ * @example
+ * ```ts
+ * import { ProteosClient, AgentClient } from '@proteos/sdk';
+ *
+ * const client = new ProteosClient({ baseUrl, token });
+ * const agent = new AgentClient(client);
+ *
+ * const agents = await agent.agents.list().all();
+ * const prompt = await agent.prompts.get('revenue-brief');
+ * ```
+ */
+export class AgentClient {
+  /** Service for managing agents. */
+  readonly agents: AgentService
+  /** Service for managing prompts (versioned). */
+  readonly prompts: PromptService
+  /** Service for managing skills (versioned bundles). */
+  readonly skills: SkillService
+  /** Service for managing tools. */
+  readonly tools: ToolService
+  /** Service for managing MCP server registrations. */
+  readonly mcpServers: McpServerService
+  /** Service for managing chat sessions (conversations + event log + stream). */
+  readonly sessions: SessionService
+
+  /**
+   * Creates a new AgentClient instance.
+   *
+   * @param client - The base ProteosClient to use for API requests
+   */
+  constructor(client: ProteosClient) {
+    this.agents = new AgentServiceImpl(client)
+    this.prompts = new PromptServiceImpl(client)
+    this.skills = new SkillServiceImpl(client)
+    this.tools = new ToolServiceImpl(client)
+    this.mcpServers = new McpServerServiceImpl(client)
+    this.sessions = new SessionServiceImpl(client)
+  }
+}
+
+// Re-export service interfaces
+export type { AgentService } from './agents.js'
+export type { McpServerService } from './mcp-servers.js'
+export type { PromptService } from './prompts.js'
+// Re-export session types
+export type {
+  AgentArtifactsPayload,
+  AgentMessagePayload,
+  AppendEventRequest,
+  ClientEventType,
+  ClientToolSchema,
+  ContentBlock,
+  ContextCompactedPayload,
+  CreateSessionRequest,
+  EmptyPayload,
+  ErrorPayload,
+  EventType,
+  FileBlock,
+  ListSessionsOptions,
+  ModelRequestEndPayload,
+  ModelRequestStartPayload,
+  ModelUsage,
+  ReasoningPayload,
+  ResultBlock,
+  Session,
+  SessionEvent,
+  SessionEventEnvelope,
+  SessionEventsOptions,
+  SessionIdlePayload,
+  SessionStatus,
+  SessionStreamOptions,
+  SessionUpdatedPayload,
+  StopReason,
+  TextBlock,
+  ToolConfirmationPayload,
+  ToolResultPayload,
+  ToolUsePayload,
+  Turn,
+  UserMessagePayload,
+} from './session-types.js'
+export type { SessionService } from './sessions.js'
+export type { SkillService } from './skills.js'
+export type { ToolService } from './tools.js'
+// Re-export types
+export type {
+  ActionBinding,
+  Agent,
+  AgentResourceListOptions,
+  CreateAgentRequest,
+  CreateMcpServerRequest,
+  CreatePromptRequest,
+  CreateToolRequest,
+  ListAgentsOptions,
+  ListMcpServersOptions,
+  ListPromptsOptions,
+  ListSkillsOptions,
+  ListToolsOptions,
+  McpBinding,
+  McpConnectionState,
+  McpConnectionStatus,
+  McpServer,
+  McpServerAuth,
+  McpServerOAuth,
+  McpToolSummary,
+  ModelConfig,
+  Prompt,
+  PromptVersion,
+  Skill,
+  SkillBundle,
+  SkillVersion,
+  StartMcpOAuthResponse,
+  Tool,
+  ToolBinding,
+  ToolKind,
+  UpdateAgentRequest,
+  UpdateMcpServerRequest,
+  UpdatePromptRequest,
+  UpdateToolRequest,
+} from './types.js'

package/src/agent/mcp-servers.ts

@@ -0,0 +1,102 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateMcpServerRequest,
+  ListMcpServersOptions,
+  McpConnectionStatus,
+  McpServer,
+  McpToolSummary,
+  StartMcpOAuthResponse,
+  UpdateMcpServerRequest,
+} from './types.js'
+
+const MCP_SERVERS_BASE_PATH = '/agents/v1/mcp-servers'
+
+/**
+ * Service for managing MCP Servers — the consumer-side registry of MCP servers
+ * an org's agents can call (the source of `kind=mcp` tools). When `auth.is_secret`
+ * is set, the token is redacted to `''` on read; send a new token only to change
+ * it.
+ */
+export interface McpServerService {
+  /** Lists MCP servers, auto-paginating. */
+  list(options?: ListMcpServersOptions): PageIterator<McpServer, ListMcpServersOptions>
+  /** Fetches a single page of MCP servers with pagination metadata. */
+  listPage(options?: ListMcpServersOptions): Promise<ListResult<McpServer>>
+  /** Gets a single MCP server by key (token redacted if secret). @throws {ProteosError} 404. */
+  get(key: string): Promise<McpServer>
+  /** Registers a new MCP server. @throws {ProteosError} 400/409. */
+  create(request: CreateMcpServerRequest): Promise<McpServer>
+  /** Patches an MCP server (partial). @throws {ProteosError} 404/400. */
+  update(key: string, request: UpdateMcpServerRequest): Promise<McpServer>
+  /** Deletes an MCP server. @throws {ProteosError} 404. */
+  delete(key: string): Promise<void>
+  /** Lists the live tools of a (connected) MCP server via tools/list. @throws {ProteosError} 404/502. */
+  listTools(key: string): Promise<McpToolSummary[]>
+  /** Reports a server's derived OAuth connection state. @throws {ProteosError} 404. */
+  getConnectionStatus(key: string): Promise<McpConnectionStatus>
+  /** Starts the OAuth connect flow; open the returned `authorization_url` in a popup. @throws {ProteosError} 400/404. */
+  startOAuth(key: string): Promise<StartMcpOAuthResponse>
+  /** Drops a server's stored OAuth tokens. @throws {ProteosError} 400/404. */
+  disconnectOAuth(key: string): Promise<void>
+}
+
+export class McpServerServiceImpl implements McpServerService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListMcpServersOptions = {}): PageIterator<McpServer, ListMcpServersOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListMcpServersOptions = {}): Promise<ListResult<McpServer>> {
+    return this.client.requestWithQuery<ListResult<McpServer>>(
+      'GET',
+      MCP_SERVERS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(key: string): Promise<McpServer> {
+    return this.client.request<McpServer>('GET', `${MCP_SERVERS_BASE_PATH}/${key}`)
+  }
+
+  async create(request: CreateMcpServerRequest): Promise<McpServer> {
+    return this.client.request<McpServer>('POST', MCP_SERVERS_BASE_PATH, request)
+  }
+
+  async update(key: string, request: UpdateMcpServerRequest): Promise<McpServer> {
+    return this.client.request<McpServer>('PATCH', `${MCP_SERVERS_BASE_PATH}/${key}`, request)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${MCP_SERVERS_BASE_PATH}/${key}`)
+  }
+
+  async listTools(key: string): Promise<McpToolSummary[]> {
+    const response = await this.client.request<{ data: McpToolSummary[] }>(
+      'GET',
+      `${MCP_SERVERS_BASE_PATH}/${key}/tools`,
+    )
+    return response.data
+  }
+
+  async getConnectionStatus(key: string): Promise<McpConnectionStatus> {
+    const response = await this.client.request<{ data: McpConnectionStatus }>(
+      'GET',
+      `${MCP_SERVERS_BASE_PATH}/${key}/connection`,
+    )
+    return response.data
+  }
+
+  async startOAuth(key: string): Promise<StartMcpOAuthResponse> {
+    return this.client.request<StartMcpOAuthResponse>(
+      'POST',
+      `${MCP_SERVERS_BASE_PATH}/${key}/oauth/connect`,
+    )
+  }
+
+  async disconnectOAuth(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${MCP_SERVERS_BASE_PATH}/${key}/oauth/connect`)
+  }
+}

package/src/agent/prompts.ts

@@ -0,0 +1,80 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreatePromptRequest,
+  ListPromptsOptions,
+  Prompt,
+  PromptVersion,
+  UpdatePromptRequest,
+} from './types.js'
+
+const PROMPTS_BASE_PATH = '/agents/v1/prompts'
+
+/**
+ * Service for managing Prompts — reusable, Liquid-templated instruction texts,
+ * versioned like storage files. A `body` change on update forks a new immutable
+ * version; metadata-only updates do not.
+ */
+export interface PromptService {
+  /** Lists prompts, auto-paginating. */
+  list(options?: ListPromptsOptions): PageIterator<Prompt, ListPromptsOptions>
+  /** Fetches a single page of prompts with pagination metadata. */
+  listPage(options?: ListPromptsOptions): Promise<ListResult<Prompt>>
+  /** Gets a prompt (with its current version) by key. @throws {ProteosError} 404. */
+  get(key: string): Promise<Prompt>
+  /** Creates a new prompt with version 1. @throws {ProteosError} 400/409. */
+  create(request: CreatePromptRequest): Promise<Prompt>
+  /** Patches a prompt; a new `body` forks a version. @throws {ProteosError} 404/400. */
+  update(key: string, request: UpdatePromptRequest): Promise<Prompt>
+  /** Deletes a prompt and all its versions. @throws {ProteosError} 404. */
+  delete(key: string): Promise<void>
+  /** Lists all immutable versions of a prompt, newest first. */
+  listVersions(key: string): Promise<PromptVersion[]>
+  /** Gets a specific immutable version by number. @throws {ProteosError} 404. */
+  getVersion(key: string, number: number): Promise<PromptVersion>
+}
+
+export class PromptServiceImpl implements PromptService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListPromptsOptions = {}): PageIterator<Prompt, ListPromptsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListPromptsOptions = {}): Promise<ListResult<Prompt>> {
+    return this.client.requestWithQuery<ListResult<Prompt>>('GET', PROMPTS_BASE_PATH, options)
+  }
+
+  async get(key: string): Promise<Prompt> {
+    return this.client.request<Prompt>('GET', `${PROMPTS_BASE_PATH}/${key}`)
+  }
+
+  async create(request: CreatePromptRequest): Promise<Prompt> {
+    return this.client.request<Prompt>('POST', PROMPTS_BASE_PATH, request)
+  }
+
+  async update(key: string, request: UpdatePromptRequest): Promise<Prompt> {
+    return this.client.request<Prompt>('PATCH', `${PROMPTS_BASE_PATH}/${key}`, request)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${PROMPTS_BASE_PATH}/${key}`)
+  }
+
+  async listVersions(key: string): Promise<PromptVersion[]> {
+    // The versions endpoint wraps in `{ data }` (no pagination meta).
+    const response = await this.client.request<{ data: PromptVersion[] }>(
+      'GET',
+      `${PROMPTS_BASE_PATH}/${key}/versions`,
+    )
+    return response.data
+  }
+
+  async getVersion(key: string, number: number): Promise<PromptVersion> {
+    return this.client.request<PromptVersion>(
+      'GET',
+      `${PROMPTS_BASE_PATH}/${key}/versions/${number}`,
+    )
+  }
+}