vessels 0.6.0 → 0.7.0

package/dist/index.js

@@ -6,9 +6,10 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, cpSync, renameSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
 import * as readline from "readline/promises";
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
@@ -4060,8 +4061,7 @@ var InteractionTypeSchema = external_exports.enum([
   "approval",
   "choice",
   "checklist",
-  "text_input",
-  "confirm_preview"
+  "text_input"
 ]);
 var ApprovalInteractionSchema = external_exports.object({
   type: external_exports.literal("approval"),
@@ -4104,22 +4104,11 @@ var TextInputInteractionSchema = external_exports.object({
   submitLabel: external_exports.string().optional(),
   metadata: external_exports.record(external_exports.unknown()).optional()
 });
-var ConfirmPreviewInteractionSchema = external_exports.object({
-  type: external_exports.literal("confirm_preview"),
-  prompt: external_exports.string().min(1),
-  previewUrl: external_exports.string().url(),
-  previewLabel: external_exports.string().optional(),
-  approveLabel: external_exports.string().optional(),
-  rejectLabel: external_exports.string().optional(),
-  reasonRequiredOnReject: external_exports.boolean().optional(),
-  metadata: external_exports.record(external_exports.unknown()).optional()
-});
 var InteractionSchema = external_exports.discriminatedUnion("type", [
   ApprovalInteractionSchema,
   ChoiceInteractionSchema,
   ChecklistInteractionSchema,
-  TextInputInteractionSchema,
-  ConfirmPreviewInteractionSchema
+  TextInputInteractionSchema
 ]);
 var AgentActivityTypeSchema = external_exports.enum(["thinking", "searching", "tool_use", "browsing", "processing"]);
 var AgentTodoStatusSchema = external_exports.enum(["pending", "in_progress", "done"]);
@@ -4139,7 +4128,10 @@ var CardFieldSchema = external_exports.object({
   value: external_exports.string()
 });
 var CardSchema = external_exports.object({
-  title: external_exports.string().min(1),
+  // Optional: a glance-facts card under a surface takes its heading from the
+  // surface `title`, so a card title is redundant there. Still allowed (e.g. a
+  // standalone card on a bubble, or a pinned card).
+  title: external_exports.string().min(1).optional(),
   fields: external_exports.array(CardFieldSchema)
 });
 var AttachmentSchema = external_exports.discriminatedUnion("type", [
@@ -4147,6 +4139,8 @@ var AttachmentSchema = external_exports.discriminatedUnion("type", [
   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(),
   vessel: external_exports.string().optional(),
@@ -4159,13 +4153,28 @@ var PushPayloadSchema = external_exports.object({
     "metadata exceeds 16KB limit"
   ).optional(),
   pinCard: CardSchema.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(),
   attachments: external_exports.array(AttachmentSchema).max(10).optional(),
   suggestions: external_exports.array(external_exports.string().min(1).max(500)).max(5).optional(),
-  agentActivity: AgentActivitySchema.optional()
-}).refine((d) => d.message || d.agentActivity, {
-  message: "Either message or agentActivity is required"
+  agentActivity: AgentActivitySchema.optional(),
+  /**
+   * Live token-stream buffer — an ephemeral monospace block the human watches
+   * fill in real time (set it on the message you create, then keep replacing it
+   * via `PATCH /messages/:id`, and clear it with `null` when done). It is a live
+   * window, not a transcript: send the tail you want shown (the SDK trims to the
+   * last 8000 chars). Plaintext, like agentActivity. Vanishes when cleared.
+   */
+  tokenStream: external_exports.string().max(8e3).optional(),
+  /** 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()
+}).refine((d) => d.message || d.agentActivity || d.tokenStream, {
+  message: "One of message, agentActivity, or tokenStream is required"
 });
 var PushManyPayloadSchema = external_exports.object({
   vessels: external_exports.array(external_exports.string().min(1)).min(1).max(100),
@@ -4174,20 +4183,33 @@ var PushManyPayloadSchema = external_exports.object({
   card: CardSchema.optional(),
   interaction: InteractionSchema.optional(),
   pinCard: CardSchema.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(),
   suggestions: external_exports.array(external_exports.string().min(1).max(500)).max(5).optional(),
   metadata: external_exports.record(external_exports.unknown()).refine(
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
-  ).optional()
+  ).optional(),
+  kind: KindSchema.optional(),
+  title: external_exports.string().max(200).optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.optional()
 });
 var MessagePatchSchema = external_exports.object({
   content: external_exports.string().min(1).max(1e4).optional(),
   card: CardSchema.nullable().optional(),
   attachments: external_exports.array(AttachmentSchema).max(10).nullable().optional(),
   suggestions: external_exports.array(external_exports.string().min(1).max(500)).max(5).nullable().optional(),
-  agentActivity: AgentActivitySchema.nullable().optional()
+  agentActivity: AgentActivitySchema.nullable().optional(),
+  /** Replace the live token-stream window, or `null` to clear it (block vanishes). */
+  tokenStream: external_exports.string().max(8e3).nullable().optional(),
+  /** Switch kind: 'surface' = full-width artifact, 'bubble' or null = chat bubble. */
+  kind: KindSchema.nullable().optional(),
+  /** Update the surface heading, or `null` to clear it. */
+  title: external_exports.string().max(200).nullable().optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -4205,16 +4227,11 @@ var ChecklistResponseSchema = external_exports.object({
 var TextInputResponseSchema = external_exports.object({
   text: external_exports.string()
 });
-var ConfirmPreviewResponseSchema = external_exports.object({
-  action: external_exports.enum(["approved", "rejected"]),
-  reason: external_exports.string().optional()
-});
 var InteractionResponseSchema = external_exports.discriminatedUnion("interactionType", [
   external_exports.object({ interactionType: external_exports.literal("approval"), response: ApprovalResponseSchema }),
   external_exports.object({ interactionType: external_exports.literal("choice"), response: ChoiceResponseSchema }),
   external_exports.object({ interactionType: external_exports.literal("checklist"), response: ChecklistResponseSchema }),
-  external_exports.object({ interactionType: external_exports.literal("text_input"), response: TextInputResponseSchema }),
-  external_exports.object({ interactionType: external_exports.literal("confirm_preview"), response: ConfirmPreviewResponseSchema })
+  external_exports.object({ interactionType: external_exports.literal("text_input"), response: TextInputResponseSchema })
 ]);
 var WebhookVesselSchema = external_exports.object({
   id: external_exports.string(),
@@ -4252,6 +4269,11 @@ var WebhookInteractionResponsePayloadSchema = external_exports.object({
     vessel: WebhookVesselSchema
   })
 });
+var SupersededInteractionSchema = external_exports.object({
+  message_id: external_exports.string(),
+  interaction_type: InteractionTypeSchema,
+  prompt: external_exports.string().nullable()
+});
 var WebhookUserMessagePayloadSchema = external_exports.object({
   event: external_exports.literal("message.user"),
   vessel_id: external_exports.string(),
@@ -4261,7 +4283,8 @@ var WebhookUserMessagePayloadSchema = external_exports.object({
     message_id: external_exports.string(),
     content: external_exports.string(),
     vessel: WebhookVesselSchema,
-    context: external_exports.array(WebhookContextMessageSchema)
+    context: external_exports.array(WebhookContextMessageSchema),
+    superseded_interaction: SupersededInteractionSchema.optional()
   })
 });
 var WebhookVesselCreatedPayloadSchema = external_exports.object({
@@ -4609,10 +4632,10 @@ async function cmdPush(args) {
   console.log(`Message sent. vessel_id=${data.vessel_id} message_id=${data.message_id}`);
 }
 function readStdin() {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const chunks = [];
     process.stdin.on("data", (c) => chunks.push(c));
-    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("end", () => resolve2(Buffer.concat(chunks).toString("utf8")));
   });
 }
 function zodIssueLines(err) {
@@ -4761,7 +4784,42 @@ async function cmdTypesToggle(enabled) {
   });
   console.log(`User-initiated vessels ${((_a = data.workspace) == null ? void 0 : _a.userVesselsEnabled) ? "enabled" : "disabled"}.`);
 }
+function templateDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "template", "agent");
+}
+async function cmdInitAgentTemplate(args) {
+  const target = resolve(args.find((a) => !a.startsWith("--")) ?? "vessels-agent");
+  const src = templateDir();
+  if (!existsSync(src)) {
+    console.error("Template not found in this CLI build. Reinstall: npm i -g vessels@latest");
+    process.exit(1);
+  }
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`Refusing to scaffold into a non-empty directory: ${target}`);
+    process.exit(1);
+  }
+  cpSync(src, target, { recursive: true });
+  for (const [from, to] of [["_gitignore", ".gitignore"], ["_env.example", ".env.example"]]) {
+    const p = join(target, from);
+    if (existsSync(p)) renameSync(p, join(target, to));
+  }
+  console.log(`
+Scaffolded a Vessels agent into ${target}
+`);
+  console.log("Next:\n");
+  console.log(`  cd ${target}`);
+  console.log("  npm install");
+  console.log("  cp .env.example .env        # then fill in your keys");
+  console.log("  npm run dev                 # webhook server on :3000\n");
+  console.log("Need keys? Run `vessels init --email you@example.com` (then --otp <code>),");
+  console.log("then point a webhook at your running server:");
+  console.log("  vessels webhooks create --url https://<your-public-url>/\n");
+  console.log("Edit src/role.ts (who your agent is) and src/tools.ts (its backend tools).");
+  console.log("Full reference: https://vessels.app/llms-full.txt");
+}
 async function cmdInit(args) {
+  if (args.includes("--agent-template")) return cmdInitAgentTemplate(args);
   const flags = parseFlags(args);
   const email = flags.email || await prompt("Email: ");
   if (!flags.otp) {
@@ -4842,11 +4900,20 @@ Quick setup (Claude Code / AI agents \u2014 fully non-interactive):
   # With a webhook (optional, run once your server is deployed):
   vessels init --email me@example.com --otp 847293 --webhook-url https://myapp.com/hooks/vessels
 
+Want a running agent to start from?
+
+  vessels init --agent-template ./my-agent   # scaffolds a Vessels-native tool-loop agent
+
 Commands:
   vessels init --email <email> [--otp <code>] [--name <key-name>] [--webhook-url <url>]
       First-time setup: account + API key (+ webhook). Two-step: run once to send OTP,
       re-run with --otp to complete. Prints copy-ready .env entries.
 
+  vessels init --agent-template [dir]
+      Scaffold a runnable, Vessels-native starter agent into <dir> (default ./vessels-agent):
+      a Claude tool-loop wired to Vessels, with stub tools to swap for your real backend.
+      Edit src/role.ts and src/tools.ts, then npm install and npm run dev.
+
   vessels login [--email <email>] [--otp <code>]
   vessels logout
   vessels whoami

package/package.json

@@ -1,20 +1,26 @@
 {
 	"name": "vessels",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Vessels CLI — manage your agent communication layer from the terminal",
 	"type": "module",
 	"bin": {
 		"vessels": "./dist/index.js"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"template"
 	],
 	"scripts": {
 		"build": "tsup",
 		"dev": "tsup --watch"
 	},
 	"license": "MIT",
-	"keywords": ["ai", "agents", "vessels", "cli"],
+	"keywords": [
+		"ai",
+		"agents",
+		"vessels",
+		"cli"
+	],
 	"devDependencies": {
 		"tsup": "^8.5.1",
 		"typescript": "^5",

package/template/agent/README.md

@@ -0,0 +1,111 @@
+# Your Vessels agent
+
+A working, Vessels-native agent. It runs on **your** box, keeps its own state where **you**
+tell it to, and talks to Vessels over HTTP purely to show your human operator what's happening
+and collect their decisions. Swap the two stub tools for your real backend and you have a real
+agent — a booking manager, a support triager, a contracts analyst, a stock-desk assistant.
+
+> **Vessels is the view/interaction layer — your agent owns its data.** Vessels never holds your
+> agent's memory, state, or business data. It carries the human-facing messages you send and the
+> answers you get back. Your conversation history and your locks live in *your* store (see
+> `src/store.ts`).
+
+## Quickstart
+
+```bash
+npm install
+cp .env.example .env        # then fill in the three required keys
+npm run dev                 # starts the webhook server on :3000
+```
+
+Don't have keys yet? Install the CLI and run setup:
+
+```bash
+npx vessels init --email you@example.com            # emails a code
+npx vessels init --email you@example.com --otp 123456
+# → prints VESSELS_API_KEY. Then point a webhook at your running server:
+npx vessels webhooks create --url https://<your-public-url>/   # → prints VESSELS_WEBHOOK_SECRET
+```
+
+For local development, expose `:3000` with a tunnel (ngrok, cloudflared, `vessels`-friendly
+host) and use that public URL as the webhook URL. Then open a vessel in the Vessels app / mobile
+and message it — your agent answers.
+
+## The two files you edit
+
+| File | What it is |
+|------|-----------|
+| **`src/role.ts`** | WHO your agent is and WHAT it does — one short paragraph. The only place the engine learns your domain. |
+| **`src/tools.ts`** | Your backend tools. Each is `{ definition, handler, narrate? }`. Replace the two stubs. |
+
+Everything else is the **engine** and you rarely touch it:
+
+| File | What it is |
+|------|-----------|
+| `src/protocol.ts` | The domain-free system prompt — how to talk to Vessels (bubbles vs surfaces, lead with a reply, plan before working, ask the human as a structured tool call). |
+| `src/vessels-tools.ts` | The fixed Vessels control tools + payload sanitisers + interaction mapping. |
+| `src/agent.ts` | One turn: the Claude tool loop, the live working card, the forced-ending safety net. |
+| `src/store.ts` | `AgentStore` — your conversation state + per-vessel lock. |
+| `src/index.ts` | The webhook server (verify → ACK → run the turn). |
+
+## How a turn works
+
+1. The human acts in Vessels → Vessels POSTs a webhook to `src/index.ts`.
+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`).
+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.
+
+**Contacting the human is a tool call.** That's the headline pattern: the model doesn't print to a
+human, it raises `request_approval`/`choice`/… and the turn pauses until they answer. Human-in-the-loop
+is native, not bolted on.
+
+## State & durability
+
+By default the agent uses **`MemoryStore`** — zero infrastructure, correct for a single long-lived
+process, state resets on restart. To make it durable, set `DATABASE_URL` and it switches to
+**`PostgresStore`**, which:
+
+- persists each vessel's conversation history, and
+- holds a **cross-process per-vessel lock** (so two webhooks for the same vessel can't run
+  interleaved turns) — the thing you need once you run more than one instance.
+
+`PostgresStore` self-provisions its tables on boot (`CREATE TABLE IF NOT EXISTS`) — there's no
+migration to run. Want Redis, Dynamo, or your own DB? Implement the `AgentStore` interface in
+`src/store.ts`; nothing else changes.
+
+## Deploying
+
+This template is a long-lived Node process, so background work after the 200 ACK simply finishes.
+If you deploy to **serverless** (Lambda / Vercel / Workers), the process can freeze right after the
+response — there you must `await` the turn before responding, or use the platform's background
+primitive (e.g. `waitUntil`) so the turn isn't killed mid-flight. The `parseWebhookEvent → ACK →
+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**
+(images/files you host), **preview links**, **suggested replies**, vessel **naming/renaming**, and
+user-initiated vessel **types**. Idempotency keys, the per-vessel lock, and the resolve-before-ask
+discipline are handled for you. (It deliberately keeps the notification rule too: the working card
+stays silent, only your reply and outcome buzz the human's phone.)
+
+A few Vessels features live on **your backend**, not inside a turn — call them on the `vessels`
+SDK directly:
+
+- `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.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.
+
+## Learn more
+
+- Full Vessels docs (API, SDK, webhooks, interaction types): <https://vessels.app/llms-full.txt>
+- The SDK: `vessels-sdk` on npm.

package/template/agent/_env.example

@@ -0,0 +1,23 @@
+# ── Required ────────────────────────────────────────────────────────────────
+# A vsl_ API key for your workspace (push back to Vessels). From `vessels init` or Settings.
+VESSELS_API_KEY=vsl_...
+# The secret printed when you created your webhook (`vessels webhooks create` or Settings).
+VESSELS_WEBHOOK_SECRET=whsec_...
+# Your Anthropic API key (drives the agent — this is YOUR LLM key, on YOUR bill).
+ANTHROPIC_API_KEY=sk-ant-...
+
+# ── Optional ────────────────────────────────────────────────────────────────
+# Claude model (default: claude-sonnet-4-6).
+# ANTHROPIC_MODEL=claude-sonnet-4-6
+# Port the webhook server listens on (default: 3000).
+# PORT=3000
+# Override the Vessels base URL (default: https://vessels.app).
+# VESSELS_BASE_URL=https://vessels.app
+# Set DEBUG=1 to log the turn flow (model calls, tools, pushes).
+# DEBUG=1
+
+# ── Durability upgrade (optional) ─────────────────────────────────────────────
+# Set DATABASE_URL and the agent uses PostgresStore: durable conversation state +
+# a cross-process lock. It self-provisions its tables on boot (no migration to run).
+# Leave it unset to use the zero-infra in-memory default.
+# DATABASE_URL=postgres://user:pass@host:5432/dbname

package/template/agent/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+*.log

package/template/agent/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "vessels-agent",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Vessels-native agent — talks to its human operator through Vessels.",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.85.0",
+    "dotenv": "^16.4.5",
+    "pg": "^8.13.0",
+    "vessels-sdk": "^0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.11.10",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}