@powerhousedao/switchboard 6.2.3-dev.30 → 6.2.3-dev.32

package/dist/{server-Cf0DB8sW.mjs → server-CKKn0aXV.mjs}

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="49b28650-fe00-57f4-844b-978a35d80e91")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ec5120f6-92b3-53b4-bab1-94d88478784d")}catch(e){}}();
 import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-uaBlzyjS.mjs";
 import { createRequire, register } from "node:module";
 import { ReactorInstrumentation } from "@powerhousedao/opentelemetry-instrumentation-reactor";
@@ -31,7 +31,7 @@ import os from "node:os";
 import { fileURLToPath } from "node:url";
 import { EnvVarProvider } from "@openfeature/env-var-provider";
 import { OpenFeature } from "@openfeature/server-sdk";
-import { GraphQLError } from "graphql";
+import { GraphQLError, Kind } from "graphql";
 import { gql } from "graphql-tag";
 import { PGliteDialect } from "kysely-pglite-dialect";
 //#region src/pglite-version.ts
@@ -1112,10 +1112,115 @@ async function initFeatureFlags() {
 	return OpenFeature.getClient();
 }
 //#endregion
+//#region src/workflow/oauth-callback.ts
+const OAUTH_CALLBACK_PATH = "oauth/callback";
+function escapeHtml(text) {
+	return text.replace(/[&<>"']/g, (char) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&#39;"
+	})[char]);
+}
+function resultPage(ok, detail) {
+	const title = ok ? "Connected" : "Sign-in failed";
+	return `<!doctype html>
+<html><head><meta charset="utf-8"><title>${title}</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>body{font:15px system-ui,sans-serif;margin:0;display:grid;place-items:center;min-height:100vh;background:#fafafa;color:#222}main{max-width:28rem;padding:1.5rem;text-align:center}h1{font-size:1.1rem}</style>
+</head><body><main><h1>${title}</h1><p>${ok ? "You can close this window." : escapeHtml(detail ?? "The sign-in did not finish.")}</p></main>
+${ok ? "<script>setTimeout(function(){window.close()},600)<\/script>" : ""}
+</body></html>`;
+}
+function registerOAuthCallback(http, runtime) {
+	return http.get(OAUTH_CALLBACK_PATH, { auth: "public" }, async (request) => {
+		const params = new URL(request.url).searchParams;
+		const state = params.get("state");
+		const result = state ? await runtime.completeOAuth({
+			state,
+			code: params.get("code") ?? void 0,
+			error: params.get("error") ?? void 0,
+			errorDescription: params.get("error_description") ?? void 0
+		}) : {
+			ok: false,
+			detail: "The provider sent no state",
+			returnUrl: null
+		};
+		if (result.returnUrl && state) {
+			const back = new URL(result.returnUrl);
+			back.searchParams.set("ph_oauth", state);
+			return new Response(null, {
+				status: 303,
+				headers: {
+					location: back.href,
+					"cache-control": "no-store"
+				}
+			});
+		}
+		return new Response(resultPage(result.ok, result.detail), {
+			status: result.ok ? 200 : 400,
+			headers: {
+				"content-type": "text/html; charset=utf-8",
+				"cache-control": "no-store",
+				"referrer-policy": "no-referrer"
+			}
+		});
+	});
+}
+function callbackUrlOf(http) {
+	return `${http.baseUrl.replace(/\/+$/, "")}/${OAUTH_CALLBACK_PATH}`;
+}
+//#endregion
 //#region src/workflow/resolvers.ts
+function blockRef(input) {
+	if (input.kind !== "action" && input.kind !== "trigger") throw new GraphQLError(`A block's kind is "action" or "trigger", got "${input.kind}"`);
+	return {
+		pieceName: input.pieceName,
+		pieceVersion: input.pieceVersion,
+		name: input.name,
+		kind: input.kind
+	};
+}
+async function cursorAware(call) {
+	try {
+		return await call();
+	} catch (error) {
+		if (error instanceof Error && error.name === "InvalidRunCursorError") throw new GraphQLError(error.message, { extensions: { code: "BAD_USER_INPUT" } });
+		throw error;
+	}
+}
+function selectsStepData(selections, path) {
+	let level = selections;
+	for (const name of [...path, "steps"]) {
+		const next = [];
+		for (const set of level) for (const selection of set.selections) {
+			if (selection.kind !== Kind.FIELD) return true;
+			if (selection.name.value === name && selection.selectionSet) next.push(selection.selectionSet);
+		}
+		if (next.length === 0) return false;
+		level = next;
+	}
+	return level.some((set) => set.selections.some((selection) => selection.kind !== Kind.FIELD || selection.name.value === "input" || selection.name.value === "output"));
+}
+function readsStepData(info, path) {
+	if (!info) return true;
+	return selectsStepData(info.fieldNodes.flatMap((node) => node.selectionSet ? [node.selectionSet] : []), path);
+}
 function requireAdmin(authorizationService, ctx) {
 	if (!authorizationService.isSupremeAdmin(ctx.user?.address)) throw new GraphQLError("Admin access required");
 }
+async function syncAware(call) {
+	try {
+		return await call();
+	} catch (error) {
+		if (error instanceof Error && error.name === "WorkflowSyncingError") throw new GraphQLError(error.message, { extensions: {
+			code: "WORKFLOW_SYNCING",
+			retryable: true
+		} });
+		throw error;
+	}
+}
 function parseJson(value) {
 	if (value === null) return null;
 	try {
@@ -1128,14 +1233,19 @@ function toStepRecord(row) {
 	return {
 		stepId: row.step_id,
 		stepKey: row.step_key,
-		blockType: row.block_type,
+		pieceName: row.piece_name,
+		blockName: row.block_name,
 		status: row.status,
 		input: parseJson(row.input),
 		output: parseJson(row.output),
 		port: row.port,
 		error: row.error,
 		startedAt: row.started_at,
-		endedAt: row.ended_at
+		endedAt: row.ended_at,
+		pieceVersion: row.piece_version,
+		pieceSource: row.piece_source,
+		versionMatch: row.version_match,
+		versionNote: row.version_note
 	};
 }
 function toRunRecord(row, steps) {
@@ -1151,24 +1261,56 @@ function toRunRecord(row, steps) {
 		startedAt: row.started_at,
 		endedAt: row.ended_at,
 		rerunOf: row.rerun_of,
+		warnings: row.warnings,
+		warningNotes: parseJson(row.warning_notes) ?? [],
 		steps: steps.map(toStepRecord)
 	};
 }
-const getResolvers = (runtime, authorizationService) => {
+function isAbsolute(url) {
+	return /^https?:\/\//i.test(url);
+}
+function redirectUriFor(routing, requested) {
+	if (!routing) throw new GraphQLError("This host serves no OAuth2 callback");
+	if (isAbsolute(routing.callbackUrl)) return routing.callbackUrl;
+	if (!requested) throw new GraphQLError("This host does not know its public URL; pass redirectUri");
+	let url;
+	try {
+		url = new URL(requested);
+	} catch {
+		throw new GraphQLError(`"${requested}" is not a URL`);
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:" || url.pathname !== routing.callbackUrl || url.search !== "" || url.hash !== "") throw new GraphQLError(`redirectUri must be this host's ${routing.callbackUrl}`);
+	return url.href;
+}
+function returnUrlFor(requested, ctx) {
+	if (!requested) return void 0;
+	const origin = ctx.headers.origin;
+	let url;
+	try {
+		url = new URL(requested);
+	} catch {
+		url = void 0;
+	}
+	if (!url || !origin || url.origin !== origin) throw new GraphQLError("returnUrl must be on the requesting page's origin");
+	return url.href;
+}
+const getResolvers = (runtime, authorizationService, oauth) => {
 	return {
 		Query: { workflowRuntime: () => ({}) },
 		WorkflowRuntimeQueries: {
 			health: () => "ok",
-			blockDescriptor: (_parent, args) => runtime.blockDescriptor(args.blockType),
-			blockOptions: (_parent, args, ctx) => runtime.blockOptions(args.blockType, args.propName, args.input, args.connectionId ?? void 0, ctx, args.searchValue ?? void 0),
+			blockDescriptor: (_parent, args) => runtime.blockDescriptor(blockRef(args.block)),
+			blockOptions: (_parent, args, ctx) => runtime.blockOptions(blockRef(args.block), args.propName, args.input, args.connectionId ?? void 0, ctx, args.searchValue ?? void 0),
 			pieceCatalog: () => runtime.pieceCatalog(),
-			pieceActions: (_parent, args) => runtime.pieceActions(args.packageName),
-			pieceTriggers: (_parent, args) => runtime.pieceTriggers(args.packageName),
-			blockOutputTree: (_parent, args) => runtime.blockOutputTree(args.blockType, args.config),
-			pieceDetail: (_parent, args) => runtime.pieceDetail(args.packageName),
+			pieceActions: (_parent, args) => runtime.pieceActions(args.packageName, args.version ?? void 0),
+			pieceTriggers: (_parent, args) => runtime.pieceTriggers(args.packageName, args.version ?? void 0),
+			blockOutputTree: (_parent, args) => runtime.blockOutputTree(blockRef(args.block), args.config),
+			stepOutputTree: (_parent, args, ctx) => runtime.stepOutputTree(args.workflowId, args.stepId, ctx),
+			blockResolutions: (_parent, args, ctx) => runtime.blockResolutions(args.workflowId, ctx),
+			pieceDetail: (_parent, args) => runtime.pieceDetail(args.packageName, args.version ?? void 0),
 			searchBlocks: (_parent, args) => runtime.searchBlocks(args.query, args.limit ?? void 0),
 			connections: (_parent, _args, ctx) => runtime.connections(ctx),
-			webhookEndpoint: (_parent, args, ctx) => runtime.webhookEndpoint(args.workflowId, ctx),
+			webhookEndpoint: (_parent, args, ctx) => syncAware(() => runtime.webhookEndpoint(args.workflowId, ctx, { driveId: args.driveId ?? void 0 })),
 			secret: async (_parent, args) => {
 				try {
 					return await (await runtime.secrets()).stat(args.ref);
@@ -1177,17 +1319,45 @@ const getResolvers = (runtime, authorizationService) => {
 				}
 			},
 			secrets: async () => (await runtime.secrets()).list(),
+			oauthRedirectUri: () => oauth?.callbackUrl ?? null,
+			oauthAttempt: (_parent, args, ctx) => runtime.oauthAttempt(args.state, ctx),
 			triggerStates: async (_parent, _args, ctx) => (await runtime.triggerStates(ctx)).map((row) => ({
 				workflowId: row.workflow_id,
-				blockType: row.block_type,
+				pieceName: row.piece_name,
+				triggerName: row.trigger_name,
 				status: row.status,
 				intervalMs: row.interval_ms,
 				nextPollAt: row.next_poll_at,
 				lastPollAt: row.last_poll_at,
 				lastError: row.last_error,
-				consecutiveFailures: row.consecutive_failures
+				consecutiveFailures: row.consecutive_failures,
+				nextRenewAt: row.next_renew_at,
+				renewError: row.renew_error,
+				renewFailures: row.renew_failures,
+				pieceVersion: row.piece_version,
+				pieceSource: row.piece_source,
+				versionMatch: row.version_match,
+				versionNote: row.version_note
 			})),
-			runs: async (_parent, args, ctx) => (await runtime.runs(args, ctx)).map((record) => toRunRecord(record.row, record.steps)),
+			runs: async (_parent, args, ctx, info) => (await runtime.runs({
+				...args,
+				withStepData: readsStepData(info, [])
+			}, ctx)).map((record) => toRunRecord(record.row, record.steps)),
+			runsPage: async (_parent, args, ctx, info) => {
+				const { paging, ...scope } = args;
+				const page = await cursorAware(() => runtime.runsPage({
+					...scope,
+					limit: paging?.limit ?? void 0,
+					cursor: paging?.cursor ?? null,
+					withStepData: readsStepData(info, ["items"])
+				}, ctx));
+				return {
+					items: page.records.map((record) => toRunRecord(record.row, record.steps)),
+					hasNextPage: page.hasNextPage,
+					hasPreviousPage: Boolean(paging?.cursor),
+					cursor: page.cursor
+				};
+			},
 			run: async (_parent, args, ctx) => {
 				const record = await runtime.run(args.id, ctx);
 				return record ? toRunRecord(record.row, record.steps) : null;
@@ -1196,7 +1366,13 @@ const getResolvers = (runtime, authorizationService) => {
 		Mutation: { workflowRuntime: () => ({}) },
 		WorkflowRuntimeMutations: {
 			fire: (_parent, args, ctx) => runtime.fire(args.workflowId, args.payload, "manual", void 0, ctx),
-			testTrigger: (_parent, args, ctx) => runtime.testTrigger(args.workflowId, ctx),
+			testTrigger: (_parent, args, ctx) => syncAware(() => runtime.testTrigger(args.workflowId, ctx, {
+				...args.payload !== void 0 ? { payload: args.payload } : {},
+				...typeof args.timeoutSeconds === "number" ? { timeoutMs: args.timeoutSeconds * 1e3 } : {},
+				driveId: args.driveId ?? void 0
+			})),
+			cancelTriggerTest: (_parent, args, ctx) => runtime.cancelTriggerTestFor(args.workflowId, ctx),
+			testStep: (_parent, args, ctx) => syncAware(() => runtime.testStep(args.workflowId, args.stepId, ctx, { driveId: args.driveId ?? void 0 })),
 			rerun: (_parent, args, ctx) => runtime.rerun(args.runId, ctx),
 			createSecret: async (_parent, args, ctx) => {
 				requireAdmin(authorizationService, ctx);
@@ -1214,7 +1390,15 @@ const getResolvers = (runtime, authorizationService) => {
 				await (await runtime.secrets()).delete(args.ref);
 				return true;
 			},
-			checkConnection: (_parent, args, ctx) => runtime.checkConnection(args.connectionId, ctx)
+			checkConnection: (_parent, args, ctx) => runtime.checkConnection(args.connectionId, ctx),
+			startOAuth: (_parent, args, ctx) => {
+				requireAdmin(authorizationService, ctx);
+				const returnUrl = returnUrlFor(args.returnUrl, ctx);
+				return runtime.startOAuth(args.connectionId, ctx, {
+					redirectUri: redirectUriFor(oauth, args.redirectUri),
+					...returnUrl ? { returnUrl } : {}
+				});
+			}
 		}
 	};
 };
@@ -1230,19 +1414,38 @@ const schema = gql`
     Persisted runs, newest first. Scope them to one workflow, or to every
     workflow a drive holds; workflowId wins when both are given.
     """
-    runs(workflowId: String, driveId: String, limit: Int): [WorkflowRunRecord!]!
+    runs(
+      workflowId: String
+      driveId: String
+      limit: Int
+      "Trigger kinds to leave out, e.g. test."
+      excludeTriggerKinds: [String!]
+    ): [WorkflowRunRecord!]!
+    """
+    The same listing a page at a time, newest journaled first. Pass a page's
+    cursor back in paging to read the next; a page is short only when
+    hasNextPage is false, or when the caller could read none of a long
+    stretch of runs. A run that starts between pages keeps its place.
+    """
+    runsPage(
+      workflowId: String
+      driveId: String
+      excludeTriggerKinds: [String!]
+      paging: WorkflowRunsPagingInput
+    ): WorkflowRunResultPage!
     run(id: String!): WorkflowRunRecord
     """
-    Action descriptor (props, auth) for a piece block type; null for core blocks.
+    The descriptor (props, auth, ports) of one action or trigger, as the
+    version that runs it describes it; triggers come back under "trigger".
     """
-    blockDescriptor(blockType: String!): Unknown
+    blockDescriptor(block: BlockInput!): Unknown
     """
     Resolves a dynamic prop against the current config values: a DROPDOWN
     yields { options, placeholder, disabled }, a DYNAMIC prop yields the
     resolved sub-property descriptor list.
     """
     blockOptions(
-      blockType: String!
+      block: BlockInput!
       propName: String!
       input: Unknown
       connectionId: String
@@ -1250,21 +1453,34 @@ const schema = gql`
       searchValue: String
     ): Unknown
     """
-    All published Activepieces pieces with at least one action.
+    Every piece this reactor offers: the core piece, its package pieces, and
+    the pieces the registry and Activepieces publish.
     """
     pieceCatalog: Unknown
     """
-    A piece's actions, each with a ready-to-use blockType.
+    A piece's actions at one version; pin a step to that version.
     """
-    pieceActions(packageName: String!): Unknown
+    pieceActions(
+      packageName: String!
+      "That version; the installed or latest one when omitted."
+      version: String
+    ): Unknown
     """
-    A piece's triggers, each with a ready-to-use "#trigger:" blockType.
+    A piece's triggers at one version; pin a trigger to that version.
     """
-    pieceTriggers(packageName: String!): Unknown
+    pieceTriggers(
+      packageName: String!
+      "That version; the installed or latest one when omitted."
+      version: String
+    ): Unknown
     """
     Full piece detail (PieceMetadataModel-shaped), verbatim from the cloud API.
     """
-    pieceDetail(packageName: String!): Unknown
+    pieceDetail(
+      packageName: String!
+      "That version; the installed or latest one when omitted."
+      version: String
+    ): Unknown
     """
     Action/trigger name search across the catalog. The index builds lazily on
     first use; poll while status is "indexing".
@@ -1277,7 +1493,17 @@ const schema = gql`
     """
     Authored output shape of a block (SDL / outputSchema / sampleData).
     """
-    blockOutputTree(blockType: String!, config: Unknown): Unknown
+    blockOutputTree(block: BlockInput!, config: Unknown): Unknown
+    """
+    Output shape of a draft step or trigger: its latest test output
+    (source "test", with sample and testedAt) when tested, else as blockOutputTree.
+    """
+    stepOutputTree(workflowId: String!, stepId: String!): Unknown
+    """
+    Every block of the draft (trigger first) as this reactor resolves it:
+    which piece version runs, from where, and how it matches the pin.
+    """
+    blockResolutions(workflowId: String!): [BlockResolutionRecord!]!
     """
     Every powerhouse/connection document, for connection pickers.
     """
@@ -1286,19 +1512,62 @@ const schema = gql`
     The webhook endpoint for a workflow: the URL to hand the provider. Minted
     on first ask, whether or not the workflow is armed — an author needs the
     URL before enabling, and the armed field carries that difference. Null
-    only when the host has no webhook service.
+    only when the host has no webhook service. With driveId, a workflow not
+    synced here yet is waited for briefly, then fails as WORKFLOW_SYNCING.
     """
-    webhookEndpoint(workflowId: String!): WebhookEndpointRecord
+    webhookEndpoint(workflowId: String!, driveId: String): WebhookEndpointRecord
     """
     Secret metadata (label, version, status). Never the value.
     """
     secret(ref: String!): SecretRecord
     secrets: [SecretRecord!]!
+    """
+    The URL an OAuth2 app must register as its redirect. A bare path when
+    this host does not know its public origin; resolve it against the URL
+    this API is reached at. Null when the host serves no HTTP routes.
+    """
+    oauthRedirectUri: String
+    """
+    How an OAuth2 sign-in opened by startOAuth stands; null when unknown.
+    """
+    oauthAttempt(state: String!): OAuthAttempt
+  }
+
+  type OAuthAttempt {
+    connectionId: String!
+    "PENDING | EXCHANGING | OK | ERROR"
+    status: String!
+    error: String
+  }
+
+  type OAuthStart {
+    state: String!
+    "Where to send the user to sign in."
+    authorizationUrl: String!
+    redirectUri: String!
+    expiresAt: String!
+  }
+
+  """
+  One action or trigger of a piece, as a workflow pins it. The engine's own
+  blocks are the piece @powerhousedao/piece-core.
+  """
+  input BlockInput {
+    pieceName: String!
+    "Exact semver."
+    pieceVersion: String!
+    "The action or trigger name."
+    name: String!
+    "action | trigger"
+    kind: String!
   }
 
   type BlockSearchHit {
-    blockType: String!
     pieceName: String!
+    "The version the hit is listed at; pin to it when picking the block."
+    pieceVersion: String!
+    "The action or trigger name."
+    name: String!
     pieceDisplayName: String!
     logoUrl: String!
     displayName: String!
@@ -1311,6 +1580,28 @@ const schema = gql`
     unsupported: String
   }
 
+  type BlockResolutionRecord {
+    "The trigger's or step's id."
+    stepId: String!
+    pieceName: String!
+    "The version the block pins."
+    pieceVersion: String!
+    "The action or trigger name."
+    name: String!
+    "action | trigger"
+    kind: String!
+    "The version that runs; null when nothing resolves."
+    resolvedVersion: String
+    "local | registry | activepieces | npm; null when nothing resolves."
+    source: String
+    "exact | compatible | fallback | installed | missing"
+    match: String!
+    "Why the version that runs differs from the pin, or why nothing resolves."
+    note: String
+    "The newest version any source offers."
+    latestVersion: String
+  }
+
   type BlockSearchResult {
     "ready | indexing | error"
     status: String!
@@ -1351,8 +1642,9 @@ const schema = gql`
     workflowId: String!
     url: String!
     """
-    False when the reactor does not know its own public origin, so the url
-    above is a bare path no provider can call: the author supplies the origin.
+    False when the host gave the webhook service no public origin, so the url
+    above is a bare path. Switchboard always gives one, falling back to
+    http://localhost:<port> when PUBLIC_URL is unset.
     """
     absoluteUrl: Boolean!
     "True while the workflow is ENABLED with a valid webhook trigger"
@@ -1362,13 +1654,24 @@ const schema = gql`
 
   type TriggerStateRecord {
     workflowId: String!
-    blockType: String!
+    pieceName: String!
+    triggerName: String!
     status: String!
     intervalMs: Int!
     nextPollAt: String
     lastPollAt: String
     lastError: String
     consecutiveFailures: Int!
+    "When a webhook trigger next renews its subscription; null if it never does."
+    nextRenewAt: String
+    "The last failed renewal, kept apart from lastError, the poll's."
+    renewError: String
+    renewFailures: Int!
+    "The piece version the trigger armed with; null for a host-fed trigger."
+    pieceVersion: String
+    pieceSource: String
+    versionMatch: String
+    versionNote: String
   }
 
   type Query {
@@ -1378,7 +1681,9 @@ const schema = gql`
   type WorkflowStepRunRecord {
     stepId: String!
     stepKey: String!
-    blockType: String!
+    pieceName: String!
+    "The action the step ran, or the trigger a trigger test sampled."
+    blockName: String!
     status: String!
     input: Unknown
     output: Unknown
@@ -1386,6 +1691,14 @@ const schema = gql`
     error: String
     startedAt: String
     endedAt: String
+    "The piece version that ran; null for an unresolved block."
+    pieceVersion: String
+    "local | registry | activepieces | npm"
+    pieceSource: String
+    "exact | compatible | fallback | installed | missing"
+    versionMatch: String
+    "Why the version that ran differs from the pin."
+    versionNote: String
   }
 
   type WorkflowRunRecord {
@@ -1397,16 +1710,38 @@ const schema = gql`
     triggerPayload: Unknown
     status: String!
     error: String
+    "When the run began executing; a PENDING run's is when it was journaled."
     startedAt: String!
     endedAt: String
     rerunOf: String
+    "How many warningNotes the run has; a run with any is not a plain success."
+    warnings: Int!
+    "Steps that ran a fallback piece version, edges on ports nothing emits."
+    warningNotes: [String!]!
     steps: [WorkflowStepRunRecord!]!
   }
 
+  input WorkflowRunsPagingInput {
+    "Page size; default 25, at most 100."
+    limit: Int
+    "The cursor of the previous page."
+    cursor: String
+  }
+
+  type WorkflowRunResultPage {
+    items: [WorkflowRunRecord!]!
+    hasNextPage: Boolean!
+    "True when the page was read after a cursor."
+    hasPreviousPage: Boolean!
+    "Resumes after this page's last run; null for an empty page."
+    cursor: String
+  }
+
   type WorkflowStepRun {
     stepId: String!
     key: String!
-    blockType: String!
+    pieceName: String!
+    blockName: String!
     status: String!
     input: Unknown
     output: Unknown
@@ -1421,18 +1756,51 @@ const schema = gql`
     steps: [WorkflowStepRun!]!
   }
 
+  type WorkflowStepTestResult {
+    "Null when the test never started, e.g. an upstream block is untested."
+    runId: String
+    "SUCCEEDED | FAILED"
+    status: String!
+    output: Unknown
+    error: String
+    durationMs: Int!
+  }
+
   """
   WorkflowRuntime Mutations
   """
   type WorkflowRuntimeMutations {
     """
-    Fires a workflow's core#manual trigger and runs it to completion.
+    Fires a workflow's manual trigger (the core piece's) and runs it to completion.
     """
     fire(workflowId: String!, payload: Unknown): WorkflowRunPayload!
     """
-    Runs a piece trigger's test hook; sample items, no cursor changes.
+    Samples the draft trigger and saves it as the trigger's last test. A piece
+    trigger runs its test hook (no cursor changes). Of the core piece's
+    triggers, manual takes payload, schedule samples a fire now, and webhook
+    waits for the next delivery to the workflow's endpoint, up to
+    timeoutSeconds (default and cap 300), and that delivery runs nothing.
+    """
+    testTrigger(
+      workflowId: String!
+      payload: Unknown
+      timeoutSeconds: Int
+      driveId: String
+    ): Unknown
+    """
+    Stops a webhook trigger test that is waiting; false when none was.
+    """
+    cancelTriggerTest(workflowId: String!): Boolean!
     """
-    testTrigger(workflowId: String!): Unknown
+    Runs one draft step against the latest test outputs of the blocks it
+    reads, journaled as a "test" run and noted as the step's lastTest.
+    driveId waits for an unsynced workflow, as for webhookEndpoint.
+    """
+    testStep(
+      workflowId: String!
+      stepId: String!
+      driveId: String
+    ): WorkflowStepTestResult!
     """
     Resumes a FAILED run: succeeded steps replay from the journal,
     execution restarts at the failure. Produces a new run.
@@ -1457,6 +1825,18 @@ const schema = gql`
     outcome on the connection document.
     """
     checkConnection(connectionId: String!): ConnectionCheckResult!
+    """
+    Opens an OAuth2 sign-in with the connection's own app (client_id in its
+    config, client_secret in its secretRefs). redirectUri is needed only when
+    oauthRedirectUri is a bare path. With returnUrl, which must be on the
+    caller's origin, the callback sends the browser back there with
+    ?ph_oauth=<state> instead of closing the window.
+    """
+    startOAuth(
+      connectionId: String!
+      redirectUri: String
+      returnUrl: String
+    ): OAuthStart!
   }
 
   type Mutation {
@@ -1467,11 +1847,11 @@ const schema = gql`
 //#region src/workflow/subgraph.ts
 /** The runtime's read/write surface. The runtime itself is composed by the
 * host, so the subgraph only serves what it is handed. */
-function createWorkflowRuntimeSubgraph(runtime) {
+function createWorkflowRuntimeSubgraph(runtime, oauth) {
 	return class WorkflowRuntimeSubgraph extends BaseSubgraph {
 		name = "workflow-runtime";
 		typeDefs = schema;
-		resolvers = getResolvers(runtime, this.authorizationService);
+		resolvers = getResolvers(runtime, this.authorizationService, oauth);
 		additionalContextFields = {};
 	};
 }
@@ -1579,7 +1959,7 @@ async function registerWorkflowTriggersReadModel(engine, runtime, clientModule)
 }
 function bindPackagePieces(registry, source) {
 	const apply = (byPackage) => {
-		registry.setPieces([...byPackage.values()].flat());
+		registry.setPieces([...byPackage.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).flatMap(([, pieces]) => pieces));
 	};
 	apply(source.getPieces());
 	source.onPiecesChange(apply);
@@ -1610,8 +1990,9 @@ async function composeWorkflowRuntime(deps) {
 	if (triggers.status === "available") deps.logger.info(`Workflow trigger read model registered (${engine.WORKFLOW_TRIGGERS_READ_MODEL}, ${engine.WORKFLOW_TRIGGERS_READ_MODEL_STAGE})`);
 	else deps.logger.error("Workflow document triggers are NOT armed (@reason): this reactor's read-model coordinator takes no live registration, so no document operation reaches the runtime. Webhook and schedule triggers are unaffected.", triggers.reason);
 	let stopped = false;
+	const oauthCallback = deps.http ? registerOAuthCallback(deps.http, runtime) : void 0;
 	return {
-		subgraph: createWorkflowRuntimeSubgraph(runtime),
+		subgraph: createWorkflowRuntimeSubgraph(runtime, deps.http ? { callbackUrl: callbackUrlOf(deps.http) } : void 0),
 		triggers,
 		async start() {
 			await runtime.registerWebhookEndpoint();
@@ -1620,6 +2001,7 @@ async function composeWorkflowRuntime(deps) {
 		stop() {
 			if (stopped) return Promise.resolve();
 			stopped = true;
+			oauthCallback?.dispose();
 			runtime.shutdown();
 			return Promise.resolve();
 		}
@@ -2314,6 +2696,7 @@ async function initServer(serverPort, options, renown, renownConfig) {
 			attachmentReferences: api.attachmentReferenceIndex.store,
 			attachmentReferenceProjection: api.attachmentReferenceProjection,
 			webhooks: api.httpRoutes.scopeFor(WORKFLOW_PACKAGE_NAME).webhooks,
+			http: api.httpRoutes.scopeFor(WORKFLOW_PACKAGE_NAME),
 			authorizationService: api.authorizationService,
 			pieces: api.packageManager,
 			pieceRegistryUrl: registryUrl,
@@ -2430,6 +2813,7 @@ async function initServer(serverPort, options, renown, renownConfig) {
 		attachmentService,
 		attachmentReferenceProjection: api.attachmentReferenceProjection,
 		workflowTriggers: workflows?.triggers,
+		workflowsEnabled,
 		renown,
 		port: serverPort,
 		shutdown
@@ -2494,5 +2878,5 @@ if (import.meta.main) await startSwitchboard({ fatalErrorShutdown: true });
 //#endregion
 export { parseForcePgVersion as a, applySwitchboardReactorDefaults as i, isPortAvailable as n, startSwitchboard as r, deriveAttachmentServiceConfig as t };
 
-//# sourceMappingURL=server-Cf0DB8sW.mjs.map
-//# debugId=49b28650-fe00-57f4-844b-978a35d80e91
+//# sourceMappingURL=server-CKKn0aXV.mjs.map
+//# debugId=ec5120f6-92b3-53b4-bab1-94d88478784d