vessels-sdk 0.9.0 → 0.11.0

package/README.md

@@ -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.
@@ -416,7 +439,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

package/dist/index.cjs

@@ -70,9 +70,17 @@ var InteractionSchema = zod.z.discriminatedUnion("type", [
   ConfirmPreviewInteractionSchema
 ]);
 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 +95,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(),
@@ -107,7 +115,7 @@ zod.z.object({
 }).refine((d) => d.message || d.agentActivity, {
   message: "Either message or agentActivity 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(),
@@ -271,6 +279,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 +318,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 +370,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 +418,44 @@ 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 });
+      }
+    };
+  }
   /**
    * 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).

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, ConfirmPreviewInteraction, 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,53 @@ 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>;
+}
 interface PushResponse {
     ok: true;
     messageId: string;
@@ -154,11 +196,27 @@ 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;
     /**
      * 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).
@@ -224,4 +282,4 @@ declare class Vessels {
     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 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, ConfirmPreviewInteraction, 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,53 @@ 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>;
+}
 interface PushResponse {
     ok: true;
     messageId: string;
@@ -154,11 +196,27 @@ 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;
     /**
      * 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).
@@ -224,4 +282,4 @@ declare class Vessels {
     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 UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.js

@@ -68,9 +68,17 @@ var InteractionSchema = z.discriminatedUnion("type", [
   ConfirmPreviewInteractionSchema
 ]);
 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 +93,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(),
@@ -105,7 +113,7 @@ z.object({
 }).refine((d) => d.message || d.agentActivity, {
   message: "Either message or agentActivity 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(),
@@ -269,6 +277,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 +316,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 +368,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 +416,44 @@ 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 });
+      }
+    };
+  }
   /**
    * 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).

package/package.json

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