@proteos/sdk 0.57.1 → 0.59.0

package/src/auth/platform-entities.ts

@@ -83,6 +83,8 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'glossary-terms', name: 'Glossary Terms' },
   // Mistranscribed terms proposed by the post-transcription review pass.
   { slug: 'mistranscribed-terms', name: 'Mistranscribed Terms' },
+  // Live speech-to-text (the dictation stream) — `read` opens a stream.
+  { slug: 'voice', name: 'Voice' },
   // The person-level identity layer (contacts + addresses + merges + consent +
   // erasure) — one grant governs the whole aggregate.
   { slug: 'contacts', name: 'Contacts' },
@@ -105,6 +107,12 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'channel-events', name: 'Channel Events' },
   // Conversation briefs: guidance prepared ahead of a conversation (call, meeting) with a contact.
   { slug: 'conversation-briefs', name: 'Conversation Briefs' },
+  // Conversation intelligence: the typed questions asked of conversations
+  // (definitions), where/when they are evaluated (sets), and the observations
+  // they produce incl. their evaluation history (tags).
+  { slug: 'conversation-tag-definitions', name: 'Conversation Tag Definitions' },
+  { slug: 'conversation-tag-sets', name: 'Conversation Tag Sets' },
+  { slug: 'conversation-tags', name: 'Conversation Tags' },
   // Connectors (connector-service). `connections` above is shared; this is the
   // manifest catalog.
   { slug: 'connectors', name: 'Connectors' },
@@ -130,7 +138,25 @@ export const PLATFORM_ENTITY_SLUGS: readonly string[] = PLATFORM_ENTITIES.map(
  * by it — so permission UIs only offer the scoped column for these. Extend as
  * services adopt scoped enforcement.
  */
-export const SCOPED_PLATFORM_ENTITY_SLUGS: readonly string[] = ['knowledge-nodes']
+export const SCOPED_PLATFORM_ENTITY_SLUGS: readonly string[] = [
+  'knowledge-nodes',
+  // agent-service: sessions are owned by their starter; the six config
+  // resources by their creator. Scoped lists + /agents/v1/shares.
+  'agent-sessions',
+  'agents',
+  'prompts',
+  'skills',
+  'tools',
+  'toolsets',
+  'mcp-servers',
+  // conversation-service: a connection is owned by its owner (user-scoped) or
+  // open to the org through its org share (org-scoped); a conversation's rows
+  // are stamped once at creation from its connection / parent and extended by
+  // shares; messages inherit their conversation. /conversations/v1/shares.
+  'connections',
+  'conversations',
+  'messages',
+]
 
 /** True when `slug` belongs to a platform entity (reserved; can't be user-created). */
 export function isPlatformEntity(slug: string): boolean {

package/src/auth/shares.ts

@@ -27,6 +27,7 @@ const PLATFORM_ENTITY_SERVICE: Readonly<Record<string, string>> = {
   tools: '/agents',
   toolsets: '/agents',
   'mcp-servers': '/agents',
+  'agent-sessions': '/agents',
   // Knowledge (knowledge-service)
   'knowledge-spaces': '/knowledge',
   'knowledge-nodes': '/knowledge',
@@ -38,11 +39,11 @@ const PLATFORM_ENTITY_SERVICE: Readonly<Record<string, string>> = {
 /**
  * The services that actually serve `/v1/shares` today.
  *
- * Deliberately separate from the map above: the other services get the endpoint
- * in later phases, and until then a share must fail with a clear message rather
- * than a bare 404 that reads like the record does not exist.
+ * Deliberately separate from the map above: a service that has not adopted
+ * the endpoint yet must fail with a clear message rather than a bare 404 that
+ * reads like the record does not exist.
  */
-const SERVICES_WITH_SHARING: ReadonlySet<string> = new Set(['/data', '/knowledge'])
+const SERVICES_WITH_SHARING: ReadonlySet<string> = new Set(['/data', '/knowledge', '/agents', '/conversations'])
 
 /** Records live in data-service; user-defined entities are the unlisted majority. */
 const DEFAULT_SERVICE = '/data'

package/src/conversation/index.ts

@@ -21,7 +21,13 @@ import type {
   ConversationBrief,
   ConversationFilter,
   ConversationFilterEvent,
+  ConversationTag,
+  ConversationTagDefinition,
+  ConversationTagEvaluation,
+  ConversationTagSet,
   ConversationType,
+  CountConversationTagsQuery,
+  CountConversationTagsResponse,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateContactGroupRequest,
@@ -29,6 +35,9 @@ import type {
   CreateContactRequest,
   CreateConversationBriefRequest,
   CreateConversationFilterRequest,
+  CreateConversationTagDefinitionRequest,
+  CreateConversationTagRequest,
+  CreateConversationTagSetRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
   CreateSendingRuleRequest,
@@ -42,6 +51,7 @@ import type {
   EmailSender,
   EmailSuppression,
   EmailSuppressionKind,
+  EvaluateConversationTagsRequest,
   GetConnectionHealthQuery,
   GlossaryTerm,
   InstallConnectionRequest,
@@ -59,6 +69,10 @@ import type {
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
   ListConversationsQuery,
+  ListConversationTagDefinitionsQuery,
+  ListConversationTagEvaluationsQuery,
+  ListConversationTagSetsQuery,
+  ListConversationTagsQuery,
   ListConversationTypesQuery,
   ListGlossaryTermsQuery,
   ListMessagesQuery,
@@ -101,6 +115,9 @@ import type {
   UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
   UpdateConversationRequest,
+  UpdateConversationTagDefinitionRequest,
+  UpdateConversationTagRequest,
+  UpdateConversationTagSetRequest,
   UpdateConversationTypeRequest,
   UpdateDraftRequest,
   UpdateGlossaryTermRequest,
@@ -144,6 +161,12 @@ export class ConversationClient {
   readonly glossaryTerms: GlossaryTermService
   /** Conversation taxonomy: the types the pre-summary classifier assigns. */
   readonly conversationTypes: ConversationTypeService
+  /** Conversation intelligence: WHAT to look for — typed questions asked of conversations. */
+  readonly conversationTagDefinitions: ConversationTagDefinitionService
+  /** Conversation intelligence: WHERE and WHEN definitions are evaluated. */
+  readonly conversationTagSets: ConversationTagSetService
+  /** Conversation intelligence: the observations produced + their evaluation history. */
+  readonly conversationTags: ConversationTagService
   /** Generic audience taxonomy; membership lives on the contact. */
   readonly contactGroups: ContactGroupService
   /** Tone-of-voice synthesis: per-user setups + the generated profiles. */
@@ -171,6 +194,9 @@ export class ConversationClient {
     this.channelEvents = new ChannelEventServiceImpl(client)
     this.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.conversationTypes = new ConversationTypeServiceImpl(client)
+    this.conversationTagDefinitions = new ConversationTagDefinitionServiceImpl(client)
+    this.conversationTagSets = new ConversationTagSetServiceImpl(client)
+    this.conversationTags = new ConversationTagServiceImpl(client)
     this.contactGroups = new ContactGroupServiceImpl(client)
     this.toneProfiles = new ToneProfileServiceImpl(client)
     this.transcriptions = new TranscriptionServiceImpl(client)
@@ -1044,6 +1070,266 @@ class ConversationTypeServiceImpl implements ConversationTypeService {
   }
 }
 
+/**
+ * Conversation tag definitions: WHAT to look for in a conversation — one
+ * typed question (boolean / choice / score) plus where its answers anchor
+ * (`scope`) and which model path answers (`evaluator`). A definition is only
+ * evaluated through the tag sets that reference it. Keyed by `key` (not id);
+ * `upsert` is the idempotent module-deploy door.
+ */
+export interface ConversationTagDefinitionService {
+  list(
+    query?: ListConversationTagDefinitionsQuery,
+  ): Promise<ListResponse<ConversationTagDefinition>>
+  get(key: string): Promise<ConversationTagDefinition>
+  create(request: CreateConversationTagDefinitionRequest): Promise<ConversationTagDefinition>
+  update(
+    key: string,
+    request: UpdateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(
+    key: string,
+    request: CreateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition>
+  delete(key: string): Promise<void>
+}
+
+class ConversationTagDefinitionServiceImpl implements ConversationTagDefinitionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    query: ListConversationTagDefinitionsQuery = {},
+  ): Promise<ListResponse<ConversationTagDefinition>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions`,
+      query,
+    )
+  }
+
+  get(key: string): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(request: CreateConversationTagDefinitionRequest): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions`,
+      request,
+    )
+  }
+
+  update(
+    key: string,
+    request: UpdateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(
+    key: string,
+    request: CreateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Conversation tag sets: WHERE and WHEN a group of definitions is evaluated.
+ * A set needs at least one conversation selector (`channels`,
+ * `connection_ids`, `type_keys`) — tagging is opt-in, never org-wide by
+ * accident — and `evaluate_on` is a non-empty subset of realtime|completion.
+ * Keyed by `key` (not id); `upsert` is the idempotent module-deploy door.
+ */
+export interface ConversationTagSetService {
+  list(query?: ListConversationTagSetsQuery): Promise<ListResponse<ConversationTagSet>>
+  get(key: string): Promise<ConversationTagSet>
+  create(request: CreateConversationTagSetRequest): Promise<ConversationTagSet>
+  update(key: string, request: UpdateConversationTagSetRequest): Promise<ConversationTagSet>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(key: string, request: CreateConversationTagSetRequest): Promise<ConversationTagSet>
+  delete(key: string): Promise<void>
+}
+
+class ConversationTagSetServiceImpl implements ConversationTagSetService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConversationTagSetsQuery = {}): Promise<ListResponse<ConversationTagSet>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets`,
+      query,
+    )
+  }
+
+  get(key: string): Promise<ConversationTagSet> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(request: CreateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversation-tag-sets`, request)
+  }
+
+  update(key: string, request: UpdateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(key: string, request: CreateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Conversation tags: the observations definitions make on conversations,
+ * plus the evaluations that produced them. Per-conversation reads/writes
+ * hang off the conversation; `update`/`delete` address a tag by id; `list`
+ * and `counts` are the org-wide streams. Span offsets are UNICODE CODE POINT
+ * indexes (end exclusive) — convert to/from UTF-16 before slicing JS strings.
+ */
+export interface ConversationTagService {
+  /** Tags on one conversation (pending, active and dismissed unless `status` filters). */
+  listByConversation(
+    conversationId: string,
+    query?: ListConversationTagsQuery,
+  ): Promise<ListResponse<ConversationTag>>
+  /** A person tags a conversation, a message or a span (source = user, confidence 1). */
+  create(conversationId: string, request: CreateConversationTagRequest): Promise<ConversationTag>
+  /**
+   * Start a manual evaluation (202). Resolves with the PENDING evaluation as
+   * soon as it is accepted — the tagger runs server-side beyond this request.
+   * Poll `listEvaluations(conversationId)` until that evaluation's status is
+   * `done` | `failed`, then re-read the tags. 409
+   * `conversation_tag_set_not_matched` when no enabled set matches the
+   * conversation; 409 `conversation_tag_evaluation_in_progress` while another
+   * evaluation is still running.
+   */
+  evaluate(
+    conversationId: string,
+    request?: EvaluateConversationTagsRequest,
+  ): Promise<ConversationTagEvaluation>
+  /** The evaluation history of one conversation (newest first by default). */
+  listEvaluations(
+    conversationId: string,
+    query?: ListConversationTagEvaluationsQuery,
+  ): Promise<ListResponse<ConversationTagEvaluation>>
+  /** Flip a tag between active and dismissed (the feedback loop) and/or annotate why. */
+  update(id: string, request: UpdateConversationTagRequest): Promise<ConversationTag>
+  delete(id: string): Promise<void>
+  /** Org-wide tag stream (filter by definition, value, channel, contact, time window). */
+  list(query?: ListConversationTagsQuery): Promise<ListResponse<ConversationTag>>
+  /** Grouped counts for dashboards — `group_by` is a comma-joined string. */
+  counts(query?: CountConversationTagsQuery): Promise<CountConversationTagsResponse>
+}
+
+class ConversationTagServiceImpl implements ConversationTagService {
+  constructor(private readonly client: ProteosClient) {}
+
+  listByConversation(
+    conversationId: string,
+    query: ListConversationTagsQuery = {},
+  ): Promise<ListResponse<ConversationTag>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags`,
+      query,
+    )
+  }
+
+  create(conversationId: string, request: CreateConversationTagRequest): Promise<ConversationTag> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags`,
+      request,
+    )
+  }
+
+  evaluate(
+    conversationId: string,
+    request: EvaluateConversationTagsRequest = {},
+  ): Promise<ConversationTagEvaluation> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags/evaluate`,
+      request,
+    )
+  }
+
+  listEvaluations(
+    conversationId: string,
+    query: ListConversationTagEvaluationsQuery = {},
+  ): Promise<ListResponse<ConversationTagEvaluation>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tag-evaluations`,
+      query,
+    )
+  }
+
+  update(id: string, request: UpdateConversationTagRequest): Promise<ConversationTag> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/${encodeURIComponent(id)}`,
+      request,
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/${encodeURIComponent(id)}`,
+    )
+  }
+
+  list(query: ListConversationTagsQuery = {}): Promise<ListResponse<ConversationTag>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/conversation-tags`, query)
+  }
+
+  counts(query: CountConversationTagsQuery = {}): Promise<CountConversationTagsResponse> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/counts`,
+      query,
+    )
+  }
+}
+
 /**
  * Contact groups: the generic org-shared audience taxonomy. Membership lives
  * on the contact (`Contact.group_key`, one group per contact — assign via