vessels 0.6.0 → 0.8.0

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

@@ -0,0 +1,545 @@
+/**
+ * THE VESSELS CONTROL TOOLS — the fixed set of tools the model uses to talk to the
+ * operator (lead with a reply, plan, narrate, show a surface, ask for a decision,
+ * finish). These mirror the Vessels product 1:1 and are domain-free; you normally
+ * leave this file alone and add YOUR tools in `tools.ts`.
+ *
+ * Also here: the defensive sanitisers (the model occasionally emits a malformed
+ * optional field — one bad field would 400 the whole push, dropping the message and
+ * the state it carries), the interaction-payload builder, and the human-response
+ * renderer.
+ */
+import type { Tool } from '@anthropic-ai/sdk/resources/messages';
+import type { AgentActivityType } from 'vessels-sdk';
+
+// ─── Shared schema fragments ────────────────────────────────────────────────────
+
+const CARD_SCHEMA = {
+	type: 'object' as const,
+	properties: {
+		title: { type: 'string' },
+		fields: {
+			type: 'array',
+			items: {
+				type: 'object',
+				properties: { label: { type: 'string' }, value: { type: 'string' } },
+				required: ['label', 'value'],
+			},
+		},
+	},
+	required: ['title', 'fields'],
+};
+
+/** Inject this into a tool's input schema so the model can tick the plan in the same call. */
+export const TASK_FIELD = {
+	type: 'string' as const,
+	description:
+		'The EXACT plan() task label this work belongs to — ticks the plan to it (no separate step() needed).',
+};
+
+const OPTIONS_SCHEMA = {
+	type: 'array' as const,
+	items: {
+		type: 'object',
+		properties: { id: { type: 'string' }, label: { type: 'string' } },
+		required: ['id', 'label'],
+	},
+	minItems: 1,
+};
+
+const PIN_CARD_FIELD = {
+	...CARD_SCHEMA,
+	description:
+		"Update the vessel's pinned header card to the entity's current state. Re-send the full card to replace it.",
+};
+
+const LABELS_FIELD = {
+	type: 'array' as const,
+	items: { type: 'string' },
+	maxItems: 10,
+	description: "Replace the vessel's triage labels with this full set (≤10). Only send if they should change.",
+};
+
+const ATTACHMENTS_FIELD = {
+	type: 'array' as const,
+	maxItems: 10,
+	items: {
+		type: 'object',
+		properties: {
+			type: { type: 'string', enum: ['image', 'file'] },
+			url: { type: 'string', description: 'A public http(s) URL YOU host. Vessels renders it; it does not store files.' },
+			filename: { type: 'string', description: 'Display name for a file (optional).' },
+		},
+		required: ['type', 'url'],
+	},
+	description: 'Images render inline; files render as a download link. Only URLs you already host (e.g. from a backend tool).',
+};
+
+const METADATA_FIELD = {
+	type: 'object' as const,
+	description:
+		'Opaque key/value data that rides back to YOU verbatim in the webhook for this interaction (routing/correlation — e.g. your own record id). Vessels never interprets it.',
+	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[] = [
+	{
+		name: 'plan',
+		description:
+			'Declare your task list on the live working card. Tasks tick off as you work. Call once early; you may call again to revise the list.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				todos: {
+					type: 'array',
+					items: { type: 'string', description: 'A short task label' },
+					minItems: 1,
+					maxItems: 12,
+				},
+				vesselTitle: {
+					type: 'string',
+					description:
+						"Set or RENAME this vessel's title (≤6 words, specific). You can rename ANY time the operator asks or when a clearer name emerges. Omit when you are not (re)naming.",
+				},
+				labels: {
+					type: 'array',
+					items: { type: 'string' },
+					maxItems: 10,
+					description:
+						'Triage tags for this vessel, in your own vocabulary. REPLACE-semantics — send the full set. Set 1–3 on the first plan() of a vessel; omit later unless they change.',
+				},
+				pinCard: {
+					...CARD_SCHEMA,
+					description:
+						"A persistent header card pinning the entity's current state at a glance — stays put as the chat scrolls. Set it when you first have the key facts; re-send to UPDATE it as state changes.",
+				},
+			},
+			required: ['todos'],
+		},
+	},
+	{
+		name: 'step',
+		description:
+			'Tick the plan to the task you are now working on (EXACT label from plan()). The backend tools you call next auto-narrate under it — you do NOT write the step text yourself.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				task: { type: 'string', description: 'The exact plan task label you are now on' },
+			},
+			required: ['task'],
+		},
+	},
+	{
+		name: 'send_update',
+		description: 'Post a progress message to the operator, then keep working this turn. Not a question.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				message: { type: 'string' },
+				card: CARD_SCHEMA,
+				suggestions: { type: 'array', items: { type: 'string' }, maxItems: 5, description: 'Up to 5 tappable quick-reply chips that pre-fill the human\'s input.' },
+				attachments: ATTACHMENTS_FIELD,
+				previewUrl: { type: 'string', description: 'A single link card shown under the message (a draft/dashboard to open). Presentation only, no decision.' },
+				task: TASK_FIELD,
+			},
+			required: ['message'],
+		},
+	},
+	{
+		name: 'show_document',
+		description:
+			'Show the operator a read-only ARTIFACT — a composed document they read but do not act on (a summary, report, proposal, breakdown). Renders as a full-width SURFACE: a title heading, an optional card of glance-facts, and a block-markdown body. Does NOT end the turn and has no buttons. For something that needs a DECISION, attach an interaction with a request_* tool instead.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading' },
+				body: {
+					type: 'string',
+					description:
+						'The artifact in block markdown — tables (| a | b |), bullet lists (- ), numbered lists (1. ), blockquotes (> ), bold headings (## ), **bold**, *italic*, `code`, [links](url).',
+				},
+				card: CARD_SCHEMA,
+				attachments: ATTACHMENTS_FIELD,
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+			},
+			required: ['title', 'body'],
+		},
+	},
+	{
+		name: 'request_approval',
+		description: 'Ask the operator to approve or reject — renders as a full-width Review Card SURFACE. Ends your turn.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading.' },
+				message: {
+					type: 'string',
+					description:
+						'The artifact BODY in block markdown — the thing being reviewed. If approving text you wrote, put the FULL text here so they read the real words inline, never a "draft is ready" summary. Use tables/lists/blockquotes/**bold** as needed.',
+				},
+				prompt: { type: 'string', description: 'The yes/no decision question, shown under the title' },
+				approveLabel: { type: 'string' },
+				rejectLabel: { type: 'string' },
+				reasonRequired: { type: 'boolean', description: 'Require the human to type a reason with their approve/reject.' },
+				previewUrl: { type: 'string', description: 'Optional link for an artifact too rich to inline. For text, inline it in `message`.' },
+				card: CARD_SCHEMA,
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
+			},
+			required: ['message', 'prompt'],
+		},
+	},
+	{
+		name: 'request_choice',
+		description: 'Ask the operator to pick one option — a full-width surface. Ends your turn.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading' },
+				message: { type: 'string', description: 'Body / context (block markdown)' },
+				prompt: { type: 'string', description: 'The decision question' },
+				options: OPTIONS_SCHEMA,
+				allowCustom: { type: 'boolean', description: 'Let the human type their own answer instead of picking an option.' },
+				customPlaceholder: { type: 'string', description: 'Placeholder for the custom-answer field (when allowCustom).' },
+				card: CARD_SCHEMA,
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
+			},
+			required: ['message', 'prompt', 'options'],
+		},
+	},
+	{
+		name: 'request_checklist',
+		description: 'Ask the operator to select one or more options — a full-width surface. Ends your turn.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading' },
+				message: { type: 'string', description: 'Body / context (block markdown)' },
+				prompt: { type: 'string', description: 'The decision question' },
+				options: OPTIONS_SCHEMA,
+				minSelections: { type: 'number', description: 'Minimum number the human must select.' },
+				submitLabel: { type: 'string', description: 'Label for the submit button.' },
+				card: CARD_SCHEMA,
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+				metadata: METADATA_FIELD,
+				keepWorking: KEEP_WORKING_FIELD,
+			},
+			required: ['message', 'prompt', 'options'],
+		},
+	},
+	{
+		name: 'request_text',
+		description: 'Ask the operator for a free-text answer — a full-width surface. Ends your turn.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				title: { type: 'string', description: 'The surface heading' },
+				message: { type: 'string', description: 'Body / context (block markdown)' },
+				prompt: { type: 'string', description: 'The question' },
+				placeholder: { type: 'string' },
+				multiline: { type: 'boolean' },
+				submitLabel: { type: 'string', description: 'Label for the submit button.' },
+				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.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				message: { type: 'string' },
+				vesselTitle: { type: 'string', description: 'Rename the vessel as you wrap up (≤6 words). Omit otherwise.' },
+				pinCard: PIN_CARD_FIELD,
+				labels: LABELS_FIELD,
+			},
+			required: ['message'],
+		},
+	},
+	{
+		name: 'quick_reply',
+		description:
+			'Your FIRST action every turn: fire a one-line conversational reply to the operator RIGHT NOW (a chat bubble). It is pushed immediately. The `done` flag decides whether the turn ends here:\n• done: true → this line FULLY resolves the turn and you are handing back to the operator now. Use ONLY for a clarifying question back, or an answer you can give from what you ALREADY know (no lookup). The turn ends.\n• done: false (or omitted) → this is your "on it" line; you are about to keep working. You MUST then call plan() and work the steps. The working card opens right after this bubble.\nNEVER set done: true on a line that promises follow-up ("on it", "pulling that now", "let me check", "I\'ll get you…") or on any answer that needs a lookup — that strands the operator. When in doubt, leave done false and keep working.',
+		input_schema: {
+			type: 'object',
+			properties: {
+				message: { type: 'string', description: 'The short conversational line to send back' },
+				done: {
+					type: 'boolean',
+					description:
+						'TRUE only if this line fully resolves the turn (a question back, or an answer you already know) and you are handing back to the operator. FALSE/omitted means you are about to keep working — you must then call plan(). Defaults to false (keep working).',
+				},
+				vesselTitle: {
+					type: 'string',
+					description: 'Rename the vessel as part of this reply (≤6 words). The rename takes effect immediately; confirm it in your message. Omit when not renaming.',
+				},
+			},
+			required: ['message'],
+		},
+	},
+];
+
+/** Names of the built-in control tools — used to route a tool_use to native handling vs a backend 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', 'request_questions', 'finish']);
+
+// ─── Default narration ──────────────────────────────────────────────────────────
+
+/** Turn a tool name into a Title Case label when a backend tool supplies no `narrate`. */
+export function defaultNarrate(name: string): { type: AgentActivityType; label: string } {
+	const label = name.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+	return { type: 'tool_use', label };
+}
+
+// ─── Interaction mapping ────────────────────────────────────────────────────────
+
+/** Only pass interaction metadata that is a plain object (rides back verbatim in the webhook). */
+function cleanMetadata(raw: unknown): Record<string, unknown> | undefined {
+	return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined;
+}
+
+/** Build the camelCase `interaction` object a push expects from a request_* tool input. */
+export function buildInteraction(toolName: string, input: Record<string, unknown>): Record<string, unknown> | null {
+	const meta = cleanMetadata(input.metadata);
+	const withMeta = (obj: Record<string, unknown>) => (meta ? { ...obj, metadata: meta } : obj);
+	switch (toolName) {
+		case 'request_approval':
+			return withMeta({
+				type: 'approval',
+				prompt: String(input.prompt),
+				...(input.approveLabel ? { approveLabel: String(input.approveLabel) } : {}),
+				...(input.rejectLabel ? { rejectLabel: String(input.rejectLabel) } : {}),
+				...(input.reasonRequired ? { reasonRequired: true } : {}),
+			});
+		case 'request_choice':
+			return withMeta({
+				type: 'choice',
+				prompt: String(input.prompt),
+				options: input.options,
+				...(input.allowCustom ? { allowCustom: true } : {}),
+				...(input.customPlaceholder ? { customPlaceholder: String(input.customPlaceholder) } : {}),
+			});
+		case 'request_checklist':
+			return withMeta({
+				type: 'checklist',
+				prompt: String(input.prompt),
+				options: input.options,
+				...(typeof input.minSelections === 'number' ? { minSelections: input.minSelections } : {}),
+				...(input.submitLabel ? { submitLabel: String(input.submitLabel) } : {}),
+			});
+		case 'request_text':
+			return withMeta({
+				type: 'text_input',
+				prompt: String(input.prompt),
+				...(input.placeholder ? { placeholder: String(input.placeholder) } : {}),
+				...(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.
+ * `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,
+	interaction?: Record<string, unknown> | null
+): string {
+	const head = prompt ? `Re: "${prompt}" — ` : '';
+	switch (interactionType) {
+		case 'approval': {
+			const action = String(response.action ?? '');
+			const reason = response.reason ? ` (${response.reason})` : '';
+			return `${head}I ${action === 'approved' ? 'APPROVED' : 'REJECTED'}${reason}.`;
+		}
+		case 'choice': {
+			const sel = response.customValue ? `${response.selected} → "${response.customValue}"` : response.selected;
+			return `${head}I chose: ${sel}.`;
+		}
+		case 'checklist': {
+			const items = Array.isArray(response.selected) ? response.selected.join(', ') : '';
+			return `${head}I selected: ${items || '(none)'}.`;
+		}
+		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)}`;
+	}
+}
+
+// ─── Defensive payload sanitisers ────────────────────────────────────────────────
+
+/** Return a valid card {title, fields:[{label,value}]}, salvaging a sibling `fields`, or undefined. */
+export function sanitizeCard(
+	raw: unknown,
+	input?: Record<string, unknown>
+): { title: string; fields: { label: string; value: string }[] } | undefined {
+	const obj = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+	const titleRaw = typeof obj.title === 'string' ? obj.title : typeof raw === 'string' ? raw : '';
+	const title = String(titleRaw).replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+	const fieldsSrc = Array.isArray(obj.fields)
+		? obj.fields
+		: Array.isArray(input?.fields)
+			? (input!.fields as unknown[])
+			: [];
+	const fields = fieldsSrc
+		.filter((f): f is Record<string, unknown> => !!f && typeof f === 'object')
+		.map((f) => ({ label: String(f.label ?? '').trim(), value: String(f.value ?? '').trim() }))
+		.filter((f) => f.label && f.value);
+	if (!title || fields.length === 0) return undefined;
+	return { title, fields };
+}
+
+/** Only pass a previewUrl the API will accept (http/https), else undefined. */
+export function cleanPreviewUrl(raw: unknown): string | undefined {
+	if (typeof raw !== 'string') return undefined;
+	const u = raw.trim();
+	return /^https?:\/\/\S+$/.test(u) ? u : undefined;
+}
+
+/** A surface heading: trimmed, tag-stripped, ≤200 chars, else undefined. */
+export function cleanTitle(raw: unknown): string | undefined {
+	if (typeof raw !== 'string') return undefined;
+	const t = raw.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim().slice(0, 200);
+	return t || undefined;
+}
+
+/** Up to 5 non-empty suggestion strings, else undefined. */
+export function cleanSuggestions(raw: unknown): string[] | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const out = raw.map((s) => String(s ?? '').trim()).filter(Boolean).slice(0, 5);
+	return out.length ? out : undefined;
+}
+
+/** Up to 10 attachments with a valid http(s) url and image|file type, else undefined. */
+export function cleanAttachments(raw: unknown): Array<{ type: 'image' | 'file'; url: string; filename?: string }> | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const out: Array<{ type: 'image' | 'file'; url: string; filename?: string }> = [];
+	for (const a of raw) {
+		if (!a || typeof a !== 'object') continue;
+		const o = a as Record<string, unknown>;
+		const type = o.type === 'image' ? 'image' : o.type === 'file' ? 'file' : undefined;
+		const url = typeof o.url === 'string' && /^https?:\/\/\S+$/.test(o.url.trim()) ? o.url.trim() : undefined;
+		if (!type || !url) continue;
+		const filename = typeof o.filename === 'string' && o.filename.trim() ? o.filename.trim() : undefined;
+		out.push({ type, url, ...(type === 'file' && filename ? { filename } : {}) });
+		if (out.length >= 10) break;
+	}
+	return out.length ? out : undefined;
+}
+
+/** Up to 10 triage labels, tag-stripped, ≤50 chars, deduped (case-insensitive), else undefined. */
+export function cleanLabels(raw: unknown): string[] | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const s of raw) {
+		const t = String(s ?? '').replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim().slice(0, 50);
+		const key = t.toLowerCase();
+		if (t && !seen.has(key)) {
+			seen.add(key);
+			out.push(t);
+		}
+		if (out.length >= 10) break;
+	}
+	return out.length ? out : undefined;
+}

package/template/agent/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}