@proteos/sdk 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/sdk",
-  "version": "0.38.0",
+  "version": "0.40.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,17 @@ export type {
   SkillBundle,
   SkillVersion,
   StartMcpOAuthResponse,
+  PlatformBinding,
+  QueryBinding,
   Tool,
   ToolBinding,
   ToolKind,
+  Toolset,
+  ToolsetKind,
+  ToolsetToolSummary,
+  CreateToolsetRequest,
+  UpdateToolsetRequest,
+  ListToolsetsOptions,
   UpdateAgentRequest,
   UpdateMcpServerRequest,
   UpdatePromptRequest,

package/src/agent/session-types.ts

@@ -224,8 +224,15 @@ export interface StopReason {
 }
 
 /**
- * Emitted when a turn ends. `event_ids` carries the tool_use event ids awaiting a
- * client response when `stop_reason.type` is `user_action_required`.
+ * Ends a turn — published once per turn by the server, not an echo of the upstream
+ * provider's session status (which flips idle/running once per server-side tool
+ * round, mid-turn).
+ *
+ * `event_ids` is set only with `stop_reason.type: 'user_action_required'`, and lists
+ * the tool_use events still OUTSTANDING — the ones a client must answer. Tools the
+ * server executes itself are resolved before this event exists, so seeing this event
+ * at all means the turn cannot continue without you: answer each id with a
+ * `user.tool_result`.
  */
 export interface SessionIdlePayload {
   stop_reason: StopReason

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,12 @@ 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.
+ * - `query` stores a SQL query with declared params, executed server-side
+ *   against data-service as the acting user.
  */
-export type ToolKind = 'action' | 'mcp' | 'client'
+export type ToolKind = 'action' | 'mcp' | 'client' | 'platform' | 'query'
 
 /** Binds to a function-service Action by its key (kind=action). */
 export interface ActionBinding {
@@ -225,8 +233,28 @@ 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
+}
+
+/**
+ * Stores a SELECT-only SQL query (data-service dialect) whose `{{param}}`
+ * placeholders are filled from the declared `params` at execution time
+ * (kind=query). Params are scalar attribute definitions (string, number,
+ * integer, boolean, datetime, enum); they generate the tool's input schema.
+ */
+export interface QueryBinding {
+  sql: string
+  params?: Attribute[]
+}
+
 /** Kind-discriminated binding payload. `kind=client` carries no binding. */
-export type ToolBinding = ActionBinding | McpBinding
+export type ToolBinding = ActionBinding | McpBinding | PlatformBinding | QueryBinding
 
 /**
  * A thin registry entry over one of three binding sources. `key` is the wire
@@ -272,6 +300,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/index.ts

@@ -19,6 +19,7 @@ import type {
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
   CreateTranscriptionRequest,
+  DeleteConnectionQuery,
   DispatchMeetingBotRequest,
   GlossaryTerm,
   InstallConnectionResponse,
@@ -164,7 +165,14 @@ export interface ConnectionService {
   get(id: string): Promise<Connection>
   create(request: CreateConnectionRequest): Promise<Connection>
   update(id: string, request: UpdateConnectionRequest): Promise<Connection>
-  delete(id: string): Promise<void>
+  /**
+   * Delete a connection. The connector first releases its provider-side
+   * registration (a Recall calendar and the OAuth grant behind it); when that
+   * fails the delete is refused with a `connector_uninstall_failed` 502 rather
+   * than orphaning it. Pass `{ is_forced: true }` to drop the row anyway and
+   * clean up at the provider by hand.
+   */
+  delete(id: string, query?: DeleteConnectionQuery): Promise<void>
   /** Begin the connector's install flow; open the returned URL in a popup. */
   install(id: string): Promise<InstallConnectionResponse>
   /**
@@ -211,10 +219,11 @@ class ConnectionServiceImpl implements ConnectionService {
     )
   }
 
-  async delete(id: string): Promise<void> {
-    await this.client.request(
+  async delete(id: string, query: DeleteConnectionQuery = {}): Promise<void> {
+    await this.client.requestWithQuery(
       'DELETE',
       `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`,
+      query,
     )
   }
 
@@ -392,6 +401,11 @@ export interface ConversationService {
   /** Patch the user-editable surface (subject, summary, status, metadata). */
   update(id: string, request: UpdateConversationRequest): Promise<Conversation>
   end(id: string): Promise<Conversation>
+  /**
+   * Hard-delete the conversation, its thread children, and every dependent
+   * row (messages, attachments, read markers, transcriptions). Irreversible.
+   */
+  delete(id: string): Promise<void>
   /** Upsert the requesting user's read marker to now (open a conversation). */
   markRead(id: string): Promise<void>
   /** Remove the marker — the conversation reads as unread again. */
@@ -429,6 +443,13 @@ class ConversationServiceImpl implements ConversationService {
     )
   }
 
+  delete(id: string): Promise<void> {
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`,
+    )
+  }
+
   markRead(id: string): Promise<void> {
     return this.client.request(
       'POST',

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. */
@@ -708,6 +730,17 @@ export interface ListConnectionsQuery extends PaginationQuery {
   status?: string
 }
 
+/**
+ * The delete's escape hatch. A connection delete makes the connector release
+ * its provider-side registration first and refuses with a 502
+ * `connector_uninstall_failed` when that fails — the row is the only handle on
+ * that state. `is_forced` drops the row anyway, leaving the provider-side
+ * leftovers as a manual cleanup.
+ */
+export interface DeleteConnectionQuery {
+  is_forced?: boolean
+}
+
 export interface ListConversationsQuery extends PaginationQuery {
   channel?: string
   status?: string
@@ -761,18 +794,33 @@ export interface ListAgentListenersQuery extends PaginationQuery {
 }
 
 /**
- * Conversation filters: ingest-time rules that drop matching inbound messages
- * BEFORE persistence (no message, no contact — only a content-free audit
- * event). Scope-first evaluation: connection-scoped rules are final when one
- * matches; global rules apply otherwise. Specificity within a scope:
- * address > domain > role_based > automated > internal_conversations > all,
- * allow beats block within a class.
+ * Conversation filters: rules that drop matching inbound messages BEFORE
+ * persistence (no message, no contact — only a content-free audit event) and,
+ * on meeting calendar connections, gate whether the meeting bot is scheduled
+ * at all (pre-join enforcement of the same rules — earliest possible point).
+ * Scope-first evaluation: connection-scoped rules are final when one matches;
+ * global rules apply otherwise. Specificity within a scope:
+ * address > domain > title_keyword > role_based > automated >
+ * self_originated > internal_participant > internal_conversations > all,
+ * allow beats block within a class; an allow match is a final keep, which is
+ * the auto-join composition mechanism (e.g. "organized by me" = a
+ * connection-scoped all-block plus a self_originated allow).
+ *
+ * Channel matrix: address/self_originated/all act on every channel;
+ * domain/title_keyword/internal_participant/internal_conversations act on
+ * email + meeting connections; role_based/automated are email-only. A
+ * connection-scoped rule of a type inert on that connection's channel is
+ * rejected (invalid_filter_config); global rules are unrestricted and stay
+ * inert where their facts are missing.
  */
 export type ConversationFilterType =
   | 'address'
   | 'domain'
+  | 'title_keyword'
   | 'role_based'
   | 'automated'
+  | 'self_originated'
+  | 'internal_participant'
   | 'internal_conversations'
   | 'all'
 export type ConversationFilterAction = 'block' | 'allow'
@@ -805,6 +853,16 @@ export interface RoleBasedFilterConfig {
 export interface AutomatedFilterConfig {
   signals?: AutomatedSignal[]
 }
+/** Title/subject contains any keyword (case-insensitive substring; stored lowercased). */
+export interface TitleKeywordFilterConfig {
+  keywords: string[]
+}
+/** Conversation originates from the connection owner (meeting organizer / self sender). Empty config. */
+export type SelfOriginatedFilterConfig = Record<string, never>
+/** ≥1 participant OTHER than the connection self is on one of these domains (any-internal). */
+export interface InternalParticipantFilterConfig {
+  domains: string[]
+}
 /** Drops only when sender AND every recipient are on these domains. Always block. */
 export interface InternalConversationsFilterConfig {
   domains: string[]
@@ -815,8 +873,11 @@ export type AllFilterConfig = Record<string, never>
 export type ConversationFilterConfig =
   | AddressFilterConfig
   | DomainFilterConfig
+  | TitleKeywordFilterConfig
   | RoleBasedFilterConfig
   | AutomatedFilterConfig
+  | SelfOriginatedFilterConfig
+  | InternalParticipantFilterConfig
   | InternalConversationsFilterConfig
   | AllFilterConfig
 

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,17 @@ export type {
   StartMcpOAuthResponse,
   StopReason,
   TextBlock,
+  PlatformBinding,
+  QueryBinding,
   Tool,
   ToolBinding,
   ToolConfirmationPayload,
   ToolKind,
   ToolResultPayload,
+  Toolset,
+  ToolsetKind,
+  ToolsetService,
+  ToolsetToolSummary,
   ToolService,
   ToolUsePayload,
   Turn,
@@ -109,6 +117,7 @@ export type {
   UpdateMcpServerRequest,
   UpdatePromptRequest,
   UpdateToolRequest,
+  UpdateToolsetRequest,
   UserMessagePayload,
 } from './agent/index.js'
 export { AgentClient } from './agent/index.js'
@@ -187,6 +196,7 @@ export type {
   AgentListener,
   AgentListenerAcknowledgementConfig,
   AgentListenerAcknowledgementType,
+  AgentListenerActingUserMode,
   AgentListenerService,
   AgentListenerTriggerType,
   AllFilterConfig,