vessels-sdk 0.11.0 → 0.13.0

package/README.md

@@ -82,11 +82,11 @@ Returns `{ ok: true, messageId: string, vesselId: string, createdAt: string }`.
 | `labels` | `string[]` | Tags for filtering in the dashboard. Max 10, 50 chars each. Replaces the existing set on every push — send all labels you want, not just new ones. |
 | `metadata` | `object` | Arbitrary JSON stored on the vessel, passed through in webhook callbacks. |
 | `card` | `Card` | Structured key-value info attached to this message. `{ title: string, fields: [{ label, value }] }` |
-| `interaction` | `Interaction` | Interactive prompt for the human (one of 5 types — see helpers below). Max one per message; immutable after the human responds. |
+| `interaction` | `Interaction` | Interactive prompt for the human (one of 4 types — see helpers below). Max one per message; immutable after the human responds. |
 | `pinCard` | `Card \| null` | Persistent card pinned to the vessel header. Always visible above the message stream. Replaces any existing pinned card. Pass `null` to clear. |
 | `attachments` | `Attachment[]` | Images or files to show in the message. Max 10. You host the files; Vessels renders them. `[{ type: 'image' \| 'file', url: string, filename?: string }]` |
 | `suggestions` | `string[]` | Quick-reply chips shown below the message. Max 5. Tapping fills the text input. Disappear after the user sends any message. |
-| `previewUrl` | `string` | URL used by `confirm_preview` interactions. |
+| `previewUrl` | `string` | A single URL rendered as a tappable link card below the message. Presentation only — no response. Compose with any interaction. |
 | `notify` | `boolean` | Whether to send a push notification. Default `true`. |
 
 ```typescript
@@ -273,19 +273,18 @@ vessels.textInput({
 
 Response shape: `{ text: string }`
 
-#### `vessels.confirmPreview(opts)`
+#### Review-and-decide (the old `confirmPreview`)
 
-Approve or reject after reviewing an external preview (draft email, document, image).
+There is no separate preview interaction. To have the human review something then decide,
+attach a [`previewUrl`](#push) (a link card) to the message and use `approval`:
 
 ```typescript
-vessels.confirmPreview({
-  prompt: 'Review the draft email before sending.',
+await vessels.push({
+  vessel: 'draft-123',
+  message: 'Draft email ready for review.',
   previewUrl: 'https://your-app.com/drafts/123',
-  previewLabel: 'View draft',
-  approveLabel: 'Send',
-  rejectLabel: 'Edit',
-  reasonRequiredOnReject: true,
-})
+  interaction: vessels.approval({ prompt: 'Send this email?', approveLabel: 'Send', rejectLabel: 'Edit' }),
+});
 ```
 
 Response shape: `{ action: 'approved' | 'rejected', reason?: string }`
@@ -311,7 +310,7 @@ const { events, hasMore } = await vessels.poll({ ack: true });
 
 for (const event of events) {
   if (event.type === 'interaction.response') {
-    // event.interactionType      — 'approval' | 'choice' | 'checklist' | 'text_input' | 'confirm_preview'
+    // event.interactionType      — 'approval' | 'choice' | 'checklist' | 'text_input'
     // event.response             — response shape depends on interactionType (see above)
     // event.interactionMetadata  — metadata object you passed when creating the interaction, or null
     // event.messageId            — UUID of the message containing the interaction
@@ -490,7 +489,6 @@ import type {
   ChoiceInteraction,
   ChecklistInteraction,
   TextInputInteraction,
-  ConfirmPreviewInteraction,
 } from 'vessels-sdk';
 ```
 

package/dist/index.cjs

@@ -8,8 +8,7 @@ var InteractionTypeSchema = zod.z.enum([
   "approval",
   "choice",
   "checklist",
-  "text_input",
-  "confirm_preview"
+  "text_input"
 ]);
 var ApprovalInteractionSchema = zod.z.object({
   type: zod.z.literal("approval"),
@@ -52,22 +51,11 @@ var TextInputInteractionSchema = zod.z.object({
   submitLabel: zod.z.string().optional(),
   metadata: zod.z.record(zod.z.unknown()).optional()
 });
-var ConfirmPreviewInteractionSchema = zod.z.object({
-  type: zod.z.literal("confirm_preview"),
-  prompt: zod.z.string().min(1),
-  previewUrl: zod.z.string().url(),
-  previewLabel: zod.z.string().optional(),
-  approveLabel: zod.z.string().optional(),
-  rejectLabel: zod.z.string().optional(),
-  reasonRequiredOnReject: zod.z.boolean().optional(),
-  metadata: zod.z.record(zod.z.unknown()).optional()
-});
 var InteractionSchema = zod.z.discriminatedUnion("type", [
   ApprovalInteractionSchema,
   ChoiceInteractionSchema,
   ChecklistInteractionSchema,
-  TextInputInteractionSchema,
-  ConfirmPreviewInteractionSchema
+  TextInputInteractionSchema
 ]);
 var AgentActivityTypeSchema = zod.z.enum(["thinking", "searching", "tool_use", "browsing", "processing"]);
 var AgentTodoStatusSchema = zod.z.enum(["pending", "in_progress", "done"]);
@@ -87,7 +75,10 @@ var CardFieldSchema = zod.z.object({
   value: zod.z.string()
 });
 var CardSchema = zod.z.object({
-  title: zod.z.string().min(1),
+  // Optional: a glance-facts card under a surface takes its heading from the
+  // surface `title`, so a card title is redundant there. Still allowed (e.g. a
+  // standalone card on a bubble, or a pinned card).
+  title: zod.z.string().min(1).optional(),
   fields: zod.z.array(CardFieldSchema)
 });
 var AttachmentSchema = zod.z.discriminatedUnion("type", [
@@ -95,6 +86,8 @@ var AttachmentSchema = zod.z.discriminatedUnion("type", [
   zod.z.object({ type: zod.z.literal("file"), url: zod.z.string().url(), filename: zod.z.string().optional() })
 ]);
 var VesselStatusSchema = zod.z.enum(["active", "waiting", "resolved"]);
+var DisplaySchema = zod.z.enum(["bubble", "document"]);
+var KindSchema = zod.z.enum(["bubble", "surface"]);
 var PushPayloadSchema = zod.z.object({
   message: zod.z.string().min(1).max(1e4).optional(),
   vessel: zod.z.string().optional(),
@@ -111,9 +104,23 @@ var PushPayloadSchema = zod.z.object({
   labels: zod.z.array(zod.z.string().min(1).max(50)).max(10).optional(),
   attachments: zod.z.array(AttachmentSchema).max(10).optional(),
   suggestions: zod.z.array(zod.z.string().min(1).max(500)).max(5).optional(),
-  agentActivity: AgentActivitySchema.optional()
-}).refine((d) => d.message || d.agentActivity, {
-  message: "Either message or agentActivity is required"
+  agentActivity: AgentActivitySchema.optional(),
+  /**
+   * Live token-stream buffer — an ephemeral monospace block the human watches
+   * fill in real time (set it on the message you create, then keep replacing it
+   * via `PATCH /messages/:id`, and clear it with `null` when done). It is a live
+   * window, not a transcript: send the tail you want shown (the SDK trims to the
+   * last 8000 chars). Plaintext, like agentActivity. Vanishes when cleared.
+   */
+  tokenStream: zod.z.string().max(8e3).optional(),
+  /** Bubble (chat) vs surface (composed artifact). Defaults from interaction/card. */
+  kind: KindSchema.optional(),
+  /** Surface heading. Ignored on bubbles. */
+  title: zod.z.string().max(200).optional(),
+  /** @deprecated legacy presentation hint — use `kind`. 'document' → surface. */
+  display: DisplaySchema.optional()
+}).refine((d) => d.message || d.agentActivity || d.tokenStream, {
+  message: "One of message, agentActivity, or tokenStream is required"
 });
 var PushManyPayloadSchema = zod.z.object({
   vessels: zod.z.array(zod.z.string().min(1)).min(1).max(100),
@@ -128,14 +135,26 @@ var PushManyPayloadSchema = zod.z.object({
   metadata: zod.z.record(zod.z.unknown()).refine(
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
-  ).optional()
+  ).optional(),
+  kind: KindSchema.optional(),
+  title: zod.z.string().max(200).optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.optional()
 });
 zod.z.object({
   content: zod.z.string().min(1).max(1e4).optional(),
   card: CardSchema.nullable().optional(),
   attachments: zod.z.array(AttachmentSchema).max(10).nullable().optional(),
   suggestions: zod.z.array(zod.z.string().min(1).max(500)).max(5).nullable().optional(),
-  agentActivity: AgentActivitySchema.nullable().optional()
+  agentActivity: AgentActivitySchema.nullable().optional(),
+  /** Replace the live token-stream window, or `null` to clear it (block vanishes). */
+  tokenStream: zod.z.string().max(8e3).nullable().optional(),
+  /** Switch kind: 'surface' = full-width artifact, 'bubble' or null = chat bubble. */
+  kind: KindSchema.nullable().optional(),
+  /** Update the surface heading, or `null` to clear it. */
+  title: zod.z.string().max(200).nullable().optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -153,16 +172,11 @@ var ChecklistResponseSchema = zod.z.object({
 var TextInputResponseSchema = zod.z.object({
   text: zod.z.string()
 });
-var ConfirmPreviewResponseSchema = zod.z.object({
-  action: zod.z.enum(["approved", "rejected"]),
-  reason: zod.z.string().optional()
-});
 zod.z.discriminatedUnion("interactionType", [
   zod.z.object({ interactionType: zod.z.literal("approval"), response: ApprovalResponseSchema }),
   zod.z.object({ interactionType: zod.z.literal("choice"), response: ChoiceResponseSchema }),
   zod.z.object({ interactionType: zod.z.literal("checklist"), response: ChecklistResponseSchema }),
-  zod.z.object({ interactionType: zod.z.literal("text_input"), response: TextInputResponseSchema }),
-  zod.z.object({ interactionType: zod.z.literal("confirm_preview"), response: ConfirmPreviewResponseSchema })
+  zod.z.object({ interactionType: zod.z.literal("text_input"), response: TextInputResponseSchema })
 ]);
 var WebhookVesselSchema = zod.z.object({
   id: zod.z.string(),
@@ -368,6 +382,31 @@ var Vessels = class {
       replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
+  /**
+   * Create a **surface** — a full-width composed artifact the human reviews and
+   * optionally acts on, rendered as one piece: a `title` heading, an optional
+   * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+   * lists, blockquotes, bold headings, links), and an optional `interaction`
+   * (the action bar). Use this for an email/message draft, a quote, an invoice
+   * review, a proposal, a report — anything substantial and structured.
+   *
+   * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+   * message content. For conversation, status updates and quick questions, use
+   * {@link push} instead (a chat **bubble** — the human just replies).
+   *
+   * @example
+   * await vessels.surface({
+   *   vessel: 'inv-42',
+   *   title: 'GreenTurf Invoice #GTL-2025-042',
+   *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+   *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+   *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+   * });
+   */
+  async surface(options) {
+    const { body, ...rest } = options;
+    return this.push({ ...rest, message: body, kind: "surface" });
+  }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
     const check = PushManyPayloadSchema.safeParse(body);
@@ -456,6 +495,79 @@ var Vessels = class {
       }
     };
   }
+  /**
+   * Stream live tokens into a message: the human watches a monospace block fill
+   * in real time. Sugar over {@link editMessage} — it keeps the buffer locally
+   * and PATCHes a throttled, tail-trimmed window (replace-semantics, so a lost
+   * flush self-heals on the next one). Seal with `done()` to clear the block.
+   *
+   * @param messageId the message to stream into (create it first via `push`).
+   * @param opts.throttleMs minimum gap between server flushes (default 120ms).
+   * @param opts.maxChars longest window kept; older text scrolls off (default 8000).
+   */
+  stream(messageId, opts) {
+    const throttleMs = opts?.throttleMs ?? 120;
+    const maxChars = opts?.maxChars ?? 8e3;
+    let buffer = "";
+    let lastSent = null;
+    let timer = null;
+    let pending = Promise.resolve();
+    const windowed = () => buffer.length > maxChars ? buffer.slice(-maxChars) : buffer;
+    const flushNow = () => {
+      const text = windowed();
+      if (text === lastSent) return pending;
+      lastSent = text;
+      pending = this.editMessage(messageId, { tokenStream: text }).catch(() => {
+        lastSent = null;
+      });
+      return pending;
+    };
+    const cancelTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+    const schedule = () => {
+      if (timer) return;
+      timer = setTimeout(() => {
+        timer = null;
+        void flushNow();
+      }, throttleMs);
+      timer?.unref?.();
+    };
+    const settle = async () => {
+      cancelTimer();
+      await pending.catch(() => {
+      });
+    };
+    return {
+      write: (text) => {
+        buffer += text;
+        schedule();
+      },
+      set: async (text) => {
+        buffer = text;
+        cancelTimer();
+        await flushNow();
+      },
+      // Clear the stream AND seal any working card (agentActivity: null is a no-op
+      // when there's none), so the final content actually renders.
+      done: async (finalContent) => {
+        await settle();
+        await this.editMessage(messageId, {
+          tokenStream: null,
+          agentActivity: null,
+          ...finalContent != null ? { content: finalContent } : {}
+        });
+      },
+      // Remove only the stream; leave the working card alone.
+      clear: async () => {
+        await settle();
+        await this.editMessage(messageId, { tokenStream: null });
+      }
+    };
+  }
   /**
    * Read a vessel's message history — the human-facing record, for re-reading
    * the channel (e.g. a stateless or just-restarted worker reconciling state).
@@ -501,9 +613,6 @@ var Vessels = class {
   textInput(opts) {
     return { type: "text_input", ...opts };
   }
-  confirmPreview(opts) {
-    return { type: "confirm_preview", ...opts };
-  }
   async poll(options = {}) {
     const { since, limit = 50, ack = true } = options;
     const params = new URLSearchParams();

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _vessels_types from '@vessels/types';
-export { AgentActivity, AgentActivityType, AgentTodoInput, AgentTodoStatus, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
+export { AgentActivity, AgentActivityType, AgentTodoInput, AgentTodoStatus, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
 
 declare const AgentActivityTypes: {
     readonly thinking: "thinking";
@@ -70,6 +70,34 @@ interface ActivityHandle {
     /** Seal the activity — finishes the open step and any in-progress task. */
     done(): Promise<void>;
 }
+/**
+ * A handle for streaming live tokens into a message — the human watches a
+ * monospace block fill in real time, and it vanishes when you seal it. Obtain
+ * one with {@link Vessels.stream}; the message must already exist (get its id
+ * from {@link Vessels.push}). It is a live WINDOW, not a transcript: write all
+ * you like, only the last `maxChars` (default 8000) are shown.
+ *
+ * ```ts
+ * const { messageId } = await vessels.push({ vessel, agentActivity: { type: 'thinking' } });
+ * const out = vessels.stream(messageId);
+ * for await (const tok of llm) out.write(tok);   // throttled PATCHes under the hood
+ * await out.done('Booked you in for 2pm Thursday.');  // clears the stream, sets the final reply
+ * ```
+ */
+interface StreamHandle {
+    /** Append text to the live buffer; flushed to the server on a throttle. */
+    write(text: string): void;
+    /** Replace the whole buffer and flush immediately. */
+    set(text: string): Promise<void>;
+    /**
+     * Finish the turn: flush, clear the block, and seal any working agent-activity
+     * card (a no-op if there is none) — optionally setting the message's final
+     * content. Use this when the stream was the last thing you were doing.
+     */
+    done(finalContent?: string): Promise<void>;
+    /** Just remove the block, leaving any working card untouched (you're still working). */
+    clear(): Promise<void>;
+}
 interface PushResponse {
     ok: true;
     messageId: string;
@@ -78,6 +106,14 @@ interface PushResponse {
     /** True when this response is a replay of an earlier request with the same idempotency key. */
     replayed: boolean;
 }
+/**
+ * Options for {@link Vessels.surface}. Same as a push, but the artifact text is
+ * `body` (not `message`) and `kind` is forced to `'surface'`.
+ */
+type SurfaceOptions = Omit<_vessels_types.PushOptions, 'message' | 'kind'> & {
+    /** The artifact body — block markdown (tables, lists, blockquotes, bold headings, links). */
+    body: string;
+};
 interface PushManyResult {
     ok: true;
     results: Array<{
@@ -205,6 +241,28 @@ declare class Vessels {
     /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
     validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    /**
+     * Create a **surface** — a full-width composed artifact the human reviews and
+     * optionally acts on, rendered as one piece: a `title` heading, an optional
+     * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+     * lists, blockquotes, bold headings, links), and an optional `interaction`
+     * (the action bar). Use this for an email/message draft, a quote, an invoice
+     * review, a proposal, a report — anything substantial and structured.
+     *
+     * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+     * message content. For conversation, status updates and quick questions, use
+     * {@link push} instead (a chat **bubble** — the human just replies).
+     *
+     * @example
+     * await vessels.surface({
+     *   vessel: 'inv-42',
+     *   title: 'GreenTurf Invoice #GTL-2025-042',
+     *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+     *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+     *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+     * });
+     */
+    surface(options: SurfaceOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
@@ -217,6 +275,20 @@ declare class Vessels {
      * its id from {@link push}.
      */
     activity(messageId: string): ActivityHandle;
+    /**
+     * Stream live tokens into a message: the human watches a monospace block fill
+     * in real time. Sugar over {@link editMessage} — it keeps the buffer locally
+     * and PATCHes a throttled, tail-trimmed window (replace-semantics, so a lost
+     * flush self-heals on the next one). Seal with `done()` to clear the block.
+     *
+     * @param messageId the message to stream into (create it first via `push`).
+     * @param opts.throttleMs minimum gap between server flushes (default 120ms).
+     * @param opts.maxChars longest window kept; older text scrolls off (default 8000).
+     */
+    stream(messageId: string, opts?: {
+        throttleMs?: number;
+        maxChars?: number;
+    }): StreamHandle;
     /**
      * Read a vessel's message history — the human-facing record, for re-reading
      * the channel (e.g. a stateless or just-restarted worker reconciling state).
@@ -268,18 +340,9 @@ declare class Vessels {
         submitLabel?: string;
         metadata?: Record<string, unknown>;
     }): _vessels_types.TextInputInteraction;
-    confirmPreview(opts: {
-        prompt: string;
-        previewUrl: string;
-        previewLabel?: string;
-        approveLabel?: string;
-        rejectLabel?: string;
-        reasonRequiredOnReject?: boolean;
-        metadata?: Record<string, unknown>;
-    }): _vessels_types.ConfirmPreviewInteraction;
     poll(options?: PollOptions): Promise<PollResponse>;
     verifyWebhook(body: string, signature: string, webhookSecret: string): Promise<boolean>;
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | MessageCancelledEvent | null>;
 }
 
-export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };
+export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type SurfaceOptions, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _vessels_types from '@vessels/types';
-export { AgentActivity, AgentActivityType, AgentTodoInput, AgentTodoStatus, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
+export { AgentActivity, AgentActivityType, AgentTodoInput, AgentTodoStatus, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
 
 declare const AgentActivityTypes: {
     readonly thinking: "thinking";
@@ -70,6 +70,34 @@ interface ActivityHandle {
     /** Seal the activity — finishes the open step and any in-progress task. */
     done(): Promise<void>;
 }
+/**
+ * A handle for streaming live tokens into a message — the human watches a
+ * monospace block fill in real time, and it vanishes when you seal it. Obtain
+ * one with {@link Vessels.stream}; the message must already exist (get its id
+ * from {@link Vessels.push}). It is a live WINDOW, not a transcript: write all
+ * you like, only the last `maxChars` (default 8000) are shown.
+ *
+ * ```ts
+ * const { messageId } = await vessels.push({ vessel, agentActivity: { type: 'thinking' } });
+ * const out = vessels.stream(messageId);
+ * for await (const tok of llm) out.write(tok);   // throttled PATCHes under the hood
+ * await out.done('Booked you in for 2pm Thursday.');  // clears the stream, sets the final reply
+ * ```
+ */
+interface StreamHandle {
+    /** Append text to the live buffer; flushed to the server on a throttle. */
+    write(text: string): void;
+    /** Replace the whole buffer and flush immediately. */
+    set(text: string): Promise<void>;
+    /**
+     * Finish the turn: flush, clear the block, and seal any working agent-activity
+     * card (a no-op if there is none) — optionally setting the message's final
+     * content. Use this when the stream was the last thing you were doing.
+     */
+    done(finalContent?: string): Promise<void>;
+    /** Just remove the block, leaving any working card untouched (you're still working). */
+    clear(): Promise<void>;
+}
 interface PushResponse {
     ok: true;
     messageId: string;
@@ -78,6 +106,14 @@ interface PushResponse {
     /** True when this response is a replay of an earlier request with the same idempotency key. */
     replayed: boolean;
 }
+/**
+ * Options for {@link Vessels.surface}. Same as a push, but the artifact text is
+ * `body` (not `message`) and `kind` is forced to `'surface'`.
+ */
+type SurfaceOptions = Omit<_vessels_types.PushOptions, 'message' | 'kind'> & {
+    /** The artifact body — block markdown (tables, lists, blockquotes, bold headings, links). */
+    body: string;
+};
 interface PushManyResult {
     ok: true;
     results: Array<{
@@ -205,6 +241,28 @@ declare class Vessels {
     /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
     validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    /**
+     * Create a **surface** — a full-width composed artifact the human reviews and
+     * optionally acts on, rendered as one piece: a `title` heading, an optional
+     * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+     * lists, blockquotes, bold headings, links), and an optional `interaction`
+     * (the action bar). Use this for an email/message draft, a quote, an invoice
+     * review, a proposal, a report — anything substantial and structured.
+     *
+     * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+     * message content. For conversation, status updates and quick questions, use
+     * {@link push} instead (a chat **bubble** — the human just replies).
+     *
+     * @example
+     * await vessels.surface({
+     *   vessel: 'inv-42',
+     *   title: 'GreenTurf Invoice #GTL-2025-042',
+     *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+     *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+     *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+     * });
+     */
+    surface(options: SurfaceOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
@@ -217,6 +275,20 @@ declare class Vessels {
      * its id from {@link push}.
      */
     activity(messageId: string): ActivityHandle;
+    /**
+     * Stream live tokens into a message: the human watches a monospace block fill
+     * in real time. Sugar over {@link editMessage} — it keeps the buffer locally
+     * and PATCHes a throttled, tail-trimmed window (replace-semantics, so a lost
+     * flush self-heals on the next one). Seal with `done()` to clear the block.
+     *
+     * @param messageId the message to stream into (create it first via `push`).
+     * @param opts.throttleMs minimum gap between server flushes (default 120ms).
+     * @param opts.maxChars longest window kept; older text scrolls off (default 8000).
+     */
+    stream(messageId: string, opts?: {
+        throttleMs?: number;
+        maxChars?: number;
+    }): StreamHandle;
     /**
      * Read a vessel's message history — the human-facing record, for re-reading
      * the channel (e.g. a stateless or just-restarted worker reconciling state).
@@ -268,18 +340,9 @@ declare class Vessels {
         submitLabel?: string;
         metadata?: Record<string, unknown>;
     }): _vessels_types.TextInputInteraction;
-    confirmPreview(opts: {
-        prompt: string;
-        previewUrl: string;
-        previewLabel?: string;
-        approveLabel?: string;
-        rejectLabel?: string;
-        reasonRequiredOnReject?: boolean;
-        metadata?: Record<string, unknown>;
-    }): _vessels_types.ConfirmPreviewInteraction;
     poll(options?: PollOptions): Promise<PollResponse>;
     verifyWebhook(body: string, signature: string, webhookSecret: string): Promise<boolean>;
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | MessageCancelledEvent | null>;
 }
 
-export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };
+export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type SurfaceOptions, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.js

@@ -6,8 +6,7 @@ var InteractionTypeSchema = z.enum([
   "approval",
   "choice",
   "checklist",
-  "text_input",
-  "confirm_preview"
+  "text_input"
 ]);
 var ApprovalInteractionSchema = z.object({
   type: z.literal("approval"),
@@ -50,22 +49,11 @@ var TextInputInteractionSchema = z.object({
   submitLabel: z.string().optional(),
   metadata: z.record(z.unknown()).optional()
 });
-var ConfirmPreviewInteractionSchema = z.object({
-  type: z.literal("confirm_preview"),
-  prompt: z.string().min(1),
-  previewUrl: z.string().url(),
-  previewLabel: z.string().optional(),
-  approveLabel: z.string().optional(),
-  rejectLabel: z.string().optional(),
-  reasonRequiredOnReject: z.boolean().optional(),
-  metadata: z.record(z.unknown()).optional()
-});
 var InteractionSchema = z.discriminatedUnion("type", [
   ApprovalInteractionSchema,
   ChoiceInteractionSchema,
   ChecklistInteractionSchema,
-  TextInputInteractionSchema,
-  ConfirmPreviewInteractionSchema
+  TextInputInteractionSchema
 ]);
 var AgentActivityTypeSchema = z.enum(["thinking", "searching", "tool_use", "browsing", "processing"]);
 var AgentTodoStatusSchema = z.enum(["pending", "in_progress", "done"]);
@@ -85,7 +73,10 @@ var CardFieldSchema = z.object({
   value: z.string()
 });
 var CardSchema = z.object({
-  title: z.string().min(1),
+  // Optional: a glance-facts card under a surface takes its heading from the
+  // surface `title`, so a card title is redundant there. Still allowed (e.g. a
+  // standalone card on a bubble, or a pinned card).
+  title: z.string().min(1).optional(),
   fields: z.array(CardFieldSchema)
 });
 var AttachmentSchema = z.discriminatedUnion("type", [
@@ -93,6 +84,8 @@ var AttachmentSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("file"), url: z.string().url(), filename: z.string().optional() })
 ]);
 var VesselStatusSchema = z.enum(["active", "waiting", "resolved"]);
+var DisplaySchema = z.enum(["bubble", "document"]);
+var KindSchema = z.enum(["bubble", "surface"]);
 var PushPayloadSchema = z.object({
   message: z.string().min(1).max(1e4).optional(),
   vessel: z.string().optional(),
@@ -109,9 +102,23 @@ var PushPayloadSchema = z.object({
   labels: z.array(z.string().min(1).max(50)).max(10).optional(),
   attachments: z.array(AttachmentSchema).max(10).optional(),
   suggestions: z.array(z.string().min(1).max(500)).max(5).optional(),
-  agentActivity: AgentActivitySchema.optional()
-}).refine((d) => d.message || d.agentActivity, {
-  message: "Either message or agentActivity is required"
+  agentActivity: AgentActivitySchema.optional(),
+  /**
+   * Live token-stream buffer — an ephemeral monospace block the human watches
+   * fill in real time (set it on the message you create, then keep replacing it
+   * via `PATCH /messages/:id`, and clear it with `null` when done). It is a live
+   * window, not a transcript: send the tail you want shown (the SDK trims to the
+   * last 8000 chars). Plaintext, like agentActivity. Vanishes when cleared.
+   */
+  tokenStream: z.string().max(8e3).optional(),
+  /** Bubble (chat) vs surface (composed artifact). Defaults from interaction/card. */
+  kind: KindSchema.optional(),
+  /** Surface heading. Ignored on bubbles. */
+  title: z.string().max(200).optional(),
+  /** @deprecated legacy presentation hint — use `kind`. 'document' → surface. */
+  display: DisplaySchema.optional()
+}).refine((d) => d.message || d.agentActivity || d.tokenStream, {
+  message: "One of message, agentActivity, or tokenStream is required"
 });
 var PushManyPayloadSchema = z.object({
   vessels: z.array(z.string().min(1)).min(1).max(100),
@@ -126,14 +133,26 @@ var PushManyPayloadSchema = z.object({
   metadata: z.record(z.unknown()).refine(
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
-  ).optional()
+  ).optional(),
+  kind: KindSchema.optional(),
+  title: z.string().max(200).optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.optional()
 });
 z.object({
   content: z.string().min(1).max(1e4).optional(),
   card: CardSchema.nullable().optional(),
   attachments: z.array(AttachmentSchema).max(10).nullable().optional(),
   suggestions: z.array(z.string().min(1).max(500)).max(5).nullable().optional(),
-  agentActivity: AgentActivitySchema.nullable().optional()
+  agentActivity: AgentActivitySchema.nullable().optional(),
+  /** Replace the live token-stream window, or `null` to clear it (block vanishes). */
+  tokenStream: z.string().max(8e3).nullable().optional(),
+  /** Switch kind: 'surface' = full-width artifact, 'bubble' or null = chat bubble. */
+  kind: KindSchema.nullable().optional(),
+  /** Update the surface heading, or `null` to clear it. */
+  title: z.string().max(200).nullable().optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -151,16 +170,11 @@ var ChecklistResponseSchema = z.object({
 var TextInputResponseSchema = z.object({
   text: z.string()
 });
-var ConfirmPreviewResponseSchema = z.object({
-  action: z.enum(["approved", "rejected"]),
-  reason: z.string().optional()
-});
 z.discriminatedUnion("interactionType", [
   z.object({ interactionType: z.literal("approval"), response: ApprovalResponseSchema }),
   z.object({ interactionType: z.literal("choice"), response: ChoiceResponseSchema }),
   z.object({ interactionType: z.literal("checklist"), response: ChecklistResponseSchema }),
-  z.object({ interactionType: z.literal("text_input"), response: TextInputResponseSchema }),
-  z.object({ interactionType: z.literal("confirm_preview"), response: ConfirmPreviewResponseSchema })
+  z.object({ interactionType: z.literal("text_input"), response: TextInputResponseSchema })
 ]);
 var WebhookVesselSchema = z.object({
   id: z.string(),
@@ -366,6 +380,31 @@ var Vessels = class {
       replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
+  /**
+   * Create a **surface** — a full-width composed artifact the human reviews and
+   * optionally acts on, rendered as one piece: a `title` heading, an optional
+   * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+   * lists, blockquotes, bold headings, links), and an optional `interaction`
+   * (the action bar). Use this for an email/message draft, a quote, an invoice
+   * review, a proposal, a report — anything substantial and structured.
+   *
+   * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+   * message content. For conversation, status updates and quick questions, use
+   * {@link push} instead (a chat **bubble** — the human just replies).
+   *
+   * @example
+   * await vessels.surface({
+   *   vessel: 'inv-42',
+   *   title: 'GreenTurf Invoice #GTL-2025-042',
+   *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+   *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+   *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+   * });
+   */
+  async surface(options) {
+    const { body, ...rest } = options;
+    return this.push({ ...rest, message: body, kind: "surface" });
+  }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
     const check = PushManyPayloadSchema.safeParse(body);
@@ -454,6 +493,79 @@ var Vessels = class {
       }
     };
   }
+  /**
+   * Stream live tokens into a message: the human watches a monospace block fill
+   * in real time. Sugar over {@link editMessage} — it keeps the buffer locally
+   * and PATCHes a throttled, tail-trimmed window (replace-semantics, so a lost
+   * flush self-heals on the next one). Seal with `done()` to clear the block.
+   *
+   * @param messageId the message to stream into (create it first via `push`).
+   * @param opts.throttleMs minimum gap between server flushes (default 120ms).
+   * @param opts.maxChars longest window kept; older text scrolls off (default 8000).
+   */
+  stream(messageId, opts) {
+    const throttleMs = opts?.throttleMs ?? 120;
+    const maxChars = opts?.maxChars ?? 8e3;
+    let buffer = "";
+    let lastSent = null;
+    let timer = null;
+    let pending = Promise.resolve();
+    const windowed = () => buffer.length > maxChars ? buffer.slice(-maxChars) : buffer;
+    const flushNow = () => {
+      const text = windowed();
+      if (text === lastSent) return pending;
+      lastSent = text;
+      pending = this.editMessage(messageId, { tokenStream: text }).catch(() => {
+        lastSent = null;
+      });
+      return pending;
+    };
+    const cancelTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+    const schedule = () => {
+      if (timer) return;
+      timer = setTimeout(() => {
+        timer = null;
+        void flushNow();
+      }, throttleMs);
+      timer?.unref?.();
+    };
+    const settle = async () => {
+      cancelTimer();
+      await pending.catch(() => {
+      });
+    };
+    return {
+      write: (text) => {
+        buffer += text;
+        schedule();
+      },
+      set: async (text) => {
+        buffer = text;
+        cancelTimer();
+        await flushNow();
+      },
+      // Clear the stream AND seal any working card (agentActivity: null is a no-op
+      // when there's none), so the final content actually renders.
+      done: async (finalContent) => {
+        await settle();
+        await this.editMessage(messageId, {
+          tokenStream: null,
+          agentActivity: null,
+          ...finalContent != null ? { content: finalContent } : {}
+        });
+      },
+      // Remove only the stream; leave the working card alone.
+      clear: async () => {
+        await settle();
+        await this.editMessage(messageId, { tokenStream: null });
+      }
+    };
+  }
   /**
    * Read a vessel's message history — the human-facing record, for re-reading
    * the channel (e.g. a stateless or just-restarted worker reconciling state).
@@ -499,9 +611,6 @@ var Vessels = class {
   textInput(opts) {
     return { type: "text_input", ...opts };
   }
-  confirmPreview(opts) {
-    return { type: "confirm_preview", ...opts };
-  }
   async poll(options = {}) {
     const { since, limit = 50, ack = true } = options;
     const params = new URLSearchParams();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vessels-sdk",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"description": "Let your agent reach you. Official Vessels SDK.",
 	"type": "module",
 	"exports": {