vessels 0.6.0 → 0.7.0

package/template/agent/src/agent.ts

@@ -0,0 +1,533 @@
+/**
+ * THE ENGINE — one Vessels turn.
+ *
+ * This is the reusable, domain-free heart of the template: a Claude tool loop that
+ * leads with a reply, opens a live working card, drives your backend tools while
+ * ticking a plan, seals the card, and ends with exactly one finishing tool (a
+ * message or a human interaction). It talks to Vessels ONLY through the public SDK,
+ * exactly as any third-party agent would.
+ *
+ * What's domain-specific is injected from elsewhere and never appears here:
+ *   • `role.ts`        — who the agent is.
+ *   • `tools.ts`       — what it can do.
+ *   • `protocol.ts`    — how it talks to Vessels (the generic system prompt).
+ *   • `store.ts`       — where its state and lock live (YOUR infra, not Vessels).
+ *
+ * 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 } from '@anthropic-ai/sdk/resources/messages';
+import { Vessels } from 'vessels-sdk';
+import type { PushOptions, AgentActivityType, AgentTodoStatus } from 'vessels-sdk';
+import { ROLE } from './role.js';
+import { VESSELS_PROTOCOL, NAME_RULE } from './protocol.js';
+import { BACKEND_TOOLS } from './tools.js';
+import {
+	CONTROL_TOOLS,
+	ENDING_TOOLS,
+	TASK_FIELD,
+	buildInteraction,
+	defaultNarrate,
+	sanitizeCard,
+	cleanPreviewUrl,
+	cleanTitle,
+	cleanSuggestions,
+	cleanLabels,
+	cleanAttachments,
+} from './vessels-tools.js';
+import type { AgentStore } from './store.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 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';
+
+/** Lightweight trace — set DEBUG=1 to see the turn flow. Swap for your logger. */
+function log(...args: unknown[]): void {
+	if (DEBUG) console.log('[agent]', ...args);
+}
+
+// ─── Tool wiring: control tools + your backend tools ────────────────────────────
+
+const backendByName = new Map(BACKEND_TOOLS.map((t) => [t.definition.name, t]));
+
+/** Inject the plan-advancing `task` field into a backend tool's schema (the engine handles it). */
+function withTaskField(def: Tool): Tool {
+	const schema = def.input_schema as { properties?: Record<string, unknown>; [k: string]: unknown };
+	return {
+		...def,
+		input_schema: { ...schema, properties: { ...(schema.properties ?? {}), task: TASK_FIELD } } as Tool['input_schema'],
+	};
+}
+
+const ALL_TOOLS: Tool[] = [...CONTROL_TOOLS, ...BACKEND_TOOLS.map((t) => withTaskField(t.definition))];
+
+// ─── Conversation history helpers (your store holds the real Anthropic messages) ──
+
+/** Append the human's new turn, merging into a trailing user turn so roles stay valid. */
+function appendHumanTurn(messages: MessageParam[], humanInput: string): void {
+	const last = messages[messages.length - 1];
+	if (last && last.role === 'user') {
+		// Prior turn closed with a tool_result user turn — add the human text as a block.
+		const block = { type: 'text' as const, text: humanInput };
+		last.content = Array.isArray(last.content) ? [...last.content, block] : [{ type: 'text' as const, text: String(last.content) }, block];
+	} else {
+		messages.push({ role: 'user', content: humanInput });
+	}
+}
+
+/** Cap history at MAX_HISTORY, slicing only at a plain user message so tool_use/result pairs stay intact. */
+function trimHistory(messages: MessageParam[]): MessageParam[] {
+	if (messages.length <= MAX_HISTORY) return messages;
+	for (let i = messages.length - MAX_HISTORY; i < messages.length; i++) {
+		const m = messages[i];
+		if (m.role === 'user' && typeof m.content === 'string') return messages.slice(i);
+	}
+	return messages; // no safe cut point — keep all rather than corrupt the history
+}
+
+// ─── The turn ────────────────────────────────────────────────────────────────
+
+export interface RunTurnOpts {
+	vessels: Vessels;
+	store: AgentStore;
+	vessel: string; // external_id to push to
+	humanInput: string; // the new user turn (message.user / rendered interaction answer / [SYSTEM EVENT])
+	idempotencyKeyBase: string; // e.g. the triggering message id — makes pushes retry-safe
+	openingMessage?: string; // text for the working card (proactive triggers pass the headline)
+	vesselTitle?: string; // set on the first push (creates the vessel) for agent-initiated triggers
+	nameVessel?: boolean; // freshly-opened vessel with a placeholder title — agent names it (vessel.created)
+}
+
+/** A best-effort push that never throws — a failed push must not crash the turn. */
+async function safePush(vessels: Vessels, args: PushOptions): Promise<{ messageId?: string }> {
+	try {
+		const r = await vessels.push(args);
+		return { messageId: r.messageId };
+	} catch (e) {
+		log('push failed', e instanceof Error ? e.message : e);
+		return {};
+	}
+}
+
+/** A best-effort PATCH (live activity / token stream) — never throws. */
+async function safePatch(vessels: Vessels, messageId: string, patch: Record<string, unknown>): Promise<void> {
+	try {
+		await vessels.editMessage(messageId, patch);
+	} catch (e) {
+		log('patch failed', e instanceof Error ? e.message : e);
+	}
+}
+
+export async function runTurn(opts: RunTurnOpts): Promise<void> {
+	const { vessels, store, vessel, humanInput, idempotencyKeyBase, openingMessage, vesselTitle, nameVessel } = opts;
+	log('turn_start', { vessel, humanInput: humanInput.slice(0, 120) });
+
+	// Per-vessel mutex: serialise turns on this vessel. A blocked turn must NOT be dropped —
+	// the event that triggered it (usually a user message) would go unanswered forever. So we
+	// WAIT for the lock, polling until the holder finishes, then run normally.
+	const LOCK_TTL = 120;
+	const LOCK_WAIT_MS = 80_000;
+	const LOCK_POLL_MS = 3_000;
+	const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+	const waitDeadline = Date.now() + LOCK_WAIT_MS;
+	let gotLock = await store.acquireLock(vessel, LOCK_TTL);
+	// Contended → a prior turn is still running. Our lead reply fires only AFTER we hold the
+	// lock, so push a one-line "still here" bubble NOW so a queued turn is alive on screen.
+	if (!gotLock) {
+		await safePush(vessels, {
+			vessel,
+			message: 'Got it — just finishing the previous step, back in a moment…',
+			idempotencyKey: `${idempotencyKeyBase}:queued-ack`,
+		});
+	}
+	while (!gotLock && Date.now() < waitDeadline) {
+		await sleep(LOCK_POLL_MS);
+		gotLock = await store.acquireLock(vessel, LOCK_TTL);
+	}
+	if (!gotLock) {
+		log('gave up waiting for lock');
+		return; // the TTL will free it; rare backstop
+	}
+
+	// Recover state AFTER the lock: if we waited for a prior turn, its work is now persisted,
+	// so we thread on top of it instead of clobbering it.
+	const messages: MessageParam[] = await store.loadState(vessel);
+	appendHumanTurn(messages, humanInput);
+
+	const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, timeout: 45_000, maxRetries: 1 });
+	const systemPrompt = `${ROLE}\n\n${VESSELS_PROTOCOL}${nameVessel ? NAME_RULE : ''}`;
+
+	// ── The working card opens LAZILY — only once the agent commits to real work (a
+	// plan/step/backend tool). A turn that just needs a quick message back never opens one.
+	const opening = openingMessage ?? 'Working on it…';
+	let activityId: string | null = null;
+	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 pendingLabels: string[] | undefined;
+	const ensureWorkingCard = async (): Promise<void> => {
+		if (cardOpened) return;
+		cardOpened = true;
+		const r = await safePush(vessels, {
+			vessel,
+			...(pendingTitle ? { vesselTitle: pendingTitle } : {}),
+			...(pendingPinCard ? { pinCard: pendingPinCard } : {}),
+			...(pendingLabels ? { labels: pendingLabels } : {}),
+			...(acknowledged ? {} : { message: opening }),
+			agentActivity: { type: 'thinking', label: 'Getting started' },
+			idempotencyKey: `${idempotencyKeyBase}:work`,
+		});
+		pendingTitle = undefined;
+		pendingPinCard = undefined;
+		pendingLabels = undefined;
+		activityId = r.messageId ?? null;
+	};
+
+	// Authoritative todo list for the working card; we PATCH the full list each update.
+	type Todo = { label: string; status: AgentTodoStatus };
+	let todos: Todo[] = [];
+	const patchActivity = async (body: Record<string, unknown>) => {
+		if (activityId) await safePatch(vessels, activityId, { agentActivity: body });
+	};
+	// Tick the plan to `task`, marking the prior in-progress task done.
+	const advanceTodo = async (rawTask: unknown): Promise<boolean> => {
+		const task = String(rawTask ?? '').trim();
+		const match = task ? todos.find((t) => t.label.toLowerCase() === task.toLowerCase()) : undefined;
+		if (!match) return false;
+		todos = todos.map((t) => {
+			if (t.label.toLowerCase() === match.label.toLowerCase()) return { ...t, status: 'in_progress' as AgentTodoStatus };
+			if (t.status === 'in_progress') return { ...t, status: 'done' as AgentTodoStatus };
+			return t;
+		});
+		await patchActivity({ todos });
+		return true;
+	};
+
+	// Live token stream → fills the working card's ephemeral monospace block as the model
+	// generates, cleared when the turn seals. Throttled, replace-semantics, tail-trimmed.
+	const STREAM_THROTTLE_MS = 150;
+	const STREAM_WINDOW = 4000;
+	let streamBuf = '';
+	let streamLast: string | null = null;
+	let streamTimer: ReturnType<typeof setTimeout> | null = null;
+	let streamPending: Promise<unknown> = Promise.resolve();
+	const flushStream = (): Promise<unknown> => {
+		if (!activityId) return streamPending;
+		const text = streamBuf.length > STREAM_WINDOW ? streamBuf.slice(-STREAM_WINDOW) : streamBuf;
+		if (text === streamLast) return streamPending;
+		streamLast = text;
+		streamPending = vessels.editMessage(activityId, { tokenStream: text }).catch(() => {
+			streamLast = null;
+		});
+		return streamPending;
+	};
+	const writeStream = (delta: string) => {
+		if (!activityId || !delta) return;
+		streamBuf += delta;
+		if (!streamTimer) {
+			streamTimer = setTimeout(() => {
+				streamTimer = null;
+				void flushStream();
+			}, STREAM_THROTTLE_MS);
+		}
+	};
+	const stopStream = async () => {
+		if (streamTimer) {
+			clearTimeout(streamTimer);
+			streamTimer = null;
+		}
+		await streamPending.catch(() => {});
+	};
+
+	// pushes made this turn (product messages — the human-facing output)
+	type PendingPush = {
+		message: string;
+		kind?: 'bubble' | 'surface';
+		title?: string;
+		card?: unknown;
+		pinCard?: unknown;
+		labels?: string[];
+		interaction?: Record<string, unknown> | null;
+		suggestions?: string[];
+		previewUrl?: string;
+		attachments?: Array<{ type: 'image' | 'file'; url: string; filename?: string }>;
+	};
+	const pushes: PendingPush[] = [];
+
+	let ended = false;
+	const recordEnding = (name: string, input: Record<string, unknown>) => {
+		const msg = String(input.message ?? '');
+		const endPin = sanitizeCard(input.pinCard);
+		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 });
+		} else {
+			const interaction = buildInteraction(name, input);
+			pushes.push({
+				message: msg || String(input.prompt ?? 'Please respond.'),
+				kind: 'surface',
+				title: cleanTitle(input.title),
+				card: sanitizeCard(input.card, input),
+				pinCard: endPin,
+				labels: endLabels,
+				interaction,
+				previewUrl: cleanPreviewUrl(input.previewUrl),
+			});
+		}
+		ended = true;
+	};
+
+	const turnStart = Date.now();
+	let outOfTime = false;
+	try {
+		for (let step = 0; step < MAX_TURN_STEPS; step++) {
+			if (Date.now() - turnStart > TURN_BUDGET_MS) {
+				outOfTime = true;
+				break;
+			}
+
+			log('model_call', { step });
+			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();
+
+			messages.push({ role: 'assistant', content: resp.content });
+
+			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) });
+			}
+
+			// No tool call — treat any plain text as a final message and stop.
+			if (toolUses.length === 0) {
+				const text = resp.content.filter((b): b is TextBlock => b.type === 'text').map((b) => b.text).join('\n').trim();
+				if (text) pushes.push({ message: text });
+				ended = true;
+				break;
+			}
+
+			const ending = toolUses.find((t) => ENDING_TOOLS.has(t.name));
+			const toolResults: ToolResultBlockParam[] = [];
+
+			// Lift vesselTitle / triage off THIS turn's plan() BEFORE the lead push, so they ride
+			// the first push that lands (no extra model round-trip).
+			const planTool = toolUses.find((t) => t.name === 'plan');
+			if (planTool) {
+				const pIn = (planTool.input ?? {}) as Record<string, unknown>;
+				if (!pendingTitle) {
+					const named = cleanTitle(pIn.vesselTitle);
+					if (named) pendingTitle = named;
+				}
+				if (!pendingPinCard) pendingPinCard = sanitizeCard(pIn.pinCard);
+				if (!pendingLabels) pendingLabels = cleanLabels(pIn.labels);
+			}
+
+			// The lead reply: quick_reply opens every turn. Pushed FIRST, before the card. The turn
+			// ends here ONLY on an EXPLICIT done:true — never inferred from the absence of other tools.
+			const qrTool = toolUses.find((t) => t.name === 'quick_reply');
+			if (qrTool) {
+				const qrIn = (qrTool.input ?? {}) as Record<string, unknown>;
+				const qrMsg = String(qrIn.message ?? '').trim();
+				const qrDone = qrIn.done === true;
+				const qrTitle = cleanTitle(qrIn.vesselTitle);
+				if (qrTitle && !pendingTitle) pendingTitle = qrTitle;
+				if (!qrDone) {
+					await safePush(vessels, {
+						vessel,
+						...(pendingTitle ? { vesselTitle: pendingTitle } : {}),
+						message: qrMsg || 'On it.',
+						idempotencyKey: `${idempotencyKeyBase}:lead`,
+					});
+					pendingTitle = undefined;
+					acknowledged = true;
+				} else {
+					pushes.push({ message: qrMsg || 'Could you clarify?' });
+					ended = true;
+				}
+				toolResults.push({ type: 'tool_result', tool_use_id: qrTool.id, content: 'sent' });
+			}
+
+			// Real work opens the working card now, lazily. A quick_reply-only / finish-only turn skips this.
+			if (toolUses.some((t) => !ENDING_TOOLS.has(t.name) && t.name !== 'quick_reply')) await ensureWorkingCard();
+
+			for (const tu of toolUses) {
+				if (ENDING_TOOLS.has(tu.name) || tu.name === 'quick_reply') continue; // handled above / after loop
+				const input = (tu.input ?? {}) as Record<string, unknown>;
+				if (tu.name === 'plan') {
+					const labels = Array.isArray(input.todos) ? (input.todos as unknown[]).map(String) : [];
+					todos = labels.map((label) => ({ label, status: 'pending' as AgentTodoStatus }));
+					await patchActivity({ todos });
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'plan set' });
+				} else if (tu.name === 'step') {
+					await advanceTodo(input.task);
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'on it' });
+				} else if (tu.name === 'send_update') {
+					if (input.task) await advanceTodo(input.task);
+					const msg = String(input.message ?? '');
+					if (msg)
+						pushes.push({
+							message: msg,
+							card: sanitizeCard(input.card, input),
+							suggestions: cleanSuggestions(input.suggestions),
+							attachments: cleanAttachments(input.attachments),
+							previewUrl: cleanPreviewUrl(input.previewUrl),
+						});
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'posted' });
+				} else if (tu.name === 'show_document') {
+					const title = cleanTitle(input.title);
+					const body = String(input.body ?? '').trim();
+					const docPin = sanitizeCard(input.pinCard);
+					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;
+						if (docLabels) pendingLabels = docLabels;
+					}
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'shown' });
+				} else if (backendByName.has(tu.name)) {
+					// YOUR tool. Tick the plan (task field), run the handler, auto-narrate a step.
+					if (input.task) await advanceTodo(input.task);
+					const { task: _task, ...callInput } = input;
+					const tool = backendByName.get(tu.name)!;
+					let result: unknown;
+					try {
+						result = await tool.handler(callInput);
+					} catch (e) {
+						// A throwing tool must not crash the turn — return the failure so the model reacts.
+						result = { ok: false, error: e instanceof Error ? e.message : String(e) };
+						log('backend tool threw', tu.name, e);
+					}
+					const narr = tool.narrate ? tool.narrate(callInput, result) : defaultNarrate(tu.name);
+					await patchActivity({ type: narr.type satisfies AgentActivityType, label: narr.label });
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: JSON.stringify(result) });
+				} else {
+					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: `Unknown tool: ${tu.name}`, is_error: true });
+				}
+			}
+
+			// Close out EVERY tool_use with a result so the persisted history stays well-formed
+			// (an ending tool gets a synthetic ack — we break before its real result would matter).
+			const answered = new Set(toolResults.map((r) => r.tool_use_id));
+			for (const tu of toolUses) if (!answered.has(tu.id)) toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'acknowledged' });
+			messages.push({ role: 'user', content: toolResults });
+
+			if (ending) {
+				recordEnding(ending.name, (ending.input ?? {}) as Record<string, unknown>);
+				break;
+			}
+			if (ended) break; // quick_reply({done:true}) settled the turn
+		}
+
+		// Ran out of steps or budget without an ending tool — force ONE closing turn so an intended
+		// question/decision is never silently downgraded to "Done."
+		if (!ended) {
+			log('forced_ending', { reason: outOfTime ? 'budget' : 'out_of_steps' });
+			const stop = outOfTime
+				? 'STOP — you are out of time. Close the turn NOW with the SINGLE most important ending tool: if you were about to ask the operator something, raise THAT request_* now; otherwise finish. Call no other tool.'
+				: 'STOP — you are out of working steps. Respond with EXACTLY ONE ending tool NOW: request_approval/choice/checklist/text if the human must decide, otherwise finish. Call no other tool.';
+			try {
+				const fr = await anthropic.messages.create({
+					model: MODEL,
+					max_tokens: 768,
+					system: `${systemPrompt}\n\n${stop}`,
+					tools: ALL_TOOLS,
+					tool_choice: { type: 'any' },
+					messages,
+				});
+				const forced = fr.content.find((b): b is ToolUseBlock => b.type === 'tool_use' && ENDING_TOOLS.has(b.name));
+				if (forced) {
+					recordEnding(forced.name, (forced.input ?? {}) as Record<string, unknown>);
+					// Keep history well-formed: record the forced assistant turn + a synthetic result.
+					messages.push({ role: 'assistant', content: fr.content });
+					const uses = fr.content.filter((b): b is ToolUseBlock => b.type === 'tool_use');
+					messages.push({ role: 'user', content: uses.map((u) => ({ type: 'tool_result' as const, tool_use_id: u.id, content: 'acknowledged' })) });
+				}
+			} catch (e) {
+				log('forced_ending failed', e instanceof Error ? e.message : e);
+			}
+			if (!ended) {
+				pushes.push({ message: "Here's where I've got to — I'll pause here." });
+				ended = true;
+			}
+		}
+	} catch (err) {
+		log('turn error', err);
+		pushes.push({ message: 'I hit a snag and had to stop early.' });
+	} finally {
+		// Guarantee the seal — the working card this turn opened MUST resolve, even on an error.
+		try {
+			await stopStream();
+			if (activityId) await safePatch(vessels, activityId, { agentActivity: null, tokenStream: null });
+		} catch (e) {
+			log('seal failed', e);
+		}
+
+		if (pushes.length === 0) pushes.push({ message: 'Done.' });
+
+		// Deliver the human-facing pushes. State is saved separately (below), so a failed push
+		// never loses conversation context — it only drops a message.
+		for (let i = 0; i < pushes.length; i++) {
+			const p = pushes[i];
+			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 labelsForThisPush = p.labels ?? (i === 0 ? pendingLabels : undefined);
+			if (i === 0) {
+				pendingPinCard = undefined;
+				pendingLabels = undefined;
+			}
+			const r = await safePush(vessels, {
+				vessel,
+				...(titleForThisPush ? { vesselTitle: titleForThisPush } : {}),
+				message: p.message,
+				kind: p.kind,
+				title: p.title,
+				card: p.card as PushOptions['card'],
+				...(pinForThisPush ? { pinCard: pinForThisPush as PushOptions['pinCard'] } : {}),
+				...(labelsForThisPush ? { labels: labelsForThisPush } : {}),
+				interaction: (p.interaction ?? undefined) as PushOptions['interaction'],
+				suggestions: p.suggestions,
+				previewUrl: p.previewUrl,
+				attachments: p.attachments,
+				idempotencyKey: `${idempotencyKeyBase}:${i}`,
+			});
+			// A model-malformed optional field can still get the push rejected. The last push is the
+			// real answer/interaction — retry it stripped to the essentials the agent fully controls.
+			if (!r.messageId && isLast) {
+				await safePush(vessels, {
+					vessel,
+					message: p.message,
+					interaction: (p.interaction ?? undefined) as PushOptions['interaction'],
+					idempotencyKey: `${idempotencyKeyBase}:${i}:retry`,
+				});
+			}
+		}
+
+		// Persist the conversation BEFORE releasing the lock, so a waiting turn threads on it.
+		try {
+			await store.saveState(vessel, trimHistory(messages));
+		} catch (e) {
+			log('saveState failed', e);
+		}
+		await store.releaseLock(vessel);
+	}
+}

package/template/agent/src/index.ts

@@ -0,0 +1,130 @@
+/**
+ * Your agent's webhook server.
+ *
+ * Vessels POSTs an event here when the human acts (opens a vessel, sends a message,
+ * answers an interaction). We verify the signature, ACK 200 immediately (a Claude tool
+ * loop far exceeds the ~10s webhook timeout — never run it inline), and run the turn in
+ * the background. The engine pushes everything the human sees back through the SDK.
+ *
+ * This is a zero-dependency node:http server so it runs anywhere with no framework.
+ * Prefer Express/Hono/Next? Keep `parseWebhookEvent → ACK → runTurn` and swap the shell.
+ *
+ *   ┌── deployment note ─────────────────────────────────────────────────────────┐
+ *   │ This long-lived process keeps running after the 200, so background work just │
+ *   │ finishes. On serverless (Lambda/Vercel/Workers) the process may freeze after │
+ *   │ the response — there you must await the turn or use the platform's background │
+ *   │ primitive (e.g. waitUntil) so it isn't killed mid-turn.                       │
+ *   └────────────────────────────────────────────────────────────────────────────┘
+ */
+import 'dotenv/config';
+import http from 'node:http';
+import { Vessels } from 'vessels-sdk';
+import { createStore, type AgentStore } from './store.js';
+import { runTurn } from './agent.js';
+import { renderInteractionResponse } from './vessels-tools.js';
+
+const API_KEY = process.env.VESSELS_API_KEY;
+const WEBHOOK_SECRET = process.env.VESSELS_WEBHOOK_SECRET;
+const PORT = Number(process.env.PORT || 3000);
+
+if (!API_KEY || !WEBHOOK_SECRET || !process.env.ANTHROPIC_API_KEY) {
+	console.error('Missing env. Set VESSELS_API_KEY, VESSELS_WEBHOOK_SECRET, ANTHROPIC_API_KEY (copy .env.example → .env).');
+	process.exit(1);
+}
+
+const vessels = new Vessels({ apiKey: API_KEY, baseUrl: process.env.VESSELS_BASE_URL });
+let store: AgentStore;
+
+/** Read the raw request body (we need the exact bytes to verify the HMAC signature). */
+function readBody(req: http.IncomingMessage): Promise<string> {
+	return new Promise((resolve, reject) => {
+		let data = '';
+		req.on('data', (c) => (data += c));
+		req.on('end', () => resolve(data));
+		req.on('error', reject);
+	});
+}
+
+/** Fire-and-forget: this process is long-lived, so the turn just finishes after we ACK. */
+function runInBackground(work: Promise<unknown>): void {
+	void Promise.resolve(work).catch((err) => console.error('[agent] background error', err));
+}
+
+const server = http.createServer(async (req, res) => {
+	if (req.method === 'GET') {
+		res.writeHead(200, { 'Content-Type': 'text/plain' });
+		res.end('Vessels agent is alive. POST webhook events here.');
+		return;
+	}
+	if (req.method !== 'POST') {
+		res.writeHead(405).end();
+		return;
+	}
+
+	const raw = await readBody(req);
+	const signature = req.headers['x-vessels-signature'];
+	const event = await vessels.parseWebhookEvent(raw, Array.isArray(signature) ? signature[0] : signature ?? '', WEBHOOK_SECRET);
+
+	if (!event) {
+		res.writeHead(401, { 'Content-Type': 'application/json' });
+		res.end(JSON.stringify({ ok: false, error: 'Invalid signature or unknown event' }));
+		return;
+	}
+
+	const vessel = event.vessel.externalId ?? event.vessel.id;
+
+	// Build the turn for this event. ACK first, then run it in the background.
+	let work: Promise<void> | null = null;
+
+	if (event.type === 'vessel.created') {
+		// The human opened a new vessel from the app — it has a placeholder title; the agent
+		// names it on its first plan(). `message.content` is the first thing they typed.
+		// `vessel.type` is the type they chose (Ticket / Enquiry / …) — yours to interpret; pass
+		// it in so the agent can route on it. Enable types with `vessels types enable/add`.
+		const first = (event.message.content ?? '').trim();
+		const typeNote = event.vessel.type ? `[New ${event.vessel.type} vessel] ` : '';
+		work = runTurn({
+			vessels,
+			store,
+			vessel,
+			humanInput: `${typeNote}${first || '(the operator opened a new vessel)'}`,
+			nameVessel: true,
+			idempotencyKeyBase: `vc:${event.message.id}`,
+		});
+	} else if (event.type === 'message.user') {
+		const content = (event.message.content ?? '').trim();
+		if (content) {
+			// If this message expired a live interaction, tell the agent so it reacts to what they
+			// actually said instead of waiting on the now-dead card.
+			const sup = event.supersededInteraction;
+			const humanInput = sup
+				? `[The operator did not answer your ${sup.interactionType}${sup.prompt ? ` "${sup.prompt}"` : ''} — that card expired because they sent a message instead. Respond to what they actually said; re-offer or adjust only if it still makes sense.]\n${content}`
+				: content;
+			work = runTurn({ vessels, store, vessel, humanInput, idempotencyKeyBase: `mu:${event.message.id}` });
+		}
+	} else if (event.type === 'interaction.response') {
+		const prompt = (event.originMessage?.interaction?.prompt as string | undefined) ?? undefined;
+		work = runTurn({
+			vessels,
+			store,
+			vessel,
+			humanInput: renderInteractionResponse(event.interactionType, event.response, prompt),
+			idempotencyKeyBase: `ir:${event.id}`,
+		});
+	}
+	// event.type === 'message.cancelled' → nothing long-running to abort here; just ACK.
+
+	res.writeHead(200, { 'Content-Type': 'application/json' });
+	res.end(JSON.stringify({ ok: true }));
+	if (work) runInBackground(work);
+});
+
+createStore()
+	.then((s) => {
+		store = s;
+		server.listen(PORT, () => console.log(`Vessels agent listening on :${PORT}`));
+	})
+	.catch((err) => {
+		console.error('[agent] failed to start', err);
+		process.exit(1);
+	});