vessels 0.7.0 → 0.8.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(),

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.8.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/src/agent.ts

@@ -35,7 +35,7 @@ import {
 	cleanLabels,
 	cleanAttachments,
 } from './vessels-tools.js';
-import type { AgentStore } from './store.js';
+import type { AgentStore, ResumeMarker } 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
@@ -157,6 +157,9 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	// 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);
 
 	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,6 +194,16 @@ export async function runTurn(opts: RunTurnOpts): Promise<void> {
 	// Authoritative todo list for the working card; we PATCH the full list each update.
 	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 });
 	};
@@ -260,6 +273,9 @@ 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);
@@ -270,6 +286,7 @@ 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;
 			pushes.push({
 				message: msg || String(input.prompt ?? 'Please respond.'),
 				kind: 'surface',
@@ -372,7 +389,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 RESUME (the seeded plan keeps its done steps) and any same-turn re-plan.
+					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 +494,19 @@ 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.
+		// 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.
 		try {
 			await stopStream();
-			if (activityId) await safePatch(vessels, activityId, { agentActivity: null, tokenStream: null });
+			if (activityId) {
+				await safePatch(vessels, activityId, {
+					agentActivity: pauseForInput ? { status: 'awaiting_input' } : 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/index.ts

@@ -103,12 +103,13 @@ const server = http.createServer(async (req, res) => {
 			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;
+		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 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.
+
 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

package/template/agent/src/store.ts

@@ -18,12 +18,26 @@
  * Swap in Redis/Dynamo/your-DB by implementing the same `AgentStore` interface.
  */
 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 }[] };
 
 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. */
@@ -36,6 +50,7 @@ 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)
 
 	async loadState(vessel: string): Promise<MessageParam[]> {
@@ -46,6 +61,15 @@ 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);
@@ -79,6 +103,11 @@ 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()
+			);
 		`);
 	}
 
@@ -104,6 +133,27 @@ 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(

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)}`;
 	}