vessels 0.10.0 → 0.12.0

package/README.md

@@ -53,6 +53,8 @@ vessels webhooks enable <id>
 vessels webhooks disable <id>
 
 vessels push --vessel <id> --message <text> --key <vsl_xxx>
+vessels event --vessel <id> --title <text> [--body <markdown>] [--tone info|alert|success] --key <vsl_xxx>
+vessels mark --vessel <id> --label <text> [--type <kind>] [--subtext <text>] [--tone neutral|success|warning|danger] [--url <link>] --key <vsl_xxx>
 vessels message --vessel <id> --message <text>
 ```
 

package/dist/index.js

@@ -4056,7 +4056,7 @@ var coerce = {
 var NEVER = INVALID;
 
 // ../types/src/index.ts
-var SourceSchema = external_exports.enum(["agent", "user", "system"]);
+var SourceSchema = external_exports.enum(["agent", "user", "system", "event", "mark"]);
 var InteractionTypeSchema = external_exports.enum([
   "approval",
   "choice",
@@ -4064,18 +4064,53 @@ var InteractionTypeSchema = external_exports.enum([
   "text_input",
   "questions"
 ]);
+var AckStageSchema = external_exports.enum(["received", "processing", "completed", "dropped"]);
+var AckPayloadSchema = external_exports.object({
+  stage: AckStageSchema,
+  reason: external_exports.string().max(280).optional()
+}).strict();
+var ChoiceOptionSchema = external_exports.object({
+  id: external_exports.string().min(1),
+  label: external_exports.string().min(1)
+});
+var EditableTypeSchema = external_exports.enum(["text", "number", "currency", "date", "choice"]);
+var EditableSchema = external_exports.object({
+  /** Stable id — the key this value uses in the response `edits`, and the
+   *  `editableId` a card field binds to. */
+  id: external_exports.string().min(1),
+  type: EditableTypeSchema,
+  /** Initial value (number for number/currency, the option id for choice, a string
+   *  otherwise). Optional — a bound card field supplies the displayed value — but
+   *  recommended, so the agent has a baseline to diff the returned edit against. */
+  value: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  /** Edit-field label; falls back to the bound card field's label. */
+  label: external_exports.string().optional(),
+  /** type:'choice' — the options the value is picked from. */
+  options: external_exports.array(ChoiceOptionSchema).min(1).optional(),
+  /** Numeric bounds for number/currency, validated on submit. */
+  min: external_exports.number().optional(),
+  max: external_exports.number().optional()
+}).refine((d) => {
+  var _a;
+  return d.type !== "choice" || (((_a = d.options) == null ? void 0 : _a.length) ?? 0) > 0;
+}, {
+  message: "editable of type 'choice' requires non-empty options"
+});
 var ApprovalInteractionSchema = external_exports.object({
   type: external_exports.literal("approval"),
   prompt: external_exports.string().min(1),
   approveLabel: external_exports.string().optional(),
   rejectLabel: external_exports.string().optional(),
   reasonRequired: external_exports.boolean().optional(),
+  // `false` ⇒ a one-way consent/proceed gate: a single full-width Approve button,
+  // no reject path. Defaults to true (the two-way Approve/Reject decision).
+  rejectable: external_exports.boolean().optional(),
+  // Edit-then-approve: values the human may change before approving. Each binds to a
+  // card field via that field's `editableId` (Phase 1); changed values return in the
+  // response `edits`, keyed by editable id. The body markdown stays read-only.
+  editables: external_exports.array(EditableSchema).max(20).optional(),
   metadata: external_exports.record(external_exports.unknown()).optional()
 });
-var ChoiceOptionSchema = external_exports.object({
-  id: external_exports.string().min(1),
-  label: external_exports.string().min(1)
-});
 var ChoiceInteractionSchema = external_exports.object({
   type: external_exports.literal("choice"),
   prompt: external_exports.string().min(1),
@@ -4116,7 +4151,7 @@ var QuestionSchema = external_exports.object({
   id: external_exports.string().min(1),
   /** The question text shown to the human. */
   question: external_exports.string().min(1),
-  /** Optional short chip label (≤12 chars) — e.g. "Date", "Guests". */
+  /** Optional short chip label (≤24 chars) — e.g. "Date", "Guests". */
   header: external_exports.string().max(24).optional(),
   options: external_exports.array(QuestionOptionSchema).min(2).max(4),
   /** Allow selecting more than one option (checkboxes instead of radios). */
@@ -4158,25 +4193,43 @@ var CardFieldSchema = external_exports.object({
   label: external_exports.string().min(1),
   value: external_exports.string(),
   // Optional: render the value as a tappable link, deep-linking the human into
-  // your own web UI (e.g. an admin tray). Rendered on full-size cards (surface /
-  // pinned-card detail), not the compact vessel-list preview.
+  // your own web UI (e.g. an admin tray). Rendered on full-size surface cards,
+  // not the compact vessel-list preview.
   url: external_exports.string().url().max(2048).optional(),
   // Optional colour hint — pure styling, no behaviour. 'default' === unset.
-  tone: external_exports.enum(["default", "success", "warning", "danger"]).optional()
+  tone: external_exports.enum(["default", "success", "warning", "danger"]).optional(),
+  // Edit-then-approve (Phase 1): binds this field to an approval `editables[]` entry
+  // by id. When the message's interaction is an approval declaring that editable, the
+  // field renders as an input in edit mode and the changed value returns in `edits`.
+  // Inert everywhere else (plain surfaces, events).
+  editableId: external_exports.string().optional()
 });
 var CardSchema = external_exports.object({
   // 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).
+  // standalone card on a bubble).
   title: external_exports.string().min(1).optional(),
   fields: external_exports.array(CardFieldSchema)
 });
+var DetailFieldSchema = external_exports.object({
+  label: external_exports.string().min(1),
+  value: external_exports.string(),
+  // Render the value as a tappable link, deep-linking the human into your own
+  // web UI (e.g. their CRM record). Opens in a new tab.
+  url: external_exports.string().url().max(2048).optional(),
+  // Colour hint — pure styling, no behaviour. 'default' === unset.
+  tone: external_exports.enum(["default", "success", "warning", "danger"]).optional(),
+  // Show a copy button on the value (phone numbers, emails, ids the human grabs).
+  copyable: external_exports.boolean().optional()
+});
+var DetailsSchema = external_exports.object({
+  fields: external_exports.array(DetailFieldSchema).max(20)
+});
 var AttachmentSchema = external_exports.discriminatedUnion("type", [
   external_exports.object({ type: external_exports.literal("image"), url: external_exports.string().url() }),
   external_exports.object({ type: external_exports.literal("file"), url: external_exports.string().url(), filename: external_exports.string().optional() })
 ]);
 var VesselStatusSchema = external_exports.enum(["active", "waiting", "resolved"]);
-var DisplaySchema = external_exports.enum(["bubble", "document"]);
 var KindSchema = external_exports.enum(["bubble", "surface"]);
 var PushPayloadSchema = external_exports.object({
   message: external_exports.string().min(1).max(1e4).optional(),
@@ -4189,7 +4242,8 @@ var PushPayloadSchema = external_exports.object({
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
   ).optional(),
-  pinCard: CardSchema.nullable().optional(),
+  /** Vessel reference record (CRM-style identity), shown in the top bar. `null` clears. Replaces wholesale. */
+  details: DetailsSchema.nullable().optional(),
   /** @deprecated `waiting` is now system-derived from the message's interaction; you don't set status. Still accepted for back-compat. */
   vesselStatus: VesselStatusSchema.optional(),
   labels: external_exports.array(external_exports.string().min(1).max(50)).max(10).optional(),
@@ -4207,9 +4261,7 @@ var PushPayloadSchema = external_exports.object({
   /** Bubble (chat) vs surface (composed artifact). Defaults from interaction/card. */
   kind: KindSchema.optional(),
   /** Surface heading. Ignored on bubbles. */
-  title: external_exports.string().max(200).optional(),
-  /** @deprecated legacy presentation hint — use `kind`. 'document' → surface. */
-  display: DisplaySchema.optional()
+  title: external_exports.string().max(200).optional()
 }).refine((d) => d.message || d.agentActivity || d.tokenStream, {
   message: "One of message, agentActivity, or tokenStream is required"
 });
@@ -4219,7 +4271,8 @@ var PushManyPayloadSchema = external_exports.object({
   vesselTitle: external_exports.string().optional(),
   card: CardSchema.optional(),
   interaction: InteractionSchema.optional(),
-  pinCard: CardSchema.nullable().optional(),
+  /** Vessel reference record (CRM-style identity), shown in the top bar. `null` clears. Replaces wholesale. */
+  details: DetailsSchema.nullable().optional(),
   /** @deprecated `waiting` is now system-derived from the message's interaction; you don't set status. Still accepted for back-compat. */
   vesselStatus: VesselStatusSchema.optional(),
   attachments: external_exports.array(AttachmentSchema).max(10).optional(),
@@ -4229,9 +4282,89 @@ var PushManyPayloadSchema = external_exports.object({
     "metadata exceeds 16KB limit"
   ).optional(),
   kind: KindSchema.optional(),
-  title: external_exports.string().max(200).optional(),
-  /** @deprecated use `kind`. */
-  display: DisplaySchema.optional()
+  title: external_exports.string().max(200).optional()
+});
+var EventToneSchema = external_exports.enum(["info", "alert", "success"]);
+var ButtonSchema = external_exports.object({
+  label: external_exports.string().min(1).max(100),
+  url: external_exports.string().url().max(2048),
+  tone: external_exports.enum(["default", "primary"]).optional()
+});
+var EventSectionSchema = external_exports.object({
+  heading: external_exports.string().min(1).max(200),
+  body: external_exports.string().min(1).max(1e4),
+  collapsed: external_exports.boolean().optional()
+});
+var EventPayloadSchema = external_exports.object({
+  /** The banner heading. */
+  title: external_exports.string().min(1).max(200),
+  /** Block-markdown body (tables, lists, headings, blockquotes, rules). */
+  body: external_exports.string().min(1).max(1e4).optional(),
+  /** Accent tone. Defaults to `info`. */
+  tone: EventToneSchema.optional(),
+  /** Which vessel — your own external id (created on first write, like push). */
+  vessel: external_exports.string().optional(),
+  /** Set the vessel title (only on explicit send, like push). */
+  vesselTitle: external_exports.string().optional(),
+  /** Glance-facts card (same shape as surfaces — supports per-field url/tone). */
+  card: CardSchema.optional(),
+  /** Deep-link buttons. */
+  buttons: external_exports.array(ButtonSchema).max(6).optional(),
+  /** Collapsible detail sections. */
+  sections: external_exports.array(EventSectionSchema).max(20).optional(),
+  labels: external_exports.array(external_exports.string().min(1).max(50)).max(10).optional(),
+  attachments: external_exports.array(AttachmentSchema).max(10).optional(),
+  metadata: external_exports.record(external_exports.unknown()).refine(
+    (v) => JSON.stringify(v).length < 16e3,
+    "metadata exceeds 16KB limit"
+  ).optional()
+}).refine((d) => d.body || d.card || d.buttons && d.buttons.length || d.sections && d.sections.length, {
+  message: "An event needs at least one of: body, card, buttons, or sections"
+});
+var EventDataSchema = external_exports.object({
+  tone: EventToneSchema,
+  buttons: external_exports.array(ButtonSchema).optional(),
+  sections: external_exports.array(EventSectionSchema).optional()
+});
+var MarkTypeSchema = external_exports.enum([
+  "email_sent",
+  "payment_recorded",
+  "status_changed",
+  "booking_created",
+  "invoice_voided",
+  "generic"
+]);
+var MarkToneSchema = external_exports.enum(["neutral", "success", "warning", "danger"]);
+var MarkPayloadSchema = external_exports.object({
+  /** The chip's primary line — what happened (e.g. "Confirmation email sent"). */
+  label: external_exports.string().min(1).max(120),
+  /** Semantic kind — selects a default icon + tone. Defaults to `generic`. */
+  type: MarkTypeSchema.optional(),
+  /** Optional small secondary line under the label (an amount, an id, a target). */
+  subtext: external_exports.string().min(1).max(160).optional(),
+  /** Override the default glyph with a literal icon/emoji (e.g. '✉️'). */
+  icon: external_exports.string().min(1).max(8).optional(),
+  /** Override the default tone. */
+  tone: MarkToneSchema.optional(),
+  /** Deep-link into your own UI — renders a right chevron, opens the URL. NOT an interaction. */
+  url: external_exports.string().url().max(2048).optional(),
+  /** Which vessel — your own external id (created on first write, like push). */
+  vessel: external_exports.string().optional(),
+  /** Set the vessel title (only on explicit send, like push). */
+  vesselTitle: external_exports.string().optional(),
+  labels: external_exports.array(external_exports.string().min(1).max(50)).max(10).optional(),
+  metadata: external_exports.record(external_exports.unknown()).refine(
+    (v) => JSON.stringify(v).length < 16e3,
+    "metadata exceeds 16KB limit"
+  ).optional()
+});
+var MarkDataSchema = external_exports.object({
+  type: MarkTypeSchema,
+  label: external_exports.string(),
+  tone: MarkToneSchema,
+  subtext: external_exports.string().optional(),
+  icon: external_exports.string().optional(),
+  url: external_exports.string().optional()
 });
 var MessagePatchSchema = external_exports.object({
   content: external_exports.string().min(1).max(1e4).optional(),
@@ -4244,15 +4377,17 @@ var MessagePatchSchema = external_exports.object({
   /** 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: external_exports.string().max(200).nullable().optional(),
-  /** @deprecated use `kind`. */
-  display: DisplaySchema.nullable().optional()
+  title: external_exports.string().max(200).nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
 var ApprovalResponseSchema = external_exports.object({
   action: external_exports.enum(["approved", "rejected"]),
-  reason: external_exports.string().optional()
+  reason: external_exports.string().optional(),
+  // Edit-then-approve: the values the human changed, keyed by editable id. Present
+  // only on `approved`, and only for values that actually changed (no change ⇒ a
+  // plain approve). Each value is validated against its declared editable server-side.
+  edits: external_exports.record(external_exports.union([external_exports.string(), external_exports.number()])).optional()
 });
 var ChoiceResponseSchema = external_exports.object({
   selected: external_exports.string(),
@@ -4279,6 +4414,29 @@ var InteractionResponseSchema = external_exports.discriminatedUnion("interaction
   external_exports.object({ interactionType: external_exports.literal("text_input"), response: TextInputResponseSchema }),
   external_exports.object({ interactionType: external_exports.literal("questions"), response: QuestionsResponseSchema })
 ]);
+var InteractionOutcomeSchema = external_exports.enum([
+  "approved",
+  // green ✓
+  "rejected",
+  // red ✗
+  "cancelled",
+  // neutral — withdrawn before a decision
+  "expired"
+  // neutral — no longer relevant
+]);
+var InteractionResolveSchema = external_exports.object({
+  outcome: InteractionOutcomeSchema,
+  /** Badge text shown in place of the buttons. Defaults to the outcome name. */
+  label: external_exports.string().min(1).max(80).optional(),
+  /** Optional note; surfaced when the resolved receipt expands. */
+  reason: external_exports.string().max(2e3).optional()
+});
+var AgentResolutionSchema = external_exports.object({
+  resolvedByAgent: external_exports.literal(true),
+  outcome: InteractionOutcomeSchema,
+  label: external_exports.string().optional(),
+  reason: external_exports.string().optional()
+});
 var WebhookVesselSchema = external_exports.object({
   id: external_exports.string(),
   external_id: external_exports.string().nullable(),
@@ -4356,6 +4514,24 @@ var WebhookVesselCreatedPayloadSchema = external_exports.object({
     attachments: external_exports.array(WebhookEventAttachmentSchema).optional()
   })
 });
+var WebhookVesselArchivedPayloadSchema = external_exports.object({
+  event: external_exports.literal("vessel.archived"),
+  vessel_id: external_exports.string(),
+  workspace_id: external_exports.string(),
+  timestamp: external_exports.string(),
+  data: external_exports.object({
+    vessel: WebhookVesselSchema
+  })
+});
+var WebhookVesselDeletedPayloadSchema = external_exports.object({
+  event: external_exports.literal("vessel.deleted"),
+  vessel_id: external_exports.string(),
+  workspace_id: external_exports.string(),
+  timestamp: external_exports.string(),
+  data: external_exports.object({
+    vessel: WebhookVesselSchema
+  })
+});
 var WebhookMessageCancelledPayloadSchema = external_exports.object({
   event: external_exports.literal("message.cancelled"),
   vessel_id: external_exports.string(),
@@ -4370,6 +4546,8 @@ var WebhookPayloadSchema = external_exports.discriminatedUnion("event", [
   WebhookInteractionResponsePayloadSchema,
   WebhookUserMessagePayloadSchema,
   WebhookVesselCreatedPayloadSchema,
+  WebhookVesselArchivedPayloadSchema,
+  WebhookVesselDeletedPayloadSchema,
   WebhookMessageCancelledPayloadSchema
 ]);
 
@@ -4490,10 +4668,10 @@ async function cmdLogout() {
   console.log("Logged out.");
 }
 async function cmdWhoami() {
-  var _a, _b;
+  var _a;
   const data = await api("/api/v1/me");
   console.log(`Email:     ${readConfig().email ?? "unknown"}`);
-  console.log(`Workspace: ${(_a = data.workspace) == null ? void 0 : _a.name} (${(_b = data.workspace) == null ? void 0 : _b.plan})`);
+  console.log(`Workspace: ${(_a = data.workspace) == null ? void 0 : _a.name}`);
   console.log(`User ID:   ${data.userId}`);
 }
 async function cmdKeysList() {
@@ -4547,7 +4725,7 @@ async function cmdWebhooksCreate(args) {
     console.error("URL must start with https://");
     process.exit(1);
   }
-  const DEFAULT_EVENTS = ["interaction.response", "message.user", "vessel.created"];
+  const DEFAULT_EVENTS = ["interaction.response", "message.user", "vessel.created", "vessel.archived", "vessel.deleted"];
   let events;
   if (flags.events) {
     events = flags.events.split(/[,\s]+/).filter(Boolean);
@@ -4686,6 +4864,76 @@ async function cmdPush(args) {
   }
   console.log(`Message sent. vessel_id=${data.vessel_id} message_id=${data.message_id}`);
 }
+var EVENT_TONES = ["info", "alert", "success"];
+async function cmdEvent(args) {
+  const flags = parseFlags(args);
+  const apiKey = flags.key ?? process.env.VESSELS_API_KEY;
+  if (!apiKey) {
+    console.error("Provide an API key via --key or VESSELS_API_KEY env var");
+    process.exit(1);
+  }
+  if (!flags.title) {
+    console.error("Usage: vessels event --vessel <id> --title <text> [--body <markdown>] [--tone info|alert|success] --key <api_key>");
+    process.exit(1);
+  }
+  if (flags.tone && !EVENT_TONES.includes(flags.tone)) {
+    console.error(`--tone must be one of: ${EVENT_TONES.join(", ")}`);
+    process.exit(1);
+  }
+  const payload = { title: flags.title, vessel: flags.vessel || void 0 };
+  if (flags.body) payload.body = flags.body;
+  if (flags.tone) payload.tone = flags.tone;
+  const res = await fetch(`${BASE_URL}/api/v1/event`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify(payload)
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error("Event failed:", data.error);
+    process.exit(1);
+  }
+  console.log(`Event sent. vessel_id=${data.vessel_id} message_id=${data.message_id}`);
+}
+var MARK_TYPES = ["email_sent", "payment_recorded", "status_changed", "booking_created", "invoice_voided", "generic"];
+var MARK_TONES = ["neutral", "success", "warning", "danger"];
+async function cmdMark(args) {
+  const flags = parseFlags(args);
+  const apiKey = flags.key ?? process.env.VESSELS_API_KEY;
+  if (!apiKey) {
+    console.error("Provide an API key via --key or VESSELS_API_KEY env var");
+    process.exit(1);
+  }
+  if (!flags.label) {
+    console.error("Usage: vessels mark --vessel <id> --label <text> [--type <kind>] [--subtext <text>] [--icon <emoji>] [--tone neutral|success|warning|danger] [--url <link>] --key <api_key>");
+    process.exit(1);
+  }
+  if (flags.type && !MARK_TYPES.includes(flags.type)) {
+    console.error(`--type must be one of: ${MARK_TYPES.join(", ")}`);
+    process.exit(1);
+  }
+  if (flags.tone && !MARK_TONES.includes(flags.tone)) {
+    console.error(`--tone must be one of: ${MARK_TONES.join(", ")}`);
+    process.exit(1);
+  }
+  const payload = { label: flags.label, vessel: flags.vessel || void 0 };
+  if (flags.type) payload.type = flags.type;
+  if (flags.subtext) payload.subtext = flags.subtext;
+  if (flags.icon) payload.icon = flags.icon;
+  if (flags.tone) payload.tone = flags.tone;
+  if (flags.url) payload.url = flags.url;
+  const res = await fetch(`${BASE_URL}/api/v1/mark`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify(payload)
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error("Mark failed:", data.error);
+    process.exit(1);
+  }
+  console.log(`Mark sent. vessel_id=${data.vessel_id} message_id=${data.message_id}`);
+}
 var FEEDBACK_TYPES = ["bug", "feature", "other"];
 async function cmdFeedback(args) {
   const flags = parseFlags(args);
@@ -4728,7 +4976,7 @@ function zodIssueLines(err) {
   return err.issues.map((i) => `${i.path.join(".") || "(payload)"}: ${i.message}`);
 }
 function summarisePayload(p, isMany) {
-  var _a, _b;
+  var _a, _b, _c;
   const lines = [];
   if (isMany) lines.push(`  vessels:      ${p.vessels.length}`);
   else if (p.vessel) lines.push(`  vessel:       ${p.vessel}`);
@@ -4738,7 +4986,7 @@ function summarisePayload(p, isMany) {
   }
   if ((_a = p.interaction) == null ? void 0 : _a.type) lines.push(`  interaction:  ${p.interaction.type}`);
   if (p.card) lines.push(`  card:         "${p.card.title}" (${((_b = p.card.fields) == null ? void 0 : _b.length) ?? 0} fields)`);
-  if (p.pinCard !== void 0) lines.push(`  pinCard:      ${p.pinCard === null ? "clear" : `"${p.pinCard.title}"`}`);
+  if (p.details !== void 0) lines.push(`  details:      ${p.details === null ? "clear" : `${((_c = p.details.fields) == null ? void 0 : _c.length) ?? 0} field(s)`}`);
   if (p.vesselStatus) lines.push(`  vesselStatus: ${p.vesselStatus}`);
   if (Array.isArray(p.attachments)) lines.push(`  attachments:  ${p.attachments.length}`);
   if (Array.isArray(p.suggestions)) lines.push(`  suggestions:  ${p.suggestions.length}`);
@@ -4955,7 +5203,7 @@ Setup complete.
   if (flags["webhook-url"]) {
     const webhookData = await api("/api/v1/webhooks", {
       method: "POST",
-      body: JSON.stringify({ url: flags["webhook-url"], events: ["interaction.response", "message.user", "vessel.created"] })
+      body: JSON.stringify({ url: flags["webhook-url"], events: ["interaction.response", "message.user", "vessel.created", "vessel.archived", "vessel.deleted"] })
     });
     console.log(`  VESSELS_WEBHOOK_SECRET=${webhookData.endpoint.secret}`);
   }
@@ -5062,6 +5310,15 @@ Commands:
   vessels push --vessel <id> --message <text> --key <api_key>
       (--key can be omitted if VESSELS_API_KEY is set)
 
+  vessels event --vessel <id> --title <text> [--body <markdown>] [--tone info|alert|success] --key <api_key>
+      Paint a human-facing event banner (a fact from your backend \u2014 booking, alert).
+      Fires a notification, no webhook. Renders as a full-width tinted artifact.
+
+  vessels mark --vessel <id> --label <text> [--type <kind>] [--subtext <text>] [--icon <emoji>] [--tone neutral|success|warning|danger] [--url <link>] --key <api_key>
+      Drop a slim timeline chip recording a committed action (email sent, payment
+      recorded). --type \u2208 email_sent|payment_recorded|status_changed|booking_created|
+      invoice_voided|generic. Fires a notification, no webhook.
+
   vessels message --vessel <id> --message <text>
       Send a message as the logged-in user and print webhook delivery logs.
       Accepts vessel UUID or external_id (e.g. booking-123).
@@ -5152,6 +5409,8 @@ Run: vessels help`);
   if (cmd === "conversation" || cmd === "trace") return cmdConversation([sub, ...rest].filter(Boolean));
   if (cmd === "feedback") return cmdFeedback([sub, ...rest].filter(Boolean));
   if (cmd === "push") return cmdPush([sub, ...rest].filter(Boolean));
+  if (cmd === "event") return cmdEvent([sub, ...rest].filter(Boolean));
+  if (cmd === "mark") return cmdMark([sub, ...rest].filter(Boolean));
   if (cmd === "message") return cmdMessage([sub, ...rest].filter(Boolean));
   if (cmd === "validate") return cmdValidate([sub, ...rest].filter(Boolean));
   console.error(`Unknown command: ${cmd}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vessels",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Vessels CLI — manage your agent communication layer from the terminal",
   "type": "module",
   "bin": {

package/template/agent/README.md

@@ -54,7 +54,7 @@ Everything else is the **engine** and you rarely touch it:
 2. The server verifies the signature, **ACKs 200 immediately**, and runs the turn in the background.
 3. The engine leads with a one-line reply, opens a live working card, plans, calls **your** tools,
    and ends with exactly one finishing tool — a message (`finish`) or a human decision
-   (`request_approval` / `choice` / `checklist` / `text`).
+   (`request_approval` / `choice` / `checklist` / `text` / `questions`).
 4. When the human answers, Vessels sends another webhook and the loop continues — the engine loads
    the prior conversation from your store, so the agent picks up exactly where it left off.
 
@@ -87,10 +87,14 @@ runTurn` shape stays the same; only the server wrapper changes.
 ## The full Vessels surface
 
 The engine already exposes the breadth of Vessels to the model, so your agent can use all of it:
-chat **bubbles** and full-width **surfaces**; all four **interactions** (`approval` / `choice` /
-`checklist` / `text`, with labels, `allowCustom`, `minSelections`, `reasonRequired`, and
-**metadata** that rides back to you for routing); the live **working card** with a ticking **plan**,
-auto-narrated **steps**, and **token streaming**; **pinned cards**, **labels**, **attachments**
+chat **bubbles** and full-width **surfaces**; all five **interactions** (`approval` / `choice` /
+`checklist` / `text` / `questions` — the multi-question form, with labels, `allowCustom`,
+`minSelections`, `reasonRequired`, and **metadata** that rides back to you for routing);
+**edit-then-approve** (the operator changes a value — a price, a date — and approves, via
+`editables` bound to card fields or inline `{{id}}` body tokens; only the changes come back) and
+one-way **consent gates** (`rejectable:false`); the live **working card** with a ticking **plan**,
+auto-narrated **steps**, and **token streaming**; the vessel's persistent **details** record
+(CRM-style reference facts, shown in the top bar), **labels** (triage/status tags), **attachments**
 (images/files you host), **preview links**, **suggested replies**, vessel **naming/renaming**, and
 user-initiated vessel **types**; plus **inbound files** the human sends you — downloaded, stored on
 your infra, resolved, and (for images) read by the model via **vision** (see below). Idempotency
@@ -113,10 +117,24 @@ your externally-reachable base (your tunnel in dev) so that link is fetchable. I
 `putInboundFile` at object storage (S3/R2/GCS) and return a CDN URL — nothing else changes.
 
 A few Vessels features live on **your backend**, not inside a turn — call them on the `vessels`
-SDK directly:
-
+SDK directly (none of these round-trip through the agent's turn loop):
+
+- `vessels.event({ vessel, title, tone, card?, buttons?, sections? })` — paint a **backend event**
+  on the human's timeline: a fact from *your* system (a booking landed, an alert fired), not your
+  agent's voice. A full-width tinted banner with deep-link buttons and collapsible sections. It is
+  purely presentational — it fires **no webhook and no poll event**, so the agent never hears about
+  it through Vessels. Fire it in parallel with triggering the agent off the same fact (e.g. POST a
+  `vessel.created`/proactive trigger to this server), and the agent works and replies in its own
+  voice alongside the banner.
 - `vessels.pushMany({ vessels: [...], message, interaction })` — broadcast the same message/decision
   to many vessels at once (e.g. "course closed Saturday" to every affected booking).
+- `vessels.updateVessel(externalId, { title?, labels?, details?, archived?, pinned? })` — change
+  vessel-level state **without** posting a message; `vessels.archiveVessel(id)` / `listVessels()` /
+  `deleteVessel(id)` are the lifecycle helpers around it.
+- `vessels.clearMessages(vessel, { beforeMessageId? | afterMessageId? | before? | after? })` /
+  `vessels.deleteMessage(id)` — the durable primitive behind an agent's **/rewind**: trim the
+  human-visible feed back to a point (it does **not** touch your agent's own context, which lives
+  in your store). Resolve the operator's "rewind to yesterday" to a timestamp/id, then call this.
 - `vessels.getMessages({ vessel })` — re-read a vessel's human-facing history to reconcile a
   stateless/restarted worker (not your memory — that's your store).
 - `vessels.validatePush(payload)` — check a payload against the server schema without sending.

package/template/agent/package.json

@@ -13,7 +13,7 @@
     "@anthropic-ai/sdk": "^0.85.0",
     "dotenv": "^16.4.5",
     "pg": "^8.13.0",
-    "vessels-sdk": "^0.17.0"
+    "vessels-sdk": "^0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/template/agent/src/agent.ts

@@ -16,7 +16,7 @@
  * You usually don't edit this file. The pieces worth knowing are flagged inline.
  */
 import Anthropic from '@anthropic-ai/sdk';
-import type { MessageParam, Tool, ToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlockParam, ImageBlockParam } from '@anthropic-ai/sdk/resources/messages';
+import type { MessageParam, Tool, ToolUseBlock, TextBlock, ToolResultBlockParam, ImageBlockParam } from '@anthropic-ai/sdk/resources/messages';
 import { Vessels } from 'vessels-sdk';
 import type { PushOptions, AgentActivityType, AgentTodoStatus, InboundAttachment } from 'vessels-sdk';
 import { ROLE } from './role.js';
@@ -29,6 +29,7 @@ import {
 	buildInteraction,
 	defaultNarrate,
 	sanitizeCard,
+	sanitizeDetails,
 	cleanPreviewUrl,
 	cleanTitle,
 	cleanSuggestions,
@@ -40,8 +41,7 @@ import { handleInboundFiles, attachImagesToLastUserMessage } from './inbound.js'
 
 const MODEL = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6';
 const MAX_TURN_STEPS = 12; // tool hops within a single turn before we force an ending
-const THINKING_BUDGET = 1024; // API minimum; streamed live into the card then discarded
-const MAX_TOKENS = 4096; // think + response combined
+const MAX_TOKENS = 4096;
 const TURN_BUDGET_MS = 75_000; // safety cap — stop starting model calls past this and finish gracefully
 const MAX_HISTORY = 80; // cap persisted conversation messages (trimmed at a safe boundary)
 const DEBUG = process.env.DEBUG === '1' || process.env.DEBUG === 'true';
@@ -190,7 +190,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	let cardOpened = false;
 	let acknowledged = false; // the agent already sent its "on it" bubble → card needs no message
 	let pendingTitle = vesselTitle; // rides whichever push lands first
-	let pendingPinCard: ReturnType<typeof sanitizeCard> | undefined;
+	let pendingDetails: ReturnType<typeof sanitizeDetails> | undefined;
 	let pendingLabels: string[] | undefined;
 	const ensureWorkingCard = async (): Promise<void> => {
 		if (cardOpened) return;
@@ -198,14 +198,14 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 		const r = await safePush(vessels, {
 			vessel,
 			...(pendingTitle ? { vesselTitle: pendingTitle } : {}),
-			...(pendingPinCard ? { pinCard: pendingPinCard } : {}),
+			...(pendingDetails !== undefined ? { details: pendingDetails } : {}),
 			...(pendingLabels ? { labels: pendingLabels } : {}),
 			...(acknowledged ? {} : { message: opening }),
 			agentActivity: { type: 'thinking', label: 'Getting started' },
 			idempotencyKey: `${idempotencyKeyBase}:work`,
 		});
 		pendingTitle = undefined;
-		pendingPinCard = undefined;
+		pendingDetails = undefined;
 		pendingLabels = undefined;
 		activityId = r.messageId ?? null;
 	};
@@ -278,7 +278,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 		kind?: 'bubble' | 'surface';
 		title?: string;
 		card?: unknown;
-		pinCard?: unknown;
+		details?: unknown;
 		labels?: string[];
 		interaction?: Record<string, unknown> | null;
 		suggestions?: string[];
@@ -290,12 +290,12 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	let ended = false;
 	const recordEnding = (name: string, input: Record<string, unknown>) => {
 		const msg = String(input.message ?? '');
-		const endPin = sanitizeCard(input.pinCard);
+		const endDetails = sanitizeDetails(input.details);
 		const endLabels = cleanLabels(input.labels);
 		const endTitle = cleanTitle(input.vesselTitle);
 		if (endTitle && !pendingTitle) pendingTitle = endTitle;
 		if (name === 'finish') {
-			pushes.push({ message: msg || 'All done.', pinCard: endPin, labels: endLabels });
+			pushes.push({ message: msg || 'All done.', details: endDetails, labels: endLabels });
 		} else {
 			const interaction = buildInteraction(name, input);
 			// keepWorking is purely semantic — it tells the model the task isn't finished, so the
@@ -306,7 +306,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 				kind: 'surface',
 				title: cleanTitle(input.title),
 				card: sanitizeCard(input.card, input),
-				pinCard: endPin,
+				details: endDetails,
 				labels: endLabels,
 				interaction,
 				previewUrl: cleanPreviewUrl(input.previewUrl),
@@ -328,12 +328,10 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 			const ms = anthropic.messages.stream({
 				model: MODEL,
 				max_tokens: MAX_TOKENS,
-				thinking: { type: 'enabled', budget_tokens: THINKING_BUDGET },
 				system: systemPrompt,
 				tools: ALL_TOOLS,
 				messages,
 			});
-			ms.on('thinking', (delta) => writeStream(delta));
 			ms.on('text', (delta) => writeStream(delta));
 			ms.on('error', () => {});
 			const resp = await ms.finalMessage();
@@ -342,8 +340,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 
 			const toolUses = resp.content.filter((b): b is ToolUseBlock => b.type === 'tool_use');
 			if (DEBUG) {
-				const thinking = resp.content.filter((b): b is ThinkingBlock => b.type === 'thinking').map((b) => b.thinking).join('\n');
-				log('model_done', { step, stop: resp.stop_reason, tools: toolUses.map((t) => t.name), thinking: thinking.slice(0, 200) });
+				log('model_done', { step, stop: resp.stop_reason, tools: toolUses.map((t) => t.name) });
 			}
 
 			// No tool call — treat any plain text as a final message and stop.
@@ -366,7 +363,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 					const named = cleanTitle(pIn.vesselTitle);
 					if (named) pendingTitle = named;
 				}
-				if (!pendingPinCard) pendingPinCard = sanitizeCard(pIn.pinCard);
+				if (pendingDetails === undefined) pendingDetails = sanitizeDetails(pIn.details);
 				if (!pendingLabels) pendingLabels = cleanLabels(pIn.labels);
 			}
 
@@ -429,12 +426,12 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 				} else if (tu.name === 'show_document') {
 					const title = cleanTitle(input.title);
 					const body = String(input.body ?? '').trim();
-					const docPin = sanitizeCard(input.pinCard);
+					const docDetails = sanitizeDetails(input.details);
 					const docLabels = cleanLabels(input.labels);
 					if (body) {
-						pushes.push({ message: body, kind: 'surface', title, card: sanitizeCard(input.card, input), pinCard: docPin, labels: docLabels, attachments: cleanAttachments(input.attachments) });
-					} else if (docPin || docLabels) {
-						if (docPin) pendingPinCard = docPin;
+						pushes.push({ message: body, kind: 'surface', title, card: sanitizeCard(input.card, input), details: docDetails, labels: docLabels, attachments: cleanAttachments(input.attachments) });
+					} else if (docDetails !== undefined || docLabels) {
+						if (docDetails !== undefined) pendingDetails = docDetails;
 						if (docLabels) pendingLabels = docLabels;
 					}
 					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'shown' });
@@ -529,10 +526,10 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 			const isLast = i === pushes.length - 1;
 			const titleForThisPush = i === 0 && pendingTitle ? pendingTitle : undefined;
 			if (titleForThisPush) pendingTitle = undefined;
-			const pinForThisPush = p.pinCard ?? (i === 0 ? pendingPinCard : undefined);
+			const detailsForThisPush = p.details !== undefined ? p.details : (i === 0 ? pendingDetails : undefined);
 			const labelsForThisPush = p.labels ?? (i === 0 ? pendingLabels : undefined);
 			if (i === 0) {
-				pendingPinCard = undefined;
+				pendingDetails = undefined;
 				pendingLabels = undefined;
 			}
 			const r = await safePush(vessels, {
@@ -542,7 +539,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 				kind: p.kind,
 				title: p.title,
 				card: p.card as PushOptions['card'],
-				...(pinForThisPush ? { pinCard: pinForThisPush as PushOptions['pinCard'] } : {}),
+				...(detailsForThisPush !== undefined ? { details: detailsForThisPush as PushOptions['details'] } : {}),
 				...(labelsForThisPush ? { labels: labelsForThisPush } : {}),
 				interaction: (p.interaction ?? undefined) as PushOptions['interaction'],
 				suggestions: p.suggestions,

package/template/agent/src/protocol.ts

@@ -63,11 +63,15 @@ Tools:
 1. Plan + triage — drive the live ticking checklist AND surface the vessel's state:
    - plan(todos)  — declare 3–4 tasks up front. On a vessel's FIRST plan(), ALSO set:
        • labels: 1–3 triage tags in your own vocabulary — how this vessel shows up in the
-         operator's list. Replace-semantics (send the full set).
-       • pinCard: a compact {title, fields} pinning the entity's state at a glance — it stays
-         in the header as the chat scrolls.
-     Re-send pinCard (on a later plan/finish/request_*) to UPDATE it as state changes. Set
-     labels once unless they change.
+         operator's list. This is where STATUS lives — re-send to retag as the situation
+         moves. Replace-semantics (send the full set).
+       • details: {fields:[{label, value, url?, tone?, copyable?}]} — the vessel's persistent
+         REFERENCE record: stable identity facts about who/what this vessel is about (client
+         name, phone/email — set copyable:true on those; a url to deep-link into your own
+         admin). It is NOT status — never re-send details just to reflect a state change (that's
+         what labels are for); only rewrite it when the underlying facts change. Replaces
+         wholesale; null clears.
+     Set labels and details on the first plan(); leave them unless the facts/status change.
    - Advance the plan by passing task:"<exact label>" ON the work tool itself (your backend
      tools and send_update take it) — that ticks the plan in the SAME call. Do NOT waste a
      whole turn on a lone step(); only use step() when you advance with no tool to run. You do
@@ -82,6 +86,16 @@ Tools:
      summarise it as "draft is ready"; show the real text.
    - Reserve a previewUrl for something too long or rich to inline (a multi-page document, a
      PDF) — a link to open, not a substitute for showing short text.
+   - EDIT-THEN-APPROVE: when the operator is more likely to TWEAK a value than to reject (a
+     price, a date, a quantity), declare editables on request_approval instead of forcing a
+     reject-and-re-ask. Each editable is {id, type (text|number|currency|date|choice), value}.
+     Bind each to where it shows: either a card field carrying the same editableId, OR an inline
+     {{id}} token written straight into the message body (works in a table cell). "Edit & approve"
+     turns those into inputs; only the values they CHANGED come back to you in the response, and
+     you apply the new values in your backend. The body prose stays read-only — only the bound
+     values are editable. Don't over-use it: most approvals are a clean yes/no.
+   - CONSENT GATE: for a one-way "proceed?" with no real reject path (a confirmation before an
+     irreversible action), set rejectable:false — it renders a single full-width Approve button.
 
 3. Finishing tools — pick EXACTLY ONE as the FINAL action of your turn:
    - request_approval   — yes/no sign-off (optionally with a previewUrl to review)
@@ -108,7 +122,7 @@ Flow:
 - A [SYSTEM EVENT] means you are PROACTIVELY reaching the operator. They ALREADY see your
   opening line and a live ticking plan — so DO NOT re-announce the event or restate its
   details in a chat message. Get straight to work.
-- plan(todos, labels, pinCard) → call each task's backend tool WITH task:"<label>" (it ticks
+- plan(todos, labels, details) → call each task's backend tool WITH task:"<label>" (it ticks
   the plan + auto-narrates) → then ONE finishing tool. END the turn with a single, complete
   result: the finishing message (one sentence) plus, for approvals, a compact card. Never drop
   a bare card and trail off.

package/template/agent/src/vessels-tools.ts

@@ -17,17 +17,45 @@ import type { AgentActivityType } from 'vessels-sdk';
 const CARD_SCHEMA = {
 	type: 'object' as const,
 	properties: {
-		title: { type: 'string' },
+		title: { type: 'string', description: 'Optional heading. Redundant on a surface (the surface title is the heading); useful on a standalone bubble card.' },
 		fields: {
 			type: 'array',
 			items: {
 				type: 'object',
-				properties: { label: { type: 'string' }, value: { type: 'string' } },
+				properties: {
+					label: { type: 'string' },
+					value: { type: 'string' },
+					url: { type: 'string', description: 'Render the value as a link deep into YOUR own admin (opens a new tab). Shown on surface cards, not the list preview.' },
+					tone: { type: 'string', enum: ['default', 'success', 'warning', 'danger'], description: 'Colour hint only — no behaviour.' },
+					editableId: { type: 'string', description: 'Edit-then-approve: bind this field to an approval `editables[]` entry of the same id, so it becomes an input on "Edit & approve". Inert without that approval.' },
+				},
 				required: ['label', 'value'],
 			},
 		},
 	},
-	required: ['title', 'fields'],
+	required: ['fields'],
+};
+
+/** Edit-then-approve: the values the human may change before approving. Each binds to a
+ *  card field (by matching `editableId`) OR to an inline `{{id}}` token in the body. */
+const EDITABLES_SCHEMA = {
+	type: 'array' as const,
+	maxItems: 20,
+	description:
+		'Edit-then-approve — let the operator change specific VALUES before approving (e.g. "make it 1700, not 1500"), instead of rejecting and re-asking. Each entry binds to a card field with a matching `editableId`, or to an inline `{{id}}` token in the message body. On approve, only the values they changed come back in the response `edits` (keyed by id) — apply them in YOUR system. The body prose stays read-only.',
+	items: {
+		type: 'object',
+		properties: {
+			id: { type: 'string', description: 'Stable id — the response `edits` key and the `editableId`/`{{id}}` it binds to.' },
+			type: { type: 'string', enum: ['text', 'number', 'currency', 'date', 'choice'], description: 'text | number | currency (money) | date (YYYY-MM-DD) | choice (pick an option id).' },
+			value: { description: 'The current/baseline value (a number for number/currency, the option id for choice, else a string). Recommended so you can diff the returned edit.' },
+			label: { type: 'string', description: 'Edit-field label; falls back to the bound card field label.' },
+			options: { type: 'array', description: "type:'choice' only — the options to pick from.", items: { type: 'object', properties: { id: { type: 'string' }, label: { type: 'string' } }, required: ['id', 'label'] }, minItems: 1 },
+			min: { type: 'number', description: 'Numeric lower bound (number/currency), validated on submit.' },
+			max: { type: 'number', description: 'Numeric upper bound (number/currency), validated on submit.' },
+		},
+		required: ['id', 'type'],
+	},
 };
 
 /** Inject this into a tool's input schema so the model can tick the plan in the same call. */
@@ -47,10 +75,28 @@ const OPTIONS_SCHEMA = {
 	minItems: 1,
 };
 
-const PIN_CARD_FIELD = {
-	...CARD_SCHEMA,
+const DETAILS_FIELD = {
+	type: 'object' as const,
+	properties: {
+		fields: {
+			type: 'array',
+			maxItems: 20,
+			items: {
+				type: 'object',
+				properties: {
+					label: { type: 'string' },
+					value: { type: 'string' },
+					url: { type: 'string', description: 'Deep-link the value into YOUR own admin/CRM (opens in a new tab).' },
+					tone: { type: 'string', enum: ['default', 'success', 'warning', 'danger'], description: 'Colour hint only — no behaviour.' },
+					copyable: { type: 'boolean', description: "Show a copy button (use on phone numbers, emails, ids the human grabs)." },
+				},
+				required: ['label', 'value'],
+			},
+		},
+	},
+	required: ['fields'],
 	description:
-		"Update the vessel's pinned header card to the entity's current state. Re-send the full card to replace it.",
+		"The vessel's persistent reference record — CRM-style identity facts about who/what this vessel is about (client name, phone/email with copyable:true, links into your admin via url). NOT status (status lives in labels). Replaces wholesale on each write; send null to clear.",
 };
 
 const LABELS_FIELD = {
@@ -116,11 +162,7 @@ export const CONTROL_TOOLS: Tool[] = [
 					description:
 						'Triage tags for this vessel, in your own vocabulary. REPLACE-semantics — send the full set. Set 1–3 on the first plan() of a vessel; omit later unless they change.',
 				},
-				pinCard: {
-					...CARD_SCHEMA,
-					description:
-						"A persistent header card pinning the entity's current state at a glance — stays put as the chat scrolls. Set it when you first have the key facts; re-send to UPDATE it as state changes.",
-				},
+				details: DETAILS_FIELD,
 			},
 			required: ['todos'],
 		},
@@ -168,7 +210,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				},
 				card: CARD_SCHEMA,
 				attachments: ATTACHMENTS_FIELD,
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 			},
 			required: ['title', 'body'],
@@ -190,9 +232,11 @@ export const CONTROL_TOOLS: Tool[] = [
 				approveLabel: { type: 'string' },
 				rejectLabel: { type: 'string' },
 				reasonRequired: { type: 'boolean', description: 'Require the human to type a reason with their approve/reject.' },
+				rejectable: { type: 'boolean', description: 'Set FALSE for a one-way consent/proceed gate — a single full-width Approve button, no reject path. Defaults true (the two-way Approve/Reject decision).' },
+				editables: EDITABLES_SCHEMA,
 				previewUrl: { type: 'string', description: 'Optional link for an artifact too rich to inline. For text, inline it in `message`.' },
 				card: CARD_SCHEMA,
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
 				keepWorking: KEEP_WORKING_FIELD,
@@ -213,7 +257,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				allowCustom: { type: 'boolean', description: 'Let the human type their own answer instead of picking an option.' },
 				customPlaceholder: { type: 'string', description: 'Placeholder for the custom-answer field (when allowCustom).' },
 				card: CARD_SCHEMA,
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
 				keepWorking: KEEP_WORKING_FIELD,
@@ -234,7 +278,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				minSelections: { type: 'number', description: 'Minimum number the human must select.' },
 				submitLabel: { type: 'string', description: 'Label for the submit button.' },
 				card: CARD_SCHEMA,
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
 				keepWorking: KEEP_WORKING_FIELD,
@@ -254,7 +298,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				placeholder: { type: 'string' },
 				multiline: { type: 'boolean' },
 				submitLabel: { type: 'string', description: 'Label for the submit button.' },
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
 				keepWorking: KEEP_WORKING_FIELD,
@@ -303,7 +347,7 @@ export const CONTROL_TOOLS: Tool[] = [
 					},
 				},
 				submitLabel: { type: 'string' },
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
 				keepWorking: KEEP_WORKING_FIELD,
@@ -319,7 +363,7 @@ export const CONTROL_TOOLS: Tool[] = [
 			properties: {
 				message: { type: 'string' },
 				vesselTitle: { type: 'string', description: 'Rename the vessel as you wrap up (≤6 words). Omit otherwise.' },
-				pinCard: PIN_CARD_FIELD,
+				details: DETAILS_FIELD,
 				labels: LABELS_FIELD,
 			},
 			required: ['message'],
@@ -374,14 +418,18 @@ export function buildInteraction(toolName: string, input: Record<string, unknown
 	const meta = cleanMetadata(input.metadata);
 	const withMeta = (obj: Record<string, unknown>) => (meta ? { ...obj, metadata: meta } : obj);
 	switch (toolName) {
-		case 'request_approval':
+		case 'request_approval': {
+			const editables = sanitizeEditables(input.editables);
 			return withMeta({
 				type: 'approval',
 				prompt: String(input.prompt),
 				...(input.approveLabel ? { approveLabel: String(input.approveLabel) } : {}),
 				...(input.rejectLabel ? { rejectLabel: String(input.rejectLabel) } : {}),
 				...(input.reasonRequired ? { reasonRequired: true } : {}),
+				...(input.rejectable === false ? { rejectable: false } : {}),
+				...(editables ? { editables } : {}),
 			});
+		}
 		case 'request_choice':
 			return withMeta({
 				type: 'choice',
@@ -432,7 +480,15 @@ export function renderInteractionResponse(
 		case 'approval': {
 			const action = String(response.action ?? '');
 			const reason = response.reason ? ` (${response.reason})` : '';
-			return `${head}I ${action === 'approved' ? 'APPROVED' : 'REJECTED'}${reason}.`;
+			// Edit-then-approve: the operator changed one or more editable values before approving.
+			// Surface them so the agent applies the NEW values in its backend, not the originals.
+			const edits = response.edits && typeof response.edits === 'object' && !Array.isArray(response.edits)
+				? (response.edits as Record<string, unknown>)
+				: null;
+			const editLine = edits && Object.keys(edits).length
+				? ` — and changed: ${Object.entries(edits).map(([k, v]) => `${k} → ${String(v)}`).join(', ')} (apply these new values)`
+				: '';
+			return `${head}I ${action === 'approved' ? 'APPROVED' : 'REJECTED'}${reason}${editLine}.`;
 		}
 		case 'choice': {
 			const sel = response.customValue ? `${response.selected} → "${response.customValue}"` : response.selected;
@@ -468,11 +524,18 @@ export function renderInteractionResponse(
 
 // ─── Defensive payload sanitisers ────────────────────────────────────────────────
 
-/** Return a valid card {title, fields:[{label,value}]}, salvaging a sibling `fields`, or undefined. */
+type CardField = { label: string; value: string; url?: string; tone?: 'default' | 'success' | 'warning' | 'danger'; editableId?: string };
+
+/**
+ * Return a valid card {title?, fields:[{label,value,url?,tone?,editableId?}]}, salvaging a
+ * sibling `fields`, or undefined. Title is optional (redundant on a surface). Per-field
+ * `url`/`tone`/`editableId` are preserved — `editableId` is what binds a field to an
+ * approval's `editables[]` for edit-then-approve.
+ */
 export function sanitizeCard(
 	raw: unknown,
 	input?: Record<string, unknown>
-): { title: string; fields: { label: string; value: string }[] } | undefined {
+): { title?: string; fields: CardField[] } | undefined {
 	const obj = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
 	const titleRaw = typeof obj.title === 'string' ? obj.title : typeof raw === 'string' ? raw : '';
 	const title = String(titleRaw).replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
@@ -483,10 +546,89 @@ export function sanitizeCard(
 			: [];
 	const fields = fieldsSrc
 		.filter((f): f is Record<string, unknown> => !!f && typeof f === 'object')
-		.map((f) => ({ label: String(f.label ?? '').trim(), value: String(f.value ?? '').trim() }))
+		.map((f) => {
+			const field: CardField = { label: String(f.label ?? '').trim(), value: String(f.value ?? '').trim() };
+			if (typeof f.url === 'string' && /^https?:\/\/\S+$/.test(f.url.trim())) field.url = f.url.trim();
+			if (f.tone === 'success' || f.tone === 'warning' || f.tone === 'danger' || f.tone === 'default') field.tone = f.tone;
+			if (typeof f.editableId === 'string' && f.editableId.trim()) field.editableId = f.editableId.trim();
+			return field;
+		})
 		.filter((f) => f.label && f.value);
-	if (!title || fields.length === 0) return undefined;
-	return { title, fields };
+	if (fields.length === 0) return undefined;
+	return { ...(title ? { title } : {}), fields };
+}
+
+type EditableField = {
+	id: string;
+	type: 'text' | 'number' | 'currency' | 'date' | 'choice';
+	value?: string | number;
+	label?: string;
+	options?: { id: string; label: string }[];
+	min?: number;
+	max?: number;
+};
+
+/**
+ * Edit-then-approve: sanitise the `editables` an approval declares. A malformed entry is
+ * dropped (never 400s the whole push); a `choice` with no valid options is dropped (the API
+ * rejects it). Returns undefined when nothing usable survives.
+ */
+export function sanitizeEditables(raw: unknown): EditableField[] | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const TYPES = new Set(['text', 'number', 'currency', 'date', 'choice']);
+	const out: EditableField[] = [];
+	for (const e of raw) {
+		if (!e || typeof e !== 'object') continue;
+		const o = e as Record<string, unknown>;
+		const id = String(o.id ?? '').trim();
+		const type = String(o.type ?? '');
+		if (!id || !TYPES.has(type)) continue;
+		const field: EditableField = { id, type: type as EditableField['type'] };
+		if (typeof o.value === 'number' || typeof o.value === 'string') field.value = o.value;
+		if (typeof o.label === 'string' && o.label.trim()) field.label = o.label.trim();
+		if (typeof o.min === 'number') field.min = o.min;
+		if (typeof o.max === 'number') field.max = o.max;
+		if (type === 'choice') {
+			const opts = Array.isArray(o.options)
+				? (o.options as unknown[])
+						.filter((x): x is Record<string, unknown> => !!x && typeof x === 'object')
+						.map((x) => ({ id: String(x.id ?? '').trim(), label: String(x.label ?? '').trim() }))
+						.filter((x) => x.id && x.label)
+				: [];
+			if (!opts.length) continue; // a choice editable requires options — else the API rejects it
+			field.options = opts;
+		}
+		out.push(field);
+		if (out.length >= 20) break;
+	}
+	return out.length ? out : undefined;
+}
+
+type DetailField = { label: string; value: string; url?: string; tone?: 'default' | 'success' | 'warning' | 'danger'; copyable?: boolean };
+
+/**
+ * The vessel's reference record. `null` clears it (passes through). A malformed
+ * shape collapses to undefined (omit) so it never 400s the whole push.
+ */
+export function sanitizeDetails(raw: unknown): { fields: DetailField[] } | null | undefined {
+	if (raw === null) return null;
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+	const fieldsSrc = Array.isArray((raw as Record<string, unknown>).fields) ? ((raw as Record<string, unknown>).fields as unknown[]) : [];
+	const fields: DetailField[] = [];
+	for (const f of fieldsSrc) {
+		if (!f || typeof f !== 'object') continue;
+		const o = f as Record<string, unknown>;
+		const label = String(o.label ?? '').trim();
+		const value = String(o.value ?? '').trim();
+		if (!label || !value) continue;
+		const field: DetailField = { label, value };
+		if (typeof o.url === 'string' && /^https?:\/\/\S+$/.test(o.url.trim())) field.url = o.url.trim();
+		if (o.tone === 'success' || o.tone === 'warning' || o.tone === 'danger' || o.tone === 'default') field.tone = o.tone;
+		if (o.copyable === true) field.copyable = true;
+		fields.push(field);
+		if (fields.length >= 20) break;
+	}
+	return fields.length ? { fields } : undefined;
 }
 
 /** Only pass a previewUrl the API will accept (http/https), else undefined. */