vessels 0.8.0 → 0.9.1

package/dist/index.js

@@ -4156,7 +4156,13 @@ var AgentActivitySchema = external_exports.object({
 });
 var CardFieldSchema = external_exports.object({
   label: external_exports.string().min(1),
-  value: external_exports.string()
+  value: external_exports.string(),
+  // Optional: render the value as a tappable link, deep-linking the human into
+  // your own web UI (e.g. an admin tray). Rendered on full-size cards (surface /
+  // pinned-card detail), not the compact vessel-list preview.
+  url: external_exports.string().url().max(2048).optional(),
+  // Optional colour hint — pure styling, no behaviour. 'default' === unset.
+  tone: external_exports.enum(["default", "success", "warning", "danger"]).optional()
 });
 var CardSchema = external_exports.object({
   // Optional: a glance-facts card under a surface takes its heading from the
@@ -4314,6 +4320,13 @@ var SupersededInteractionSchema = external_exports.object({
   interaction_type: InteractionTypeSchema,
   prompt: external_exports.string().nullable()
 });
+var WebhookEventAttachmentSchema = external_exports.object({
+  type: external_exports.enum(["image", "file"]),
+  filename: external_exports.string().nullish(),
+  fileId: external_exports.string().optional(),
+  downloadUrl: external_exports.string().optional(),
+  url: external_exports.string().optional()
+});
 var WebhookUserMessagePayloadSchema = external_exports.object({
   event: external_exports.literal("message.user"),
   vessel_id: external_exports.string(),
@@ -4324,6 +4337,7 @@ var WebhookUserMessagePayloadSchema = external_exports.object({
     content: external_exports.string(),
     vessel: WebhookVesselSchema,
     context: external_exports.array(WebhookContextMessageSchema),
+    attachments: external_exports.array(WebhookEventAttachmentSchema).optional(),
     superseded_interaction: SupersededInteractionSchema.optional()
   })
 });
@@ -4338,7 +4352,8 @@ var WebhookVesselCreatedPayloadSchema = external_exports.object({
       message_id: external_exports.string(),
       content: external_exports.string().nullable(),
       created_at: external_exports.string()
-    })
+    }),
+    attachments: external_exports.array(WebhookEventAttachmentSchema).optional()
   })
 });
 var WebhookMessageCancelledPayloadSchema = external_exports.object({
@@ -4671,6 +4686,37 @@ async function cmdPush(args) {
   }
   console.log(`Message 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);
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      i++;
+      continue;
+    }
+    positionals.push(args[i]);
+  }
+  let message = (flags.message || positionals.join(" ")).trim();
+  if (!message) message = (await prompt("Your feedback (bug or feature request): ")).trim();
+  if (!message) {
+    console.error("Nothing to submit.");
+    process.exit(1);
+  }
+  const type = (flags.type || "other").toLowerCase();
+  if (!FEEDBACK_TYPES.includes(type)) {
+    console.error(`Type must be one of: ${FEEDBACK_TYPES.join(", ")}`);
+    process.exit(1);
+  }
+  const data = await api("/api/v1/feedback", {
+    method: "POST",
+    body: JSON.stringify({ type, message })
+  });
+  const label = type === "other" ? "Feedback" : type === "bug" ? "Bug report" : "Feature request";
+  console.log(`
+${label} submitted \u2014 thank you!`);
+  console.log(`  id ${data.id}`);
+}
 function readStdin() {
   return new Promise((resolve2) => {
     const chunks = [];
@@ -4976,6 +5022,10 @@ Commands:
   vessels types disable
       Manage vessel types and the user-initiated-vessels feature flag.
 
+  vessels feedback <message> [--type bug|feature|other]
+      Send a bug report or feature request to the Vessels team. Requires login.
+      Message can be positional or --message; --type defaults to "other".
+
   vessels push --vessel <id> --message <text> --key <api_key>
       (--key can be omitted if VESSELS_API_KEY is set)
 
@@ -5059,6 +5109,7 @@ Run: vessels help`);
 Run: vessels help`);
     process.exit(1);
   }
+  if (cmd === "feedback") return cmdFeedback([sub, ...rest].filter(Boolean));
   if (cmd === "push") return cmdPush([sub, ...rest].filter(Boolean));
   if (cmd === "message") return cmdMessage([sub, ...rest].filter(Boolean));
   if (cmd === "validate") return cmdValidate([sub, ...rest].filter(Boolean));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vessels",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Vessels CLI — manage your agent communication layer from the terminal",
   "type": "module",
   "bin": {

package/template/agent/README.md

@@ -92,9 +92,25 @@ chat **bubbles** and full-width **surfaces**; all four **interactions** (`approv
 **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.)
+user-initiated vessel **types**; plus **inbound files** the human sends you — downloaded, stored on
+your infra, resolved, and (for images) read by the model via **vision** (see below). Idempotency
+keys, the per-vessel lock, **one card per turn**, 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.)
+
+## Receiving files (inbound)
+
+Vessels is **not a file store** — when the human sends a photo/document, it relays the bytes
+transiently and hands you a signed, short-lived `downloadUrl`. The engine does the full handshake in
+`src/inbound.ts`: **download** it → **store** it on your infra (`store.putInboundFile`) → **resolve**
+the permanent link back (`vessels.resolveInboundFile`) so the human sees your hosted copy and Vessels
+drops its copy → for images, hand the bytes to the model as a **vision** block so your agent actually
+sees them.
+
+The zero-infra default stores files in the same `MemoryStore`/`PostgresStore` and serves them from the
+agent's own `GET /files/:id` route, so the resolved link points back at you. Set **`PUBLIC_URL`** to
+your externally-reachable base (your tunnel in dev) so that link is fetchable. In production, point
+`putInboundFile` at object storage (S3/R2/GCS) and return a CDN URL — nothing else changes.
 
 A few Vessels features live on **your backend**, not inside a turn — call them on the `vessels`
 SDK directly:

package/template/agent/_env.example

@@ -11,6 +11,10 @@ ANTHROPIC_API_KEY=sk-ant-...
 # ANTHROPIC_MODEL=claude-sonnet-4-6
 # Port the webhook server listens on (default: 3000).
 # PORT=3000
+# Your agent's externally-reachable base URL — where stored INBOUND files are served from
+# (the human's app fetches the link you resolve). In local dev this is your tunnel, the same
+# host as your webhook. Defaults to http://localhost:<PORT> (only reachable on this machine).
+# PUBLIC_URL=https://your-tunnel.example.com
 # 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).

package/template/agent/package.json

@@ -13,7 +13,7 @@
     "@anthropic-ai/sdk": "^0.85.0",
     "dotenv": "^16.4.5",
     "pg": "^8.13.0",
-    "vessels-sdk": "^0.14.0"
+    "vessels-sdk": "^0.17.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/template/agent/src/agent.ts

@@ -16,9 +16,9 @@
  * 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 type { MessageParam, Tool, ToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlockParam, ImageBlockParam } from '@anthropic-ai/sdk/resources/messages';
 import { Vessels } from 'vessels-sdk';
-import type { PushOptions, AgentActivityType, AgentTodoStatus } from 'vessels-sdk';
+import type { PushOptions, AgentActivityType, AgentTodoStatus, InboundAttachment } from 'vessels-sdk';
 import { ROLE } from './role.js';
 import { VESSELS_PROTOCOL, NAME_RULE } from './protocol.js';
 import { BACKEND_TOOLS } from './tools.js';
@@ -35,7 +35,8 @@ import {
 	cleanLabels,
 	cleanAttachments,
 } from './vessels-tools.js';
-import type { AgentStore, ResumeMarker } from './store.js';
+import type { AgentStore } from './store.js';
+import { handleInboundFiles, attachImagesToLastUserMessage } from './inbound.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
@@ -100,6 +101,7 @@ export interface RunTurnOpts {
 	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)
+	attachments?: InboundAttachment[]; // files the human sent — download → store on your infra → resolve → view (inbound.ts)
 }
 
 /** A best-effort push that never throws — a failed push must not crash the turn. */
@@ -123,7 +125,7 @@ async function safePatch(vessels: Vessels, messageId: string, patch: Record<stri
 }
 
 export async function runTurn(opts: RunTurnOpts): Promise<void> {
-	const { vessels, store, vessel, humanInput, idempotencyKeyBase, openingMessage, vesselTitle, nameVessel } = opts;
+	const { vessels, store, vessel, humanInput, idempotencyKeyBase, openingMessage, vesselTitle, nameVessel, attachments } = 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 —
@@ -156,10 +158,27 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	// 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);
-	// A prior turn may have paused a plan on a mid-plan checkpoint — recover its handle
-	// so we re-attach to the SAME working card below instead of opening a new one.
-	const resume = await store.loadResume(vessel);
+
+	// Inbound files (human → agent). Before the model runs, do the handshake for any attachments
+	// on this event: download each from the Vessels relay, store it on YOUR infra, resolve the
+	// permanent link back (the human now sees it), and collect viewable images as vision blocks.
+	// The text note rides the persisted history; the image bytes ride ONLY this live model call.
+	let effectiveHumanInput = humanInput;
+	let inboundImages: ImageBlockParam[] = [];
+	if (attachments?.length) {
+		try {
+			const inbound = await handleInboundFiles({ vessels, store, attachments });
+			inboundImages = inbound.imageBlocks;
+			if (inbound.note) effectiveHumanInput = humanInput ? `${humanInput}\n\n${inbound.note}` : inbound.note;
+		} catch (e) {
+			log('inbound files failed', e instanceof Error ? e.message : e);
+		}
+	}
+
+	appendHumanTurn(messages, effectiveHumanInput);
+	// Attach the downloaded image bytes to the current user turn so the model can SEE them
+	// (vision). Only on this live call — the persisted history stays text-only.
+	attachImagesToLastUserMessage(messages, inboundImages);
 
 	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 : ''}`;
@@ -191,19 +210,15 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 		activityId = r.messageId ?? null;
 	};
 
-	// Authoritative todo list for the working card; we PATCH the full list each update.
+	// Authoritative todo list for THIS turn's working card; we PATCH the full list each update.
+	// ONE CARD PER TURN: always starts empty — the model declares the turn's plan with plan().
+	// We never re-attach to a prior turn's card. A card is anchored at one point in the stream;
+	// mutating it on a later turn renders its new steps ABOVE messages that already followed it
+	// (chronological inversion) and mis-files them under a stale task. So every turn opens its
+	// own card at the bottom and seals it on end. Continuity lives in the recovered history.
 	type Todo = { label: string; status: AgentTodoStatus };
 	let todos: Todo[] = [];
 
-	// RESUME a paused plan: re-attach to the SAME working card and its plan instead of
-	// opening a fresh one, so the operator sees ONE continuous card across the whole
-	// multi-step flow. The first work patch flips it from awaiting_input back to working.
-	if (resume?.activityId) {
-		activityId = resume.activityId;
-		cardOpened = true;
-		if (Array.isArray(resume.todos)) todos = resume.todos.map((t) => ({ label: String(t.label), status: t.status }));
-		log('resume', { activityId, todos: todos.length });
-	}
 	const patchActivity = async (body: Record<string, unknown>) => {
 		if (activityId) await safePatch(vessels, activityId, { agentActivity: body });
 	};
@@ -273,9 +288,6 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	const pushes: PendingPush[] = [];
 
 	let ended = false;
-	// A mid-plan checkpoint (request_* with keepWorking) ends the MODEL loop but does NOT
-	// seal the card: the plan pauses on the human and resumes on their reply (see finally).
-	let pauseForInput = false;
 	const recordEnding = (name: string, input: Record<string, unknown>) => {
 		const msg = String(input.message ?? '');
 		const endPin = sanitizeCard(input.pinCard);
@@ -286,7 +298,9 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 			pushes.push({ message: msg || 'All done.', pinCard: endPin, labels: endLabels });
 		} else {
 			const interaction = buildInteraction(name, input);
-			if (input.keepWorking === true) pauseForInput = true;
+			// keepWorking is purely semantic — it tells the model the task isn't finished, so the
+			// NEXT turn continues it in a fresh card. It does NOT keep this card alive: every turn
+			// seals its own card on end (one card per turn).
 			pushes.push({
 				message: msg || String(input.prompt ?? 'Please respond.'),
 				kind: 'surface',
@@ -390,7 +404,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 				if (tu.name === 'plan') {
 					const labels = Array.isArray(input.todos) ? (input.todos as unknown[]).map(String) : [];
 					// Merge by label, preserving the status of tasks already in flight — matters on
-					// a RESUME (the seeded plan keeps its done steps) and any same-turn re-plan.
+					// a same-turn re-plan (a tweaked plan keeps the steps it already ticked).
 					todos = labels.map((label) => {
 						const prev = todos.find((t) => t.label.toLowerCase() === label.toLowerCase());
 						return { label, status: prev?.status ?? ('pending' as AgentTodoStatus) };
@@ -494,19 +508,14 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 		log('turn error', err);
 		pushes.push({ message: 'I hit a snag and had to stop early.' });
 	} finally {
-		// Resolve the working card — UNLESS this turn paused on a mid-plan checkpoint, in
-		// which case we leave it live (awaiting_input) for the next turn to resume. Either way
-		// the card never orphans, even on an error.
+		// ALWAYS seal this turn's working card (one card per turn) — even when the turn ends on
+		// a keepWorking checkpoint, the card resolves here as a faithful record of THIS turn's
+		// work; the next turn opens its own fresh card. Never orphans, even on an error.
 		try {
 			await stopStream();
 			if (activityId) {
-				await safePatch(vessels, activityId, {
-					agentActivity: pauseForInput ? { status: 'awaiting_input' } : null,
-					tokenStream: null,
-				});
+				await safePatch(vessels, activityId, { agentActivity: null, tokenStream: null });
 			}
-			// Persist the paused-plan handle (or clear a prior one now the plan resumed/ended).
-			await store.saveResume(vessel, pauseForInput && activityId ? { activityId, todos } : null);
 		} catch (e) {
 			log('seal failed', e);
 		}

package/template/agent/src/inbound.ts

@@ -0,0 +1,125 @@
+/**
+ * INBOUND FILES — the human → agent handshake.
+ *
+ * When the human attaches a photo/document, Vessels holds the bytes TRANSIENTLY and hands
+ * you a signed, short-lived `downloadUrl` on the `message.user` / `vessel.created` event
+ * (Vessels is not a file store). You must fetch it, store it on YOUR own infra, and hand
+ * back a permanent link — then Vessels swaps in your link and drops its copy. Per file:
+ *
+ *   1. download  — fetch the signed downloadUrl (plain HTTP)
+ *   2. store     — `store.putInboundFile(...)` → a permanent URL on YOUR infra (store.ts)
+ *   3. resolve   — `vessels.resolveInboundFile(fileId, url)` so the human sees your copy
+ *   4. view      — for supported images, hand the bytes to the model as a vision block so
+ *                  your agent can ACTUALLY SEE the image
+ *
+ * You usually don't edit this file — point `store.putInboundFile` at S3/R2/GCS and you're done.
+ */
+import type { ImageBlockParam, MessageParam, ContentBlockParam } from '@anthropic-ai/sdk/resources/messages';
+import type { Vessels, InboundAttachment } from 'vessels-sdk';
+import type { AgentStore } from './store.js';
+
+// Anthropic vision accepts these as base64 image blocks. Other image kinds and all
+// non-images are still stored + resolved, just not shown to the model inline.
+const VISION_MIME = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+const MAX_VISION_BYTES = 4 * 1024 * 1024; // ~Anthropic's practical per-image base64 ceiling
+
+function extToMime(filename?: string | null): string | undefined {
+	const ext = (filename ?? '').toLowerCase().match(/\.([a-z0-9]+)$/)?.[1];
+	switch (ext) {
+		case 'jpg':
+		case 'jpeg': return 'image/jpeg';
+		case 'png': return 'image/png';
+		case 'gif': return 'image/gif';
+		case 'webp': return 'image/webp';
+		case 'pdf': return 'application/pdf';
+		default: return undefined;
+	}
+}
+
+export interface InboundResult {
+	/** Image blocks to append to the model's current user turn (vision). */
+	imageBlocks: ImageBlockParam[];
+	/** A text note describing what arrived + where it landed, appended to the user turn. */
+	note: string;
+}
+
+/**
+ * Run the full inbound handshake for every attachment on this event, in parallel. Returns
+ * the image blocks to show the model and a note for the user turn. Best-effort per file —
+ * one file's failure never sinks the others (or the turn).
+ */
+export async function handleInboundFiles(opts: {
+	vessels: Vessels;
+	store: AgentStore;
+	attachments: InboundAttachment[];
+}): Promise<InboundResult> {
+	const pending = opts.attachments.filter((a) => a.fileId && a.downloadUrl);
+	if (!pending.length) return { imageBlocks: [], note: '' };
+
+	const imageBlocks: ImageBlockParam[] = [];
+	const lines: string[] = [];
+
+	const results = await Promise.all(
+		pending.map(async (att) => {
+			try {
+				// 1 — download from the Vessels relay (signed, short-lived URL).
+				const res = await fetch(att.downloadUrl!);
+				if (!res.ok) throw new Error(`download ${res.status}`);
+				const headerMime = res.headers.get('content-type')?.split(';')[0]?.trim();
+				const mime = headerMime && headerMime !== 'application/octet-stream'
+					? headerMime
+					: extToMime(att.filename) ?? (att.type === 'image' ? 'image/jpeg' : 'application/octet-stream');
+				const bytes = new Uint8Array(await res.arrayBuffer());
+
+				// 2 — store on YOUR infra, 3 — resolve the permanent link back to Vessels.
+				const url = await opts.store.putInboundFile({ fileId: att.fileId, bytes, contentType: mime, filename: att.filename ?? undefined });
+				await opts.vessels.resolveInboundFile(att.fileId, url);
+
+				// 4 — supported, in-budget image → vision block.
+				const viewable = att.type === 'image' && VISION_MIME.has(mime) && bytes.byteLength <= MAX_VISION_BYTES;
+				if (viewable) {
+					imageBlocks.push({
+						type: 'image',
+						source: { type: 'base64', media_type: mime as 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp', data: Buffer.from(bytes).toString('base64') },
+					});
+				}
+				return { att, url, viewable, ok: true as const };
+			} catch {
+				return { att, ok: false as const };
+			}
+		})
+	);
+
+	for (const r of results) {
+		const label = `${r.att.filename ?? r.att.fileId} (${r.att.type})`;
+		if (!r.ok) lines.push(`- ${label} → could not be retrieved (the relay link may have expired)`);
+		else if (r.viewable) lines.push(`- ${label} → stored at ${r.url}; the image is attached to this message for you to view`);
+		else lines.push(`- ${label} → stored at ${r.url}`);
+	}
+
+	const one = pending.length === 1;
+	const note =
+		`[The operator attached ${one ? 'a file' : `${pending.length} files`}. Your backend downloaded ${one ? 'it' : 'them'} from ` +
+		`Vessels, stored ${one ? 'it' : 'them'} on your own storage, and confirmed the permanent link(s) back (the operator now ` +
+		`sees your hosted file(s)):\n${lines.join('\n')}\n` +
+		(imageBlocks.length
+			? `The image${imageBlocks.length === 1 ? ' is' : 's are'} included for you to read directly — act on what you actually see, don't guess.`
+			: `No previewable image was included; reference the stored file(s) by name.`);
+
+	return { imageBlocks, note };
+}
+
+/** Append image blocks to the most recent user message, converting its text to a block array. */
+export function attachImagesToLastUserMessage(messages: MessageParam[], imageBlocks: ImageBlockParam[]): void {
+	if (!imageBlocks.length) return;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		if (messages[i].role !== 'user') continue;
+		const existing = messages[i].content;
+		const textBlocks: ContentBlockParam[] =
+			typeof existing === 'string'
+				? existing ? [{ type: 'text', text: existing }] : []
+				: (existing as ContentBlockParam[]);
+		messages[i] = { role: 'user', content: [...textBlocks, ...imageBlocks] };
+		return;
+	}
+}

package/template/agent/src/index.ts

@@ -52,6 +52,21 @@ function runInBackground(work: Promise<unknown>): void {
 
 const server = http.createServer(async (req, res) => {
 	if (req.method === 'GET') {
+		// Serve inbound files we stored on our own infra. After the human sends a photo/doc, the
+		// engine downloads it from Vessels, stores it here, and resolves a permanent link pointing
+		// back at this route (see inbound.ts + store.ts). The app fetches THIS url to render it.
+		// In production you'd store in object storage and serve from a CDN instead.
+		const fileMatch = req.url && /^\/files\/([^/?]+)/.exec(req.url);
+		if (fileMatch) {
+			const file = await store.getInboundFile(decodeURIComponent(fileMatch[1])).catch(() => null);
+			if (!file) {
+				res.writeHead(404).end();
+				return;
+			}
+			res.writeHead(200, { 'Content-Type': file.contentType, 'Content-Length': String(file.bytes.byteLength) });
+			res.end(Buffer.from(file.bytes));
+			return;
+		}
 		res.writeHead(200, { 'Content-Type': 'text/plain' });
 		res.end('Vessels agent is alive. POST webhook events here.');
 		return;
@@ -89,18 +104,24 @@ const server = http.createServer(async (req, res) => {
 			vessel,
 			humanInput: `${typeNote}${first || '(the operator opened a new vessel)'}`,
 			nameVessel: true,
+			// Files attached to the first message ride the vessel.created event too.
+			attachments: event.attachments,
 			idempotencyKeyBase: `vc:${event.message.id}`,
 		});
 	} else if (event.type === 'message.user') {
 		const content = (event.message.content ?? '').trim();
-		if (content) {
+		// Files the human attached (signed downloadUrls) — the engine does the download → store →
+		// resolve handshake before the model runs (inbound.ts). A message can be attachments-only.
+		const attachments = event.attachments;
+		if (content || attachments?.length) {
 			// 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
+			const base = content || '(the operator sent the attached file(s) with no message)';
+			const humanInput = sup && content
 				? `[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}` });
+				: base;
+			work = runTurn({ vessels, store, vessel, humanInput, attachments, idempotencyKeyBase: `mu:${event.message.id}` });
 		}
 	} else if (event.type === 'interaction.response') {
 		const originInteraction = event.originMessage?.interaction ?? null;

package/template/agent/src/protocol.ts

@@ -91,12 +91,12 @@ Tools:
    - request_questions  — SEVERAL questions at once, answered together (a short form)
    - finish             — wrap up; no further human action needed
 
-   MID-PLAN CHECKPOINTS — keepWorking: when a multi-step plan needs the operator's input
-   PART-WAY THROUGH (e.g. plan = Draft → Get approval → Send), raise the request_* with
-   keepWorking:true. The plan card stays LIVE and paused on them — pending tasks intact, not
-   greyed out — and when they answer you pick the SAME plan back up and finish the remaining
-   steps, one continuous card. Omit keepWorking on the FINAL question/decision, which seals
-   the plan and ends the turn.
+   MID-PLAN CHECKPOINTS — keepWorking: when a multi-step task needs the operator's input
+   PART-WAY THROUGH (e.g. Draft → Get approval → Send), raise the request_* with
+   keepWorking:true. It signals the task ISN'T finished — this turn's working card seals as a
+   clean record of what you just did, and when they answer you continue the remaining steps in
+   a FRESH card next turn (each turn is its own card, in order). Omit keepWorking on the FINAL
+   question/decision, where nothing follows.
 
 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
@@ -120,9 +120,20 @@ Flow:
 - 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.
 
+FILES the operator sends you (images, PDFs, docs):
+- Your backend has ALREADY handled them before you read this turn: it downloaded each from
+  Vessels, stored it on YOUR storage, and confirmed the permanent link back — the operator
+  already sees your hosted copy. A bracketed note tells you what arrived and where it landed.
+  So NEVER say you "can't receive files" or ask them to re-send — the file is in hand.
+- IMAGES are attached to this turn for you to actually SEE — read what's genuinely there and
+  act on it (a receipt → the amount; a form → the fields). Reference real details you observe;
+  do NOT invent contents. Non-image files are stored but not shown inline — work from the
+  filename and the operator's words.
+
 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).
+- ATTACHMENTS (outbound): 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, or a stored inbound file).
 - 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
@@ -136,6 +147,11 @@ Be efficient — every assistant turn is a slow round-trip, so do MORE per turn:
 - 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."
+- Once you've called plan(), a real DECISION you need from the operator goes through a STRUCTURED
+  interaction, not prose: a clean either/or is request_choice; a single value is request_text —
+  with keepWorking:true when steps remain after the answer. Do NOT write the question as a plain
+  message and stop; that strands an unworked plan and denies the operator the action bar. (A bare
+  clarifying question with NO plan can still be a quick_reply done:true.)
 - 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.`;
 

package/template/agent/src/store.ts

@@ -1,47 +1,55 @@
 /**
  * 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":
+ * Three things live here, and all 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.
+ *   3. Inbound files — when a human sends a photo/document, Vessels relays it
+ *      TRANSIENTLY and you must store it on your OWN infra, then hand back a permanent
+ *      link (see inbound.ts). The bytes live here; the link points back at your agent.
  *
  * 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.
+ *     State + files live in RAM and reset on restart; the lock is an in-process mutex.
+ *   • PostgresStore — set DATABASE_URL and you get durable state, files, and a
+ *     cross-process lock. Self-provisions (CREATE TABLE IF NOT EXISTS on init).
  *
- * Swap in Redis/Dynamo/your-DB by implementing the same `AgentStore` interface.
+ * Swap in Redis/Dynamo/S3/your-DB by implementing the same `AgentStore` interface.
+ * In production you'd typically store inbound files in object storage (S3/R2/GCS) and
+ * return a CDN URL from `putInboundFile` — here we serve them off the agent itself.
  */
 import type { MessageParam } from '@anthropic-ai/sdk/resources/messages';
-import type { AgentTodoStatus } from 'vessels-sdk';
 
-/**
- * A paused plan's handle, saved when a turn ends on a MID-PLAN checkpoint
- * (a request_* with keepWorking). The next turn re-attaches to the SAME working
- * card (`activityId`) and its `todos` instead of opening a new one — so the
- * operator sees one continuous card across a multi-step flow. Like everything in
- * the store, this is the agent's own runtime state, never Vessels'.
- */
-export type ResumeMarker = { activityId: string; todos: { label: string; status: AgentTodoStatus }[] };
+/** A stored inbound file, served back by the agent's own `GET /files/:id` route. */
+export interface StoredFile {
+	bytes: Uint8Array;
+	contentType: string;
+	filename?: string;
+}
+
+/** The agent's externally-reachable base URL — where resolved inbound files are served
+ * from. In local dev this is your tunnel (same host as your webhook). */
+export function publicBaseUrl(): string {
+	return (process.env.PUBLIC_URL || `http://localhost:${process.env.PORT || 3000}`).replace(/\/$/, '');
+}
 
 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>;
-	/** The paused-plan handle for this vessel, or null when no plan is paused. */
-	loadResume(vessel: string): Promise<ResumeMarker | null>;
-	/** Save the paused-plan handle (or null to clear it once the plan resumes/ends). */
-	saveResume(vessel: string, marker: ResumeMarker | null): 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>;
+	/** Store an inbound file on YOUR infra; returns a permanent, publicly-fetchable URL.
+	 * (Swap the body for S3/R2/GCS in production and return the CDN URL.) */
+	putInboundFile(file: { fileId: string; bytes: Uint8Array; contentType: string; filename?: string }): Promise<string>;
+	/** Read a stored inbound file back — the `GET /files/:id` route serves it to the app. */
+	getInboundFile(fileId: string): Promise<StoredFile | null>;
 	/** Optional one-time setup (e.g. create tables). Called once at boot. */
 	init?(): Promise<void>;
 }
@@ -50,8 +58,8 @@ export interface AgentStore {
 
 export class MemoryStore implements AgentStore {
 	private state = new Map<string, MessageParam[]>();
-	private resume = new Map<string, ResumeMarker>();
 	private locks = new Map<string, number>(); // vessel → expiry (ms epoch)
+	private files = new Map<string, StoredFile>();
 
 	async loadState(vessel: string): Promise<MessageParam[]> {
 		return this.state.get(vessel) ?? [];
@@ -61,15 +69,6 @@ export class MemoryStore implements AgentStore {
 		this.state.set(vessel, messages);
 	}
 
-	async loadResume(vessel: string): Promise<ResumeMarker | null> {
-		return this.resume.get(vessel) ?? null;
-	}
-
-	async saveResume(vessel: string, marker: ResumeMarker | null): Promise<void> {
-		if (marker) this.resume.set(vessel, marker);
-		else this.resume.delete(vessel);
-	}
-
 	async acquireLock(vessel: string, ttlSeconds: number): Promise<boolean> {
 		const now = Date.now();
 		const until = this.locks.get(vessel);
@@ -81,6 +80,15 @@ export class MemoryStore implements AgentStore {
 	async releaseLock(vessel: string): Promise<void> {
 		this.locks.delete(vessel);
 	}
+
+	async putInboundFile(file: { fileId: string; bytes: Uint8Array; contentType: string; filename?: string }): Promise<string> {
+		this.files.set(file.fileId, { bytes: file.bytes, contentType: file.contentType, filename: file.filename });
+		return `${publicBaseUrl()}/files/${file.fileId}`;
+	}
+
+	async getInboundFile(fileId: string): Promise<StoredFile | null> {
+		return this.files.get(fileId) ?? null;
+	}
 }
 
 // ─── PostgresStore — durable, self-provisioning ─────────────────────────────────
@@ -103,10 +111,12 @@ export class PostgresStore implements AgentStore {
 				vessel     TEXT PRIMARY KEY,
 				expires_at TIMESTAMPTZ NOT NULL
 			);
-			CREATE TABLE IF NOT EXISTS agent_resume (
-				vessel     TEXT PRIMARY KEY,
-				marker     JSONB NOT NULL,
-				updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+			CREATE TABLE IF NOT EXISTS agent_files (
+				file_id      TEXT PRIMARY KEY,
+				bytes        BYTEA NOT NULL,
+				content_type TEXT NOT NULL,
+				filename     TEXT,
+				created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
 			);
 		`);
 	}
@@ -133,27 +143,6 @@ export class PostgresStore implements AgentStore {
 		);
 	}
 
-	async loadResume(vessel: string): Promise<ResumeMarker | null> {
-		const { rows } = await this.db.query<{ marker: ResumeMarker }>(
-			'SELECT marker FROM agent_resume WHERE vessel = $1',
-			[vessel]
-		);
-		return rows[0]?.marker ?? null;
-	}
-
-	async saveResume(vessel: string, marker: ResumeMarker | null): Promise<void> {
-		if (!marker) {
-			await this.db.query('DELETE FROM agent_resume WHERE vessel = $1', [vessel]);
-			return;
-		}
-		await this.db.query(
-			`INSERT INTO agent_resume (vessel, marker, updated_at)
-			 VALUES ($1, $2, now())
-			 ON CONFLICT (vessel) DO UPDATE SET marker = EXCLUDED.marker, updated_at = now()`,
-			[vessel, JSON.stringify(marker)]
-		);
-	}
-
 	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(
@@ -171,6 +160,25 @@ export class PostgresStore implements AgentStore {
 	async releaseLock(vessel: string): Promise<void> {
 		await this.db.query('DELETE FROM agent_locks WHERE vessel = $1', [vessel]);
 	}
+
+	async putInboundFile(file: { fileId: string; bytes: Uint8Array; contentType: string; filename?: string }): Promise<string> {
+		await this.db.query(
+			`INSERT INTO agent_files (file_id, bytes, content_type, filename)
+			 VALUES ($1, $2, $3, $4)
+			 ON CONFLICT (file_id) DO UPDATE SET bytes = EXCLUDED.bytes, content_type = EXCLUDED.content_type, filename = EXCLUDED.filename`,
+			[file.fileId, Buffer.from(file.bytes), file.contentType, file.filename ?? null]
+		);
+		return `${publicBaseUrl()}/files/${file.fileId}`;
+	}
+
+	async getInboundFile(fileId: string): Promise<StoredFile | null> {
+		const { rows } = await this.db.query<{ bytes: Buffer; content_type: string; filename: string | null }>(
+			'SELECT bytes, content_type, filename FROM agent_files WHERE file_id = $1',
+			[fileId]
+		);
+		const r = rows[0];
+		return r ? { bytes: new Uint8Array(r.bytes), contentType: r.content_type, filename: r.filename ?? undefined } : null;
+	}
 }
 
 /**