@proteos/sdk 0.57.1 → 0.59.0

package/src/conversation/types.ts

@@ -3,6 +3,7 @@
  * mirror of packages/go/model/conversation (snake_case, Is-prefixed booleans).
  */
 
+import type { PrincipalRef } from '../meta/types.js'
 import type { FileRef } from '../types/common.js'
 
 /**
@@ -862,6 +863,579 @@ export interface ListConversationTypesQuery extends PaginationQuery {
   module_slug?: string
 }
 
+// ---------------------------------------------------------------------------
+// Conversation intelligence — tag definitions, tag sets, tags, evaluations.
+// Hand-maintained mirror of conversation-tag-*.go + api/conversation-tag-*.go.
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminates a tag definition's question (1:1 with the agent-service
+ * decision question types): boolean ("is this present?"), choice ("which
+ * one?"), score ("where on this ordered scale?").
+ */
+export type ConversationTagQuestionType = 'boolean' | 'choice' | 'score'
+
+/**
+ * What a tag anchors to: the whole conversation (one value per conversation),
+ * one message (a verdict per message), or a span (character ranges inside a
+ * message, or message-to-message ranges). `span` REQUIRES evaluator kind
+ * `reason` — only a reasoning generation can localise verbatim quotes.
+ */
+export type ConversationTagScope = 'conversation' | 'message' | 'span'
+
+/**
+ * The model path a definition is judged by: `decide` (agent-service's
+ * calibrated typed decision — probabilities, no prose, no localisation) or
+ * `reason` (a schema-constrained generation that returns rationale + verbatim
+ * anchors; required for span scope).
+ */
+export type ConversationTagEvaluatorKind = 'decide' | 'reason'
+
+/**
+ * WHY an evaluation ran: `realtime` (the debounced window after new messages),
+ * `completion` (the conversation completed — final transcript + summary for
+ * spoken media, End for the rest) or `manual` (`conversationTags.evaluate`).
+ * A tag set's `evaluate_on` lists the automatic ones it subscribes to; manual
+ * ignores it.
+ */
+export type ConversationTagTrigger = 'realtime' | 'completion' | 'manual'
+
+/** Who produced a tag: the evaluator (`model`) or a person (`user`). */
+export type ConversationTagSource = 'model' | 'user'
+
+/**
+ * `pending` = a provisional realtime observation on a spoken-medium
+ * conversation that is still live (a completion evaluation will replace it);
+ * `active` = current; `dismissed` = a person rejected it — kept as feedback
+ * and never re-created by a later evaluation.
+ */
+export type ConversationTagStatus = 'pending' | 'active' | 'dismissed'
+
+/**
+ * One evaluation's lifecycle: `pending` (a manual evaluation was accepted and
+ * not yet started), `running`, `done`, `failed`.
+ */
+export type ConversationTagEvaluationStatus = 'pending' | 'running' | 'done' | 'failed'
+
+/**
+ * Spells out what makes a boolean question hold (`true`) or not (`false`)
+ * when the boundary is subtle.
+ */
+export interface BooleanTagCriteria {
+  true: string
+  false: string
+}
+
+/**
+ * Populated per question type: boolean → `boolean` (optional, both
+ * descriptions or neither), choice → `choice` (option key → description,
+ * ≥ 2), score → `score` (ordered level descriptions, ≥ 2; the tag value is
+ * the 0-based level index). Descriptions are handed to the evaluator
+ * verbatim, so they should describe the observable content, not internal
+ * process.
+ */
+export interface ConversationTagCriteria {
+  boolean?: BooleanTagCriteria
+  choice?: Record<string, string>
+  score?: string[]
+}
+
+/**
+ * The decide-shaped question a definition asks over a conversation — the
+ * same three types as the agent-service decision question, with criteria in
+ * an explicit struct so manifests and SDKs need no tagged-union decoder.
+ * `type` is immutable after create: tag values are typed by it.
+ */
+export interface ConversationTagQuestion {
+  type: ConversationTagQuestionType
+  instructions: string
+  /** Always on the wire; pass `{}` for a boolean question without descriptions. */
+  criteria: ConversationTagCriteria
+}
+
+/**
+ * Makes a `reason` definition ask the cheap decide model first whether it
+ * applies anywhere in the judged window (its own boolean question, one answer
+ * per window); only a definition that passes (probability ≥ `min_probability`)
+ * reaches the reasoning call, which is skipped entirely when nothing passes. A
+ * screened-out definition's stale tags are still replaced. Boolean questions
+ * only — choice and score always have an answer. Omitted = screening on with
+ * the service default threshold (0.3, `CONVERSATION_TAG_SCREENING_MIN_PROBABILITY`);
+ * `{ is_enabled: false }` turns it off. The service rejects `screening` on a
+ * `decide` evaluator or on a choice/score question, and a `min_probability`
+ * outside 0..1.
+ */
+export interface ConversationTagScreening {
+  is_enabled: boolean
+  /** Pass threshold in 0..1; absent = the service default. */
+  min_probability?: number
+}
+
+/**
+ * Selects the model path. `model_id` is only meaningful for `reason` (absent =
+ * the service default); `decide` always uses the service-wide decision model.
+ * `screening` is only meaningful for `reason` with a boolean question; absent =
+ * screening on with the service default threshold.
+ */
+export interface ConversationTagEvaluator {
+  kind: ConversationTagEvaluatorKind
+  model_id?: string
+  screening?: ConversationTagScreening
+}
+
+/**
+ * Describes WHAT to look for in a conversation: one typed question plus where
+ * its answers anchor (`scope`) and which model path answers it (`evaluator`).
+ * WHERE and WHEN a definition is evaluated is a ConversationTagSet's business
+ * — a definition that no enabled set references is never evaluated. Keyed
+ * (org_id, key) and module-deployable (conversation-tag-definitions/<key>.json),
+ * like conversation types.
+ */
+export interface ConversationTagDefinition {
+  org_id: string
+  /** Immutable identity within the org — the value every tag carries as `definition_key`. */
+  key: string
+  name: string
+  /** Free grouping for UIs ("content", "sentiment", "signal"). */
+  group?: string
+  question: ConversationTagQuestion
+  /** `span` requires `evaluator.kind = 'reason'`. */
+  scope: ConversationTagScope
+  evaluator: ConversationTagEvaluator
+  /**
+   * Narrows message/span-scope judging to messages of these directions (e.g.
+   * inbound only for customer sentiment); empty = all. Ignored for
+   * conversation scope.
+   */
+  directions: MessageDirection[]
+  /**
+   * Observations below it are dropped, for every question type — an absent
+   * tag means "not determined", not "false".
+   */
+  min_confidence: number
+  /** Optional UI hint (any CSS color token the client accepts). */
+  color?: string
+  is_enabled: boolean
+  /** Module that deployed the definition; absent when not module-owned. */
+  module_slug?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * Describes WHERE and WHEN a group of tag definitions is evaluated. A
+ * conversation matches a set when every NON-EMPTY selector contains it:
+ * `channels`, `connection_ids`, `type_keys` (an empty conversation `type_key`
+ * never matches a type-scoped set, so type-scoped sets only apply once a
+ * conversation has been classified). At least one of those three must be
+ * non-empty — tagging is opt-in, never org-wide by accident. `directions` is
+ * a message-level filter on top (which messages arm / are judged), not a
+ * conversation selector. Matched sets union their definition keys; timing
+ * takes the minimum quiet window and max wait over the matched sets that
+ * evaluate in realtime. Keyed (org_id, key) and module-deployable
+ * (conversation-tag-sets/<key>.json).
+ */
+export interface ConversationTagSet {
+  org_id: string
+  key: string
+  name: string
+  /**
+   * The definitions this set evaluates (≥ 1; each must exist in the org at
+   * write time — a definition deleted later is skipped).
+   */
+  definition_keys: string[]
+  channels: Channel[]
+  connection_ids: string[]
+  type_keys: string[]
+  /**
+   * Narrows which NEW messages arm a realtime evaluation (and which messages a
+   * completion evaluation judges for message/span scope): inbound only,
+   * outbound only, or both when empty. A definition's own `directions`
+   * narrows further.
+   */
+  directions: MessageDirection[]
+  /**
+   * A non-empty subset of [realtime, completion]: realtime = the debounced
+   * window after new messages arrive; completion = once the conversation
+   * completed (final transcript + summary for spoken media, End for the
+   * rest). Manual evaluations ignore it.
+   */
+  evaluate_on: ConversationTagTrigger[]
+  /** A realtime evaluation fires this long after the LAST new message (default 90, min 5). */
+  quiet_window_seconds: number
+  /**
+   * Bounds the wait since the FIRST unjudged message (default 600, ≥ quiet
+   * window) so a busy stream is still tagged periodically.
+   */
+  max_wait_seconds: number
+  is_enabled: boolean
+  /** Module that deployed the set; absent when not module-owned. */
+  module_slug?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * One observation a definition made on a conversation.
+ *
+ * Anchors encode the definition's scope: conversation scope = every anchor
+ * field absent; message scope = `start_message_id === end_message_id` with no
+ * offsets; span = offsets set (a span may cross messages, then start/end
+ * message ids differ). Offsets are UNICODE CODE POINT indexes into the
+ * message's first text content block, end exclusive — JS strings are UTF-16,
+ * so convert (e.g. via `Array.from(text)` / code-point iteration) before
+ * slicing. `quote` (and `end_quote` for a span that continues into a later
+ * message) is the verbatim text at the anchor: the reason evaluator emits
+ * quotes because a model cannot count characters, the service resolves them
+ * to offsets, and afterwards the quote is the evidence that survives a message
+ * row change (the final transcript swaps realtime message ids; a term
+ * correction edits text) — a tag whose anchors no longer resolve still shows
+ * its quote and can be re-anchored by search.
+ *
+ * `value` is normalized per question type: `"true"` for a boolean (false is
+ * never stored), the option key for a choice, the 0-based level index AS A
+ * STRING for a score. Status `pending` marks a provisional realtime
+ * observation on a live spoken-medium conversation; a completion evaluation
+ * replaces it. Dismissed tags are feedback: a later evaluation never
+ * re-creates a tag matching a dismissed one on (definition_key, value,
+ * start/end message).
+ */
+export interface ConversationTag {
+  id: string
+  org_id: string
+  conversation_id: string
+  /**
+   * Denormalized from the conversation so org-wide lists and counts group by
+   * channel without a join.
+   */
+  channel: Channel
+  definition_key: string
+  /** `"true"` | choice option key | score level index as a string. */
+  value: string
+  confidence: number
+  /**
+   * The raw decide distribution (`{"true":p,"false":1-p}`, option → p, or
+   * `{"levels":[…],"mean":x}`); a screened reason tag carries
+   * `{"screening":p}` instead; absent for unscreened reason and user tags.
+   */
+  probabilities?: Record<string, unknown>
+  /** The reason evaluator's one-line rationale; absent for decide. */
+  why?: string
+  source: ConversationTagSource
+  status: ConversationTagStatus
+  /** Links a model tag to the evaluation that produced it. */
+  evaluation_id?: string
+  start_message_id?: string
+  /** Unicode code-point index, inclusive. */
+  start_offset?: number
+  end_message_id?: string
+  /** Unicode code-point index, exclusive. */
+  end_offset?: number
+  start_occurred_at?: string
+  end_occurred_at?: string
+  quote?: string
+  end_quote?: string
+  /**
+   * When the observed thing happened (the end message's `occurred_at`, else
+   * the last message's) — the time-series axis.
+   */
+  observed_at: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * One row of `conversationTags.counts`: the grouped columns that were
+ * requested plus the count.
+ */
+export interface ConversationTagCount {
+  definition_key?: string
+  value?: string
+  channel?: Channel
+  count: number
+}
+
+/**
+ * The model spend of one evaluation, summed over its decide and generate
+ * calls.
+ */
+export interface ConversationTagUsage {
+  input_tokens: number
+  output_tokens: number
+  request_count: number
+}
+
+/**
+ * One screening verdict of an evaluation: the decide probability that the
+ * definition applies in the judged window and whether that passed the
+ * threshold. `probability` is absent (and `error` set) when the screening
+ * could not be asked — it then passes, fail-open.
+ */
+export interface ConversationTagScreeningResult {
+  definition_key: string
+  probability?: number
+  is_passed: boolean
+  error?: string
+}
+
+/**
+ * Records one time the tagger ran on a conversation: why (`trigger`), what it
+ * judged (`definition_keys`, the message window), with which models, what it
+ * cost, and how it ended. Model tags reference it through `evaluation_id`
+ * (provenance), the UI polls it after a manual evaluate (202), and the latest
+ * done realtime/completion evaluation's `window_end_occurred_at` is the
+ * watermark the next realtime window starts after.
+ *
+ * Window = the messages JUDGED by this evaluation. realtime: everything after
+ * the previous watermark (older messages ride along as context only);
+ * completion/manual: all messages. Lifecycle: manual creates `pending` on the
+ * 202 then flips to `running`; realtime/completion create `running` directly;
+ * ends `done` or `failed`.
+ */
+export interface ConversationTagEvaluation {
+  id: string
+  org_id: string
+  conversation_id: string
+  trigger: ConversationTagTrigger
+  status: ConversationTagEvaluationStatus
+  definition_keys: string[]
+  model_ids: string[]
+  usage: ConversationTagUsage
+  /**
+   * The rendered state exceeded the cap and older context (or, for a huge
+   * window, the newest window messages — deferred to the next evaluation) was
+   * dropped.
+   */
+  is_truncated: boolean
+  window_start_occurred_at?: string
+  window_end_occurred_at?: string
+  window_message_ids: string[]
+  /**
+   * Every screened reason definition's verdict, so "why was nothing tagged"
+   * is answerable and thresholds can be tuned. Empty when no definition was
+   * screened.
+   */
+  screenings: ConversationTagScreeningResult[]
+  error?: string
+  started_at: string
+  finished_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * The `conversation.tagged` event payload: the conversation, the evaluation
+ * that landed, and every tag it produced (status pending or active — the
+ * event header carries the status so a consumer can filter provisional
+ * realtime observations without decoding).
+ */
+export interface ConversationTaggedEvent {
+  conversation: Conversation
+  evaluation: ConversationTagEvaluation
+  tags: ConversationTag[]
+}
+
+/**
+ * Creates one tag definition. `key` is the immutable identity (kebab/snake,
+ * like every platform key); `question` is the decide-shaped question the
+ * evaluator answers; `scope` and `evaluator` say where answers anchor and
+ * which model path answers (`span` requires `evaluator.kind = 'reason'`).
+ * `is_enabled` omitted ⇒ true (manifests may omit it). `module_slug` is
+ * stamped by `pro module deploy` — interactive callers leave it empty.
+ */
+export interface CreateConversationTagDefinitionRequest {
+  key: string
+  name?: string
+  group?: string
+  question: ConversationTagQuestion
+  scope: ConversationTagScope
+  evaluator: ConversationTagEvaluator
+  directions?: MessageDirection[]
+  /** 0..1 */
+  min_confidence?: number
+  color?: string
+  is_enabled?: boolean
+  module_slug?: string
+}
+
+/**
+ * Partial update — an omitted field leaves the stored value untouched.
+ * `question`, when present, replaces the stored question wholesale but must
+ * keep its `type` (400 `conversation_tag_question_type_immutable` otherwise).
+ * `directions` replaces wholesale. `key` is immutable.
+ */
+export interface UpdateConversationTagDefinitionRequest {
+  name?: string
+  group?: string
+  question?: ConversationTagQuestion
+  scope?: ConversationTagScope
+  evaluator?: ConversationTagEvaluator
+  directions?: MessageDirection[]
+  /** 0..1 */
+  min_confidence?: number
+  color?: string
+  is_enabled?: boolean
+}
+
+export interface ListConversationTagDefinitionsQuery extends PaginationQuery {
+  /** Definitions deployed by one module — the `pro module` remote-state discovery door. */
+  module_slug?: string
+  /** Exact filter. */
+  group?: string
+  /** Exact filter. */
+  scope?: string
+  is_enabled?: boolean
+  /** Case-insensitive substring match on key or name. */
+  search?: string
+}
+
+/**
+ * Creates one tag set: which definitions to evaluate (`definition_keys`, ≥ 1,
+ * each must exist), for which conversations (at least one of `channels` /
+ * `connection_ids` / `type_keys` non-empty; `directions` additionally limits
+ * which messages arm/are judged — empty = both), when (`evaluate_on` ⊆
+ * [realtime, completion], ≥ 1) and the realtime timing (omitted ⇒ defaults:
+ * quiet 90s, max wait 600s). `is_enabled` omitted ⇒ true. `module_slug` is
+ * stamped by `pro module deploy`.
+ */
+export interface CreateConversationTagSetRequest {
+  key: string
+  name?: string
+  definition_keys: string[]
+  channels?: Channel[]
+  connection_ids?: string[]
+  type_keys?: string[]
+  directions?: MessageDirection[]
+  evaluate_on: ConversationTagTrigger[]
+  quiet_window_seconds?: number
+  max_wait_seconds?: number
+  is_enabled?: boolean
+  module_slug?: string
+}
+
+/**
+ * Partial update — an omitted field leaves the stored value untouched; arrays
+ * replace wholesale. `key` is immutable.
+ */
+export interface UpdateConversationTagSetRequest {
+  name?: string
+  definition_keys?: string[]
+  channels?: Channel[]
+  connection_ids?: string[]
+  type_keys?: string[]
+  directions?: MessageDirection[]
+  evaluate_on?: ConversationTagTrigger[]
+  quiet_window_seconds?: number
+  max_wait_seconds?: number
+  is_enabled?: boolean
+}
+
+export interface ListConversationTagSetsQuery extends PaginationQuery {
+  /** Sets deployed by one module. */
+  module_slug?: string
+  /** Sets that reference the definition. */
+  definition_key?: string
+  is_enabled?: boolean
+  /** Case-insensitive substring match on key or name. */
+  search?: string
+}
+
+/**
+ * The manual door (`conversationTags.create`): a person tags a conversation,
+ * a message or a span. Anchors follow the definition's scope (conversation:
+ * none; message: start == end message, no offsets; span: UNICODE CODE POINT
+ * offsets into the message's first text block, end exclusive — convert from
+ * UTF-16 indexes before sending). The service stamps `source = 'user'`,
+ * confidence 1, and fills `quote` from the anchored text.
+ */
+export interface CreateConversationTagRequest {
+  definition_key: string
+  /** `"true"` | choice option key | score level index as a string. */
+  value: string
+  why?: string
+  start_message_id?: string
+  /** Unicode code-point index, inclusive. */
+  start_offset?: number
+  end_message_id?: string
+  /** Unicode code-point index, exclusive. */
+  end_offset?: number
+}
+
+/**
+ * Flips a tag between `active` and `dismissed` (the feedback loop) and lets a
+ * person annotate why.
+ */
+export interface UpdateConversationTagRequest {
+  status?: ConversationTagStatus
+  why?: string
+}
+
+/**
+ * Starts a manual evaluation (`conversationTags.evaluate`, 202). Omitted or
+ * empty `definition_keys` = every definition the currently matching sets
+ * reference (and every model tag on the conversation is replaced); a list
+ * narrows both the questions and the replacement to those keys.
+ */
+export interface EvaluateConversationTagsRequest {
+  definition_keys?: string[]
+}
+
+/**
+ * Serves both `conversationTags.listByConversation` (the service forces
+ * `conversation_id` from the path) and the org-wide `conversationTags.list`.
+ */
+export interface ListConversationTagsQuery extends PaginationQuery {
+  conversation_id?: string
+  definition_key?: string
+  value?: string
+  channel?: string
+  source?: string
+  status?: string
+  /** Tags anchored on the message at either end. */
+  message_id?: string
+  /** Tags on conversations whose roster contains the contact. */
+  contact_id?: string
+  /** Lower bound on `observed_at` (inclusive), RFC 3339. */
+  since?: string
+  /** Upper bound on `observed_at` (exclusive), RFC 3339. */
+  until?: string
+}
+
+/**
+ * Groups active tags for dashboards. `group_by` is a COMMA-JOINED string
+ * (`'definition_key,value'`) — not an array, because the query serializer
+ * repeats array keys — whitelisted to definition_key, value, channel (order
+ * kept).
+ */
+export interface CountConversationTagsQuery {
+  group_by?: string
+  definition_key?: string
+  channel?: string
+  source?: string
+  status?: string
+  /** Lower bound on `observed_at` (inclusive), RFC 3339. */
+  since?: string
+  /** Upper bound on `observed_at` (exclusive), RFC 3339. */
+  until?: string
+}
+
+export interface CountConversationTagsResponse {
+  data: ConversationTagCount[]
+}
+
+export interface ListConversationTagEvaluationsQuery extends PaginationQuery {
+  trigger?: string
+  status?: string
+}
+
 /** Who assigned a contact's group membership. */
 export type ContactGroupSource = 'manual' | 'model'
 
@@ -1039,6 +1613,11 @@ export interface ListConnectionsQuery extends PaginationQuery {
    */
   owner_id?: string
   status?: string
+  /**
+   * The caller's intent: `read` (default) lists every connection they reach;
+   * `write` only those they may send through — the compose picker's question.
+   */
+  permission?: 'read' | 'write'
 }
 
 /**
@@ -1079,6 +1658,13 @@ export interface ListConversationsQuery extends PaginationQuery {
   sender_address_id?: string
   /** Opt into the root/latest message projection on each row. */
   include?: 'messages_summary'
+  /**
+   * Conversations carrying an ACTIVE conversation tag of this definition —
+   * the "which conversations talk about billing" stream.
+   */
+  tag_key?: string
+  /** With `tag_key`: only conversations whose tag has this value. */
+  tag_value?: string
 }
 
 /**
@@ -1136,7 +1722,13 @@ export type ConversationFilterType =
   | 'internal_participant'
   | 'internal_conversations'
   | 'all'
-export type ConversationFilterAction = 'block' | 'allow'
+/**
+ * block drops the message; allow keeps it. restrict and share keep it too
+ * (they rank as allow) and decide who sees the thread the message CREATES:
+ * restrict writes only the rule's principals onto the new thread, share adds
+ * them on top of what the thread inherits. Applied once, at creation.
+ */
+export type ConversationFilterAction = 'block' | 'allow' | 'restrict' | 'share'
 /** Which side of the message address/domain rules test (default: sender). */
 export type FilterMatchOn = 'sender' | 'any_participant'
 /** Deterministic machine-mail header signals the automated filter matches. */
@@ -1203,7 +1795,11 @@ export interface ConversationFilter {
   action: ConversationFilterAction
   filter_config?: ConversationFilterConfig
   is_enabled: boolean
-  /** Read-only rollup: messages this rule dropped in the last 30 days. */
+  /** restrict / share only: who the created thread is opened to. */
+  principals?: PrincipalRef[]
+  /** restrict / share only: read or write (write implies read; the default). */
+  permission?: 'read' | 'write'
+  /** Read-only rollup: messages this rule matched in the last 30 days. */
   recent_event_count?: number
   created_at: string
   created_by: UserRef
@@ -1222,6 +1818,8 @@ export interface ConversationFilterEvent {
   sender_kind?: ContactAddressKind
   sender_value?: string
   external_message_id?: string
+  /** The thread a restrict / share match applied to; empty on a drop. */
+  conversation_id?: string
   occurred_at: string
 }
 
@@ -1231,6 +1829,9 @@ export interface CreateConversationFilterRequest {
   action: ConversationFilterAction
   filter_config?: Record<string, unknown>
   is_enabled?: boolean
+  /** Required for restrict / share, empty otherwise. */
+  principals?: PrincipalRef[]
+  permission?: 'read' | 'write'
   /** Opts past the own-domain guard (self_domain_block). */
   is_self_domain_acknowledged?: boolean
 }
@@ -1241,6 +1842,8 @@ export interface UpdateConversationFilterRequest {
   action?: ConversationFilterAction
   filter_config?: Record<string, unknown>
   is_enabled?: boolean
+  principals?: PrincipalRef[]
+  permission?: 'read' | 'write'
   is_self_domain_acknowledged?: boolean
 }