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,118 @@
+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 unknown;
+	if (raw === undefined || raw === null) return requestOptions;
+
+	// An expression can resolve this string field to any type (`={{ $json.id }}`
+	// over a numeric column), and a non-string is never a UUID. Treating one as
+	// empty would wave it past the guard while the routing expression still put
+	// it on the wire — the exact bypass this function exists to close — so it
+	// earns the same named error a source name does.
+	const value = typeof raw === 'string' ? raw.trim() : raw;
+	if (value === '') return requestOptions;
+	if (typeof value === 'string' && UUID_RE.test(value)) return requestOptions;
+
+	throw new NodeOperationError(
+		this.getNode(),
+		`Connection ID must be a connection UUID, not "${String(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',
+				// `.trim()` BEFORE the falsy check, so what goes on the wire is what
+				// the guard above actually validated. The guard trims its input, so
+				// "   " is accepted as "not provided" — but untrimmed `$value` is
+				// truthy, so without this the node sent "   ", core put it in the
+				// UUID column, and the caller got back the exact
+				// `502 "Upstream source error."` this whole field exists to prevent.
+				// Verified against a pre-fix core on 2026-08-12.
+				//
+				// Trimming also rescues a pasted " <uuid> ": core parses this value
+				// with `UUID()`, which does not tolerate surrounding whitespace and
+				// 400s on the padded form.
+				//
+				// `String(...)` because an expression can resolve this field to a
+				// non-string (`={{ $json.id }}` over a numeric column) and a bare
+				// `.trim()` would throw a raw TypeError from inside the expression —
+				// which runs BEFORE preSend, so it would pre-empt the guard's named
+				// error with an unreadable one. Coercing keeps the guard in charge of
+				// the message; it rejects every non-string anyway.
+				//
+				// `|| 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: '={{ String($value ?? "").trim() || 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),
 ];