ENG-3697: Bound Live and Get responses, and stop List deleting its own content

nodes/Hyperspell/resources/document/get.ts

@@ -1,5 +1,6 @@
 import type { INodeProperties } from 'n8n-workflow';
 import { sourceOptions } from '../shared';
+import { simplifyProperty } from '../simplify';
 
 const showOnlyForDocumentGet = {
 	operation: ['get'],
@@ -26,4 +27,5 @@ export const documentGetDescription: INodeProperties[] = [
 		displayOptions: { show: showOnlyForDocumentGet },
 		description: 'The resource ID returned when the document was added',
 	},
+	simplifyProperty(showOnlyForDocumentGet),
 ];

nodes/Hyperspell/resources/document/index.ts

@@ -1,7 +1,7 @@
 import type { INodeProperties } from 'n8n-workflow';
 import { raiseApiErrors } from '../errors';
 import { hintAppScopedEmpty } from '../actAsUser';
-import { simplifyDocuments } from '../simplify';
+import { simplifyDocuments, simplifyOne } from '../simplify';
 import { documentAddDescription } from './add';
 import { documentGetDescription } from './get';
 import { documentListDescription } from './list';
@@ -50,8 +50,10 @@ export const documentDescription: INodeProperties[] = [
 					},
 					// ignoreHttpStatusErrors is on globally, so EVERY operation needs this —
 					// without it a 4xx would flow through as if it were a result.
+					// Then bound the body: a get returns one full hyperdoc tree, which
+					// is the single largest per-item payload the node can emit.
 					output: {
-						postReceive: [raiseApiErrors],
+						postReceive: [raiseApiErrors, simplifyOne],
 					},
 				},
 			},

nodes/Hyperspell/resources/live/connectionId.ts

@@ -0,0 +1,91 @@
+import type {
+	IExecuteSingleFunctions,
+	IHttpRequestOptions,
+	INodeProperties,
+} from 'n8n-workflow';
+import { NodeOperationError } from 'n8n-workflow';
+
+// Connection ID is the one Live field an AI Agent gets wrong in a way the API
+// cannot recover from.
+//
+// The node sets `usableAsTool`, so when it runs as an Agent tool the model
+// fills the parameters from their descriptions. "Specific connection ID when
+// the user has multiple connections for this source" reads, to a model, like
+// an invitation to name the source — and that is exactly what happens.
+// Observed in prod on 2026-08-10: `connection_id` arriving as 'linear',
+// 'github', 'google_drive'.
+//
+// Core takes that string straight into a UUID-typed column
+// (`live_access.py`: `stmt.where(Connection.id == connection_id)`), asyncpg
+// rejects it with a DataError, and a blanket `except Exception` in
+// `api/live.py` turns it into `502 "Upstream source error."`. That message is
+// worse than useless: it blames the provider when no provider was ever
+// contacted, so the workflow author reasonably concludes Linear is down.
+//
+// Core should return a 400 here and will (tracked separately) — but the node
+// should not be shipping a malformed request in the first place, and this
+// guard keeps working against every already-deployed core version.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * preSend: reject a Connection ID that isn't a UUID, naming the likely mistake.
+ *
+ * Deliberately NOT a silent drop. Silently ignoring the field would make a
+ * request scoped to the wrong connection look like it succeeded — the same
+ * class of silent-wrong-answer this node has been bitten by before.
+ */
+export async function validateConnectionId(
+	this: IExecuteSingleFunctions,
+	requestOptions: IHttpRequestOptions,
+): Promise<IHttpRequestOptions> {
+	const raw = this.getNodeParameter('connection_id', '') as string | undefined;
+	const value = typeof raw === 'string' ? raw.trim() : '';
+	if (value === '' || UUID_RE.test(value)) return requestOptions;
+
+	throw new NodeOperationError(
+		this.getNode(),
+		`Connection ID must be a connection UUID, not "${value}".`,
+		{
+			description:
+				'Connection ID identifies ONE specific connection when a user has connected the same source more than once — it is not the source name. Leave it empty to use the caller\'s connection automatically. If this node is running as an AI Agent tool, pin this field to empty so the model cannot fill it.',
+		},
+	);
+}
+
+/**
+ * The Connection ID field, shared by the three document-shaped Live operations.
+ *
+ * `transport` differs by operation — Search POSTs a body, Get and List Resources
+ * put it on the query string — but the validation and the wording must not, so
+ * both go through here rather than being restated three times.
+ */
+export function connectionIdProperty(
+	show: NonNullable<INodeProperties['displayOptions']>['show'],
+	transport: 'body' | 'query' = 'body',
+): INodeProperties {
+	return {
+		displayName: 'Connection ID',
+		name: 'connection_id',
+		type: 'string',
+		default: '',
+		placeholder: '',
+		displayOptions: { show },
+		// Description is the model's only input when this runs as a tool, so it
+		// states the format, and states the default, before it states the purpose.
+		description:
+			'Leave empty. Optional UUID identifying one specific connection, used only when the same user has connected this source more than once. This is NOT the source name.',
+		routing: {
+			send: {
+				type: transport,
+				property: 'connection_id',
+				// `|| undefined` so an untouched field is OMITTED rather than sent as
+				// "". Core types it `str | None` and only falsy-checks it, so ""
+				// happens to be harmless — but the sibling Live ops say "no connection
+				// specified" by omission, and this one shouldn't rely on a
+				// falsy-string coincidence.
+				value: '={{ $value || undefined }}',
+				preSend: [validateConnectionId],
+			},
+		},
+	};
+}

nodes/Hyperspell/resources/live/get.ts

@@ -1,4 +1,5 @@
 import type { INodeProperties } from 'n8n-workflow';
+import { connectionIdProperty } from './connectionId';
 
 const showOnlyForLiveGet = {
 	resource: ['live'],
@@ -25,13 +26,5 @@ export const liveGetDescription: INodeProperties[] = [
 		description: 'Whether to also queue the fetched resource for indexing so it is on-hand next time. The "indexed" and "notes" fields on each output item report what happened.',
 		routing: { request: { qs: { index: '={{$value}}' } } },
 	},
-	{
-		displayName: 'Connection ID',
-		name: 'connection_id',
-		type: 'string',
-		default: '',
-		displayOptions: { show: showOnlyForLiveGet },
-		description: 'Specific connection ID when the user has multiple connections for this source',
-		routing: { request: { qs: { connection_id: '={{$value || undefined}}' } } },
-	},
+	connectionIdProperty(showOnlyForLiveGet, 'query'),
 ];

nodes/Hyperspell/resources/live/index.ts

@@ -2,6 +2,7 @@ import type { INodeProperties } from 'n8n-workflow';
 import { raiseApiErrors } from '../errors';
 import { hintAppScopedEmpty } from '../actAsUser';
 import { sourceOptions } from '../shared';
+import { simplifyProperty } from '../simplify';
 import { unwrapCursorPage, unwrapLiveEnvelope } from './output';
 import { liveSearchDescription } from './search';
 import { liveGetDescription } from './get';
@@ -93,6 +94,13 @@ export const liveDescription: INodeProperties[] = [
 		],
 		default: 'search',
 	},
+	// List Sources is excluded deliberately: it returns capability descriptors,
+	// not documents, so there is no tree to bound and a toggle there would only
+	// be noise.
+	simplifyProperty({
+		resource: ['live'],
+		operation: ['search', 'getResource', 'listResources'],
+	}),
 	{
 		// Used in the request URL path ({{$parameter.source}}) for all ops except List Sources.
 		displayName: 'Source',

nodes/Hyperspell/resources/live/list.ts

@@ -1,4 +1,5 @@
 import type { INodeProperties } from 'n8n-workflow';
+import { connectionIdProperty } from './connectionId';
 import { PAGED_QS } from '../shared';
 
 const showOnlyForLiveList = {
@@ -73,13 +74,5 @@ export const liveListDescription: INodeProperties[] = [
 			'Opaque cursor from a previous page (the next_cursor field on returned items). Leave empty for the first page.',
 		routing: { request: { qs: { cursor: '={{ $value || undefined }}' } } },
 	},
-	{
-		displayName: 'Connection ID',
-		name: 'connection_id',
-		type: 'string',
-		default: '',
-		displayOptions: { show: showOnlyForLiveList },
-		description: 'Specific connection ID when the user has multiple connections for this source',
-		routing: { request: { qs: { connection_id: '={{$value || undefined}}' } } },
-	},
+	connectionIdProperty(showOnlyForLiveList, 'query'),
 ];

nodes/Hyperspell/resources/live/output.ts

@@ -4,6 +4,7 @@ import type {
 	IN8nHttpFullResponse,
 	INodeExecutionData,
 } from 'n8n-workflow';
+import { simplifyDocument } from '../simplify';
 
 // The /live/* endpoints wrap results in envelopes (ENG-2479 Hyperdoc migration):
 //   Search / Get Resource → LiveResourceResponse { documents, indexed, notes }
@@ -27,6 +28,19 @@ interface CursorPageEnvelope {
 	next_cursor?: string | null;
 }
 
+// Every /live/* route returns the plain `DocumentResponse` — full hyperdoc
+// tree, no summary, no highlights. Until now nothing bounded it, so the one
+// surface explicitly built for an AI-agent node ("reach LIVE into a connected
+// source", api/live.py) was also the only one that handed a model an unbounded
+// payload. Same Simplify contract as Search/List: default on, one toggle off.
+function boundDocuments(
+	context: IExecuteSingleFunctions,
+	documents: IDataObject[],
+): IDataObject[] {
+	if (context.getNodeParameter('simplify', true) === false) return documents;
+	return documents.map((document) => simplifyDocument(document));
+}
+
 export async function unwrapLiveEnvelope(
 	this: IExecuteSingleFunctions,
 	_items: INodeExecutionData[],
@@ -44,7 +58,9 @@ export async function unwrapLiveEnvelope(
 		// stays zero-item so IF-node emptiness checks keep working.
 		return notes.length > 0 ? [{ json: { documents: [], indexed, notes } }] : [];
 	}
-	return documents.map((document) => ({ json: { ...document, indexed, notes } }));
+	return boundDocuments(this, documents).map((document) => ({
+		json: { ...document, indexed, notes },
+	}));
 }
 
 export async function unwrapCursorPage(
@@ -59,5 +75,7 @@ export async function unwrapCursorPage(
 	// Auto-pagination is unaffected — it reads next_cursor from the raw body
 	// before postReceive runs.
 	const nextCursor = body.next_cursor ?? null;
-	return pageItems.map((item) => ({ json: { ...item, next_cursor: nextCursor } }));
+	return boundDocuments(this, pageItems).map((item) => ({
+		json: { ...item, next_cursor: nextCursor },
+	}));
 }

nodes/Hyperspell/resources/live/search.ts

@@ -1,4 +1,5 @@
 import type { INodeProperties } from 'n8n-workflow';
+import { connectionIdProperty } from './connectionId';
 
 const showOnlyForLiveSearch = {
 	resource: ['live'],
@@ -37,24 +38,5 @@ export const liveSearchDescription: INodeProperties[] = [
 			},
 		},
 	},
-	{
-		displayName: 'Connection ID',
-		name: 'connection_id',
-		type: 'string',
-		default: '',
-		displayOptions: { show: showOnlyForLiveSearch },
-		description: 'Specific connection ID when the user has multiple connections for this source',
-		routing: {
-			send: {
-				type: 'body',
-				property: 'connection_id',
-				// `|| undefined` so an untouched field is OMITTED rather than sent as
-				// "". Core types it `str | None` and today only falsy-checks it
-				// (live_access.py `if connection_id:`), so "" happens to be harmless —
-				// but the sibling Live ops say "no connection specified" by omission,
-				// and this one shouldn't rely on a falsy-string coincidence.
-				value: '={{ $value || undefined }}',
-			},
-		},
-	},
+	connectionIdProperty(showOnlyForLiveSearch),
 ];

nodes/Hyperspell/resources/simplify.ts

@@ -46,29 +46,73 @@ interface Highlight {
 	score?: number;
 }
 
+interface HyperdocNode extends IDataObject {
+	text?: string;
+	children?: HyperdocNode[];
+}
+
 interface HyperspellDocument extends IDataObject {
 	summary?: string;
 	highlights?: Highlight[];
-	document?: IDataObject;
+	document?: HyperdocNode;
 }
 
 // Result-array keys across the document-shaped responses:
-//   POST /memories/query → documents;  GET /memories/list → items.
+//   POST /memories/query → documents;  GET /memories/list → items;
+//   GET /live/{source}/resources → items.
 const RESULT_ARRAY_KEYS = ['documents', 'items'];
 
-/** The matched text, preferring the server's concatenation of the highlights. */
+// Only the QUERY path returns `ScoredDocumentResponse` (schemas.py:152), which
+// is the sole model carrying `summary`/`highlights`. `/memories/list`,
+// `/memories/get/*` and every `/live/*` route return the plain
+// `DocumentResponse` (schemas.py:75) — no summary, no highlights, body only in
+// the `document` tree. Simplifying those on the highlights-only path emitted
+// `text: ''` and dropped the tree, i.e. deleted the content outright (shipped
+// in 0.7.0; Document → List returned metadata-only rows). So the tree is the
+// fallback source of text, flattened and capped rather than passed through.
+//
+// 2000 chars mirrors the API's own per-highlight cap, which keeps a simplified
+// row roughly the size of one query hit no matter which endpoint produced it.
+// Callers who need the whole body turn Simplify off.
+export const MAX_SIMPLIFIED_TEXT = 2000;
+
+/** Depth-first concatenation of a hyperdoc tree's `text` nodes, capped. */
+function flattenHyperdoc(node: HyperdocNode | undefined, budget: number): string {
+	if (node === undefined || node === null || budget <= 0) return '';
+	const parts: string[] = [];
+	let remaining = budget;
+	const visit = (current: HyperdocNode | undefined): void => {
+		if (current === undefined || current === null || remaining <= 0) return;
+		if (typeof current.text === 'string' && current.text.length > 0) {
+			parts.push(current.text.slice(0, remaining));
+			remaining -= Math.min(current.text.length, remaining);
+		}
+		const children = Array.isArray(current.children) ? current.children : [];
+		for (const child of children) visit(child);
+	};
+	visit(node);
+	return parts.join('\n');
+}
+
+/**
+ * The document's text: the server's highlight concatenation on the query path,
+ * otherwise the flattened hyperdoc tree. Never the raw tree, and never empty
+ * when the document has any text at all.
+ */
 function matchedText(document: HyperspellDocument): string {
 	if (typeof document.summary === 'string' && document.summary.length > 0) {
 		return document.summary;
 	}
 	const highlights = Array.isArray(document.highlights) ? document.highlights : [];
-	return highlights
+	const fromHighlights = highlights
 		.map((highlight) => highlight?.text)
 		.filter((text): text is string => typeof text === 'string' && text.length > 0)
 		.join('\n\n');
+	if (fromHighlights.length > 0) return fromHighlights;
+	return flattenHyperdoc(document.document, MAX_SIMPLIFIED_TEXT);
 }
 
-function simplifyDocument(document: HyperspellDocument): IDataObject {
+export function simplifyDocument(document: HyperspellDocument): IDataObject {
 	// Explicit allow-list, not a `delete document.document`: `summary` and
 	// `highlights[].text` carry the SAME text (summary is defined as their
 	// concatenation), so passing both through would ship every matched chunk
@@ -117,3 +161,25 @@ export async function simplifyDocuments(
 		return { ...item, json: { ...json, [key]: documents.map(simplifyDocument) } };
 	});
 }
+
+/**
+ * postReceive for the single-document responses — `GET /memories/get/*` returns
+ * a bare `DocumentResponse`, not an array, so `simplifyDocuments` (which looks
+ * for a result-array key) passes it through untouched and the full tree reaches
+ * the caller. One document is exactly the case where the tree is largest per
+ * item, so this is the operation most worth bounding, not the least.
+ */
+export async function simplifyOne(
+	this: IExecuteSingleFunctions,
+	items: INodeExecutionData[],
+): Promise<INodeExecutionData[]> {
+	if (this.getNodeParameter('simplify', true) === false) return items;
+
+	return items.map((item) => {
+		const json = (item.json ?? {}) as HyperspellDocument;
+		// Only rewrite something that actually looks like a document response;
+		// an error body or a notice item must pass through untouched.
+		if (json.resource_id === undefined) return item;
+		return { ...item, json: simplifyDocument(json) };
+	});
+}