vessels-sdk 0.9.0 → 0.12.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
@@ -144,6 +144,29 @@ for (const r of results) {
 
 ---
 
+### `vessels.validatePush(payload)` / `vessels.validatePushMany(payload)`
+
+Check that a payload complies with the required syntax **without sending anything**. Useful for confirming an agent's message is well-formed in a test or dry run before it reaches a human. This runs the **same schema the server enforces**, so a payload that passes here is exactly one the API will accept.
+
+Returns `{ valid: boolean, errors: string[], details? }` — `errors` is a list of readable `field.path: message` lines; `details` is Zod's `flatten()` output (`{ formErrors, fieldErrors }`).
+
+```typescript
+const check = vessels.validatePush({
+  vessel: 'booking-123',
+  message: 'New booking',
+  interaction: { type: 'approval', prompt: 'Confirm?' },
+});
+
+if (!check.valid) {
+  console.error(check.errors);
+  // e.g. ['suggestions: Array must contain at most 5 element(s)']
+}
+```
+
+You don't have to call this explicitly: `push()` and `pushMany()` run the same check internally and throw a `VesselsValidationError` **before** the network request, so a malformed payload fails fast without burning an API call. Call `validatePush` directly when you want a result object instead of an exception.
+
+---
+
 ### `vessels.editMessage(messageId, patch)`
 
 Edit an existing agent-sent message in place. The message re-renders via Supabase Realtime without reloading.
@@ -250,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 }`
@@ -288,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
@@ -416,7 +438,7 @@ Three typed error classes are exported alongside `Vessels`:
 | Class | HTTP status | Description |
 |-------|-------------|-------------|
 | `VesselsAuthError` | 401 | Invalid or revoked API key |
-| `VesselsValidationError` | 400 | Bad request payload. Check `.details` for field-level errors. |
+| `VesselsValidationError` | 400 | Bad request payload. Also thrown **locally, before the request** by `push()`/`pushMany()` when the payload fails client-side validation. Check `.details` for field-level errors. |
 | `VesselsRateLimitError` | 429 | Rate limit exceeded. Check `.retryAfter` (seconds) before retrying. |
 
 ```typescript
@@ -467,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,27 +51,24 @@ 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"]);
+var AgentTodoInputSchema = zod.z.object({
+  label: zod.z.string().min(1).max(200),
+  status: AgentTodoStatusSchema.optional()
+});
 var AgentActivitySchema = zod.z.object({
-  type: AgentActivityTypeSchema,
-  label: zod.z.string().max(200).optional()
+  type: AgentActivityTypeSchema.optional(),
+  label: zod.z.string().max(200).optional(),
+  todos: zod.z.array(AgentTodoInputSchema).max(50).optional()
+}).refine((d) => d.type != null || d.todos != null, {
+  message: "agentActivity requires `type` (a step) or `todos` (a plan)"
 });
 var CardFieldSchema = zod.z.object({
   label: zod.z.string().min(1),
@@ -87,7 +83,7 @@ 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"]);
-zod.z.object({
+var PushPayloadSchema = zod.z.object({
   message: zod.z.string().min(1).max(1e4).optional(),
   vessel: zod.z.string().optional(),
   vesselTitle: zod.z.string().optional(),
@@ -103,11 +99,19 @@ 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()
+}).refine((d) => d.message || d.agentActivity || d.tokenStream, {
+  message: "One of message, agentActivity, or tokenStream is required"
 });
-zod.z.object({
+var PushManyPayloadSchema = zod.z.object({
   vessels: zod.z.array(zod.z.string().min(1)).min(1).max(100),
   message: zod.z.string().min(1).max(1e4),
   vesselTitle: zod.z.string().optional(),
@@ -127,7 +131,9 @@ zod.z.object({
   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()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -145,16 +151,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(),
@@ -271,6 +272,13 @@ var VesselsConflictError = class extends Error {
     this.name = "VesselsConflictError";
   }
 };
+function formatZodError(error) {
+  const errors = error.issues.map((i) => {
+    const path = i.path.join(".") || "(payload)";
+    return `${path}: ${i.message}`;
+  });
+  return { errors, details: error.flatten() };
+}
 var Vessels = class {
   apiKey;
   baseUrl;
@@ -303,8 +311,33 @@ var Vessels = class {
     }
     return res;
   }
+  /**
+   * Check a push payload against the schema the server enforces, WITHOUT sending
+   * anything. Use this to confirm an agent's message complies before it goes
+   * live (e.g. in a test or a dry-run). `push()` runs the same check internally.
+   */
+  validatePush(payload) {
+    const { idempotencyKey: _ignored, ...body } = payload;
+    const result = PushPayloadSchema.safeParse(body);
+    if (result.success) return { valid: true, errors: [] };
+    const { errors, details } = formatZodError(result.error);
+    return { valid: false, errors, details };
+  }
+  /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
+  validatePushMany(payload) {
+    const { idempotencyKey: _ignored, ...body } = payload;
+    const result = PushManyPayloadSchema.safeParse(body);
+    if (result.success) return { valid: true, errors: [] };
+    const { errors, details } = formatZodError(result.error);
+    return { valid: false, errors, details };
+  }
   async push(payload) {
     const { idempotencyKey, ...body } = payload;
+    const check = PushPayloadSchema.safeParse(body);
+    if (!check.success) {
+      const { errors, details } = formatZodError(check.error);
+      throw new VesselsValidationError(`Invalid push payload \u2014 ${errors.join("; ")}`, details);
+    }
     const res = await this._fetch(`${this.baseUrl}/api/v1/push`, {
       method: "POST",
       headers: {
@@ -330,6 +363,11 @@ var Vessels = class {
   }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
+    const check = PushManyPayloadSchema.safeParse(body);
+    if (!check.success) {
+      const { errors, details } = formatZodError(check.error);
+      throw new VesselsValidationError(`Invalid pushMany payload \u2014 ${errors.join("; ")}`, details);
+    }
     const res = await this._fetch(`${this.baseUrl}/api/v1/push/many`, {
       method: "POST",
       headers: {
@@ -373,6 +411,117 @@ var Vessels = class {
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return { ok: true };
   }
+  /**
+   * Narrate a working message: declare a plan, file steps under each task as you
+   * go, and seal it when done. Sugar over {@link editMessage} — it tracks the
+   * todo list locally and PATCHes the full list each update (the server is
+   * authoritative and reconciles by label). The message must already exist; get
+   * its id from {@link push}.
+   */
+  activity(messageId) {
+    let todos = [];
+    const sendTodos = () => this.editMessage(messageId, { agentActivity: { todos } });
+    return {
+      plan: async (tasks) => {
+        todos = tasks.map(
+          (t) => typeof t === "string" ? { label: t, status: "pending" } : { label: t.label, status: t.status ?? "pending" }
+        );
+        await sendTodos();
+      },
+      start: async (label) => {
+        todos = todos.map(
+          (t) => t.label === label ? { ...t, status: "in_progress" } : t.status === "in_progress" ? { ...t, status: "done" } : t
+        );
+        if (!todos.some((t) => t.label === label)) todos.push({ label, status: "in_progress" });
+        await sendTodos();
+      },
+      step: async (type, label) => {
+        await this.editMessage(messageId, { agentActivity: { type, label } });
+      },
+      complete: async (label) => {
+        todos = todos.map(
+          (t) => (label ? t.label === label : t.status === "in_progress") ? { ...t, status: "done" } : t
+        );
+        await sendTodos();
+      },
+      done: async () => {
+        await this.editMessage(messageId, { agentActivity: null });
+      }
+    };
+  }
+  /**
+   * 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).
@@ -418,9 +567,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, 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";
@@ -23,11 +23,81 @@ declare class VesselsRateLimitError extends Error {
 declare class VesselsConflictError extends Error {
     constructor(message: string);
 }
+/** Result of a client-side payload check via {@link Vessels.validatePush}. */
+interface ValidationResult {
+    /** True when the payload satisfies the schema the server enforces. */
+    valid: boolean;
+    /** Human-readable `field.path: message` lines — empty when valid. */
+    errors: string[];
+    /** Zod `flatten()` output (field + form errors) — present only when invalid. */
+    details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    };
+}
 interface VesselsConfig {
     apiKey: string;
     baseUrl?: string;
     debug?: boolean;
 }
+/**
+ * A stateful handle for narrating a working message — the plan and the work it
+ * produces resolve into one artifact. Steps emitted while a task is active are
+ * filed under it server-side. Obtain one with {@link Vessels.activity}.
+ *
+ * ```ts
+ * const act = vessels.activity(messageId);
+ * await act.plan(['Check availability', 'Draft email', 'Send to customer']);
+ * await act.start('Check availability');           // → in_progress, step target
+ * await act.step('searching', 'Querying calendar');
+ * await act.start('Draft email');                  // auto-finishes the prior task
+ * await act.step('tool_use', 'Sending via SendGrid');
+ * await act.done();                                // seals everything
+ * ```
+ */
+interface ActivityHandle {
+    /** Declare (or replace) the plan. Tasks default to `pending`. */
+    plan(tasks: Array<string | {
+        label: string;
+        status?: _vessels_types.AgentTodoStatus;
+    }>): Promise<void>;
+    /** Mark a task in-progress (creating it if new); any other in-progress task is finished. */
+    start(label: string): Promise<void>;
+    /** Append a step, filed under the active task. */
+    step(type: _vessels_types.AgentActivityType, label?: string): Promise<void>;
+    /** Finish a task by label, or the current in-progress task if omitted. */
+    complete(label?: string): Promise<void>;
+    /** 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;
@@ -154,11 +224,41 @@ declare class Vessels {
     private _debug;
     constructor(config: VesselsConfig);
     private _fetch;
+    /**
+     * Check a push payload against the schema the server enforces, WITHOUT sending
+     * anything. Use this to confirm an agent's message complies before it goes
+     * live (e.g. in a test or a dry-run). `push()` runs the same check internally.
+     */
+    validatePush(payload: _vessels_types.PushOptions): ValidationResult;
+    /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
+    validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
     }>;
+    /**
+     * Narrate a working message: declare a plan, file steps under each task as you
+     * go, and seal it when done. Sugar over {@link editMessage} — it tracks the
+     * todo list locally and PATCHes the full list each update (the server is
+     * authoritative and reconciles by label). The message must already exist; get
+     * 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).
@@ -210,18 +310,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 { AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, 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 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, 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";
@@ -23,11 +23,81 @@ declare class VesselsRateLimitError extends Error {
 declare class VesselsConflictError extends Error {
     constructor(message: string);
 }
+/** Result of a client-side payload check via {@link Vessels.validatePush}. */
+interface ValidationResult {
+    /** True when the payload satisfies the schema the server enforces. */
+    valid: boolean;
+    /** Human-readable `field.path: message` lines — empty when valid. */
+    errors: string[];
+    /** Zod `flatten()` output (field + form errors) — present only when invalid. */
+    details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    };
+}
 interface VesselsConfig {
     apiKey: string;
     baseUrl?: string;
     debug?: boolean;
 }
+/**
+ * A stateful handle for narrating a working message — the plan and the work it
+ * produces resolve into one artifact. Steps emitted while a task is active are
+ * filed under it server-side. Obtain one with {@link Vessels.activity}.
+ *
+ * ```ts
+ * const act = vessels.activity(messageId);
+ * await act.plan(['Check availability', 'Draft email', 'Send to customer']);
+ * await act.start('Check availability');           // → in_progress, step target
+ * await act.step('searching', 'Querying calendar');
+ * await act.start('Draft email');                  // auto-finishes the prior task
+ * await act.step('tool_use', 'Sending via SendGrid');
+ * await act.done();                                // seals everything
+ * ```
+ */
+interface ActivityHandle {
+    /** Declare (or replace) the plan. Tasks default to `pending`. */
+    plan(tasks: Array<string | {
+        label: string;
+        status?: _vessels_types.AgentTodoStatus;
+    }>): Promise<void>;
+    /** Mark a task in-progress (creating it if new); any other in-progress task is finished. */
+    start(label: string): Promise<void>;
+    /** Append a step, filed under the active task. */
+    step(type: _vessels_types.AgentActivityType, label?: string): Promise<void>;
+    /** Finish a task by label, or the current in-progress task if omitted. */
+    complete(label?: string): Promise<void>;
+    /** 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;
@@ -154,11 +224,41 @@ declare class Vessels {
     private _debug;
     constructor(config: VesselsConfig);
     private _fetch;
+    /**
+     * Check a push payload against the schema the server enforces, WITHOUT sending
+     * anything. Use this to confirm an agent's message complies before it goes
+     * live (e.g. in a test or a dry-run). `push()` runs the same check internally.
+     */
+    validatePush(payload: _vessels_types.PushOptions): ValidationResult;
+    /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
+    validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
     }>;
+    /**
+     * Narrate a working message: declare a plan, file steps under each task as you
+     * go, and seal it when done. Sugar over {@link editMessage} — it tracks the
+     * todo list locally and PATCHes the full list each update (the server is
+     * authoritative and reconciles by label). The message must already exist; get
+     * 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).
@@ -210,18 +310,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 { AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, 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 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,27 +49,24 @@ 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"]);
+var AgentTodoInputSchema = z.object({
+  label: z.string().min(1).max(200),
+  status: AgentTodoStatusSchema.optional()
+});
 var AgentActivitySchema = z.object({
-  type: AgentActivityTypeSchema,
-  label: z.string().max(200).optional()
+  type: AgentActivityTypeSchema.optional(),
+  label: z.string().max(200).optional(),
+  todos: z.array(AgentTodoInputSchema).max(50).optional()
+}).refine((d) => d.type != null || d.todos != null, {
+  message: "agentActivity requires `type` (a step) or `todos` (a plan)"
 });
 var CardFieldSchema = z.object({
   label: z.string().min(1),
@@ -85,7 +81,7 @@ 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"]);
-z.object({
+var PushPayloadSchema = z.object({
   message: z.string().min(1).max(1e4).optional(),
   vessel: z.string().optional(),
   vesselTitle: z.string().optional(),
@@ -101,11 +97,19 @@ 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()
+}).refine((d) => d.message || d.agentActivity || d.tokenStream, {
+  message: "One of message, agentActivity, or tokenStream is required"
 });
-z.object({
+var PushManyPayloadSchema = z.object({
   vessels: z.array(z.string().min(1)).min(1).max(100),
   message: z.string().min(1).max(1e4),
   vesselTitle: z.string().optional(),
@@ -125,7 +129,9 @@ z.object({
   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()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -143,16 +149,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(),
@@ -269,6 +270,13 @@ var VesselsConflictError = class extends Error {
     this.name = "VesselsConflictError";
   }
 };
+function formatZodError(error) {
+  const errors = error.issues.map((i) => {
+    const path = i.path.join(".") || "(payload)";
+    return `${path}: ${i.message}`;
+  });
+  return { errors, details: error.flatten() };
+}
 var Vessels = class {
   apiKey;
   baseUrl;
@@ -301,8 +309,33 @@ var Vessels = class {
     }
     return res;
   }
+  /**
+   * Check a push payload against the schema the server enforces, WITHOUT sending
+   * anything. Use this to confirm an agent's message complies before it goes
+   * live (e.g. in a test or a dry-run). `push()` runs the same check internally.
+   */
+  validatePush(payload) {
+    const { idempotencyKey: _ignored, ...body } = payload;
+    const result = PushPayloadSchema.safeParse(body);
+    if (result.success) return { valid: true, errors: [] };
+    const { errors, details } = formatZodError(result.error);
+    return { valid: false, errors, details };
+  }
+  /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
+  validatePushMany(payload) {
+    const { idempotencyKey: _ignored, ...body } = payload;
+    const result = PushManyPayloadSchema.safeParse(body);
+    if (result.success) return { valid: true, errors: [] };
+    const { errors, details } = formatZodError(result.error);
+    return { valid: false, errors, details };
+  }
   async push(payload) {
     const { idempotencyKey, ...body } = payload;
+    const check = PushPayloadSchema.safeParse(body);
+    if (!check.success) {
+      const { errors, details } = formatZodError(check.error);
+      throw new VesselsValidationError(`Invalid push payload \u2014 ${errors.join("; ")}`, details);
+    }
     const res = await this._fetch(`${this.baseUrl}/api/v1/push`, {
       method: "POST",
       headers: {
@@ -328,6 +361,11 @@ var Vessels = class {
   }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
+    const check = PushManyPayloadSchema.safeParse(body);
+    if (!check.success) {
+      const { errors, details } = formatZodError(check.error);
+      throw new VesselsValidationError(`Invalid pushMany payload \u2014 ${errors.join("; ")}`, details);
+    }
     const res = await this._fetch(`${this.baseUrl}/api/v1/push/many`, {
       method: "POST",
       headers: {
@@ -371,6 +409,117 @@ var Vessels = class {
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return { ok: true };
   }
+  /**
+   * Narrate a working message: declare a plan, file steps under each task as you
+   * go, and seal it when done. Sugar over {@link editMessage} — it tracks the
+   * todo list locally and PATCHes the full list each update (the server is
+   * authoritative and reconciles by label). The message must already exist; get
+   * its id from {@link push}.
+   */
+  activity(messageId) {
+    let todos = [];
+    const sendTodos = () => this.editMessage(messageId, { agentActivity: { todos } });
+    return {
+      plan: async (tasks) => {
+        todos = tasks.map(
+          (t) => typeof t === "string" ? { label: t, status: "pending" } : { label: t.label, status: t.status ?? "pending" }
+        );
+        await sendTodos();
+      },
+      start: async (label) => {
+        todos = todos.map(
+          (t) => t.label === label ? { ...t, status: "in_progress" } : t.status === "in_progress" ? { ...t, status: "done" } : t
+        );
+        if (!todos.some((t) => t.label === label)) todos.push({ label, status: "in_progress" });
+        await sendTodos();
+      },
+      step: async (type, label) => {
+        await this.editMessage(messageId, { agentActivity: { type, label } });
+      },
+      complete: async (label) => {
+        todos = todos.map(
+          (t) => (label ? t.label === label : t.status === "in_progress") ? { ...t, status: "done" } : t
+        );
+        await sendTodos();
+      },
+      done: async () => {
+        await this.editMessage(messageId, { agentActivity: null });
+      }
+    };
+  }
+  /**
+   * 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).
@@ -416,9 +565,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.9.0",
+	"version": "0.12.0",
 	"description": "Let your agent reach you. Official Vessels SDK.",
 	"type": "module",
 	"exports": {