vessels 0.3.0 → 0.7.0

package/package.json

@@ -1,24 +1,31 @@
 {
 	"name": "vessels",
-	"version": "0.3.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",
-		"@types/node": "^25.5.2"
+		"@types/node": "^25.5.2",
+		"@vessels/types": "workspace:*"
 	},
 	"dependencies": {}
 }

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"
+  }
+}