vessels 0.3.0 → 0.7.0

package/template/agent/src/protocol.ts

@@ -0,0 +1,140 @@
+/**
+ * THE VESSELS PROTOCOL — how your agent talks to its human operator.
+ *
+ * This prompt is DOMAIN-FREE on purpose. It teaches the model the *mechanics* of
+ * Vessels — the message kinds, the control tools, the payload shape Vessels reads,
+ * and the interaction principles (lead with a reply, plan before working, contact
+ * the human as a structured tool call). It says NOTHING about WHAT your agent does.
+ *
+ * Your agent's job lives in two other places you own:
+ *   • `role.ts`  — WHO the agent is and WHAT it does (one short paragraph).
+ *   • `tools.ts` — your real backend tools.
+ *
+ * At runtime the system prompt is:  ROLE  +  VESSELS_PROTOCOL  (+ NAME_RULE on a
+ * freshly-opened vessel). Keep this file as-is unless the Vessels product changes;
+ * shape the agent through role.ts and tools.ts instead.
+ */
+
+export const VESSELS_PROTOCOL = `You reach your human operator through Vessels. They are not at a terminal watching logs — they see a clean feed of messages from you and answer when you ask. Contacting them is a deliberate, structured act: you do not "print" to them, you call a tool. Everything below is HOW to use that channel well.
+
+BUBBLES vs SURFACES — every message you send is one of two kinds:
+- BUBBLE (chat): quick_reply, send_update, finish. A conversational line — inline markdown
+  only (**bold**, *italic*, \`code\`, [links](url)). No card, no interaction. ONE short
+  sentence; the reply IS the interaction (the human just types back). This is most of what
+  you send: heads-ups, progress, completion notes, quick questions.
+- SURFACE (artifact): a full-width composed thing the human reviews — something to approve,
+  a report or proposal to read. You compose it as ONE piece: a \`title\` heading, an optional
+  \`card\` of glance-facts, and a block-markdown \`body\` (the artifact itself — tables,
+  bullet/numbered lists, blockquotes, bold headings, links). Two ways to make one:
+    • request_approval/choice/checklist/text → a surface WITH a decision (the action bar).
+    • show_document(title, body) → a read-only surface (no decision, doesn't end the turn).
+  Put the REAL artifact in the body — never a "draft is ready" summary. The body is the one
+  place length is welcome; everything else stays terse.
+
+KEEP CHAT OUTPUT TERSE (writing it is the slow part) — this is about bubbles, NOT surface bodies:
+- A chat MESSAGE (send_update, or a finishing tool's message): ONE short sentence. No preamble, no 🎉.
+- plan() task labels: ≤ 5 words each.
+- Cards: ≤ 4 fields, short values.
+- The plan + auto-narrated steps + card carry the detail.
+Your private reasoning already streams live into the card as you work and then vanishes
+(it is NOT saved) — so think naturally and the operator sees the work happen. You do NOT
+need to narrate in chat messages; keep saved messages terse and let the live thinking show it.
+
+ALWAYS LEAD WITH quick_reply — never leave the operator on a blank screen while you think.
+Your FIRST action every turn is quick_reply: one short conversational line, pushed instantly.
+The turn ends ONLY when you SAY so — via the quick_reply "done" flag. Nothing is inferred:
+- quick_reply({ done: true }) → this line FULLY resolves the turn and you're handing back to
+  the operator now. The turn ends. Only two things qualify: a clarifying question back (you're
+  missing something you need), or an answer you can give from what you ALREADY know — no
+  lookup, no backend work.
+- quick_reply (done false/omitted) → this is your "on it" reply; you're about to keep working.
+  Call plan([...]) and work the steps, then end with the right finishing tool (request_* / finish).
+LITMUS TEST before you set done: true — does the line PROMISE something will follow? Anything
+like "on it", "pulling that now", "let me check", "looking into it", "I'll get you…", "one
+sec" — or any answer you can't give without a lookup — is a promise. NEVER mark a promise
+done: true; that ends the turn and the work never happens. When in doubt, leave done false
+and keep working — an unfinished promise is the one thing you must never leave.
+So: quick_reply first, every turn; then either mark it done (you've settled it) or keep
+working. Don't manufacture a 4-step plan for what's really one quick question back; and
+whenever you'd otherwise GUESS a key detail, ask it as a done:true question instead.
+
+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.
+   - 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
+     NOT write step narration — the backend tools auto-narrate under the task.
+
+2. Backend tools — YOUR tools (defined in tools.ts). Each can take task:"<label>" to tick the
+   plan as it runs. Call independent tools TOGETHER in one response to move fast — each
+   round-trip is slow.
+   - When the operator must review TEXT YOU WROTE before approving (a message, a reply, a
+     note), put the FULL text in the request_approval message field — it renders as the review
+     body, so they read the actual words inline. Do NOT bury it behind a previewUrl or
+     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.
+
+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)
+   - request_choice     — pick one option (with options[])
+   - request_checklist  — pick several options (with options[])
+   - request_text       — free-text answer
+   - finish             — wrap up; no further human action needed
+
+0. quick_reply(message, done?) — ALWAYS your first action (see the lead-with-a-reply rule
+   above): one conversational line, pushed instantly. done:true → it's the whole answer and
+   the turn ends. done false/omitted → it's your "on it" line; the working card opens right
+   after and you MUST plan() and work. NEVER mark a promise ("on it", "pulling that now")
+   done:true — leave done false and work.
+
+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
+  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.
+- Across the conversation, spread the interaction types (a choice, then an approval, then a
+  checklist, then a text question) rather than leaning on only one.
+- You CAN rename the vessel any time — set vesselTitle on plan(), quick_reply or finish. If the
+  operator asks to rename it, just do it and confirm; never claim titles are fixed.
+- After the human answers, do what it implies, then finish or ask the next question.
+- ONE closing line per turn. The finishing tool's message IS the wrap-up — do NOT also send a
+  near-duplicate finish/send_update saying the same thing.
+
+More you can attach (use when they genuinely help — don't decorate):
+- ATTACHMENTS: images render inline, files as a download link. Pass {type, url, filename?} on
+  send_update or show_document — only URLs you already host (e.g. one a backend tool returned).
+- PREVIEW LINK: a single tappable link card under a message (previewUrl) — a draft/dashboard to
+  open. Presentation only, no response. Pair it with a request_* when they should look THEN decide.
+- INTERACTION METADATA: attach metadata to any request_* and it rides back to you verbatim in the
+  response — use it to correlate the answer with your own record (an id, a type) instead of guessing.
+- The operator's messages may contain /commands or @mentions your workspace defined — they arrive
+  as plain text; interpret them per your role.
+
+Be efficient — every assistant turn is a slow round-trip, so do MORE per turn:
+- BUNDLE: advance the plan via task:"<label>" ON the work tool, and call independent work tools
+  TOGETHER in one response. A lone step() burns a whole round-trip.
+- You MUST end with an ending tool (request_* or finish). When you reach the task that needs the
+  human, call its work tools AND the request_* tool in the SAME response — do not tick that task
+  and stop. If you trail off without an ending tool the turn dies as a bare "Done."
+- Never repeat a tool call with identical arguments — reuse the result you already have.
+- In task:"…" use the EXACT task label from your plan() — never invent a new name.`;
+
+// Appended on a freshly-opened vessel (a vessel.created event), which arrives with a
+// placeholder title. The agent names it from the task on its first plan(). Domain-free.
+export const NAME_RULE = `
+
+NAME THIS VESSEL — it was just opened with a placeholder title. In your FIRST plan() this turn,
+set vesselTitle to a short, specific name drawn from the task: who or what it's about, ≤6 words,
+no generic words like "New" or "Request". Set it once; omit vesselTitle on later plan() calls.`;

package/template/agent/src/role.ts

@@ -0,0 +1,21 @@
+/**
+ * ★ EDIT THIS FILE ★
+ *
+ * This is the ONE place the engine learns your domain. Everything else in this
+ * template is Vessels-generic — the tool loop, the message protocol, the store.
+ * Describe WHO your agent is and WHAT it does, in a few plain sentences. Do not
+ * re-explain how to talk to Vessels here (that's `protocol.ts`, appended for you).
+ *
+ * Whatever you write becomes the top of the system prompt, ahead of the Vessels
+ * protocol. Keep it tight — a paragraph, not a manual. The same template that runs
+ * a booking manager runs a legal analyst or a stock-desk agent; only this string
+ * and `tools.ts` change.
+ *
+ * Examples of the SHAPE (replace entirely — these are not your agent):
+ *   "You are Atlas, a support-triage agent for an analytics SaaS. You read incoming
+ *    tickets, pull account context, and either resolve them or escalate to a human."
+ *   "You are a contracts analyst. You review redline requests, check them against
+ *    our standard terms, and surface anything that needs a lawyer's sign-off."
+ */
+
+export const ROLE = `TODO: Describe your agent. You are <name>, a <role> that <does what> on your operator's behalf. Add any standing rules it should always follow (tone, what it may decide alone vs. must hand back for approval, hard constraints).`;

package/template/agent/src/store.ts

@@ -0,0 +1,135 @@
+/**
+ * THE STORE SEAM — your agent's runtime state, on YOUR infrastructure.
+ *
+ * Two things live here, and both are facets of "the agent owns its own runtime":
+ *   1. Conversation state — the real Anthropic message history per vessel (including
+ *      tool_use / tool_result blocks). This is your agent's memory. Vessels is NOT
+ *      your memory; it only shows the human what happened.
+ *   2. A per-vessel lock — "don't run two turns for one vessel at once." That's a
+ *      property of YOUR deployment, so it lives here too, never in Vessels.
+ *
+ * Durability is an UPGRADE, not a prerequisite:
+ *   • MemoryStore (default) — zero infra. Correct for a single long-lived process.
+ *     State lives in RAM and resets on restart; the lock is an in-process mutex.
+ *   • PostgresStore — set DATABASE_URL and you get durable state + a cross-process
+ *     lock. It self-provisions (CREATE TABLE IF NOT EXISTS on init) — no migration
+ *     to run. Horizontally scaled? This is the lock that keeps turns serialised.
+ *
+ * Swap in Redis/Dynamo/your-DB by implementing the same `AgentStore` interface.
+ */
+import type { MessageParam } from '@anthropic-ai/sdk/resources/messages';
+
+export interface AgentStore {
+	/** The agent's conversation history for this vessel (empty array if new). */
+	loadState(vessel: string): Promise<MessageParam[]>;
+	/** Persist the full conversation history for this vessel. */
+	saveState(vessel: string, messages: MessageParam[]): Promise<void>;
+	/** Try to take the per-vessel lock. Returns false if someone else holds it. TTL bounds a crash. */
+	acquireLock(vessel: string, ttlSeconds: number): Promise<boolean>;
+	/** Release the per-vessel lock. */
+	releaseLock(vessel: string): Promise<void>;
+	/** Optional one-time setup (e.g. create tables). Called once at boot. */
+	init?(): Promise<void>;
+}
+
+// ─── MemoryStore — the zero-infra default ──────────────────────────────────────
+
+export class MemoryStore implements AgentStore {
+	private state = new Map<string, MessageParam[]>();
+	private locks = new Map<string, number>(); // vessel → expiry (ms epoch)
+
+	async loadState(vessel: string): Promise<MessageParam[]> {
+		return this.state.get(vessel) ?? [];
+	}
+
+	async saveState(vessel: string, messages: MessageParam[]): Promise<void> {
+		this.state.set(vessel, messages);
+	}
+
+	async acquireLock(vessel: string, ttlSeconds: number): Promise<boolean> {
+		const now = Date.now();
+		const until = this.locks.get(vessel);
+		if (until && until > now) return false; // still held
+		this.locks.set(vessel, now + ttlSeconds * 1000);
+		return true;
+	}
+
+	async releaseLock(vessel: string): Promise<void> {
+		this.locks.delete(vessel);
+	}
+}
+
+// ─── PostgresStore — durable, self-provisioning ─────────────────────────────────
+
+export class PostgresStore implements AgentStore {
+	// `pg` is imported lazily so MemoryStore users don't need a database driver loaded.
+	private pool: import('pg').Pool | null = null;
+	constructor(private readonly connectionString: string) {}
+
+	async init(): Promise<void> {
+		const { default: pg } = await import('pg');
+		this.pool = new pg.Pool({ connectionString: this.connectionString });
+		await this.pool.query(`
+			CREATE TABLE IF NOT EXISTS agent_state (
+				vessel     TEXT PRIMARY KEY,
+				messages   JSONB NOT NULL,
+				updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+			);
+			CREATE TABLE IF NOT EXISTS agent_locks (
+				vessel     TEXT PRIMARY KEY,
+				expires_at TIMESTAMPTZ NOT NULL
+			);
+		`);
+	}
+
+	private get db(): import('pg').Pool {
+		if (!this.pool) throw new Error('PostgresStore not initialised — call init() at boot');
+		return this.pool;
+	}
+
+	async loadState(vessel: string): Promise<MessageParam[]> {
+		const { rows } = await this.db.query<{ messages: MessageParam[] }>(
+			'SELECT messages FROM agent_state WHERE vessel = $1',
+			[vessel]
+		);
+		return rows[0]?.messages ?? [];
+	}
+
+	async saveState(vessel: string, messages: MessageParam[]): Promise<void> {
+		await this.db.query(
+			`INSERT INTO agent_state (vessel, messages, updated_at)
+			 VALUES ($1, $2, now())
+			 ON CONFLICT (vessel) DO UPDATE SET messages = EXCLUDED.messages, updated_at = now()`,
+			[vessel, JSON.stringify(messages)]
+		);
+	}
+
+	async acquireLock(vessel: string, ttlSeconds: number): Promise<boolean> {
+		// Atomic: take the row if free, OR steal it if the prior holder's TTL has lapsed.
+		const { rows } = await this.db.query(
+			`INSERT INTO agent_locks (vessel, expires_at)
+			 VALUES ($1, now() + make_interval(secs => $2))
+			 ON CONFLICT (vessel) DO UPDATE
+			   SET expires_at = EXCLUDED.expires_at
+			   WHERE agent_locks.expires_at < now()
+			 RETURNING vessel`,
+			[vessel, ttlSeconds]
+		);
+		return rows.length > 0;
+	}
+
+	async releaseLock(vessel: string): Promise<void> {
+		await this.db.query('DELETE FROM agent_locks WHERE vessel = $1', [vessel]);
+	}
+}
+
+/**
+ * Pick a store from the environment: PostgresStore when DATABASE_URL is set, else the
+ * in-memory default. Calls init() once. Replace this with your own wiring as you grow.
+ */
+export async function createStore(): Promise<AgentStore> {
+	const url = process.env.DATABASE_URL;
+	const store: AgentStore = url ? new PostgresStore(url) : new MemoryStore();
+	await store.init?.();
+	return store;
+}

package/template/agent/src/tools.ts

@@ -0,0 +1,90 @@
+/**
+ * ★ EDIT THIS FILE ★
+ *
+ * Your agent's BACKEND tools — the things it actually does in YOUR system (look
+ * something up, charge a card, file a ticket, run a query). The engine wires these
+ * into the Claude tool loop next to the built-in Vessels control tools (quick_reply,
+ * plan, request_approval, …). When the model calls one, the engine runs your
+ * `handler`, feeds the result back to the model, and (optionally) ticks the live
+ * working card via `narrate`.
+ *
+ * THE STATE BOUNDARY: these handlers run against YOUR backend and YOUR data. Vessels
+ * never sees your business data and is never your agent's memory — it only carries
+ * the human-facing messages the engine sends. A handler returns plain data; the model
+ * decides what (if anything) to surface to the operator.
+ *
+ * You do NOT need to add a `task` field to your schema — the engine injects it into
+ * every tool automatically so the model can tick the plan in the same call. Your
+ * handler receives the model's input WITHOUT `task`.
+ */
+import type { AgentActivityType } from 'vessels-sdk';
+import type { Tool } from '@anthropic-ai/sdk/resources/messages';
+
+export interface BackendTool {
+	/** The Anthropic tool definition the model sees (name, description, input_schema). */
+	definition: Tool;
+	/** Run the tool against your backend. Return any JSON-serialisable result. */
+	handler: (input: Record<string, unknown>) => Promise<unknown> | unknown;
+	/**
+	 * Optional: turn a call into a one-line working-card step (an icon + label the
+	 * operator sees tick by under the current task). Omit and the engine derives a
+	 * label from the tool name. `type` drives the icon (searching, processing, …).
+	 */
+	narrate?: (
+		input: Record<string, unknown>,
+		result: unknown
+	) => { type: AgentActivityType; label: string };
+}
+
+/**
+ * Your tools. Replace these two stubs with real ones. Keep them small and composable —
+ * the model calls several per turn. Anything that can fail should return a result that
+ * SAYS it failed (e.g. `{ ok: false, reason: '…' }`) rather than throwing, so the model
+ * can react and tell the operator.
+ */
+export const BACKEND_TOOLS: BackendTool[] = [
+	{
+		// ── TODO: replace with a real read from your system ───────────────────────
+		definition: {
+			name: 'lookup_record',
+			description:
+				'TODO: Look something up in your backend by id/name. Describe exactly what it returns so the model uses it well.',
+			input_schema: {
+				type: 'object',
+				properties: {
+					query: { type: 'string', description: 'What to look up' },
+				},
+				required: ['query'],
+			},
+		},
+		handler: async (input) => {
+			// TODO: call your API / DB here and return the real record.
+			throw new Error(
+				`lookup_record is a stub — implement it in tools.ts (query=${String(input.query)})`
+			);
+		},
+		narrate: (input) => ({ type: 'searching', label: `Looked up ${String(input.query ?? '')}`.trim() }),
+	},
+	{
+		// ── TODO: replace with a real action in your system ───────────────────────
+		definition: {
+			name: 'perform_action',
+			description:
+				'TODO: Do something in your backend (create/update/send). Describe its effect and what it returns.',
+			input_schema: {
+				type: 'object',
+				properties: {
+					action: { type: 'string', description: 'What to do' },
+					detail: { type: 'string', description: 'Any relevant detail / args' },
+				},
+				required: ['action'],
+			},
+		},
+		handler: async (input) => {
+			// TODO: perform the real action and return its outcome.
+			throw new Error(
+				`perform_action is a stub — implement it in tools.ts (action=${String(input.action)})`
+			);
+		},
+	},
+];