@stackbone/cli 0.2.3 → 0.2.4

package/main.js

@@ -2988,7 +2988,7 @@ var DEV_HMAC_SECRET = "dev-stackbone-local-emulator-hmac-secret";
 //#endregion
 //#region ../../libs/runtime/agent-emulator/src/lib/server/contract.ts
 init_src$14();
-var STACKBONE_CLI_BUILD_VERSION = "0.2.3";
+var STACKBONE_CLI_BUILD_VERSION = "0.2.4";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -13712,7 +13712,15 @@ var init_trigger_descriptor = __esmMin((() => {
 		/** Dot-path, per item, to the sortable marker used to compute the next cursor. */
 		field: z.string(),
 		/** Request arg set to the stored cursor so the provider filters server-side. */
-		param: z.string()
+		param: z.string(),
+		/**
+		* Optional template for the parameter value — when present, the stored cursor
+		* is interpolated into this template via `{cursor}` instead of injected as a
+		* bare value. Use when the provider needs a full expression rather than a raw
+		* value, e.g. `receivedDateTime gt {cursor}` for OData `$filter` params.
+		* Absent = backward-compatible bare-value injection.
+		*/
+		cursorTemplate: z.string().optional()
 	}), z.object({
 		kind: z.literal("opaque"),
 		/** Dot-path in the list response to the next opaque token. */
@@ -13732,6 +13740,23 @@ var init_trigger_descriptor = __esmMin((() => {
 		pageToken: z.object({
 			requestParam: z.string(),
 			responsePath: z.string()
+		}).optional(),
+		/**
+		* Offset-based pagination via `$skip`/`$top` — an alternative to `pageToken`
+		* for providers whose OpenAPI spec does not expose the page cursor (e.g.
+		* Microsoft Graph, which paginates via `@odata.nextLink` URLs but only
+		* exposes `$skip` as a query parameter). When present, the engine calls the
+		* list operation with `pageSizeParam` set to `stride` on every request, and
+		* increments `param` by `stride` each page. Stops when a page returns fewer
+		* items than `stride`. Mutually exclusive with `pageToken`.
+		*/
+		pageSkip: z.object({
+			/** Query param name for the offset, e.g. `$skip`. */
+			param: z.string(),
+			/** Query param name for the page size, e.g. `$top`. */
+			pageSizeParam: z.string(),
+			/** Number of items per page, also the stride for incrementing `param`. */
+			stride: z.number()
 		}).optional()
 	});
 	triggerItemStepSchema = z.object({
@@ -13900,6 +13925,173 @@ var init_registry_store = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/gmail/gmail.connector.ts
+var GMAIL_CONNECTOR;
+var init_gmail_connector = __esmMin((() => {
+	GMAIL_CONNECTOR = {
+		id: "gmail",
+		displayName: "Gmail",
+		description: "Send email and read messages from a connected Gmail account.",
+		logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://mail.google.com&size=64",
+		category: "email",
+		protocol: "openapi",
+		baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+		authMode: "oauth",
+		placement: { kind: "bearer" },
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"https://www.googleapis.com/auth/gmail.readonly",
+			"https://www.googleapis.com/auth/gmail.send"
+		],
+		authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+		tokenUrl: "https://oauth2.googleapis.com/token",
+		authorizeParams: {
+			access_type: "offline",
+			prompt: "consent"
+		},
+		specSource: {
+			kind: "url",
+			url: "https://api.apis.guru/v2/specs/googleapis.com/gmail/v1/openapi.json"
+		},
+		triggers: [{
+			id: "message-received",
+			displayName: "Message received",
+			description: "Fires when a new message arrives in the inbox.",
+			sampleData: {
+				messageId: "18e0a1b2c3d4e5f6",
+				threadId: "18e0a1b2c3d4e5f6",
+				from: "Ada Lovelace <ada@example.com>",
+				to: "agent@stackbone.ai",
+				subject: "Quarterly report",
+				snippet: "Here is the quarterly report you asked for…",
+				date: "Mon, 10 Jun 2024 09:15:00 +0000",
+				raw: {
+					messageId: "18e0a1b2c3d4e5f6",
+					threadId: "18e0a1b2c3d4e5f6",
+					historyId: "987654"
+				}
+			},
+			poll: {
+				kind: "strategy",
+				strategy: "gmail.history"
+			}
+		}]
+	};
+}));
+//#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/outlook/outlook.connector.ts
+var OUTLOOK_CONNECTOR;
+var init_outlook_connector = __esmMin((() => {
+	OUTLOOK_CONNECTOR = {
+		id: "outlook",
+		displayName: "Outlook",
+		description: "Send email and read messages from a connected Outlook account.",
+		logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http://microsoft.com&size=64",
+		category: "email",
+		protocol: "openapi",
+		baseUrl: "https://graph.microsoft.com/v1.0",
+		authMode: "oauth",
+		placement: { kind: "bearer" },
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"Mail.Read",
+			"Mail.Send",
+			"offline_access"
+		],
+		authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+		tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+		specSource: {
+			kind: "url",
+			url: "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/default.yaml"
+		},
+		authorizeParams: { prompt: "consent" },
+		triggers: [{
+			id: "message-received",
+			displayName: "Message received",
+			description: "Fires when a new message arrives in the Inbox.",
+			sampleData: {
+				messageId: "AAMkAD...",
+				conversationId: "AAQkAD...",
+				from: {
+					name: "Ada Lovelace",
+					address: "ada@example.com"
+				},
+				subject: "Quarterly report",
+				snippet: "Here is the quarterly report...",
+				date: "2024-06-10T09:15:00Z",
+				isRead: false
+			},
+			poll: {
+				kind: "declarative",
+				list: {
+					operationId: "me.mailFolders.ListMessages",
+					args: { "mailFolder-id": "Inbox" },
+					itemsPath: "value",
+					pageSkip: {
+						param: "$skip",
+						pageSizeParam: "$top",
+						stride: 100
+					}
+				},
+				cursor: {
+					kind: "timestamp",
+					field: "receivedDateTime",
+					param: "$filter",
+					cursorTemplate: "receivedDateTime gt {cursor}"
+				},
+				dedup: { idPath: "id" },
+				map: {
+					messageId: "id",
+					conversationId: "conversationId",
+					from: "from",
+					subject: "subject",
+					snippet: "bodyPreview",
+					date: "receivedDateTime",
+					isRead: "isRead"
+				}
+			}
+		}]
+	};
+}));
+//#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/telegram/telegram.connector.ts
+var TELEGRAM_CONNECTOR;
+var init_telegram_connector = __esmMin((() => {
+	TELEGRAM_CONNECTOR = {
+		id: "telegram",
+		displayName: "Telegram",
+		description: "Send and receive messages through a Telegram bot.",
+		logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://telegram.org/&size=64",
+		category: "messaging",
+		protocol: "openapi",
+		baseUrl: "https://api.telegram.org",
+		authMode: "api_key",
+		placement: { kind: "bearer" },
+		scopes: []
+	};
+}));
+//#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/whatsapp/whatsapp.connector.ts
+var WHATSAPP_CONNECTOR;
+var init_whatsapp_connector = __esmMin((() => {
+	WHATSAPP_CONNECTOR = {
+		id: "whatsapp",
+		displayName: "WhatsApp",
+		description: "Send and receive messages through a WhatsApp bot.",
+		logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://www.whatsapp.com/&size=64",
+		category: "messaging",
+		protocol: "openapi",
+		baseUrl: "https://api.whatsapp.com/v1",
+		authMode: "api_key",
+		placement: { kind: "bearer" },
+		scopes: []
+	};
+}));
+//#endregion
 //#region ../../libs/shared/connect-registry/src/lib/catalog/built-in-catalog.ts
 /**
 * Seed `store` with the built-in catalog. Returns `loadFromJson`'s outcome so the
@@ -13911,91 +14103,15 @@ function loadBuiltInCatalog(store) {
 }
 var BUILT_IN_CONNECTOR_DOCS;
 var init_built_in_catalog = __esmMin((() => {
+	init_gmail_connector();
+	init_outlook_connector();
+	init_telegram_connector();
+	init_whatsapp_connector();
 	BUILT_IN_CONNECTOR_DOCS = [
-		{
-			id: "gmail",
-			displayName: "Gmail",
-			description: "Send email and read messages from a connected Gmail account.",
-			logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://mail.google.com&size=64",
-			category: "email",
-			protocol: "openapi",
-			baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
-			authMode: "oauth",
-			placement: { kind: "bearer" },
-			scopes: [
-				"openid",
-				"email",
-				"profile",
-				"https://www.googleapis.com/auth/gmail.readonly",
-				"https://www.googleapis.com/auth/gmail.send"
-			],
-			authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
-			tokenUrl: "https://oauth2.googleapis.com/token",
-			authorizeParams: {
-				access_type: "offline",
-				prompt: "consent"
-			},
-			specSource: {
-				kind: "url",
-				url: "https://api.apis.guru/v2/specs/googleapis.com/gmail/v1/openapi.json"
-			},
-			triggers: [{
-				id: "message-received",
-				displayName: "Message received",
-				description: "Fires when a new message arrives in the inbox.",
-				sampleData: {
-					messageId: "18e0a1b2c3d4e5f6",
-					threadId: "18e0a1b2c3d4e5f6",
-					from: "Ada Lovelace <ada@example.com>",
-					to: "agent@stackbone.ai",
-					subject: "Quarterly report",
-					snippet: "Here is the quarterly report you asked for…",
-					date: "Mon, 10 Jun 2024 09:15:00 +0000",
-					raw: {
-						messageId: "18e0a1b2c3d4e5f6",
-						threadId: "18e0a1b2c3d4e5f6",
-						historyId: "987654"
-					}
-				},
-				poll: {
-					kind: "strategy",
-					strategy: "gmail.history"
-				}
-			}]
-		},
-		{
-			id: "outlook",
-			displayName: "Outlook",
-			description: "Send email and read messages from a connected Outlook account.",
-			logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http://microsoft.com&size=64",
-			category: "email",
-			protocol: "openapi",
-			baseUrl: "https://graph.microsoft.com/v1.0",
-			authMode: "oauth",
-			placement: { kind: "bearer" },
-			scopes: [
-				"openid",
-				"email",
-				"profile",
-				"Mail.Read",
-				"Mail.Send",
-				"offline_access"
-			],
-			authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
-			tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
-		},
-		{
-			id: "telegram",
-			displayName: "Telegram",
-			description: "Send and receive messages through a Telegram bot.",
-			logoUrl: "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://telegram.org/&size=64",
-			category: "messaging",
-			protocol: "openapi",
-			baseUrl: "https://api.telegram.org",
-			authMode: "api_key",
-			placement: { kind: "bearer" },
-			scopes: []
-		}
+		GMAIL_CONNECTOR,
+		OUTLOOK_CONNECTOR,
+		TELEGRAM_CONNECTOR,
+		WHATSAPP_CONNECTOR
 	];
 }));
 //#endregion
@@ -14568,14 +14684,17 @@ function latestTimestamp(items, field) {
 function createDeclarativePoll(spec) {
 	return async (ctx, cursor) => {
 		const baseArgs = { ...spec.list.args ?? {} };
-		if (cursor !== null && cursor !== void 0) if (spec.cursor.kind === "timestamp") baseArgs[spec.cursor.param] = cursor;
+		if (cursor !== null && cursor !== void 0) if (spec.cursor.kind === "timestamp") baseArgs[spec.cursor.param] = spec.cursor.cursorTemplate ? spec.cursor.cursorTemplate.replace("{cursor}", String(cursor)) : cursor;
 		else baseArgs[spec.cursor.requestParam] = cursor;
 		const rawItems = [];
 		let opaqueNext;
 		let pageToken;
 		for (let page = 0; page < MAX_PAGES; page += 1) {
 			const args = { ...baseArgs };
-			if (pageToken !== null && pageToken !== void 0 && spec.list.pageToken) args[spec.list.pageToken.requestParam] = pageToken;
+			if (spec.list.pageSkip) {
+				args[spec.list.pageSkip.pageSizeParam] = spec.list.pageSkip.stride;
+				if (page > 0) args[spec.list.pageSkip.param] = page * spec.list.pageSkip.stride;
+			} else if (pageToken !== null && pageToken !== void 0 && spec.list.pageToken) args[spec.list.pageToken.requestParam] = pageToken;
 			const response = await ctx.runOperation(spec.list.operationId, args);
 			const items = getPath(response, spec.list.itemsPath);
 			if (Array.isArray(items)) rawItems.push(...items);
@@ -14583,8 +14702,12 @@ function createDeclarativePoll(spec) {
 				const next = getPath(response, spec.cursor.responsePath);
 				if (next !== null && next !== void 0) opaqueNext = next;
 			}
-			pageToken = spec.list.pageToken ? getPath(response, spec.list.pageToken.responsePath) : void 0;
-			if (pageToken === null || pageToken === void 0) break;
+			if (spec.list.pageSkip) {
+				if (!Array.isArray(items) || items.length < spec.list.pageSkip.stride) break;
+			} else {
+				pageToken = spec.list.pageToken ? getPath(response, spec.list.pageToken.responsePath) : void 0;
+				if (pageToken === null || pageToken === void 0) break;
+			}
 		}
 		let items = rawItems;
 		if (spec.item) {
@@ -14610,6 +14733,113 @@ var init_declarative_poll = __esmMin((() => {
 	MAX_PAGES = 100;
 }));
 //#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/gmail/gmail.history-strategy.ts
+function isGmailCursor(cursor) {
+	return typeof cursor === "object" && cursor !== null && typeof cursor.historyId === "string" && cursor.historyId.length > 0;
+}
+/** Read a single header value (case-insensitive) off a Gmail message payload. */
+function header(message, name) {
+	const match = (message.payload?.headers ?? []).find((h) => (h.name ?? "").toLowerCase() === name.toLowerCase());
+	return typeof match?.value === "string" ? match.value : "";
+}
+/** Fetch one message (metadata format) and normalize it to a poll item. */
+async function fetchMessageEvent(ctx, id) {
+	const message = await ctx.runOperation("gmail.users.messages.get", {
+		userId: USER_ID,
+		id,
+		format: "metadata"
+	});
+	const payload = {
+		messageId: message.id ?? id,
+		threadId: message.threadId ?? "",
+		from: header(message, "From"),
+		to: header(message, "To"),
+		subject: header(message, "Subject"),
+		snippet: typeof message.snippet === "string" ? message.snippet : "",
+		date: header(message, "Date"),
+		raw: {
+			messageId: message.id ?? id,
+			threadId: message.threadId ?? "",
+			historyId: typeof message.historyId === "string" ? message.historyId : null
+		}
+	};
+	return {
+		id: message.id ?? id,
+		payload
+	};
+}
+function readHistoryId(event) {
+	const raw = (event?.payload)?.raw;
+	return raw && typeof raw.historyId === "string" ? raw.historyId : null;
+}
+/**
+* Bootstrap path (empty cursor): list the most recent inbox messages, normalize
+* them, and seed the cursor from the newest message's `historyId`. Dedup is the
+* platform's job (by message id), so a first poll legitimately returns the recent
+* window and the next poll resumes from the history API.
+*/
+async function bootstrap(ctx) {
+	const items = await mapWithConcurrency(((await ctx.runOperation("gmail.users.messages.list", {
+		userId: USER_ID,
+		maxResults: BOOTSTRAP_MAX_RESULTS,
+		labelIds: "INBOX"
+	})).messages ?? []).map((m) => m.id).filter((id) => typeof id === "string" && id.length > 0), 6, (id) => fetchMessageEvent(ctx, id));
+	const seedHistoryId = readHistoryId(items[0]);
+	return {
+		items,
+		nextCursor: seedHistoryId ? { historyId: seedHistoryId } : null
+	};
+}
+/**
+* Incremental path (valid cursor): pull history records added since the persisted
+* `historyId` via `history.list`, drain EVERY page (so messages on pages 2+ are
+* never skipped when the cursor advances), normalize each new arrival, and move
+* the cursor to the response's latest `historyId`.
+*/
+async function pollFromCursor(ctx, cursor) {
+	const addedIds = [];
+	let latestHistoryId = cursor.historyId;
+	let pageToken;
+	for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
+		const history = await ctx.runOperation("gmail.users.history.list", {
+			userId: USER_ID,
+			startHistoryId: cursor.historyId,
+			historyTypes: "messageAdded",
+			labelId: "INBOX",
+			...pageToken ? { pageToken } : {}
+		});
+		for (const record of history.history ?? []) for (const added of record.messagesAdded ?? []) {
+			const id = added.message?.id;
+			if (typeof id === "string" && id.length > 0) addedIds.push(id);
+		}
+		if (typeof history.historyId === "string" && history.historyId.length > 0) latestHistoryId = history.historyId;
+		if (typeof history.nextPageToken === "string" && history.nextPageToken.length > 0) pageToken = history.nextPageToken;
+		else break;
+	}
+	return {
+		items: await mapWithConcurrency(addedIds, 6, (id) => fetchMessageEvent(ctx, id)),
+		nextCursor: { historyId: latestHistoryId }
+	};
+}
+var USER_ID, BOOTSTRAP_MAX_RESULTS, MAX_HISTORY_PAGES, gmailHistoryPoll;
+var init_gmail_history_strategy = __esmMin((() => {
+	init_concurrency();
+	USER_ID = "me";
+	BOOTSTRAP_MAX_RESULTS = 25;
+	MAX_HISTORY_PAGES = 100;
+	gmailHistoryPoll = async (ctx, cursor) => {
+		if (!isGmailCursor(cursor)) return bootstrap(ctx);
+		return pollFromCursor(ctx, cursor);
+	};
+}));
+//#endregion
+//#region ../../libs/shared/connect-registry/src/lib/catalog/built-in-strategies.ts
+var BUILT_IN_STRATEGIES;
+var init_built_in_strategies = __esmMin((() => {
+	init_gmail_history_strategy();
+	BUILT_IN_STRATEGIES = { "gmail.history": gmailHistoryPoll };
+}));
+//#endregion
 //#region ../../libs/shared/connect-registry/src/index.ts
 var init_src$3 = __esmMin((() => {
 	init_types$1();
@@ -14622,6 +14852,7 @@ var init_src$3 = __esmMin((() => {
 	init_trigger_descriptor();
 	init_declarative_poll();
 	init_concurrency();
+	init_built_in_strategies();
 }));
 //#endregion
 //#region ../../libs/platform/connect-broker/src/lib/executor/spec-introspection.ts
@@ -16695,8 +16926,14 @@ function invalidRequest(message) {
 }
 //#endregion
 //#region ../../libs/runtime/agent-emulator/src/lib/deep-agents/registry.ts
-var DEEP_AGENTS_WELL_KNOWN_DIR, isPlainRecord, readConfigStrings, toMetadata, isDeepAgentDefinition, bundleAndLoad, loadPrebuilt, createDeepAgentRegistry, errMessage$9, matchChangedPathsToAgents;
+var SYSTEM_DEEP_AGENTS, isInternalDeepAgent, DEEP_AGENTS_WELL_KNOWN_DIR, isPlainRecord, readConfigStrings, toMetadata, isDeepAgentDefinition, bundleAndLoad, loadPrebuilt, createDeepAgentRegistry, errMessage$9, matchChangedPathsToAgents;
 var init_registry$1 = __esmMin((() => {
+	SYSTEM_DEEP_AGENTS = new Set(["rag-ingest"]);
+	isInternalDeepAgent = (agent) => {
+		if (agent.$internal === false) return false;
+		if (agent.$internal === true) return true;
+		return SYSTEM_DEEP_AGENTS.has(agent.name);
+	};
 	DEEP_AGENTS_WELL_KNOWN_DIR = ".well-known/deep-agents";
 	isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 	readConfigStrings = (config) => {
@@ -16788,7 +17025,8 @@ var init_registry$1 = __esmMin((() => {
 						metadata: toMetadata(def)
 					},
 					createGraph: def.createGraph.bind(def),
-					supportsCheckpointer: def.capabilities?.checkpointer === true
+					supportsCheckpointer: def.capabilities?.checkpointer === true,
+					$internal: isInternalDeepAgent(agent)
 				});
 				logger.info(`deep agent "${agent.name}" ready (model ${def.metadata.model}).`);
 				return true;
@@ -16829,7 +17067,7 @@ var init_registry$1 = __esmMin((() => {
 		return {
 			list: () => {
 				const checkpointerReady = opts.checkpointer?.status?.() === "ready";
-				return [...registered.values()].map((e) => ({
+				return [...registered.values()].filter((e) => !e.$internal).map((e) => ({
 					name: e.view.name,
 					metadata: e.view.metadata,
 					durable: e.supportsCheckpointer && checkpointerReady
@@ -22240,13 +22478,19 @@ var init_workflow_step_world_port = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/runtime/agent-emulator/src/lib/workflow/registry.ts
-var hasDeclaredSchema, workflowStartTrigger, buildManifest;
+var hasDeclaredSchema, workflowStartTrigger, SYSTEM_WORKFLOWS, isInternalWorkflow, buildManifest;
 var init_registry = __esmMin((() => {
 	hasDeclaredSchema = (pair) => pair != null && (pair.input != null || pair.output != null);
 	workflowStartTrigger = (name) => `POST /api/workflows/${name}/start`;
+	SYSTEM_WORKFLOWS = new Set(["rag-ingest"]);
+	isInternalWorkflow = (workflow) => {
+		if (workflow.$internal === false) return false;
+		if (workflow.$internal === true) return true;
+		return SYSTEM_WORKFLOWS.has(workflow.name);
+	};
 	buildManifest = (input) => ({
 		agents: [],
-		workflows: input.workspace.workflows.map((w) => {
+		workflows: input.workspace.workflows.filter((w) => !isInternalWorkflow(w)).map((w) => {
 			const steps = input.workflowSteps?.get(w.name);
 			return {
 				name: w.name,
@@ -22488,6 +22732,28 @@ var init_workflow_start_service = __esmMin((() => {
 			return triggerWorkflowStartAndWait(deps, name, input);
 		}
 	});
+}));
+//#endregion
+//#region ../../libs/runtime/agent-emulator/src/lib/workflow/approval-recorder-bridge.ts
+var createApprovalRecorder;
+var init_approval_recorder_bridge = __esmMin((() => {
+	createApprovalRecorder = (deps) => ({ async request(args) {
+		const context = deps.getInvocationContext?.();
+		const enriched = { ...args };
+		if (context?.runId !== void 0) enriched["runId"] = context.runId;
+		if (context?.requestedByStepId !== void 0) enriched["requestedByStepId"] = context.requestedByStepId;
+		try {
+			const result = await deps.request(enriched);
+			if (result.error) {
+				const code = result.error.code ?? "approval_persist_failed";
+				const message = result.error.message ?? "Failed to write the approval to the agent database.";
+				throw new Error(`requestApproval could not persist the approvals row (${code}): ${message} The workflow step will retry — a HITL decision is never quietly lost.`);
+			}
+		} catch (err) {
+			console.error("[approval-recorder] failed to persist approvals row:", err instanceof Error ? err.message : String(err));
+			throw err;
+		}
+	} });
 })), DEFAULT_TZ, TICK_JOB_NAME$1, DECL_PREFIX, DYN_PREFIX, declSchedulerId, dynSchedulerId, planDeclarativeReconcile, expandDeclaredSchedules, parseSchedulerId, consoleLogger$2, WorkflowCronScheduler, createWorkflowSchedulerBridge;
 var init_workflow_cron_scheduler = __esmMin((() => {
 	DEFAULT_TZ = "UTC";
@@ -23057,111 +23323,11 @@ var init_intake_scheduler = __esmMin((() => {
 	};
 }));
 //#endregion
-//#region ../../libs/runtime/agent-emulator/src/lib/connect-inbound/gmail-history-strategy.ts
-function isGmailCursor(cursor) {
-	return typeof cursor === "object" && cursor !== null && typeof cursor.historyId === "string" && cursor.historyId.length > 0;
-}
-/** Read a single header value (case-insensitive) off a Gmail message payload. */
-function header(message, name) {
-	const match = (message.payload?.headers ?? []).find((h) => (h.name ?? "").toLowerCase() === name.toLowerCase());
-	return typeof match?.value === "string" ? match.value : "";
-}
-/** Fetch one message (metadata format) and normalize it to a poll item. */
-async function fetchMessageEvent(ctx, id) {
-	const message = await ctx.runOperation("gmail.users.messages.get", {
-		userId: USER_ID,
-		id,
-		format: "metadata"
-	});
-	const payload = {
-		messageId: message.id ?? id,
-		threadId: message.threadId ?? "",
-		from: header(message, "From"),
-		to: header(message, "To"),
-		subject: header(message, "Subject"),
-		snippet: typeof message.snippet === "string" ? message.snippet : "",
-		date: header(message, "Date"),
-		raw: {
-			messageId: message.id ?? id,
-			threadId: message.threadId ?? "",
-			historyId: typeof message.historyId === "string" ? message.historyId : null
-		}
-	};
-	return {
-		id: message.id ?? id,
-		payload
-	};
-}
-function readHistoryId(event) {
-	const raw = (event?.payload)?.raw;
-	return raw && typeof raw.historyId === "string" ? raw.historyId : null;
-}
-/**
-* Bootstrap path (empty cursor): list the most recent inbox messages, normalize
-* them, and seed the cursor from the newest message's `historyId`. Dedup is the
-* platform's job (by message id), so a first poll legitimately returns the recent
-* window and the next poll resumes from the history API.
-*/
-async function bootstrap(ctx) {
-	const items = await mapWithConcurrency(((await ctx.runOperation("gmail.users.messages.list", {
-		userId: USER_ID,
-		maxResults: BOOTSTRAP_MAX_RESULTS,
-		labelIds: "INBOX"
-	})).messages ?? []).map((m) => m.id).filter((id) => typeof id === "string" && id.length > 0), 6, (id) => fetchMessageEvent(ctx, id));
-	const seedHistoryId = readHistoryId(items[0]);
-	return {
-		items,
-		nextCursor: seedHistoryId ? { historyId: seedHistoryId } : null
-	};
-}
-/**
-* Incremental path (valid cursor): pull history records added since the persisted
-* `historyId` via `history.list`, drain EVERY page (so messages on pages 2+ are
-* never skipped when the cursor advances), normalize each new arrival, and move
-* the cursor to the response's latest `historyId`.
-*/
-async function pollFromCursor(ctx, cursor) {
-	const addedIds = [];
-	let latestHistoryId = cursor.historyId;
-	let pageToken;
-	for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
-		const history = await ctx.runOperation("gmail.users.history.list", {
-			userId: USER_ID,
-			startHistoryId: cursor.historyId,
-			historyTypes: "messageAdded",
-			labelId: "INBOX",
-			...pageToken ? { pageToken } : {}
-		});
-		for (const record of history.history ?? []) for (const added of record.messagesAdded ?? []) {
-			const id = added.message?.id;
-			if (typeof id === "string" && id.length > 0) addedIds.push(id);
-		}
-		if (typeof history.historyId === "string" && history.historyId.length > 0) latestHistoryId = history.historyId;
-		if (typeof history.nextPageToken === "string" && history.nextPageToken.length > 0) pageToken = history.nextPageToken;
-		else break;
-	}
-	return {
-		items: await mapWithConcurrency(addedIds, 6, (id) => fetchMessageEvent(ctx, id)),
-		nextCursor: { historyId: latestHistoryId }
-	};
-}
-var USER_ID, BOOTSTRAP_MAX_RESULTS, MAX_HISTORY_PAGES, gmailHistoryPoll;
-var init_gmail_history_strategy = __esmMin((() => {
-	init_src$3();
-	USER_ID = "me";
-	BOOTSTRAP_MAX_RESULTS = 25;
-	MAX_HISTORY_PAGES = 100;
-	gmailHistoryPoll = async (ctx, cursor) => {
-		if (!isGmailCursor(cursor)) return bootstrap(ctx);
-		return pollFromCursor(ctx, cursor);
-	};
-}));
-//#endregion
 //#region ../../libs/runtime/agent-emulator/src/lib/connect-inbound/trigger-strategies.ts
 var STRATEGIES, resolveStrategy;
 var init_trigger_strategies = __esmMin((() => {
-	init_gmail_history_strategy();
-	STRATEGIES = { "gmail.history": gmailHistoryPoll };
+	init_src$3();
+	STRATEGIES = { ...BUILT_IN_STRATEGIES };
 	resolveStrategy = (name) => STRATEGIES[name] ?? null;
 }));
 //#endregion
@@ -23392,6 +23558,7 @@ var init_runtime_mount = __esmMin((() => {
 	init_workflow_run_projector();
 	init_workflow_invoker();
 	init_workflow_start_service();
+	init_approval_recorder_bridge();
 	init_workflow_cron_scheduler();
 	init_workflow_hook_resume();
 	init_workflow_frame_sse();
@@ -23471,6 +23638,11 @@ var init_runtime_mount = __esmMin((() => {
 		let setWorkflowStarter;
 		let setWorkflowScheduler;
 		let setDeepAgentInvoker;
+		let setAiUsageReporter;
+		let setApprovalRecorder;
+		let approvalRequest;
+		let setConnectorInvoker;
+		let connectorInvoker;
 		try {
 			const sdk = await importProject("@stackbone/sdk");
 			runWithInvocationContext = sdk.runWithInvocationContext;
@@ -23478,12 +23650,34 @@ var init_runtime_mount = __esmMin((() => {
 			setWorkflowStarter = sdk.setWorkflowStarter;
 			setWorkflowScheduler = sdk.setWorkflowScheduler;
 			setDeepAgentInvoker = sdk.setDeepAgentInvoker;
+			setAiUsageReporter = sdk.setAiUsageReporter;
+			setApprovalRecorder = sdk.setApprovalRecorder;
+			setConnectorInvoker = sdk.setConnectorInvoker;
+			connectorInvoker = sdk.createConnectInvoker?.();
+			const ambientStackbone = sdk.stackbone;
+			if (ambientStackbone) approvalRequest = async (args) => {
+				const approval = ambientStackbone.approval;
+				if (!approval?.request) return {
+					data: null,
+					error: {
+						code: "approval_unavailable",
+						message: "The project SDK exposes no ambient approval writer."
+					}
+				};
+				return approval.request(args);
+			};
+			else approvalRequest = void 0;
 		} catch {
 			runWithInvocationContext = void 0;
 			getInvocationContext = void 0;
 			setWorkflowStarter = void 0;
 			setWorkflowScheduler = void 0;
 			setDeepAgentInvoker = void 0;
+			setAiUsageReporter = void 0;
+			setApprovalRecorder = void 0;
+			approvalRequest = void 0;
+			setConnectorInvoker = void 0;
+			connectorInvoker = void 0;
 		}
 		const stepUrl = pathToFileURL(resolve(projectRoot, WELL_KNOWN_DIR$2, "step.mjs")).href;
 		await (runtimeEnv.generation ? import(`${stepUrl}?v=${runtimeEnv.generation}`) : import(stepUrl));
@@ -23495,7 +23689,12 @@ var init_runtime_mount = __esmMin((() => {
 			resumeHook,
 			setWorkflowStarter,
 			setWorkflowScheduler,
-			setDeepAgentInvoker
+			setDeepAgentInvoker,
+			setAiUsageReporter,
+			setApprovalRecorder,
+			approvalRequest,
+			setConnectorInvoker,
+			connectorInvoker
 		};
 	};
 	mountWorkflowRuntime = async (app, opts) => {
@@ -23581,6 +23780,21 @@ var init_runtime_mount = __esmMin((() => {
 						return invoker(name, input, options);
 					});
 				}
+				if (rt.setAiUsageReporter) {
+					const invocations = opts.invocations;
+					rt.setAiUsageReporter((usage) => {
+						const runId = rt.getInvocationContext?.()?.runId;
+						if (!runId || !invocations) return;
+						invocations.addRunTokens(runId, usage).catch((err) => {
+							console.warn(`[ai-usage] token fold failed for run ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+						});
+					});
+				}
+				if (rt.setApprovalRecorder && rt.approvalRequest) rt.setApprovalRecorder(createApprovalRecorder({
+					request: rt.approvalRequest,
+					...rt.getInvocationContext ? { getInvocationContext: rt.getInvocationContext } : {}
+				}));
+				if (rt.setConnectorInvoker && rt.connectorInvoker) rt.setConnectorInvoker(rt.connectorInvoker);
 				return rt;
 			}).catch((err) => {
 				runtimePromise = null;
@@ -23811,7 +24025,11 @@ var init_runtime_mount = __esmMin((() => {
 				await cronScheduler?.close();
 				await intakeRuntime?.close();
 				if (runtimePromise) try {
-					(await runtimePromise).setDeepAgentInvoker?.(void 0);
+					const rt = await runtimePromise;
+					rt.setDeepAgentInvoker?.(void 0);
+					rt.setAiUsageReporter?.(void 0);
+					rt.setApprovalRecorder?.(void 0);
+					rt.setConnectorInvoker?.(void 0);
 				} catch {}
 			},
 			triggerWorkflowStart: (name, input) => triggerWorkflowStart(startDeps, name, input),
@@ -30830,6 +31048,62 @@ var findWorkflowFiles = async (projectRoot, extraModules = []) => {
 	return files;
 };
 /**
+* Scan the final `workflow.vm.js` text for any `require(...)` call and throw an
+* actionable error if one is found.
+*
+* The workflow VM bundle runs on `node:vm`, which has NO `require`. A `require(`
+* token surviving into the bundle means something reachable from a workflow body
+* (a helper, a transitive import) dragged a Node-only dependency into the VM graph
+* — the Workflow SDK (WDK) compiler inlines the whole module, and the inlined
+* `require()` throws `ReferenceError: require is not defined` at instantiation,
+* crashing EVERY workflow in the project with an opaque `USER_ERROR` / "Unknown
+* error" (the bug this guard makes impossible to ship silently).
+*
+* Pure + exported so it is unit-testable in isolation (prior art:
+* `foldSchemasIntoManifest`). False-positive discipline: it matches `require(`
+* only as a CALL shape, not the substring inside a comment or a string literal
+* that is not actually invoked — the VM bundle is generated code, so a literal
+* `require(` in a string is still a smell worth flagging, but the guard reports
+* the surrounding context so a human can tell a real leak from a benign mention.
+*/
+var assertNoLeakedNodeRequire = (bundleText) => {
+	const requirePattern = /require\s*\(\s*['"`]/g;
+	const matches = [];
+	const lines = bundleText.split("\n");
+	for (const match of bundleText.matchAll(requirePattern)) {
+		const index = match.index ?? 0;
+		let line = 1;
+		let column = 1;
+		let consumed = 0;
+		for (let i = 0; i < lines.length; i += 1) {
+			const lineText = lines[i];
+			if (lineText === void 0) break;
+			const lineEnd = consumed + lineText.length + 1;
+			if (index < lineEnd) {
+				line = i + 1;
+				column = index - consumed + 1;
+				break;
+			}
+			consumed = lineEnd;
+		}
+		const start = Math.max(0, index - 80);
+		const end = Math.min(bundleText.length, index + 120);
+		const snippet = bundleText.slice(start, end).replace(/\s+/g, " ").trim();
+		matches.push({
+			index,
+			line,
+			column,
+			snippet
+		});
+	}
+	if (matches.length === 0) return;
+	const first = matches[0];
+	if (!first) return;
+	const listing = matches.slice(0, 5).map((m, i) => `  ${i + 1}. line ${m.line}:${m.column}  …${m.snippet}…`).join("\n");
+	const more = matches.length > 5 ? `\n  (and ${matches.length - 5} more)` : "";
+	throw new Error(`Workflow VM bundle contains ${matches.length} require() call(s) — the workflow VM (node:vm) has no \`require\`, so the bundle will crash at instantiation with \`ReferenceError: require is not defined\`, breaking EVERY workflow in this project.\nThis means a Node-only dependency (e.g. node:crypto, the Postgres driver, the OpenAI / AWS SDKs) is reachable from a workflow body or a "use step" that was not properly externalized. The most common cause is a workflow-steps helper that touches Node at module scope — it must reach Node only through a runtime-planted binding (see @stackbone/sdk/workflow-steps/*) or be wrapped in a "use step" that the WDK stubs out of the VM graph.\nFirst occurrence: line ${first.line}:${first.column}\n${listing}${more}\nFix: move the Node-bearing code behind a runtime binding, wrap the call in a "use step" function, or import the helper from @stackbone/sdk/workflow-steps/* (the per-domain entry that the WDK keeps out of the VM body).`);
+};
+/**
 * Build the workspace's workflows into `<projectRoot>/.well-known/workflow/v1/`:
 *   - `step.mjs`        — steps bundle (runtime external)
 *   - `workflow.vm.js`  — the workflow VM bundle text fed to `workflowEntrypoint`
@@ -30858,7 +31132,7 @@ var buildWorkflows = async (projectRoot, workflows, logger) => {
 		stepsBundlePath: `./${WELL_KNOWN_DIR}/step.mjs`,
 		workflowsBundlePath: `./${WELL_KNOWN_DIR}/workflow.vm.js`,
 		webhookBundlePath: `./${WELL_KNOWN_DIR}/webhook.mjs`,
-		externalPackages: ["@stackbone/sdk", "@stackbone/sdk/*"]
+		externalPackages: []
 	});
 	const prevCwd = process.cwd();
 	let manifest;
@@ -30885,6 +31159,7 @@ var buildWorkflows = async (projectRoot, workflows, logger) => {
 	const streaming = await detectStreamingWorkflows(projectRoot, workflows);
 	foldSchemasIntoManifest(manifest, workflows, schemas, streaming, schedules);
 	await writeFile(resolve(wkDir, "workflow.vm.js"), interimBundleText, "utf8");
+	assertNoLeakedNodeRequire(interimBundleText);
 	await writeFile(resolve(wkDir, "manifest.json"), JSON.stringify(manifest), "utf8");
 	for (const name of [
 		"step.mjs",
@@ -31179,7 +31454,8 @@ var loadWorkspace = async (projectRoot) => {
 	if (!isWorkspace(workspace)) throw new Error(`${configPath} must default-export a workspace with \`agents\` and \`workflows\` arrays (via \`defineWorkspace({ agents, workflows })\`).`);
 	return {
 		agents: workspace.agents,
-		workflows: workspace.workflows
+		workflows: workspace.workflows,
+		deepAgents: workspace.deepAgents
 	};
 };
 //#endregion
@@ -31249,10 +31525,11 @@ var discoverDeepAgents = async (root) => {
 /**
 * Derive `{ agents, workflows, deepAgents }` for the workspace rooted at `root`.
 * `agents` is always `[]` (there is no server-per-agent runtime). A `stackbone.config.ts`
-* override wins for workflows; deep agents are always discovered by folder
-* convention (the config format does not declare them), and `deepAgents` is
-* omitted entirely when none are found so an empty workspace is byte-identical to
-* before.
+* override wins for workflows AND deep agents; when the config declares `deepAgents`,
+* those win over auto-discovery (use to mark agents as `$internal` or customize the
+* registry). When omitted, deep agents are discovered by folder convention and
+* `deepAgents` is omitted entirely when none are found so an empty workspace is
+* byte-identical to before.
 */
 var discoverWorkspace = async (root) => {
 	const deepAgents = await discoverDeepAgents(root);
@@ -31260,10 +31537,18 @@ var discoverWorkspace = async (root) => {
 		...ws,
 		deepAgents
 	};
-	if (await fileExists$1(resolve(root, "stackbone.config.ts"))) return withDeepAgents({
-		agents: [],
-		workflows: (await loadWorkspace(root)).workflows
-	});
+	if (await fileExists$1(resolve(root, "stackbone.config.ts"))) {
+		const ws = await loadWorkspace(root);
+		const resultDeepAgents = ws.deepAgents ?? deepAgents;
+		const baseResult = {
+			agents: [],
+			workflows: ws.workflows
+		};
+		return resultDeepAgents.length === 0 ? baseResult : {
+			...baseResult,
+			deepAgents: resultDeepAgents
+		};
+	}
 	return withDeepAgents({
 		agents: [],
 		workflows: await discoverWorkflows(root)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {