@proteos/sdk 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/sdk",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "license": "Apache-2.0",
   "description": "TypeScript SDK for the Proteos platform",
   "repository": {

package/src/agent/index.ts

@@ -5,6 +5,7 @@ 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'
+import { type ToolsetService, ToolsetServiceImpl } from './toolsets.js'
 
 /**
  * Client for the Proteos Agent Service API.
@@ -33,6 +34,8 @@ export class AgentClient {
   readonly skills: SkillService
   /** Service for managing tools. */
   readonly tools: ToolService
+  /** Service for managing toolsets (platform + custom tool groups). */
+  readonly toolsets: ToolsetService
   /** Service for managing MCP server registrations. */
   readonly mcpServers: McpServerService
   /** Service for managing chat sessions (conversations + event log + stream). */
@@ -48,6 +51,7 @@ export class AgentClient {
     this.prompts = new PromptServiceImpl(client)
     this.skills = new SkillServiceImpl(client)
     this.tools = new ToolServiceImpl(client)
+    this.toolsets = new ToolsetServiceImpl(client)
     this.mcpServers = new McpServerServiceImpl(client)
     this.sessions = new SessionServiceImpl(client)
   }
@@ -96,6 +100,7 @@ export type {
 export type { SessionService } from './sessions.js'
 export type { SkillService } from './skills.js'
 export type { ToolService } from './tools.js'
+export type { ToolsetService } from './toolsets.js'
 // Re-export types
 export type {
   ActionBinding,
@@ -126,9 +131,16 @@ export type {
   SkillBundle,
   SkillVersion,
   StartMcpOAuthResponse,
+  PlatformBinding,
   Tool,
   ToolBinding,
   ToolKind,
+  Toolset,
+  ToolsetKind,
+  ToolsetToolSummary,
+  CreateToolsetRequest,
+  UpdateToolsetRequest,
+  ListToolsetsOptions,
   UpdateAgentRequest,
   UpdateMcpServerRequest,
   UpdatePromptRequest,

package/src/agent/toolsets.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 {
+  CreateToolsetRequest,
+  ListToolsetsOptions,
+  Toolset,
+  ToolsetToolSummary,
+  UpdateToolsetRequest,
+} from './types.js'
+
+const TOOLSETS_BASE_PATH = '/agents/v1/toolsets'
+
+/**
+ * Service for managing Toolsets — the hardcoded platform toolsets (read-only)
+ * merged with the org's custom groups of its own tools. Writes apply to custom
+ * toolsets only; a platform key is rejected with `toolset_read_only`.
+ */
+export interface ToolsetService {
+  /** Lists toolsets (platform + custom merged), auto-paginating. Filterable by `kind`. */
+  list(options?: ListToolsetsOptions): PageIterator<Toolset, ListToolsetsOptions>
+  /** Fetches a single page of toolsets with pagination metadata. */
+  listPage(options?: ListToolsetsOptions): Promise<ListResult<Toolset>>
+  /** Gets a single toolset by key (platform or custom). @throws {ProteosError} 404. */
+  get(key: string): Promise<Toolset>
+  /**
+   * Lists the tools inside a toolset — platform members proxied from the
+   * platform MCP server, custom members summarized from the org's Tool rows.
+   * @throws {ProteosError} 404.
+   */
+  listTools(key: string): Promise<ToolsetToolSummary[]>
+  /** Creates a custom toolset. @throws {ProteosError} 400/409. */
+  create(request: CreateToolsetRequest): Promise<Toolset>
+  /** Fully replaces a custom toolset's definition. @throws {ProteosError} 404/400. */
+  update(key: string, request: UpdateToolsetRequest): Promise<Toolset>
+  /** Creates or fully replaces a custom toolset (idempotent deploy entry point). */
+  upsert(key: string, request: CreateToolsetRequest): Promise<Toolset>
+  /** Deletes a custom toolset. @throws {ProteosError} 404/400. */
+  delete(key: string): Promise<void>
+}
+
+export class ToolsetServiceImpl implements ToolsetService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListToolsetsOptions = {}): PageIterator<Toolset, ListToolsetsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListToolsetsOptions = {}): Promise<ListResult<Toolset>> {
+    return this.client.requestWithQuery<ListResult<Toolset>>('GET', TOOLSETS_BASE_PATH, options)
+  }
+
+  async get(key: string): Promise<Toolset> {
+    return this.client.request<Toolset>('GET', `${TOOLSETS_BASE_PATH}/${key}`)
+  }
+
+  async listTools(key: string): Promise<ToolsetToolSummary[]> {
+    const response = await this.client.request<{ data: ToolsetToolSummary[] }>(
+      'GET',
+      `${TOOLSETS_BASE_PATH}/${key}/tools`,
+    )
+    return response.data
+  }
+
+  async create(request: CreateToolsetRequest): Promise<Toolset> {
+    return this.client.request<Toolset>('POST', TOOLSETS_BASE_PATH, request)
+  }
+
+  async update(key: string, request: UpdateToolsetRequest): Promise<Toolset> {
+    return this.client.request<Toolset>('PATCH', `${TOOLSETS_BASE_PATH}/${key}`, request)
+  }
+
+  async upsert(key: string, request: CreateToolsetRequest): Promise<Toolset> {
+    return this.client.request<Toolset>('PUT', `${TOOLSETS_BASE_PATH}/${key}`, request)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${TOOLSETS_BASE_PATH}/${key}`)
+  }
+}

package/src/agent/types.ts

@@ -64,6 +64,8 @@ export interface Agent extends AuditFields {
   tools: string[]
   subagents: string[]
   mcp_servers: string[]
+  /** Toolset keys (platform or custom) attached as whole tool groups. */
+  toolsets: string[]
   /** Marks the single agent surfaced by default for the org (at most one). */
   is_org_default: boolean
   version: number
@@ -80,6 +82,7 @@ export interface CreateAgentRequest {
   tools?: string[]
   subagents?: string[]
   mcp_servers?: string[]
+  toolsets?: string[]
   is_org_default?: boolean
 }
 
@@ -93,6 +96,7 @@ export interface UpdateAgentRequest {
   tools?: string[]
   subagents?: string[]
   mcp_servers?: string[]
+  toolsets?: string[]
   is_org_default?: boolean
 }
 
@@ -211,8 +215,10 @@ export type ListSkillsOptions = AgentResourceListOptions
  * - `action` binds to a function-service Action.
  * - `mcp` binds to one tool on a registered {@link McpServer}.
  * - `client` is a host-provided builtin and carries no binding.
+ * - `platform` binds to one tool of the platform MCP server (mcp-service),
+ *   executed server-side as the acting user.
  */
-export type ToolKind = 'action' | 'mcp' | 'client'
+export type ToolKind = 'action' | 'mcp' | 'client' | 'platform'
 
 /** Binds to a function-service Action by its key (kind=action). */
 export interface ActionBinding {
@@ -225,8 +231,17 @@ export interface McpBinding {
   tool_name: string
 }
 
+/**
+ * Binds to one tool of the platform MCP server (kind=platform). `toolset` pins
+ * the server mount the tool lives in.
+ */
+export interface PlatformBinding {
+  toolset: string
+  tool_name: string
+}
+
 /** Kind-discriminated binding payload. `kind=client` carries no binding. */
-export type ToolBinding = ActionBinding | McpBinding
+export type ToolBinding = ActionBinding | McpBinding | PlatformBinding
 
 /**
  * A thin registry entry over one of three binding sources. `key` is the wire
@@ -272,6 +287,65 @@ export interface ListToolsOptions extends AgentResourceListOptions {
   kind?: ToolKind
 }
 
+// ---------------------------------------------------------------------------
+// Toolsets
+// ---------------------------------------------------------------------------
+
+/**
+ * Toolset origin: `platform` toolsets are the hardcoded groups of the platform
+ * MCP server (read-only, one per server mount); `custom` toolsets are
+ * org-authored groups of the org's own {@link Tool} rows.
+ */
+export type ToolsetKind = 'platform' | 'custom'
+
+/**
+ * A named group of tools an agent attaches as one unit (`Agent.toolsets`).
+ * Platform and custom toolsets share one key namespace (platform keys are
+ * reserved). For platform toolsets `tools` is empty — the members live in
+ * mcp-service and are listed via `toolsets.listTools`; for custom toolsets it
+ * carries the member Tool keys. Keyed by (org_id, key).
+ */
+export interface Toolset extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  description: string
+  kind: ToolsetKind
+  tools: string[]
+  version: number
+}
+
+/** Creates a CUSTOM toolset — platform toolsets are hardcoded and read-only. */
+export interface CreateToolsetRequest {
+  key: string
+  name: string
+  module_slug?: string
+  description?: string
+  /** Member Tool keys; existence is validated on write. */
+  tools?: string[]
+}
+
+/** Fully replaces the custom toolset's definition (membership is a set). */
+export interface UpdateToolsetRequest {
+  name: string
+  module_slug?: string
+  description?: string
+  tools?: string[]
+}
+
+export interface ListToolsetsOptions extends AgentResourceListOptions {
+  /** Filter the merged listing by origin. */
+  kind?: ToolsetKind
+}
+
+/** One tool inside a toolset, for pickers: the wire name + display metadata. */
+export interface ToolsetToolSummary {
+  name: string
+  title?: string
+  description?: string
+}
+
 // ---------------------------------------------------------------------------
 // MCP Servers
 // ---------------------------------------------------------------------------

package/src/auth/platform-entities.ts

@@ -52,6 +52,7 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'prompts', name: 'Prompts' },
   { slug: 'skills', name: 'Skills' },
   { slug: 'tools', name: 'Tools' },
+  { slug: 'toolsets', name: 'Toolsets' },
   { slug: 'mcp-servers', name: 'MCP Servers' },
   { slug: 'agent-sessions', name: 'Agent Sessions' },
   // Messaging bus (event-service)

package/src/conversation/types.ts

@@ -415,6 +415,14 @@ export interface AgentListenerAcknowledgementConfig {
   text?: string
 }
 
+/**
+ * Where the dispatcher takes its acting user from: 'defined' (the listener's
+ * stored acting_user — the default) or 'inferred' (the triggering message
+ * sender's resolved platform user, with acting_user as OPTIONAL fallback — no
+ * platform user and no fallback means the dispatch is skipped).
+ */
+export type AgentListenerActingUserMode = 'defined' | 'inferred'
+
 export interface AgentListener {
   id: string
   org_id: string
@@ -444,7 +452,12 @@ export interface AgentListener {
    */
   acknowledgement_type: AgentListenerAcknowledgementType
   acknowledgement_config?: AgentListenerAcknowledgementConfig
-  /** The user the dispatcher acts as when driving the agent. */
+  acting_user_mode: AgentListenerActingUserMode
+  /**
+   * The user the dispatcher acts as (mode 'defined'), or the optional fallback
+   * when the sender has no platform user (mode 'inferred'; an empty ref means
+   * no fallback).
+   */
   acting_user: UserRef
   is_enabled: boolean
   /**
@@ -561,8 +574,14 @@ export interface CreateAgentListenerRequest {
    */
   acknowledgement_type?: AgentListenerAcknowledgementType
   acknowledgement_config?: AgentListenerAcknowledgementConfig
-  /** A bare user id; the service wraps it into a person UserRef. */
-  acting_user_id: string
+  /** Omit to default to 'defined'. */
+  acting_user_mode?: AgentListenerActingUserMode
+  /**
+   * A bare user id; the service wraps it into a person UserRef. Required in
+   * 'defined' mode (the default); optional in 'inferred' mode, where it is the
+   * fallback when the sender has no platform user.
+   */
+  acting_user_id?: string
   /** Omit to default to enabled. */
   is_enabled?: boolean
   /**
@@ -593,6 +612,9 @@ export interface UpdateAgentListenerRequest {
    */
   acknowledgement_type?: AgentListenerAcknowledgementType
   acknowledgement_config?: AgentListenerAcknowledgementConfig
+  /** Switching to 'defined' requires an effective acting user (stored or in this request). */
+  acting_user_mode?: AgentListenerActingUserMode
+  /** Pass "" to clear the user — only valid when the effective mode is 'inferred'. */
   acting_user_id?: string
   is_enabled?: boolean
   /** Toggle whether the platform auto-forwards the agent's text reply. */

package/src/index.ts

@@ -52,6 +52,7 @@ export type {
   CreatePromptRequest,
   CreateSessionRequest,
   CreateToolRequest,
+  CreateToolsetRequest,
   DependentAgent,
   DependentSyncResult,
   EmptyPayload,
@@ -64,6 +65,7 @@ export type {
   ListSessionsOptions,
   ListSkillsOptions,
   ListToolsOptions,
+  ListToolsetsOptions,
   McpBinding,
   McpConnectionState,
   McpConnectionStatus,
@@ -97,11 +99,16 @@ export type {
   StartMcpOAuthResponse,
   StopReason,
   TextBlock,
+  PlatformBinding,
   Tool,
   ToolBinding,
   ToolConfirmationPayload,
   ToolKind,
   ToolResultPayload,
+  Toolset,
+  ToolsetKind,
+  ToolsetService,
+  ToolsetToolSummary,
   ToolService,
   ToolUsePayload,
   Turn,
@@ -109,6 +116,7 @@ export type {
   UpdateMcpServerRequest,
   UpdatePromptRequest,
   UpdateToolRequest,
+  UpdateToolsetRequest,
   UserMessagePayload,
 } from './agent/index.js'
 export { AgentClient } from './agent/index.js'
@@ -187,6 +195,7 @@ export type {
   AgentListener,
   AgentListenerAcknowledgementConfig,
   AgentListenerAcknowledgementType,
+  AgentListenerActingUserMode,
   AgentListenerService,
   AgentListenerTriggerType,
   AllFilterConfig,