vessels 0.9.1 → 0.11.0

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"]);
 var InteractionTypeSchema = external_exports.enum([
   "approval",
   "choice",
@@ -4233,6 +4233,48 @@ var PushManyPayloadSchema = external_exports.object({
   /** @deprecated use `kind`. */
   display: DisplaySchema.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 MessagePatchSchema = external_exports.object({
   content: external_exports.string().min(1).max(1e4).optional(),
   card: CardSchema.nullable().optional(),
@@ -4686,6 +4728,37 @@ 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 FEEDBACK_TYPES = ["bug", "feature", "other"];
 async function cmdFeedback(args) {
   const flags = parseFlags(args);
@@ -4972,6 +5045,39 @@ Install the SDK:
   }
   console.log(`Full reference: https://vessels.app/llms-full.txt`);
 }
+async function cmdConversation(args) {
+  const flags = parseFlags(args);
+  const vessel = flags.vessel ?? args.find((a) => !a.startsWith("--"));
+  if (!vessel) {
+    console.error("Usage: vessels conversation <vessel> [--out <file.json>] [--limit <n>]");
+    process.exit(1);
+  }
+  const vesselId = await resolveVesselId(vessel);
+  const qs = flags.limit ? `?limit=${encodeURIComponent(flags.limit)}` : "";
+  const data = await api(`/api/v1/vessels/${vesselId}/trace${qs}`);
+  const trace = data.trace;
+  const outPath = resolve(flags.out ?? `vessels-trace-${vessel.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`);
+  writeFileSync(outPath, JSON.stringify(trace, null, 2));
+  const s = trace.summary;
+  console.log(`
+Wrote ${s.events} events \u2192 ${outPath}`);
+  console.log(`  ${s.requests} agent calls \xB7 ${s.degraded} degraded \xB7 ${s.rejected} rejected \xB7 ${s.webhookFailures} webhook failures`);
+  if (!trace.verbose) {
+    console.log(`  note: workspace not in debug mode \u2014 request bodies weren't captured, so agent calls are absent.`);
+  }
+  if (s.issues.length) {
+    console.log(`
+${s.issues.length} issue(s) \u2014 read these first:
+`);
+    for (const i of s.issues) {
+      const where = i.endpoint ? ` ${i.endpoint}` : "";
+      console.log(`  [#${i.seq} ${i.severity}] ${i.code}${i.field ? ` (${i.field})` : ""}${where}`);
+      console.log(`     ${i.message}`);
+      if (i.hint) console.log(`     \u2192 ${i.hint}`);
+    }
+  }
+  console.log("");
+}
 var [, , cmd, sub, ...rest] = process.argv;
 var HELP = `
 vessels \u2014 CLI for Vessels (vessels.app)
@@ -5029,10 +5135,21 @@ 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 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).
 
+  vessels conversation <vessel> [--out <file.json>] [--limit <n>]
+      Replay a vessel to a JSON trace file for debugging an agent run: a single
+      timeline of your agent's calls (with the sent-vs-applied diff \u2014 which fields
+      actually landed), the messages that rendered, agent-activity step timing,
+      human responses and webhook deliveries. Prints a summary + issues; the full
+      trace goes to the file. Accepts vessel UUID or external_id.
+
   vessels validate <file.json>
       Check a push payload against the required syntax WITHOUT sending it.
       Also reads piped JSON (cat payload.json | vessels validate) or an inline
@@ -5109,8 +5226,10 @@ Run: vessels help`);
 Run: vessels help`);
     process.exit(1);
   }
+  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 === "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.9.1",
+  "version": "0.11.0",
   "description": "Vessels CLI — manage your agent communication layer from the terminal",
   "type": "module",
   "bin": {