vessels 0.7.0 → 0.9.0

package/dist/index.js

@@ -4061,7 +4061,8 @@ var InteractionTypeSchema = external_exports.enum([
   "approval",
   "choice",
   "checklist",
-  "text_input"
+  "text_input",
+  "questions"
 ]);
 var ApprovalInteractionSchema = external_exports.object({
   type: external_exports.literal("approval"),
@@ -4104,11 +4105,39 @@ var TextInputInteractionSchema = external_exports.object({
   submitLabel: external_exports.string().optional(),
   metadata: external_exports.record(external_exports.unknown()).optional()
 });
+var QuestionOptionSchema = external_exports.object({
+  id: external_exports.string().min(1),
+  label: external_exports.string().min(1),
+  /** Optional one-line explanation of what this option means. */
+  description: external_exports.string().optional()
+});
+var QuestionSchema = external_exports.object({
+  /** Stable id used to key this question's answer in the response. */
+  id: external_exports.string().min(1),
+  /** The question text shown to the human. */
+  question: external_exports.string().min(1),
+  /** Optional short chip label (≤12 chars) — e.g. "Date", "Guests". */
+  header: external_exports.string().max(24).optional(),
+  options: external_exports.array(QuestionOptionSchema).min(2).max(4),
+  /** Allow selecting more than one option (checkboxes instead of radios). */
+  multiSelect: external_exports.boolean().optional(),
+  /** Offer a free-text "Other" field alongside the options (default true). */
+  allowOther: external_exports.boolean().optional()
+});
+var QuestionsInteractionSchema = external_exports.object({
+  type: external_exports.literal("questions"),
+  /** Overall heading / context for the batch (the surface prompt). */
+  prompt: external_exports.string().min(1),
+  questions: external_exports.array(QuestionSchema).min(1).max(4),
+  submitLabel: external_exports.string().optional(),
+  metadata: external_exports.record(external_exports.unknown()).optional()
+});
 var InteractionSchema = external_exports.discriminatedUnion("type", [
   ApprovalInteractionSchema,
   ChoiceInteractionSchema,
   ChecklistInteractionSchema,
-  TextInputInteractionSchema
+  TextInputInteractionSchema,
+  QuestionsInteractionSchema
 ]);
 var AgentActivityTypeSchema = external_exports.enum(["thinking", "searching", "tool_use", "browsing", "processing"]);
 var AgentTodoStatusSchema = external_exports.enum(["pending", "in_progress", "done"]);
@@ -4116,12 +4145,14 @@ var AgentTodoInputSchema = external_exports.object({
   label: external_exports.string().min(1).max(200),
   status: AgentTodoStatusSchema.optional()
 });
+var AgentActivityStatusInputSchema = external_exports.enum(["working", "awaiting_input"]);
 var AgentActivitySchema = external_exports.object({
   type: AgentActivityTypeSchema.optional(),
   label: external_exports.string().max(200).optional(),
-  todos: external_exports.array(AgentTodoInputSchema).max(50).optional()
-}).refine((d) => d.type != null || d.todos != null, {
-  message: "agentActivity requires `type` (a step) or `todos` (a plan)"
+  todos: external_exports.array(AgentTodoInputSchema).max(50).optional(),
+  status: AgentActivityStatusInputSchema.optional()
+}).refine((d) => d.type != null || d.todos != null || d.status != null, {
+  message: "agentActivity requires `type` (a step), `todos` (a plan), or `status`"
 });
 var CardFieldSchema = external_exports.object({
   label: external_exports.string().min(1),
@@ -4227,11 +4258,20 @@ var ChecklistResponseSchema = external_exports.object({
 var TextInputResponseSchema = external_exports.object({
   text: external_exports.string()
 });
+var QuestionAnswerSchema = external_exports.object({
+  questionId: external_exports.string().min(1),
+  selected: external_exports.array(external_exports.string()),
+  other: external_exports.string().optional()
+});
+var QuestionsResponseSchema = external_exports.object({
+  answers: external_exports.array(QuestionAnswerSchema)
+});
 var InteractionResponseSchema = external_exports.discriminatedUnion("interactionType", [
   external_exports.object({ interactionType: external_exports.literal("approval"), response: ApprovalResponseSchema }),
   external_exports.object({ interactionType: external_exports.literal("choice"), response: ChoiceResponseSchema }),
   external_exports.object({ interactionType: external_exports.literal("checklist"), response: ChecklistResponseSchema }),
-  external_exports.object({ interactionType: external_exports.literal("text_input"), response: TextInputResponseSchema })
+  external_exports.object({ interactionType: external_exports.literal("text_input"), response: TextInputResponseSchema }),
+  external_exports.object({ interactionType: external_exports.literal("questions"), response: QuestionsResponseSchema })
 ]);
 var WebhookVesselSchema = external_exports.object({
   id: external_exports.string(),
@@ -4274,6 +4314,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(),
@@ -4284,6 +4331,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()
   })
 });
@@ -4298,7 +4346,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({
@@ -4631,6 +4680,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 = [];
@@ -4936,6 +5016,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)
 
@@ -5019,6 +5103,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,31 +1,31 @@
 {
-	"name": "vessels",
-	"version": "0.7.0",
-	"description": "Vessels CLI — manage your agent communication layer from the terminal",
-	"type": "module",
-	"bin": {
-		"vessels": "./dist/index.js"
-	},
-	"files": [
-		"dist",
-		"template"
-	],
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch"
-	},
-	"license": "MIT",
-	"keywords": [
-		"ai",
-		"agents",
-		"vessels",
-		"cli"
-	],
-	"devDependencies": {
-		"tsup": "^8.5.1",
-		"typescript": "^5",
-		"@types/node": "^25.5.2",
-		"@vessels/types": "workspace:*"
-	},
-	"dependencies": {}
+  "name": "vessels",
+  "version": "0.9.0",
+  "description": "Vessels CLI — manage your agent communication layer from the terminal",
+  "type": "module",
+  "bin": {
+    "vessels": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "agents",
+    "vessels",
+    "cli"
+  ],
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5",
+    "@types/node": "^25.5.2",
+    "@vessels/types": "workspace:*"
+  },
+  "dependencies": {}
 }

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';
@@ -36,6 +36,7 @@ import {
 	cleanAttachments,
 } from './vessels-tools.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,7 +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);
+
+	// 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 : ''}`;
@@ -188,9 +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[] = [];
+
 	const patchActivity = async (body: Record<string, unknown>) => {
 		if (activityId) await safePatch(vessels, activityId, { agentActivity: body });
 	};
@@ -270,6 +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);
+			// 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',
@@ -372,7 +403,12 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 				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 }));
+					// Merge by label, preserving the status of tasks already in flight — matters on
+					// 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) };
+					});
 					await patchActivity({ todos });
 					toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content: 'plan set' });
 				} else if (tu.name === 'step') {
@@ -472,10 +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 {
-		// Guarantee the seal — the working card this turn opened MUST resolve, 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: null, tokenStream: null });
+			if (activityId) {
+				await safePatch(vessels, activityId, { agentActivity: null, tokenStream: 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,26 +104,33 @@ 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 prompt = (event.originMessage?.interaction?.prompt as string | undefined) ?? undefined;
+		const originInteraction = event.originMessage?.interaction ?? null;
+		const prompt = (originInteraction?.prompt as string | undefined) ?? undefined;
 		work = runTurn({
 			vessels,
 			store,
 			vessel,
-			humanInput: renderInteractionResponse(event.interactionType, event.response, prompt),
+			humanInput: renderInteractionResponse(event.interactionType, event.response, prompt, originInteraction),
 			idempotencyKeyBase: `ir:${event.id}`,
 		});
 	}

package/template/agent/src/protocol.ts

@@ -88,8 +88,16 @@ Tools:
    - request_choice     — pick one option (with options[])
    - request_checklist  — pick several options (with options[])
    - request_text       — free-text answer
+   - 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 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
    the turn ends. done false/omitted → it's your "on it" line; the working card opens right
@@ -112,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
@@ -128,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,24 +1,41 @@
 /**
  * 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';
 
+/** 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[]>;
@@ -28,6 +45,11 @@ export interface AgentStore {
 	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>;
 }
@@ -37,6 +59,7 @@ export interface AgentStore {
 export class MemoryStore implements AgentStore {
 	private state = new Map<string, MessageParam[]>();
 	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) ?? [];
@@ -57,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 ─────────────────────────────────
@@ -79,6 +111,13 @@ export class PostgresStore implements AgentStore {
 				vessel     TEXT PRIMARY KEY,
 				expires_at TIMESTAMPTZ NOT NULL
 			);
+			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()
+			);
 		`);
 	}
 
@@ -121,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;
+	}
 }
 
 /**

package/template/agent/src/vessels-tools.ts

@@ -82,6 +82,12 @@ const METADATA_FIELD = {
 	additionalProperties: true,
 };
 
+const KEEP_WORKING_FIELD = {
+	type: 'boolean' as const,
+	description:
+		'TRUE when this question is a MID-PLAN checkpoint — you still have remaining plan steps to do AFTER you get the answer. The working card stays live (paused on the operator, plan intact, not greyed out), and you pick the SAME plan back up on their reply instead of starting over. Use it for a multi-step plan where one step needs a sign-off before the next. OMIT (or false) for the FINAL decision of the turn — that seals the plan and hands back.',
+};
+
 // ─── The control tools ──────────────────────────────────────────────────────────
 
 export const CONTROL_TOOLS: Tool[] = [
@@ -189,6 +195,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				pinCard: PIN_CARD_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
 			},
 			required: ['message', 'prompt'],
 		},
@@ -209,6 +216,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				pinCard: PIN_CARD_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
 			},
 			required: ['message', 'prompt', 'options'],
 		},
@@ -229,6 +237,7 @@ export const CONTROL_TOOLS: Tool[] = [
 				pinCard: PIN_CARD_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
 			},
 			required: ['message', 'prompt', 'options'],
 		},
@@ -248,10 +257,60 @@ export const CONTROL_TOOLS: Tool[] = [
 				pinCard: PIN_CARD_FIELD,
 				labels: LABELS_FIELD,
 				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
 			},
 			required: ['message', 'prompt'],
 		},
 	},
+	{
+		name: 'request_questions',
+		description:
+			'Ask the operator SEVERAL questions AT ONCE — a short form they fill in and submit together. Each question is a single- or multi-select over 2–4 options, with an optional free-text Other. Use when a step needs a few answers at once instead of a back-and-forth. A full-width surface; ends your turn (or pauses it mid-plan with keepWorking).',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading' },
+				message: { type: 'string', description: 'Optional context body (block markdown) above the questions' },
+				prompt: { type: 'string', description: 'One line framing the batch of questions' },
+				questions: {
+					type: 'array',
+					minItems: 1,
+					maxItems: 4,
+					items: {
+						type: 'object',
+						properties: {
+							id: { type: 'string', description: 'Stable id used to key this answer' },
+							question: { type: 'string', description: 'The question text' },
+							header: { type: 'string', description: 'Short chip label, ≤12 chars (e.g. "Date", "Guests")' },
+							options: {
+								type: 'array',
+								minItems: 2,
+								maxItems: 4,
+								items: {
+									type: 'object',
+									properties: {
+										id: { type: 'string' },
+										label: { type: 'string' },
+										description: { type: 'string', description: 'Optional one-line explanation' },
+									},
+									required: ['id', 'label'],
+								},
+							},
+							multiSelect: { type: 'boolean', description: 'Allow more than one option (checkboxes).' },
+							allowOther: { type: 'boolean', description: 'Offer a free-text Other field (default true).' },
+						},
+						required: ['id', 'question', 'options'],
+					},
+				},
+				submitLabel: { type: 'string' },
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
+			},
+			required: ['prompt', 'questions'],
+		},
+	},
 	{
 		name: 'finish',
 		description: 'Conclude — no further human action needed. Ends your turn.',
@@ -293,7 +352,7 @@ export const CONTROL_TOOLS: Tool[] = [
 export const CONTROL_TOOL_NAMES = new Set(CONTROL_TOOLS.map((t) => t.name));
 
 /** The tools that END a turn — exactly one is the final action. */
-export const ENDING_TOOLS = new Set(['request_approval', 'request_choice', 'request_checklist', 'request_text', 'finish']);
+export const ENDING_TOOLS = new Set(['request_approval', 'request_choice', 'request_checklist', 'request_text', 'request_questions', 'finish']);
 
 // ─── Default narration ──────────────────────────────────────────────────────────
 
@@ -347,16 +406,26 @@ export function buildInteraction(toolName: string, input: Record<string, unknown
 				...(input.multiline ? { multiline: true } : {}),
 				...(input.submitLabel ? { submitLabel: String(input.submitLabel) } : {}),
 			});
+		case 'request_questions':
+			return withMeta({
+				type: 'questions',
+				prompt: String(input.prompt),
+				questions: input.questions,
+				...(input.submitLabel ? { submitLabel: String(input.submitLabel) } : {}),
+			});
 		default:
 			return null;
 	}
 }
 
-/** Render a human's interaction response as a readable user turn for the model. */
+/** Render a human's interaction response as a readable user turn for the model.
+ * `interaction` (the original interaction object) is optional but lets the questions
+ * renderer map option ids back to their human labels. */
 export function renderInteractionResponse(
 	interactionType: string,
 	response: Record<string, unknown>,
-	prompt?: string
+	prompt?: string,
+	interaction?: Record<string, unknown> | null
 ): string {
 	const head = prompt ? `Re: "${prompt}" — ` : '';
 	switch (interactionType) {
@@ -375,6 +444,23 @@ export function renderInteractionResponse(
 		}
 		case 'text_input':
 			return `${head}${response.text ?? ''}`;
+		case 'questions': {
+			const qs = Array.isArray(interaction?.questions)
+				? (interaction!.questions as Array<{ id: string; question?: string; header?: string; options?: Array<{ id: string; label: string }> }>)
+				: [];
+			const answers = Array.isArray(response.answers)
+				? (response.answers as Array<{ questionId: string; selected?: string[]; other?: string }>)
+				: [];
+			const lines = answers.map((a) => {
+				const q = qs.find((x) => x.id === a.questionId);
+				const label = q?.question ?? q?.header ?? a.questionId;
+				const opts = q?.options ?? [];
+				const picked = (a.selected ?? []).map((id) => opts.find((o) => o.id === id)?.label ?? id);
+				if (a.other) picked.push(a.other);
+				return `• ${label}: ${picked.length ? picked.join(', ') : '(none)'}`;
+			});
+			return `${head}I answered:\n${lines.join('\n')}`;
+		}
 		default:
 			return `${head}${JSON.stringify(response)}`;
 	}