@smooai/smooth-operator 1.18.0 → 1.21.0

package/src/generated/types.ts

@@ -66,6 +66,10 @@ export interface CreateConversationSessionRequest {
      * Browser fingerprint string (e.g. from ThumbmarkJS) used for anonymous user correlation across sessions.
      */
     browserFingerprint?: string;
+    /**
+     * Client render capabilities for this session — a per-kind list gating the Rich Interactions the server may emit mid-turn (`interaction_required`). Each interaction kind declares the capability that gates it (e.g. kind `identity_intake` → capability `identity_form`); future kinds add their own values (`date_picker`, `file_upload`, …). Text-only channels (SMS, voice) omit this and the server degrades each kind to its conversational fallback. Unknown values are ignored (forward-compatible).
+     */
+    supports?: string[];
     /**
      * Arbitrary key/value metadata to attach to the session.
      */
@@ -321,6 +325,10 @@ export interface SendMessageRequest {
      * Whether to receive incremental `stream_chunk` and `stream_token` events. Defaults to `true`. Set to `false` to receive only the final `eventual_response`.
      */
     stream?: boolean;
+    /**
+     * Optional gateway model id to run THIS turn on (e.g. a /smooth-mode preset). Absent → the server's configured default model.
+     */
+    model?: string;
 }
 
 // ── from actions/send-message.schema.json ──
@@ -372,6 +380,49 @@ export interface GeneralAgentResponse {
     suggestedNextActions: string[];
 }
 
+// ── from actions/submit-interaction.schema.json ──
+/**
+ * Fields sent by the client to submit (or decline) a parked interaction.
+ */
+export interface SubmitInteractionRequest {
+    /**
+     * Action discriminator.
+     */
+    action: 'submit_interaction';
+    /**
+     * Must match the `requestId` from the `interaction_required` event being responded to.
+     */
+    requestId: string;
+    /**
+     * Session ID of the parked session.
+     */
+    sessionId: string;
+    /**
+     * Must match the `interactionId` from the `interaction_required` event, so a stale submit can never resolve a newer park.
+     */
+    interactionId: string;
+    /**
+     * Optional interaction kind, for cross-checking; the server already knows the parked interaction's kind. When present and mismatched, the submit is rejected.
+     */
+    kind?: string;
+    /**
+     * Kind-specific submitted values. Required unless `declined` is true. Shape per `interactions/<kind>.schema.json#/$defs/Values` (e.g. identity_intake's `{ name?, email?, phone? }`). Validated server-side by the kind's validator.
+     */
+    values?: {};
+    /**
+     * True when the visitor refused the interaction. The turn resumes with a declined payload so the agent can proceed gracefully. When true, `values` is ignored.
+     */
+    declined?: boolean;
+}
+
+// ── from actions/submit-interaction.schema.json ──
+/**
+ * No dedicated response event for `submit_interaction`. Valid values (or a decline) are acked with an `immediate_response` and the parked turn resumes its normal streaming sequence. Invalid values emit `interaction_invalid` (the turn stays parked). This schema is provided for documentation completeness only.
+ */
+export interface SubmitInteractionResponse {
+    [k: string]: unknown;
+}
+
 // ── from actions/verify-otp.schema.json ──
 /**
  * Fields sent by the client to submit an OTP code.
@@ -718,6 +769,10 @@ export interface Session {
      * The conversation this session is attached to.
      */
     conversationId: string;
+    /**
+     * The organization that owns this session. Mirrors `organizationId` on the conversation, participants, and messages so org-scoping is uniform across every domain type and storage backends can write the session's org directly.
+     */
+    organizationId: string;
     /**
      * The agent handling this session.
      */
@@ -804,6 +859,7 @@ export interface ActionEnvelope {
         | 'get_conversation_messages'
         | 'confirm_tool_action'
         | 'verify_otp'
+        | 'submit_interaction'
         | 'ping';
     /**
      * Client-generated correlation ID. Will be echoed back on all related server events. Should be unique per in-flight request. If omitted the server may generate one, but correlating responses becomes the client's problem.
@@ -919,6 +975,23 @@ export interface EventualResponse {
              * Human-readable escalation reason when `needsEscalation` is true.
              */
             escalationReason?: string;
+            /**
+             * Per-turn token accounting and cost, captured from the engine's terminal completion event. Lets a client accumulate live session cost. Optional and back-compatible: absent when the engine reported no usage for the turn (e.g. an offline/mock turn).
+             */
+            usage?: {
+                /**
+                 * Accumulated cost in USD across every LLM call in this turn (gateway-priced).
+                 */
+                costUsd?: number;
+                /**
+                 * Accumulated prompt (input) tokens across every LLM call in this turn.
+                 */
+                promptTokens?: number;
+                /**
+                 * Accumulated completion (output) tokens across every LLM call in this turn.
+                 */
+                completionTokens?: number;
+            };
             /**
              * The sources that grounded this answer, when any were retrieved. Collected by the runtime from the documents that actually grounded the turn — the auto-injected `[Relevant knowledge]` context and any `knowledge_search` tool results — deduplicated by source id and capped. Optional and back-compatible: absent when the turn used no knowledge sources. Each item is a `Citation` (see `domain/citation.schema.json`).
              */
@@ -985,6 +1058,127 @@ export interface ImmediateResponse {
     timestamp?: number;
 }
 
+// ── from events/interaction-invalid.schema.json ──
+/**
+ * Event: `interaction_invalid`. Emitted when a `submit_interaction` action carried values that failed the kind's server-side validation. The turn REMAINS parked — the client should re-render the interaction card with the per-field errors and let the visitor resubmit. Mirrors `otp_invalid`: invalid input is a retryable state, never a terminal `error` event.
+ */
+export interface InteractionInvalid {
+    /**
+     * Event type discriminator.
+     */
+    type: 'interaction_invalid';
+    /**
+     * Echoes the `requestId` of the parked turn (same correlation as the `interaction_required` event).
+     */
+    requestId?: string;
+    /**
+     * Validation failure details.
+     */
+    data: {
+        /**
+         * The request ID this interaction belongs to.
+         */
+        requestId: string;
+        /**
+         * Per-field validation errors.
+         */
+        data: {
+            /**
+             * The interaction instance the rejected submit targeted.
+             */
+            interactionId: string;
+            /**
+             * The interaction kind (e.g. `identity_intake`).
+             */
+            kind: string;
+            /**
+             * One entry per failed field. `field` is a kind-specific field key (identity_intake: `name` | `email` | `phone`).
+             *
+             * @minItems 1
+             */
+            errors: [
+                {
+                    /**
+                     * The kind-specific field that failed validation.
+                     */
+                    field: string;
+                    /**
+                     * Human-readable validation message for this field.
+                     */
+                    message: string;
+                },
+                ...{
+                    /**
+                     * The kind-specific field that failed validation.
+                     */
+                    field: string;
+                    /**
+                     * Human-readable validation message for this field.
+                     */
+                    message: string;
+                }[],
+            ];
+            /**
+             * Human-readable summary suitable for a card-level error line.
+             */
+            message: string;
+        };
+    };
+    /**
+     * Unix epoch milliseconds when the event was emitted.
+     */
+    timestamp?: number;
+}
+
+// ── from events/interaction-required.schema.json ──
+/**
+ * Event: `interaction_required`. The Rich Interactions envelope: emitted mid-turn when the agent requests a structured interaction (identity intake, a date picker, choice chips, …) and the session declared the interaction kind's render capability in `supports` at `create_conversation_session`. The turn is parked until the client replies with a `submit_interaction` action carrying the same `requestId` + `interactionId` (values or `declined: true`). Sessions without the capability never receive this event — the server degrades that kind to its conversational fallback instead. `kind` selects the client card and the server validator; `spec` is the kind-specific payload whose shape is defined by `interactions/<kind>.schema.json` (e.g. `interactions/identity-intake.schema.json#/$defs/Spec`).
+ */
+export interface InteractionRequired {
+    /**
+     * Event type discriminator.
+     */
+    type: 'interaction_required';
+    /**
+     * Echoes the `requestId` from the originating `send_message` action. Must be included in the `submit_interaction` reply.
+     */
+    requestId?: string;
+    /**
+     * Interaction prompt details.
+     */
+    data: {
+        /**
+         * The request ID this interaction belongs to.
+         */
+        requestId: string;
+        /**
+         * The interaction the client should render.
+         */
+        data: {
+            /**
+             * Server-generated ID for this specific interaction instance. Must be echoed on the `submit_interaction` reply so a stale submit can never resolve a newer park.
+             */
+            interactionId: string;
+            /**
+             * The interaction kind (e.g. `identity_intake`). Selects the client's card component and the server's validator. The kind catalog lives in `spec/interactions/`.
+             */
+            kind: string;
+            /**
+             * Kind-specific render spec. Shape per `interactions/<kind>.schema.json#/$defs/Spec` (e.g. identity_intake's `{ fields: [...] }`).
+             */
+            spec: {};
+            /**
+             * Human-readable reason the agent raised this interaction, suitable for the card header (e.g. `to send you the quote`).
+             */
+            reason: string;
+        };
+    };
+    /**
+     * Unix epoch milliseconds when the event was emitted.
+     */
+    timestamp?: number;
+}
+
 // ── from events/keepalive.schema.json ──
 /**
  * Event: `keepalive`. Sent periodically by the server during long-running agent turns (typically every 30 seconds) to prevent AWS API Gateway's 10-minute idle connection timeout from closing the WebSocket while the backend is still computing. Clients should acknowledge receipt by updating their last-seen timestamp, but no reply action is needed. Distinct from `ping`/`pong` which are client-initiated.
@@ -1280,6 +1474,42 @@ export interface StreamChunk {
     timestamp?: number;
 }
 
+// ── from events/stream-reasoning.schema.json ──
+/**
+ * Event: `stream_reasoning`. A single *reasoning* token from a reasoning-model's separate thinking channel (`reasoning_content`/`reasoning` deltas — e.g. DeepSeek, gpt-oss/harmony, MiniMax, GLM), forwarded to the client in real time. Corresponds to smooth-operator's `AgentEvent::ReasoningDelta`. Shaped identically to `stream_token` so clients can render it the same way, but on a distinct `type` so reasoning is shown as collapsible "thinking" and is NEVER folded into the answer. The final response (carried by `eventual_response`) already excludes reasoning. Clients that do not recognize this event MUST ignore it — the answer still streams via `stream_token`, so reasoning simply isn't shown.
+ */
+export interface StreamReasoning {
+    /**
+     * Event type discriminator.
+     */
+    type: 'stream_reasoning';
+    /**
+     * Echoes the `requestId` from the originating `send_message` action.
+     */
+    requestId?: string;
+    /**
+     * The raw reasoning token text. Also present inside `data.token` for consumers that only inspect `data`.
+     */
+    token?: string;
+    /**
+     * Reasoning token event payload.
+     */
+    data: {
+        /**
+         * The request ID this reasoning token belongs to.
+         */
+        requestId: string;
+        /**
+         * The raw reasoning token text.
+         */
+        token: string;
+    };
+    /**
+     * Unix epoch milliseconds when the event was emitted.
+     */
+    timestamp?: number;
+}
+
 // ── from events/stream-token.schema.json ──
 /**
  * Event: `stream_token`. A single LLM output token forwarded to the client in real time. Corresponds to smooth-operator's `AgentEvent::TokenDelta`. Clients accumulate tokens to display a live typing animation. After the node finishes, a `stream_chunk` event carries the complete state snapshot for that node.
@@ -1356,3 +1586,90 @@ export interface WriteConfirmationRequired {
      */
     timestamp?: number;
 }
+
+// ── from interactions/identity-intake.schema.json ──
+/**
+ * The `spec` carried on `interaction_required` for kind `identity_intake`: which fields to collect.
+ */
+export interface IdentityIntakeSpec {
+    /**
+     * The identity fields to collect, in display order.
+     *
+     * @minItems 1
+     */
+    fields: [
+        {
+            /**
+             * Which identity field to collect.
+             */
+            key: 'name' | 'email' | 'phone';
+            /**
+             * Whether the visitor must provide this field to submit.
+             */
+            required: boolean;
+            /**
+             * Optional display label overriding the client's default for this field.
+             */
+            label?: string;
+        },
+        ...{
+            /**
+             * Which identity field to collect.
+             */
+            key: 'name' | 'email' | 'phone';
+            /**
+             * Whether the visitor must provide this field to submit.
+             */
+            required: boolean;
+            /**
+             * Optional display label overriding the client's default for this field.
+             */
+            label?: string;
+        }[],
+    ];
+}
+
+// ── from interactions/identity-intake.schema.json ──
+/**
+ * The `values` a client submits via `submit_interaction` for kind `identity_intake`. Validated server-side: required fields present, email shape, phone normalized to E.164.
+ */
+export interface IdentityIntakeValues {
+    /**
+     * The visitor's display name.
+     */
+    name?: string;
+    /**
+     * The visitor's email address (validated server-side).
+     */
+    email?: string;
+    /**
+     * The visitor's phone number (normalized server-side to E.164).
+     */
+    phone?: string;
+}
+
+// ── from interactions/identity-intake.schema.json ──
+/**
+ * The canonical validated payload the parked turn resumes with (identical on the form and conversational paths). On success the server also attaches the identity to the session (metadata `userName` / `contactEmail` / `contactPhone` — the same keys the OTP contact seam reads).
+ */
+export interface IdentityIntakePayload {
+    /**
+     * How the interaction resolved.
+     */
+    status: 'submitted' | 'declined' | 'no_response';
+    /**
+     * Present when `status` is `submitted`: the validated, normalized values.
+     */
+    values?: {
+        name?: string;
+        email?: string;
+        /**
+         * E.164-normalized (`+15551234567`).
+         */
+        phone?: string;
+    };
+    /**
+     * Guidance for the agent when `status` is `declined` / `no_response`.
+     */
+    message?: string;
+}

package/src/types.ts

@@ -22,6 +22,8 @@ import type {
     GetSessionRequest,
     GetSessionResponse,
     ImmediateResponse,
+    InteractionInvalid,
+    InteractionRequired,
     Keepalive,
     OtpInvalid,
     OtpSent,
@@ -33,6 +35,7 @@ import type {
     SendMessageResponse,
     StreamChunk,
     StreamToken,
+    SubmitInteractionRequest,
     VerifyOtpRequest,
     WriteConfirmationRequired,
 } from './generated/types.js';
@@ -55,6 +58,7 @@ export const ACTION_TYPES = [
     'get_conversation_messages',
     'confirm_tool_action',
     'verify_otp',
+    'submit_interaction',
     'ping',
 ] as const;
 export type ActionType = (typeof ACTION_TYPES)[number];
@@ -71,6 +75,8 @@ export const EVENT_TYPES = [
     'otp_sent',
     'otp_verified',
     'otp_invalid',
+    'interaction_required',
+    'interaction_invalid',
     'error',
     'pong',
 ] as const;
@@ -89,6 +95,7 @@ export type ClientAction =
     | GetMessagesRequest
     | ConfirmToolActionRequest
     | VerifyOtpRequest
+    | SubmitInteractionRequest
     | PingRequest;
 
 // ───────────────────────────── Server events ───────────────────────────────
@@ -108,6 +115,8 @@ export type ServerEvent =
     | OtpSent
     | OtpVerified
     | OtpInvalid
+    | InteractionRequired
+    | InteractionInvalid
     | GeneratedErrorEvent
     | Pong;
 
@@ -125,6 +134,8 @@ export interface ServerEventByType {
     otp_sent: OtpSent;
     otp_verified: OtpVerified;
     otp_invalid: OtpInvalid;
+    interaction_required: InteractionRequired;
+    interaction_invalid: InteractionInvalid;
     error: GeneratedErrorEvent;
     pong: Pong;
 }
@@ -137,6 +148,7 @@ export interface ClientActionByType {
     get_conversation_messages: GetMessagesRequest;
     confirm_tool_action: ConfirmToolActionRequest;
     verify_otp: VerifyOtpRequest;
+    submit_interaction: SubmitInteractionRequest;
     ping: PingRequest;
 }
 

package/src/validate.ts

@@ -47,6 +47,8 @@ const EVENT_SCHEMA_FILE: Record<EventType, string> = {
     otp_sent: 'events/otp-sent.schema.json',
     otp_verified: 'events/otp-verified.schema.json',
     otp_invalid: 'events/otp-invalid.schema.json',
+    interaction_required: 'events/interaction-required.schema.json',
+    interaction_invalid: 'events/interaction-invalid.schema.json',
     error: 'events/error.schema.json',
     pong: 'events/pong.schema.json',
 };
@@ -59,6 +61,7 @@ const ACTION_SCHEMA_REF: Record<ActionType, string> = {
     get_conversation_messages: 'actions/get-messages.schema.json#/$defs/Request',
     confirm_tool_action: 'actions/confirm-tool-action.schema.json#/$defs/Request',
     verify_otp: 'actions/verify-otp.schema.json#/$defs/Request',
+    submit_interaction: 'actions/submit-interaction.schema.json#/$defs/Request',
     ping: 'actions/ping.schema.json#/$defs/Request',
 };
 
@@ -84,7 +87,7 @@ export class ProtocolValidator {
 
         const validator = new ProtocolValidator(ajv);
 
-        for (const sub of ['', 'actions', 'events', 'domain']) {
+        for (const sub of ['', 'actions', 'events', 'domain', 'interactions']) {
             const dir = sub ? join(specDir, sub) : specDir;
             const entries = await readdir(dir, { withFileTypes: true });
             for (const e of entries) {